@bastani/atomic 0.8.14-0 → 0.8.15-0

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

@@ -7,16 +7,14 @@
  * iteration feeds review findings into the next planner with ctx.task().
  */
 
-import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, extname, join } from "node:path";
+import { dirname, join } from "node:path";
 import { defineWorkflow } from "../src/index.js";
 import type { WorkflowTaskResult } from "../src/shared/types.js";
 
 const DEFAULT_MAX_LOOPS = 10;
-const DEFAULT_SPEC_DIR = "specs";
 const IMPLEMENTATION_NOTES_FILENAME = "implementation-notes.md";
-const MAX_SPEC_SLUG_LENGTH = 80;
 
 type ReviewFinding = {
   readonly title: string;
@@ -47,6 +45,9 @@ type ReviewDecision = {
   readonly overall_correctness: "patch is correct" | "patch is incorrect";
   readonly overall_explanation: string;
   readonly overall_confidence_score: number;
+  readonly goal_oracle_satisfied: boolean;
+  readonly receipt_assessment: string;
+  readonly verification_remaining: string;
   readonly stop_review_loop: boolean;
   readonly reviewer_error?: ReviewerError | null;
 };
@@ -59,6 +60,9 @@ const reviewDecisionSchema = {
     "overall_correctness",
     "overall_explanation",
     "overall_confidence_score",
+    "goal_oracle_satisfied",
+    "receipt_assessment",
+    "verification_remaining",
     "stop_review_loop",
   ],
   properties: {
@@ -99,6 +103,9 @@ const reviewDecisionSchema = {
     },
     overall_explanation: { type: "string" },
     overall_confidence_score: { type: "number", minimum: 0, maximum: 1 },
+    goal_oracle_satisfied: { type: "boolean" },
+    receipt_assessment: { type: "string" },
+    verification_remaining: { type: "string" },
     stop_review_loop: { type: "boolean" },
     reviewer_error: {
       anyOf: [
@@ -148,75 +155,98 @@ const reviewDecisionTool = {
   },
 };
 
-const PLANNER_RFC_TEMPLATE = `
-# [Project Name] Technical Design Document / RFC
+const GOAL_CONTRACT_TEMPLATE = `
+# Goal Contract / Execution Brief
 
 | Document Metadata      | Details                                                                        |
 | ---------------------- | ------------------------------------------------------------------------------ |
 | Author(s)              | !\`git config user.name\`                                                        |
-| Status                 | Draft (WIP) / In Review (RFC) / Approved / Implemented / Deprecated / Rejected |
+| Status                 | Draft (WIP) / In Review (goal contract) / Approved / Implemented / Deprecated / Rejected |
 | Team / Owner           |                                                                                |
 | Created / Last Updated |                                                                                |
 
-## 1. Executive Summary
+## 1. Outcome
 
-## 2. Context and Motivation
+## 2. Scope and Non-Goals
 
-### 2.1 Current State
+## 3. Verification Oracle
 
-### 2.2 The Problem
+## 4. Work Surface and Execution Loop
 
-## 3. Goals and Non-Goals
+## 5. Proof and Review Criteria
 
-### 3.1 Functional Goals
+## 6. Implementation Strategy
 
-### 3.2 Non-Goals (Out of Scope)
+## 7. Context and Motivation
 
-## 4. Proposed Solution (High-Level Design)
+### 7.1 Current State
 
-### 4.1 System Architecture Diagram
+### 7.2 The Problem
+
+## 8. Bounded Work Slices
+
+## 9. Proposed Approach
+
+### 9.1 System Architecture Diagram
 
 Include a Mermaid system architecture diagram grounded in the actual components this work touches.
 
-### 4.2 Architectural Pattern
+### 9.2 Architectural Pattern
 
-### 4.3 Key Components
+### 9.3 Key Components
 
 | Component | Responsibility | Technology Stack | Justification |
 | --------- | -------------- | ---------------- | ------------- |
 
-## 5. Detailed Design
+## 10. Implementation Notes
 
-### 5.1 API Interfaces
+### 10.1 API Interfaces
 
-### 5.2 Data Model / Schema
+### 10.2 Data Model / Schema
 
-### 5.3 Algorithms and State Management
+### 10.3 Algorithms and State Management
 
-## 6. Alternatives Considered
+## 11. Alternatives Considered
 
 | Option | Pros | Cons | Reason for Rejection |
 | ------ | ---- | ---- | -------------------- |
 
-## 7. Cross-Cutting Concerns
+## 12. Cross-Cutting Concerns
 
-### 7.1 Security and Privacy
+### 12.1 Security and Privacy
 
-### 7.2 Observability Strategy
+### 12.2 Observability Strategy
 
-### 7.3 Scalability and Capacity Planning
+### 12.3 Scalability and Capacity Planning
 
-## 8. Migration, Rollout, and Testing
+## 13. Validation and Rollout
 
-### 8.1 Deployment Strategy
+### 13.1 Deployment Strategy
 
-### 8.2 Data Migration Plan
+### 13.2 Data Migration Plan
 
-### 8.3 Test Plan
+### 13.3 Test Plan
 
-## 9. Open Questions / Unresolved Issues
+## 14. Open Questions / Unresolved Issues
 `.trim();
 
+const GOAL_OPERATING_LOOP =
+  "intent, verification oracle, work surface, execution loop, and proof";
+
+const GOAL_METHOD_REFERENCE = [
+  "Maintain a concrete goal contract for the run: intent, verification oracle, work surface, execution loop, and proof.",
+  "Infer the owner outcome and a verifiable oracle from the user's task and repository evidence; do not ask the user unless the workflow is truly blocked.",
+  "Treat any user-supplied planning artifacts as supporting context, not as the primary success criterion.",
+  "Keep pressure on current evidence: the current worktree, artifacts, command output, tests, demos, generated files, and explicit human decisions are more authoritative than prior conversation summaries.",
+  "Never call the work complete because planning, discovery, task selection, or a substantial-looking diff exists; completion requires proof mapped back to the original owner outcome.",
+].join("\n");
+
+const RECEIPT_EXPECTATIONS = [
+  "Every implementation, simplification, discovery, review, and audit stage should leave a receipt reviewers can inspect.",
+  "A useful receipt names what changed, files touched, commands or checks run with outcomes, artifacts produced, decisions made, blockers, residual risks, and the next safest action.",
+  "Receipts should explicitly say which part of the verification oracle they support or what verification remains.",
+].join("\n");
+
 type PromptSection = readonly [tag: string, content: string];
 
 function taggedPrompt(sections: readonly PromptSection[]): string {
@@ -245,60 +275,32 @@ function normalizeBranchInput(
   return looksLikeSafeGitRef ? trimmed : fallback;
 }
 
-function slugifySpecTopic(prompt: string): string {
-  const slug = prompt
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, MAX_SPEC_SLUG_LENGTH)
-    .replace(/-+$/g, "");
-  return slug.length > 0 ? slug : "plan";
-}
-
-function defaultSpecPath(prompt: string, now = new Date()): string {
-  const date = now.toISOString().slice(0, 10);
-  return join(DEFAULT_SPEC_DIR, `${date}-${slugifySpecTopic(prompt)}.md`);
-}
-
-function suffixedPath(path: string, suffix: number): string {
-  const extension = extname(path);
-  const stem = extension.length === 0 ? path : path.slice(0, -extension.length);
-  return `${stem}-${suffix}${extension}`;
-}
-
-function isFileExistsError(error: unknown): boolean {
-  return error instanceof Error && (error as { readonly code?: string }).code === "EEXIST";
-}
-
-async function writeSpecFile(path: string, content: string): Promise<string> {
-  await mkdir(dirname(path), { recursive: true });
-
-  for (let suffix = 0; ; suffix += 1) {
-    const candidate = suffix === 0 ? path : suffixedPath(path, suffix + 1);
-    try {
-      await writeFile(candidate, content.endsWith("\n") ? content : `${content}\n`, {
-        encoding: "utf8",
-        flag: "wx",
-      });
-      return candidate;
-    } catch (error) {
-      if (isFileExistsError(error)) continue;
-      throw error;
-    }
-  }
-}
-
 async function createImplementationNotesFile(prompt: string): Promise<string> {
-  const notesDir = await mkdtemp(join(tmpdir(), "atomic-ralph-notes-"));
+  const notesDir = await mkdtemp(join(tmpdir(), "atomic-goal-notes-"));
   const notesPath = join(notesDir, IMPLEMENTATION_NOTES_FILENAME);
   const initialNotes = [
     "# Implementation Notes",
     "",
     `Task: ${prompt || "(empty prompt)"}`,
     "",
-    "## Running Notes",
+    "## Goal Charter",
+    "",
+    "- Outcome: inferred by the planner/orchestrator from the user task and repository evidence.",
+    "- Scope: record allowed changes and explicit non-goals as they become clear.",
+    "- Oracle: record the observable signal that proves the owner outcome is true.",
+    `- Execution contract: ${GOAL_OPERATING_LOOP}`,
+    "- Proof: collect receipts that map implementation and validation back to the oracle.",
+    "",
+    "## Work Surface State",
     "",
-    "- Record implementation decisions, deviations from the spec, tradeoffs, blockers, validation notes, and anything else the user should know.",
+    "- Active work: none recorded yet.",
+    "- Blocked work: none recorded yet.",
+    "- Completed work: none recorded yet.",
+    "- Verification status: no receipts yet.",
+    "",
+    "## Receipts",
+    "",
+    "- Record implementation decisions, deviations from the goal contract, tradeoffs, blockers, validation notes, artifacts, and anything else the user should know.",
   ].join("\n");
   await writeFile(notesPath, `${initialNotes}\n`, {
     encoding: "utf8",
@@ -320,6 +322,9 @@ function parseReviewDecision(text: string): ReviewDecision | undefined {
     if (typeof parsed.stop_review_loop !== "boolean") return undefined;
     if (typeof parsed.overall_explanation !== "string") return undefined;
     if (typeof parsed.overall_confidence_score !== "number") return undefined;
+    if (typeof parsed.goal_oracle_satisfied !== "boolean") return undefined;
+    if (typeof parsed.receipt_assessment !== "string") return undefined;
+    if (typeof parsed.verification_remaining !== "string") return undefined;
     return parsed as ReviewDecision;
   } catch {
     return undefined;
@@ -332,6 +337,7 @@ function reviewApproved(text: string): boolean {
   return (
     decision.stop_review_loop === true &&
     decision.overall_correctness === "patch is correct" &&
+    decision.goal_oracle_satisfied === true &&
     decision.findings.length === 0 &&
     decision.reviewer_error == null
   );
@@ -347,6 +353,10 @@ function reviewerErrorResult(
     overall_explanation:
       "Reviewer execution failed, so the review loop cannot safely approve this iteration.",
     overall_confidence_score: 0,
+    goal_oracle_satisfied: false,
+    receipt_assessment:
+      "No reviewer receipt could be produced because reviewer execution failed.",
+    verification_remaining: "Recover reviewer execution and re-run oracle validation.",
     stop_review_loop: false,
     reviewer_error: {
       kind: "reviewer_failure",
@@ -362,19 +372,6 @@ function reviewerErrorResult(
   };
 }
 
-function discoveryContextLabel(name: string | undefined): string {
-  if (name?.startsWith("infra-locate-")) return "Infrastructure locator";
-  if (name?.startsWith("infra-analyze-")) return "Infrastructure analyzer";
-  if (name?.startsWith("infra-patterns-")) return "Infrastructure pattern finder";
-  return "Infrastructure discovery";
-}
-
-function formatDiscovery(results: readonly WorkflowTaskResult[]): string {
-  return results
-    .map((result) => `### ${discoveryContextLabel(result.name)}\n\n${result.text}`)
-    .join("\n\n---\n\n");
-}
-
 function formatReview(results: readonly WorkflowTaskResult[]): string {
   return results
     .map((result) => `### ${result.name}\n\n${result.text}`)
@@ -417,6 +414,7 @@ export default defineWorkflow("ralph")
     let finalResult = "";
     let finalPrReport = "";
     const implementationNotesPath = await createImplementationNotesFile(prompt);
+    const goalContractPath = join(dirname(implementationNotesPath), "goal-contract.md");
     let approved = false;
     let iterationsCompleted = 0;
 
@@ -483,18 +481,6 @@ export default defineWorkflow("ralph")
       customTools: [reviewDecisionTool],
     };
 
-    let explorerModelConfig = {
-      model: "openai/gpt-5.4-mini",
-      fallbackModels: [
-        "openai-codex/gpt-5.4-mini",
-        "github-copilot/gpt-5.4-mini",
-        "anthropic/claude-haiku-4-5",
-        "github-copilot/claude-haiku-4.5",
-      ],
-      thinkingLevel: "low" as const,
-      tools: noAskQuestionToolSet,
-    };
-
     for (let iteration = 1; iteration <= maxLoops; iteration += 1) {
       iterationsCompleted = iteration;
 
@@ -502,19 +488,21 @@ export default defineWorkflow("ralph")
         prompt: taggedPrompt([
           [
             "role",
-            "You are a technical architect. Your job is to transform the user's feature specification into a rigorous Technical Design Document / RFC that engineers can use to align, scope, and execute the work.",
+            "You are a technical architect. Your job is to transform the user's task into a goal charter, verification oracle, review criteria, and supporting goal contract that engineers can use to execute against evidence.",
           ],
+          ["goal_framework", GOAL_METHOD_REFERENCE],
           [
             "critical_deliverable",
             [
-              "Your final output is a filled-in RFC rendered as markdown text.",
-              "Render the RFC Template in this prompt with every section populated by feature-specific content drawn from the user's specification and your codebase investigation.",
-              "Do not implement code changes in this stage; this stage only investigates and authors the RFC.",
+              "Your final output is a filled-in goal contract rendered as markdown text, with explicit outcome, scope, verification oracle, work surface, and proof sections.",
+              "Render the goal contract template in this prompt with every section populated by feature-specific content drawn from the user's task and your codebase investigation.",
+              "The goal contract artifact supports implementation, but the primary success criterion is whether receipts and verification prove the inferred owner outcome.",
+              "Do not implement code changes in this stage; this stage only investigates, infers the verification contract, and authors the goal contract.",
             ].join("\n"),
           ],
           [
             "task",
-            `Plan iteration ${iteration}/${maxLoops} for this user specification:\n${prompt}`,
+            `Plan iteration ${iteration}/${maxLoops} for this user task:\n${prompt}`,
           ],
           [
             "previous_review_findings",
@@ -523,20 +511,20 @@ export default defineWorkflow("ralph")
               : "No prior review findings; this is the first iteration.",
           ],
           [
-            "input_spec_files",
+            "input_goal_contract_files",
             [
-              "If the user specification is a file path instead of raw prose, read that file and use it as source material for the RFC.",
-              "Still author the RFC normally; do not output only a forwarded path.",
+              "If the user task is a file path instead of raw prose, read that file and use it as source material for the goal contract.",
+              "Still author the goal contract normally; do not output only a forwarded path.",
             ].join("\n"),
           ],
           [
             "investigation_phase",
             [
-              "Before drafting, read the specification carefully and identify the concrete problem, success criteria, hard constraints, and non-goals.",
-              "Survey the codebase using file/search tools such as read plus grep/rg/find/glob-style shell commands to ground the RFC in current architecture.",
+              "Before drafting, read the task carefully and infer the concrete goal contract: outcome, scope, non-goals, verification oracle, work surface, proof expectations, and review criteria tied to the oracle.",
+              "Survey the codebase using file/search tools such as read plus grep/rg/find/glob-style shell commands to ground the goal contract in current architecture.",
               "Name concrete services, modules, files, tests, data models, APIs, CLIs, config files, and external integrations this work will touch.",
               "Capture metadata with bash: `git config user.name` for Author(s), and `date '+%Y-%m-%d'` for Created / Last Updated.",
-              "Look for prior art: existing RFCs, ADRs, README files, specs, docs, tests, or code comments that explain why the current state exists.",
+              "Look for prior art: existing goal contracts, ADRs, README files, plans, docs, tests, or code comments that explain why the current state exists.",
             ].join("\n"),
           ],
           [
@@ -545,37 +533,40 @@ export default defineWorkflow("ralph")
               "Be specific: `src/server/auth.ts:42` beats `the auth layer`.",
               "Trade-offs over conclusions: Alternatives Considered must include at least two real alternatives with honest pros, cons, and rejection reasons.",
               "Non-goals matter: explicitly exclude work that is out of scope to prevent scope creep.",
-              "Diagrams are load-bearing: Section 4.1 must include a Mermaid system architecture diagram grounded in real components.",
-              "Surface open questions in Section 9 with owner placeholders such as `[OWNER: infra team]`; do not paper over uncertainty.",
+              "Diagrams are load-bearing when architecture changes are involved: include a Mermaid system architecture diagram grounded in real components in Section 9.1; for non-architecture work, state why no diagram is needed.",
+              "Surface open questions in Section 14 with owner placeholders such as `[OWNER: infra team]`; do not paper over uncertainty, but make the workflow autonomous by choosing safe defaults and verifiable assumptions when possible.",
               "Match depth to stakes: a small refactor can be concise, but every template section header must remain present.",
               "If prior review findings are present, explicitly address each finding or explain why it is obsolete.",
+              "For Sections 1-5, include review criteria tied to the oracle, not document-completeness criteria.",
             ].join("\n"),
           ],
           [
             "stage_contract",
             [
-              "This stage is investigation-first RFC authoring. The RFC is only valid if it is grounded in repository inspection performed during this stage.",
-              "Do not fill the template from generic architecture guesses. Before writing the final RFC, inspect relevant code, docs, tests, configs, and prior design material.",
+              "This stage is investigation-first goal-charter and goal contract authoring. The goal contract is only valid if it is grounded in repository inspection performed during this stage.",
+              "Do not fill the template from generic architecture guesses. Before writing the final goal contract, inspect relevant code, docs, tests, configs, and prior design material.",
               "Treat the output format as the report after investigation, not a substitute for investigation.",
+              "Treat the goal contract as supporting context rather than the primary success criterion; success is receipt-backed satisfaction of the verification oracle.",
             ].join("\n"),
           ],
           [
             "evidence_expectations",
             [
-              "Every major design claim should be traceable to concrete evidence: file paths, symbols, commands, docs, tests, configs, or prior RFCs.",
-              "Include those concrete references inside the RFC sections where they support the design.",
-              "If expected evidence cannot be found, say so in the relevant RFC section or Open Questions rather than papering over the gap.",
+              "Every major design claim should be traceable to concrete evidence: file paths, symbols, commands, docs, tests, configs, or prior goal contracts.",
+              "Include those concrete references inside the goal contract sections where they support the design.",
+              "For the verification oracle, name the observable proof signal: passing tests, browser walkthrough, generated artifact, benchmark, migration result, demo transcript, source-backed answer, or explicit human decision.",
+              "If expected evidence cannot be found, say so in the relevant goal contract section or Open Questions rather than papering over the gap.",
             ].join("\n"),
           ],
           [
             "output_discipline",
             [
-              "Render the RFC Template exactly as the final document structure: preserve every header and the metadata table.",
-              "Replace instructional placeholders with real, feature-specific content; do not leave template guidance in the final RFC.",
-              "Output nothing after the RFC: no meta-commentary, no summary of what you wrote, no implementation log.",
+              "Render the goal contract template exactly as the final document structure: preserve every header and the metadata table.",
+              "Replace instructional placeholders with real, feature-specific content; do not leave template guidance in the final goal contract.",
+              "Output nothing after the goal contract: no meta-commentary, no summary of what you wrote, no implementation log.",
             ].join("\n"),
           ],
-          ["rfc_template", PLANNER_RFC_TEMPLATE],
+          ["goal_contract_template", GOAL_CONTRACT_TEMPLATE],
         ]),
         ...(reviewReport
           ? { previous: { name: "review-report", text: reviewReport } }
@@ -583,8 +574,11 @@ export default defineWorkflow("ralph")
         ...plannerModelConfig,
       });
       finalPlan = planner.text;
-      const specPath = await writeSpecFile(defaultSpecPath(prompt), planner.text);
-      finalPlanPath = specPath;
+      await writeFile(goalContractPath, planner.text.endsWith("\n") ? planner.text : `${planner.text}\n`, {
+        encoding: "utf8",
+        flag: "w",
+      });
+      finalPlanPath = goalContractPath;
 
       const orchestrator = await ctx.task(`orchestrator-${iteration}`, {
         prompt: taggedPrompt([
@@ -596,24 +590,41 @@ export default defineWorkflow("ralph")
             "objective",
             `Implement iteration ${iteration}/${maxLoops} for the task: ${prompt}`,
           ],
+          ["goal_framework", GOAL_METHOD_REFERENCE],
           [
-            "spec_file",
+            "goal_contract_file",
             [
-              `The technical specification for this iteration was written to: ${specPath}`,
-              "Read this file before delegating or implementing anything.",
-              "Do not rely on an inline planner transcript; the spec file is the authoritative plan for this iteration.",
+              `The goal contract for this iteration was written to: ${goalContractPath}`,
+              "Read this file before delegating or implementing anything, especially the outcome, scope, verification oracle, work surface, and proof sections.",
+              "Do not rely on an inline planner transcript; the goal contract file is the authoritative supporting plan for this iteration.",
+              "The goal contract is not the finish line: the finish line is receipt-backed proof that the verification oracle is satisfied.",
             ].join("\n"),
           ],
           [
             "implementation_notes",
             [
               `Keep a running Markdown implementation notes file at this OS temp directory path: ${implementationNotesPath}`,
-              "The file has already been initialized for this workflow run; update it while you implement the spec.",
-              "Record decisions you had to make that were not in the spec, things you had to change from the spec, tradeoffs you had to make, blockers, validation outcomes, and anything else the user should know.",
-              "Ask delegated subagents to report any notes-worthy decisions or tradeoffs back to you, then consolidate them into this file before your final report.",
+              "The file has already been initialized for this workflow run; update it while you implement the goal contract.",
+              "Maintain the Goal Charter, Work Surface State, and Receipts sections while you implement.",
+              "Record active work, blocked work, completed work, verification status, decisions you had to make that were not in the goal contract, things you had to change from the goal contract, tradeoffs you had to make, blockers, validation outcomes, and anything else the user should know.",
+              "Ask delegated subagents to report receipts and any notes-worthy decisions or tradeoffs back to you, then consolidate them into this file before your final report.",
               "Do not include secrets, credentials, tokens, or unrelated environment details in the notes file.",
             ].join("\n"),
           ],
+          [
+            "project_initialization_preflight",
+            [
+              "Before normal implementation delegation, determine whether this checkout appears initialized for its actual language, framework, and build system.",
+              "Do not rely on hard-coded assumptions about JavaScript, TypeScript, Python, Rust, Go, Java, mobile, or any other ecosystem. Infer the project type and setup requirements from repository evidence.",
+              "Inspect source layout, setup docs, package/build manifests, lockfiles, toolchain files, generated-artifact conventions, CI workflows, workflow configuration, and package scripts or equivalent task definitions.",
+              "Look for evidence that dependencies, generated files, local toolchains, submodules, codegen outputs, or other project-specific initialization artifacts are missing for this checkout.",
+              "When repository evidence shows missing initialization, run or delegate the appropriate documented setup command before implementation work.",
+              "You are responsible for initializing the checkout when setup commands are documented; missing dependencies, generated files, or local toolchains are setup work, not user handoff work.",
+              "Once setup succeeds, continue normal implementation orchestration. Do not treat missing dependencies or generated setup artifacts in a fresh worktree as implementation failures.",
+              "If setup requirements cannot be determined confidently, delegate a focused discovery task before implementation instead of guessing.",
+              "If setup remains blocked after evidence-based discovery and setup attempts, report the blocker with commands tried and the exact evidence needed to continue.",
+            ].join("\n"),
+          ],
           [
             "delegation_policy",
             [
@@ -621,7 +632,8 @@ export default defineWorkflow("ralph")
               "All non-trivial operations must be delegated to subagents via the `subagent` tool before you claim progress.",
               "Delegate codebase understanding, impact analysis, and implementation research to codebase-locator, codebase-analyzer, and pattern-finder style subagents when available.",
               "Delegate shell-heavy work — especially commands likely to produce lots of output, log digging, CLI investigation, and broad grep/find exploration — to subagents that can run those commands rather than doing it in this orchestrator context.",
-              "Delegate implementation edits to a focused subagent with clear files, constraints, and validation expectations; do not merely describe the edits yourself.",
+              "Delegate implementation edits to a focused subagent with clear files, constraints, validation expectations, and the receipts it must return; do not merely describe the edits yourself.",
+              "Choose the largest safe useful slice for each write delegation: safe means bounded, explicit, verified, and reversible, not tiny.",
               "Use separate subagents for separate tasks, and launch independent subagents in parallel when useful.",
               "Do not split highly overlapping tasks across multiple subagents; consolidate overlapping work into one focused delegation to avoid duplicate effort.",
               "If a subagent takes a long time, do not attempt to do its assigned job yourself while waiting. Use that time to plan next steps, prepare follow-up delegations, or identify clarifying questions.",
@@ -631,9 +643,9 @@ export default defineWorkflow("ralph")
             "execution_contract",
             [
               "The required output format is a completion report, not the task itself.",
-              "Do not jump straight to the report. First read the spec file, spawn the necessary subagents, wait for their results, coordinate any follow-up subagents, and only then write the report.",
-              "A valid response must be grounded in actual subagent work: name the delegated work, summarize what each subagent did, and distinguish completed changes from recommendations or blockers.",
-              "If you cannot read the spec file, spawn subagents, or use subagents, treat that as a blocker and report it honestly instead of pretending the requested work was done.",
+              "Do not jump straight to the report. First read the goal contract file, spawn the necessary subagents, wait for their results, coordinate any follow-up subagents, and only then write the report.",
+              "A valid response must be grounded in actual subagent work: name the delegated work, summarize what each subagent did, preserve its receipt, and distinguish completed changes from recommendations or blockers.",
+              "If you cannot read the goal contract file, spawn subagents, or use subagents, treat that as a blocker and report it honestly instead of pretending the requested work was done.",
             ].join("\n"),
           ],
           [
@@ -641,22 +653,23 @@ export default defineWorkflow("ralph")
             [
               "Use the `todo` tool as your active control ledger for subagent work.",
               "Before launching subagents, create todo items for each delegated task with enough detail to identify owner, purpose, and expected output.",
-              "Mark todo items in_progress when the corresponding subagent starts, append progress/results as subagents report back, and close them only after you have incorporated or explicitly rejected their result.",
-              "Keep pending, in_progress, blocked, and completed work accurate so you do not lose track of parallel subagents or unresolved follow-ups.",
+              "Mark todo items in_progress when the corresponding subagent starts, append progress/results/receipts as subagents report back, and close them only after you have incorporated or explicitly rejected their result.",
+              "Keep pending, in_progress, blocked, completed, and verification status accurate so you do not lose track of parallel subagents or unresolved follow-ups.",
               "Before writing the final report, review the todo list and resolve every pending/in_progress item as completed, blocked, or deferred with an explanation.",
             ].join("\n"),
           ],
           [
             "instructions",
             [
-              `Start by reading the spec file at ${specPath}.`,
-              "Decompose the work into delegated subagent tasks based on that spec file.",
-              "Pass each subagent the relevant task, constraints, files, validation expectations, any prior review findings from the spec, and instructions to report implementation-note-worthy decisions or tradeoffs.",
-              "Coordinate subagent results into the smallest coherent set of changes that satisfies the spec.",
-              "Preserve existing architecture and repository conventions unless the spec explicitly justifies a change.",
+              `Start by reading the goal contract file at ${goalContractPath}.`,
+              "Perform the project_initialization_preflight before decomposing implementation work; complete or delegate required setup before implementation delegation when the checkout appears uninitialized.",
+              "Decompose the work into delegated subagent tasks based on that goal contract file.",
+              "Pass each subagent the relevant task, constraints, files, validation expectations, verification oracle, any prior review findings from the goal contract, and instructions to return a receipt: changed files, checks run, artifacts, decisions, blockers, residual risks, and what remains to verify.",
+              "Coordinate subagent results into the largest safe useful slice that advances the owner outcome and remains reversible and verifiable.",
+              "Preserve existing architecture and repository conventions unless the goal contract explicitly justifies a change.",
               "Run or delegate the most relevant validation commands available in the repository.",
-              `Before your final report, update the running implementation notes file at ${implementationNotesPath} with decisions, spec deviations, tradeoffs, blockers, and validation outcomes from this iteration.`,
-              "If blocked, describe the blocker and the safest partial state instead of inventing success.",
+              `Before your final report, update the running implementation notes file at ${implementationNotesPath} with the current Goal Charter, Work Surface State, receipts, decisions, goal-contract deviations, tradeoffs, blockers, and validation outcomes from this iteration.`,
+              "If a specific slice is blocked, record that blocker and continue adjacent safe local work that advances the full goal when possible; do not treat one blocked slice as a completed goal.",
               "Do not hide failures; reviewers need accurate status.",
             ].join("\n"),
           ],
@@ -664,17 +677,20 @@ export default defineWorkflow("ralph")
             "output_format",
             [
               "After subagents have done the work, return Markdown with headings:",
-              "1. Spec file — the path you read",
-              "2. Delegations performed — subagents spawned and what each completed",
-              "3. Changes made — concrete changes from subagent work, not intentions",
-              "4. Files touched",
-              "5. Validation run / recommended",
-              "6. Deferred work or blockers",
-              "7. Implementation notes — confirm the OS temp notes path was updated",
+              "1. Goal contract file — the path you read",
+              "2. Goal contract — the inferred outcome, scope, verification oracle, and proof loop used",
+              "3. Work surface state — active, blocked, completed, and verification status",
+              "4. Delegations performed — subagents spawned and what each completed",
+              "5. Receipts — concrete evidence from each stage, including changed files, checks, artifacts, decisions, and risks",
+              "6. Changes made — concrete changes from subagent work, not intentions",
+              "7. Files touched",
+              "8. Validation run / recommended — map each check to the verification oracle",
+              "9. Deferred work or blockers",
+              "10. Implementation notes — confirm the OS temp notes path was updated",
             ].join("\n"),
           ],
         ]),
-        reads: [specPath, implementationNotesPath],
+        reads: [goalContractPath, implementationNotesPath],
         ...orchestratorModelConfig,
       });
       finalResult = orchestrator.text;
@@ -691,8 +707,9 @@ export default defineWorkflow("ralph")
           ],
           [
             "objective",
-            `Refine recently modified code for this task while preserving exact behavior: ${prompt}`,
+            `Refine recently modified code for this task while preserving exact behavior and the verification oracle: ${prompt}`,
           ],
+          ["goal_framework", GOAL_METHOD_REFERENCE],
           ["current_iteration_context", "{previous}"],
           [
             "functionality_preservation",
@@ -749,7 +766,10 @@ export default defineWorkflow("ralph")
           ],
           [
             "handoff_expectations",
-            "In the final report, distinguish edits actually applied from observations only. Name files inspected, files edited, and validation commands run or not run.",
+            [
+              "In the final report, distinguish edits actually applied from observations only. Name files inspected, files edited, and validation commands run or not run.",
+              "Produce a receipt that maps simplifications and validation back to the verification oracle or explicitly says no oracle-relevant simplification was needed.",
+            ].join("\n"),
           ],
           [
             "process",
@@ -766,9 +786,10 @@ export default defineWorkflow("ralph")
             [
               "Markdown with headings:",
               "1. Simplifications applied",
-              "2. Behavior-preservation notes",
-              "3. Validation run / recommended",
-              "4. Skipped risky simplifications",
+              "2. Receipt — files inspected/edited, checks run, artifacts, and oracle relevance",
+              "3. Behavior-preservation notes",
+              "4. Validation run / recommended",
+              "5. Skipped risky simplifications",
             ].join("\n"),
           ],
         ]),
@@ -776,130 +797,6 @@ export default defineWorkflow("ralph")
         ...simplifierModelConfig,
       });
 
-      const discovery = await ctx.parallel(
-        [
-          {
-            name: `infra-locate-${iteration}`,
-            task: taggedPrompt([
-              [
-                "role",
-                "You locate project infrastructure needed for patch review.",
-              ],
-              [
-                "objective",
-                `Find review-relevant infrastructure for the task: ${prompt}`,
-              ],
-              [
-                "stage_contract",
-                [
-                  "This is a repository-discovery stage. Do not answer from assumptions or common project layouts.",
-                  "Before output, inspect the repository for each infrastructure category: package scripts, test configs, CI workflows, generated artifacts, lint/typecheck setup, and release gates.",
-                  "The table is a compact handoff after discovery, not a substitute for discovery.",
-                ].join("\n"),
-              ],
-              [
-                "instructions",
-                [
-                  "Locate package scripts, test configs, CI workflows, generated artifacts, lint/typecheck setup, and release gates.",
-                  "Search/read relevant files such as package manifests, CI workflow directories, test configs, lint/typecheck configs, build scripts, release configs, and generated-artifact markers.",
-                  "Prefer exact file paths and commands.",
-                  "Explain how each item should influence review or validation.",
-                  "If a category does not exist, report `not found` and briefly name the paths or patterns checked.",
-                ].join("\n"),
-              ],
-              [
-                "output_format",
-                "Markdown table: Area | Path/command | Why it matters | Confidence.",
-              ],
-            ]),
-            ...explorerModelConfig,
-          },
-          {
-            name: `infra-analyze-${iteration}`,
-            task: taggedPrompt([
-              [
-                "role",
-                "You analyze integration risks in project infrastructure.",
-              ],
-              [
-                "objective",
-                `Assess infrastructure and changed-code risks for the task: ${prompt}`,
-              ],
-              [
-                "stage_contract",
-                [
-                  "This stage analyzes actual repository coupling, not generic integration risks.",
-                  "Before output, inspect the changed-code context plus relevant infrastructure/configuration files discovered or inferable from the repo.",
-                  "Classify a risk as confirmed only when repository evidence shows the coupling; otherwise mark it speculative.",
-                ].join("\n"),
-              ],
-              [
-                "instructions",
-                [
-                  "Identify hidden coupling with build, tests, linting, runtime config, release automation, or generated files.",
-                  "Name the exact validations that would most efficiently detect regressions.",
-                  "Separate confirmed risks from speculative risks.",
-                  "Do not repeat generic review advice; ground findings in repository evidence.",
-                  "Copy validation commands from actual repository scripts/configs when available; do not invent commands that are not supported by the repo.",
-                ].join("\n"),
-              ],
-              [
-                "evidence_expectations",
-                "Each confirmed risk must include concrete evidence: path, command, symbol, config key, script name, or file relationship.",
-              ],
-              [
-                "output_format",
-                "Markdown with sections: Confirmed risks, Speculative risks, Validation commands, Evidence.",
-              ],
-            ]),
-            ...explorerModelConfig,
-          },
-          {
-            name: `infra-patterns-${iteration}`,
-            task: taggedPrompt([
-              [
-                "role",
-                "You find repository patterns that a patch must follow.",
-              ],
-              [
-                "objective",
-                `Extract conventions relevant to reviewing this task: ${prompt}`,
-              ],
-              [
-                "stage_contract",
-                [
-                  "This is an evidence-gathering stage for repository conventions. Do not describe generic best practices.",
-                  "Before output, find concrete examples in the repository that demonstrate conventions relevant to this task.",
-                  "Read enough of each example to understand the convention before reporting it.",
-                ].join("\n"),
-              ],
-              [
-                "instructions",
-                [
-                  "Find examples of build/test/style/release/architecture patterns the patch should mirror.",
-                  "Search for nearby or analogous implementations, tests, configs, scripts, and docs.",
-                  "Use concrete paths, commands, or symbols as evidence.",
-                  "Highlight conventions that commonly cause subtle review failures.",
-                  "If examples conflict, describe the conflict instead of forcing a single rule.",
-                  "If no relevant example exists, state what was searched and that no pattern was found.",
-                ].join("\n"),
-              ],
-              [
-                "handoff_expectations",
-                "For every required convention or useful example, include the supporting path, command, symbol, or file relationship so reviewers can verify it quickly.",
-              ],
-              [
-                "output_format",
-                "Markdown with sections: Required conventions, Useful examples, Exceptions, Review implications.",
-              ],
-            ]),
-            ...explorerModelConfig,
-          },
-        ],
-        { task: prompt },
-      );
-
-      const discoveryContext = formatDiscovery(discovery);
       const reviewPrompt = taggedPrompt([
         [
           "role",
@@ -913,6 +810,17 @@ export default defineWorkflow("ralph")
           "objective",
           `Review the current code delta for the task: ${prompt}`,
         ],
+        ["goal_framework", GOAL_METHOD_REFERENCE],
+        ["receipt_expectations", RECEIPT_EXPECTATIONS],
+        [
+          "goal_context_files",
+          [
+            `Planner/supporting goal contract path: ${goalContractPath}`,
+            `Implementation notes and receipts path: ${implementationNotesPath}`,
+            "Read these files to recover the goal charter, verification oracle, work surface state, receipts, and verification claims before approving anything.",
+            "Review success is whether current evidence and receipts satisfy the verification oracle, not whether the supporting goal contract looks complete.",
+          ].join("\n"),
+        ],
         [
           "comparison_baseline",
           [
@@ -921,11 +829,12 @@ export default defineWorkflow("ralph")
             `Start with \`git status --short\`, then use working-tree-aware commands such as \`git diff ${comparisonBaseBranch}\` and \`git diff --cached ${comparisonBaseBranch}\` to identify changed tracked files; inspect untracked files from status directly.`,
           ].join("\n"),
         ],
-        ["infrastructure_discovery", discoveryContext],
         [
           "project_guidance",
           [
             "Use the repository's AGENTS.md and/or CLAUDE.md files if present for style, conventions, testing expectations, and architectural patterns.",
+            "Inspect the codebase for testing, linting, typecheck, build, generated-artifact, and CI patterns that should shape review; prefer commands and conventions copied from actual repository scripts/configs over invented checks.",
+            "When changed files touch an area with established test or lint patterns, compare the patch against nearby tests, package scripts, config files, and CI workflows before approving.",
             "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.",
@@ -935,6 +844,9 @@ export default defineWorkflow("ralph")
           "validation_expectations",
           [
             "Inspect the actual diff/repository state rather than trusting stage summaries.",
+            "Identify the smallest relevant validation set from repository evidence: targeted tests, lint, typecheck, build, generated-artifact checks, CI-equivalent scripts, or user-flow proof.",
+            "When practical, include an end-to-end QA check that exercises the app the way a user would: use the tmux skill for terminal app environments and playwright-cli for web app environments.",
+            "For web app environments, capture a screenshot as a certificate of correct completion when the UI state proves the oracle; for terminal app environments, capture the terminal window/output that shows proof of correctness.",
             "Run or delegate focused validation when it is necessary to distinguish a real bug from a hunch.",
             "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.",
@@ -953,7 +865,7 @@ export default defineWorkflow("ralph")
             "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.",
             "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.",
+            "If no finding clears this bar and receipts prove the verification oracle, return an empty findings array, mark the patch correct, set goal_oracle_satisfied true, and set stop_review_loop true.",
           ].join("\n"),
         ],
         [
@@ -973,7 +885,7 @@ export default defineWorkflow("ralph")
           "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.",
+            "If no such findings exist, return an empty findings array and mark the patch correct only when receipt-backed evidence also satisfies the verification oracle.",
             "Do not stop after the first qualifying finding; continue until every qualifying finding is listed.",
           ].join("\n"),
         ],
@@ -982,6 +894,8 @@ export default defineWorkflow("ralph")
           [
             "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.",
+            "Treat this review as the completion audit for the current iteration: approval means receipts and current evidence prove the original owner outcome against the verification oracle.",
+            "Do not approve when proof only shows planning, discovery, task selection, helper documents, or a narrow slice while the broader requested outcome still has safe local work remaining.",
             "The tool call is the final verdict after review work, not a shortcut around review work.",
           ].join("\n"),
         ],
@@ -990,14 +904,18 @@ export default defineWorkflow("ralph")
           [
             "1. Identify the changed files or diff under review.",
             "2. Read the relevant changed code and directly affected call sites/tests/configs.",
-            "3. Run or delegate focused validation when needed to resolve uncertainty.",
-            "4. If you cannot inspect or validate enough to approve safely, populate reviewer_error and set stop_review_loop=false.",
+            "3. Read the implementation notes receipts and map them to the inferred verification oracle and original owner outcome.",
+            "4. Run or delegate focused validation when needed to resolve uncertainty.",
+            "5. Decide whether the receipt/evidence map proves completion; if evidence is uncertain, indirect, stale, missing, or narrower than the requested outcome, set goal_oracle_satisfied=false and stop_review_loop=false.",
+            "6. If you cannot inspect receipts 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.",
+            "The receipt_assessment should map concrete receipts, files, commands, artifacts, or reviewer checks back to the original owner outcome and verification oracle.",
+            "The verification_remaining field should say `none` only when no oracle-relevant verification remains.",
             "Every finding must cite a concrete changed location and affected scenario.",
           ].join("\n"),
         ],
@@ -1007,7 +925,7 @@ export default defineWorkflow("ralph")
             "You have a structured-output tool named review_decision. Use it after your investigation and validation attempts.",
             "The tool terminates the turn and provides the structured data; do not emit a separate final assistant response after calling it.",
             "The review loop decides whether to stop only by parsing the JSON object returned by this tool; invalid JSON, missing fields, reviewer_error, or stop_review_loop=false are treated as not approved for safety.",
-            "Set stop_review_loop=true only when findings is empty, overall_correctness is patch is correct, and reviewer_error is null/omitted.",
+            "Set stop_review_loop=true only when findings is empty, overall_correctness is patch is correct, goal_oracle_satisfied is true, verification_remaining is `none` or equivalent, and reviewer_error is null/omitted.",
             "If you hit a reviewer/tool/validation error, still return the object with stop_review_loop=false and reviewer_error populated instead of pretending the patch is approved.",
             "The JSON must match this schema exactly:",
             "{",
@@ -1026,6 +944,9 @@ export default defineWorkflow("ralph")
             '  "overall_correctness": "patch is correct" | "patch is incorrect",',
             '  "overall_explanation": "<1-3 sentence explanation justifying the verdict>",',
             '  "overall_confidence_score": <float 0.0-1.0>,',
+            '  "goal_oracle_satisfied": <boolean>,',
+            '  "receipt_assessment": "<how receipts/current evidence map to the verification oracle>",',
+            '  "verification_remaining": "<oracle-relevant verification still missing, or none>",',
             '  "stop_review_loop": <boolean>,',
             '  "reviewer_error": null | {"kind": "validation_unavailable" | "dependency_unavailable" | "tool_failure" | "reviewer_failure", "message": "<what failed>", "attempted_recovery": "<what you tried>"}',
             "}",
@@ -1040,11 +961,13 @@ export default defineWorkflow("ralph")
             {
               name: "reviewer-a",
               task: reviewPrompt,
+              reads: [goalContractPath, implementationNotesPath],
               ...reviewerModelConfig,
             },
             {
               name: "reviewer-b",
               task: reviewPrompt,
+              reads: [goalContractPath, implementationNotesPath],
               ...reviewerModelConfig,
             },
           ],
@@ -1078,9 +1001,12 @@ export default defineWorkflow("ralph")
             `Original task: ${prompt}`,
             `Review loop approved: ${approved ? "yes" : "no"}`,
             finalPlanPath
-              ? `Planner spec path: ${finalPlanPath}`
-              : "Planner spec path: unavailable",
+              ? `Planner goal contract path: ${finalPlanPath}`
+              : "Planner goal contract path: unavailable",
             `Implementation notes path: ${implementationNotesPath}`,
+            reviewReport
+              ? `Latest reviewer decisions:\n${reviewReport}`
+              : "Latest reviewer decisions: unavailable",
           ].join("\n"),
         ],
         [
@@ -1089,7 +1015,8 @@ export default defineWorkflow("ralph")
             "Start by inspecting `git status --short` so unstaged, staged, and untracked changes are all visible.",
             `Review the patch against \`${comparisonBaseBranch}\` with working-tree-aware commands such as \`git diff ${comparisonBaseBranch}\` and \`git diff --cached ${comparisonBaseBranch}\`.`,
             "If untracked files are present, inspect them directly before deciding whether they belong in the PR.",
-            "Read the implementation notes file and use its full contents as the body of a PR comment after the pull request exists.",
+            "Read the implementation notes file and latest structured reviewer decisions before deciding whether the PR is ready.",
+            "Use the implementation notes contents as the body of a PR comment after the pull request exists.",
             "Check the local Git identity with `git config user.name` and `git config user.email` so you can prefer the matching GitHub account when multiple accounts are logged in.",
             "Check whether GitHub credentials are available with non-destructive commands such as `gh auth status` and `gh auth status --show-token-scopes` before attempting PR creation.",
             "If multiple GitHub accounts or hosts are logged in, use the git config username/email as a heuristic to choose the most likely identity, but try each available credential/account and use the first one that can read the repository and create the PR.",
@@ -1100,7 +1027,7 @@ export default defineWorkflow("ralph")
           [
             "Create a PR only if there are meaningful changes, a remote/branch target is available, credentials are available, and the current state is suitable for review.",
             "If no logged-in account can access the repository or create the PR, do not fake success; report each credential/account tried, what failed, and provide the command the user can run later.",
-            "When you successfully create or update the PR, create a PR comment containing the implementation notes file contents as the last action of this workflow stage.",
+            "When you successfully create or update the PR, create a PR comment containing the implementation notes file contents and latest reviewer approval summary as the last action of this workflow stage.",
             "If PR creation is not possible, do not create a standalone comment elsewhere; include the implementation notes path and summary in your report instead.",
             "If the review loop did not approve, prefer reporting the remaining blockers over creating a PR unless the changes are still intentionally ready for human review.",
             "Do not make unrelated code edits in this phase. Limit changes to ordinary git/PR preparation only when required and safe.",
@@ -1112,7 +1039,7 @@ export default defineWorkflow("ralph")
             "Return Markdown with headings:",
             "1. Change review — summary of files and diff scope inspected",
             "2. PR status — created PR URL, or why no PR was created",
-            "3. Implementation notes comment — whether the PR comment was created as the last action, or why it could not be created",
+            "3. Implementation notes and reviewer approval comment — whether the PR comment was created as the last action, or why it could not be created",
             "4. Commands run — include exit status or clear outcome",
             "5. Follow-up for the user — exact next steps if credentials or repository state blocked PR creation",
           ].join("\n"),