@bastani/atomic 0.9.4 → 0.9.5-alpha.10

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

@@ -1,18 +1,67 @@
 import type { WorkflowTaskResult } from "../src/shared/types.js";
 import type { ReviewDecision, ReviewRecord } from "./goal-types.js";
+import {
+  finalActionRemaining,
+  parseFailureDiagnostics,
+  summarizeReviewConvergence,
+  traceabilityProvenExceptFinalAction,
+  type ParsedReviewDecision,
+} from "./review-convergence.js";
 
 export function reviewDecisionFromResult(result: WorkflowTaskResult): ReviewDecision | undefined {
   return result.structured as ReviewDecision | undefined;
 }
 
-export function reviewApproved(decision: ReviewDecision): boolean {
-  const hasBlockingFindings = decision.findings.some(
-    (finding) => finding.priority !== 3,
-  );
+export function parsedReviewDecisionFromResult(
+  result: WorkflowTaskResult,
+  reviewer: string,
+): ParsedReviewDecision<ReviewDecision> {
+  const parsed = reviewDecisionFromResult(result);
+  if (parsed !== undefined) {
+    return { decision: parsed, parsed: true, diagnostics: [] };
+  }
+  const diagnostics = parseFailureDiagnostics(reviewer, result.text);
+  return {
+    decision: reviewerErrorDecision(diagnostics.join("\n")),
+    parsed: false,
+    diagnostics,
+  };
+}
+
+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,
+  allowFinalActionRemaining: boolean,
+): boolean {
+  return traceabilityProvenExceptFinalAction({
+    traceability: decision.requirements_traceability,
+    allowFinalActionRemaining,
+  });
+}
+
+export function reviewApproved(
+  decision: ReviewDecision,
+  options: { readonly allowFinalActionRemaining?: boolean } = {},
+): boolean {
+  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, options.allowFinalActionRemaining === true) &&
     !hasBlockingFindings &&
     decision.reviewer_error == null
   );
@@ -26,6 +75,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.",
@@ -57,18 +107,43 @@ export function reviewDecisionToRecord(args: {
   readonly reviewer: string;
   readonly artifactPath: string;
   readonly decision: ReviewDecision;
+  readonly parsed: boolean;
+  readonly diagnostics: readonly string[];
+  readonly allowFinalActionRemaining: boolean;
 }): ReviewRecord {
   const blocker = blockerFromReviewDecision(args.decision);
-  const approved = reviewApproved(args.decision);
+  const approved = reviewApproved(args.decision, {
+    allowFinalActionRemaining: args.allowFinalActionRemaining,
+  });
+  const hasFinalActionRemaining = args.allowFinalActionRemaining &&
+    finalActionRemaining(args.decision.requirements_traceability);
   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
       ? []
       : [`${args.decision.reviewer_error.kind}: ${args.decision.reviewer_error.message}`]),
   ];
 
+  const nextAction = approved
+    ? hasFinalActionRemaining ? "pull-request" : "finish"
+    : blocker === null ? "implementation" : "blocked";
+  const convergenceDecision = summarizeReviewConvergence({
+    parsed: args.parsed,
+    approved,
+    stopReviewLoop: args.decision.stop_review_loop,
+    nextAction,
+    finalActionRemaining: approved && hasFinalActionRemaining,
+    diagnostics: args.diagnostics,
+  });
+
   return {
     ...args.decision,
     decision: approved ? "complete" : blocker === null ? "continue" : "blocked",
@@ -80,5 +155,9 @@ export function reviewDecisionToRecord(args: {
     turn: args.turn,
     reviewer: args.reviewer,
     artifact_path: args.artifactPath,
+    parsed: args.parsed,
+    approved,
+    parse_diagnostics: args.diagnostics,
+    convergence_decision: convergenceDecision,
   };
 }

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

@@ -8,8 +8,9 @@ import {
   type GoalWorkflowInputs,
   type GoalWorkflowOutputs,
   type ReviewRecord,
+  type ReducerDecision,
 } from "./goal-types.js";
-import { writeReviewArtifact, writeReviewRoundArtifact } from "./goal-artifacts.js";
+import { artifactSafeName, writeReviewArtifact, writeReviewRoundArtifact } from "./goal-artifacts.js";
 import { appendLifecycleEvent, createGoalLedger, writeGoalLedger } from "./goal-ledger.js";
 import {
   collectRemainingWork,
@@ -17,14 +18,13 @@ import {
 } from "./goal-reducer.js";
 import { formatReviewReport, renderFinalReport } from "./goal-reports.js";
 import {
-  reviewDecisionFromResult,
-  reviewerErrorDecision,
+  parsedReviewDecisionFromResult,
   reviewDecisionToRecord,
 } from "./goal-review.js";
+import { reviewerFailureText } from "./review-convergence.js";
 import {
   WORKER_PREFLIGHT_CONTRACT,
   WORKER_RECEIPT_CONTRACT,
-  goalRunnerTools,
   renderForkedGoalWorkerPrompt,
   renderGoalContinuationPrompt,
   renderReviewerPrompt,
@@ -76,6 +76,27 @@ type GoalWorkflowOptions = {
   readonly workflowStartCwd: string;
 };
 
+function reviewerExecutionFailedDecision(input: {
+  readonly turn: number;
+  readonly reviewQuorum: number;
+  readonly reviews: readonly ReviewRecord[];
+  readonly reason: string;
+}): ReducerDecision {
+  return {
+    turn: input.turn,
+    decision: "needs_human",
+    reason: input.reason,
+    complete_votes: input.reviews.filter((review) => review.decision === "complete").length,
+    review_quorum: input.reviewQuorum,
+    parsed: input.reviews.every((review) => review.parsed),
+    approved: false,
+    stopReviewLoop: false,
+    nextAction: "needs_human",
+    finalActionRemaining: false,
+    diagnostics: input.reviews.flatMap((review) => review.parse_diagnostics),
+  };
+}
+
 export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkflowOptions): Promise<GoalWorkflowOutputs> {
     const inputs = ctx.inputs;
     const createPr = options.createPr;
@@ -85,49 +106,72 @@ 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).
+    // Chains curated from Atomic's agentic-coding benchmark; see ralph-models.ts for frontier data and drop rationale.
     const workerModelConfig = {
-      model: "openai-codex/gpt-5.5:medium",
+      model: "openai-codex/gpt-5.6-sol:medium",
       fallbackModels: [
-          "github-copilot/gpt-5.5:medium",
-          "openai/gpt-5.5:medium",
-          "anthropic/claude-fable-5:low",
-          "github-copilot/claude-opus-4.8 (1m):medium",
-          "anthropic/claude-opus-4-8:medium",
-          "zai/glm-5.2:high",
-          "zai-coding-cn/glm-5.2:high",
-          "openrouter/openai/gpt-5.5:medium",
-          "openrouter/anthropic/claude-fable-5:low",
-          "openrouter/anthropic/claude-opus-4-8:medium",
-          "openrouter/z-ai/glm-5.2:xhigh"
+        "github-copilot/gpt-5.6-sol:medium",
+        "openai/gpt-5.6-sol:medium",
+        "openai-codex/gpt-5.5:medium",
+        "github-copilot/gpt-5.5:medium",
+        "openai/gpt-5.5:medium",
+        "anthropic/claude-fable-5:low",
+        "github-copilot/claude-opus-4.8 (1m):medium",
+        "anthropic/claude-opus-4-8:medium",
+        "cursor/gpt-5.6-sol:medium",
+        "cursor/gpt-5.5:medium",
+        "cursor/claude-fable-5:low",
+        "cursor/claude-opus-4-8-thinking:medium",
+        "cursor/grok-4.5",
+        "zai/glm-5.2:high",
+        "zai-coding-cn/glm-5.2:high",
+        "cursor/glm-5.2",
+        "openrouter/openai/gpt-5.6-sol:medium",
+        "openrouter/openai/gpt-5.5:medium",
+        "openrouter/anthropic/claude-fable-5:low",
+        "openrouter/anthropic/claude-opus-4-8:medium",
+        "openrouter/x-ai/grok-4.5",
+        "openrouter/z-ai/glm-5.2:xhigh"
       ],
-      tools: goalRunnerTools,
+      excludedTools: ["ask_user_question"],
     };
 
     const reviewerModelConfig = {
-      model: "anthropic/claude-fable-5:xhigh",
+      model: "anthropic/claude-fable-5:high",
       fallbackModels: [
-          "openai-codex/gpt-5.5:xhigh",
-          "github-copilot/gpt-5.5:xhigh",
-          "openai/gpt-5.5:xhigh",
-          "github-copilot/claude-opus-4.8 (1m):high",
-          "anthropic/claude-opus-4-8:high",
-          "zai/glm-5.2:xhigh",
-          "zai-coding-cn/glm-5.2:xhigh",
-          "openrouter/anthropic/claude-fable-5:xhigh",
-          "openrouter/openai/gpt-5.5:xhigh",
-          "openrouter/anthropic/claude-opus-4-8:high",
-          "openrouter/z-ai/glm-5.2:xhigh"
+        "openai-codex/gpt-5.6-sol:max",
+        "github-copilot/gpt-5.6-sol:max",
+        "openai/gpt-5.6-sol:max",
+        "openai-codex/gpt-5.5:xhigh",
+        "github-copilot/gpt-5.5:xhigh",
+        "openai/gpt-5.5:xhigh",
+        "github-copilot/claude-opus-4.8 (1m):high",
+        "anthropic/claude-opus-4-8:high",
+        "cursor/claude-fable-5:high",
+        "cursor/gpt-5.6-sol:max",
+        "cursor/gpt-5.5:high",
+        "cursor/claude-opus-4-8-thinking:high",
+        "cursor/grok-4.5",
+        "zai/glm-5.2:xhigh",
+        "zai-coding-cn/glm-5.2:xhigh",
+        "cursor/glm-5.2",
+        "openrouter/anthropic/claude-fable-5:high",
+        "openrouter/openai/gpt-5.6-sol:max",
+        "openrouter/sakana/fugu-ultra:high",
+        "openrouter/openai/gpt-5.5:xhigh",
+        "openrouter/anthropic/claude-opus-4-8:high",
+        "openrouter/x-ai/grok-4.5",
+        "openrouter/z-ai/glm-5.2:xhigh"
       ],
-      tools: goalRunnerTools,
+      excludedTools: ["ask_user_question"],
       schema: reviewDecisionSchema,
     };
 
@@ -191,6 +235,12 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
           reason: terminalRemainingWork,
           complete_votes: 0,
           review_quorum: reviewQuorum,
+          parsed: false,
+          approved: false,
+          stopReviewLoop: false,
+          nextAction: "needs_human",
+          finalActionRemaining: false,
+          diagnostics: [terminalRemainingWork],
         });
         appendLifecycleEvent(ledger, "status_decided", terminalRemainingWork, turn);
         await writeGoalLedger(ledgerPath, ledger);
@@ -223,6 +273,7 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
           comparisonBaseBranch,
           reviewQuorum,
           blockerThreshold,
+          createPr,
         }),
         reads: [ledgerPath, workTurnPath],
         ...reviewerModelConfig,
@@ -247,42 +298,48 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
       ];
 
       let reviewResults: WorkflowTaskResult[];
+      let reviewerBatchFailed = false;
       try {
         reviewResults = await ctx.parallel(reviewerSteps, {
           task: objective,
-          failFast: false,
+          failFast: true,
         });
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        const structured = reviewerErrorDecision(message);
+        reviewerBatchFailed = true;
         reviewResults = [
           {
             name: "reviewer-error",
             stageName: "reviewer-error",
-            text: JSON.stringify(structured, null, 2),
-            structured,
+            text: reviewerFailureText(err),
           },
         ];
       }
 
       latestReviews = await Promise.all(reviewResults.map(async (result) => {
         const reviewerName = result.name ?? result.stageName;
-        const parsed = reviewDecisionFromResult(result) ??
-          reviewerErrorDecision(
-            `Reviewer ${reviewerName} returned no structured decision.`,
-          );
-        const reviewArtifactPath = await writeReviewArtifact(
+        const normalizedReviewerName = reviewerName.replace(/-\d+$/u, "");
+        const parsed = parsedReviewDecisionFromResult(result, reviewerName);
+        const reviewArtifactPath = join(
           artifactDir,
-          reviewerName.replace(/-\d+$/u, ""),
-          parsed,
-          result.text,
+          `review-${artifactSafeName(normalizedReviewerName)}.json`,
         );
-        return reviewDecisionToRecord({
+        const record = reviewDecisionToRecord({
           turn,
-          reviewer: reviewerName.replace(/-\d+$/u, ""),
+          reviewer: normalizedReviewerName,
           artifactPath: reviewArtifactPath,
-          decision: parsed,
+          decision: parsed.decision,
+          parsed: parsed.parsed,
+          diagnostics: parsed.diagnostics,
+          allowFinalActionRemaining: createPr,
         });
+        await writeReviewArtifact(
+          artifactDir,
+          normalizedReviewerName,
+          parsed.decision,
+          result.text,
+          record.convergence_decision,
+        );
+        return record;
       }));
       latestReviewArtifactPaths = latestReviews.map((review) => review.artifact_path);
       latestReviewReportPath = await writeReviewRoundArtifact(
@@ -296,12 +353,27 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
         `Recorded ${latestReviews.length} reviewer decisions.`,
         turn,
       );
+      if (reviewerBatchFailed) {
+        terminalRemainingWork = collectRemainingWork(latestReviews);
+        const reason = `Reviewer execution failed before quorum could be established. Remaining work: ${terminalRemainingWork}`;
+        ledger.decisions.push(reviewerExecutionFailedDecision({
+          turn,
+          reviewQuorum,
+          reviews: latestReviews,
+          reason,
+        }));
+        ledger.status = "needs_human";
+        appendLifecycleEvent(ledger, "status_decided", reason, turn);
+        await writeGoalLedger(ledgerPath, ledger);
+        break;
+      }
 
       const reducerOutcome = reduceGoalDecision(ledger, latestReviews, {
         turn,
         maxTurns,
         reviewQuorum,
         blockerThreshold,
+        nextActionOnComplete: createPr ? "pull-request" : "finish",
       });
       if (reducerOutcome.blockerObservation !== undefined) {
         ledger.blockers.push(reducerOutcome.blockerObservation);
@@ -415,6 +487,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

@@ -1,3 +1,5 @@
+import type { ReviewConvergenceSummary } from "./review-convergence.js";
+
 export const DEFAULT_MAX_TURNS = 10;
 // Goal Runner runs three independent reviewer personas; two approvals form a majority.
 export const DEFAULT_REVIEW_QUORUM = 2;
@@ -14,10 +16,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 +59,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;
@@ -60,6 +76,10 @@ export type ReviewRecord = ReviewDecision & {
   readonly turn: number;
   readonly reviewer: string;
   readonly artifact_path: string;
+  readonly parsed: boolean;
+  readonly approved: boolean;
+  readonly parse_diagnostics: readonly string[];
+  readonly convergence_decision: ReviewConvergenceSummary;
 };
 
 export type BlockerObservation = {
@@ -68,7 +88,7 @@ export type BlockerObservation = {
   readonly reviewers: readonly string[];
 };
 
-export type ReducerDecision = {
+export type ReducerDecision = ReviewConvergenceSummary & {
   readonly turn: number;
   readonly decision: "complete" | "continue" | "blocked" | "needs_human";
   readonly reason: string;
@@ -93,6 +113,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,8 +133,10 @@ export type ReducerOutcome = {
 
 export type GoalWorkflowInputs = {
   readonly objective: string;
+  readonly acceptance_criteria?: string;
   readonly max_turns: number;
   readonly base_branch: string;
+  readonly git_worktree_dir: string;
   readonly create_pr: boolean;
 };
 
@@ -123,6 +146,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,15 +11,19 @@ export type GoalWorkflowReceipt = {
 
 export type GoalWorkflowInputs = WorkflowInputValues & {
   readonly objective: string;
+  readonly acceptance_criteria?: string;
   readonly max_turns: number;
   readonly base_branch: string;
+  readonly git_worktree_dir: string;
   readonly create_pr: boolean;
 };
 
 export type GoalWorkflowRunInputs = WorkflowInputValues & {
   readonly objective: string;
+  readonly acceptance_criteria?: string;
   readonly max_turns?: number;
   readonly base_branch?: string;
+  readonly git_worktree_dir?: string;
   readonly create_pr?: boolean;
 };
 
@@ -29,6 +33,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.",
@@ -24,6 +25,11 @@ export default workflow({
       default: "origin/main",
       description: "Optional branch reviewers compare the current code delta against (default origin/main).",
     }),
+    git_worktree_dir: Type.String({
+      default: "",
+      description:
+        "Optional Git worktree path. Must start inside a Git repo; absolute paths are used as-is, relative paths resolve from the repo root, existing Git worktrees from the invoking repository are reused/shared as-is, and missing paths are created from base_branch.",
+    }),
     create_pr: Type.Boolean({
       default: false,
       description:
@@ -39,6 +45,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." })),
@@ -53,6 +60,10 @@ export default workflow({
     review_report_path: Type.Optional(Type.String({ description: "JSON artifact path for the latest reviewer decision round." })),
     pr_report: Type.Optional(Type.String({ description: "Pull-request report emitted only when create_pr=true, Goal reaches complete, and the final pull-request stage runs." })),
   },
+  worktreeFromInputs: {
+    gitWorktreeDir: "git_worktree_dir",
+    baseBranch: "base_branch",
+  },
   run: async (ctx) => {
     const workflowCtx = ctx;
     const workflowStartCwd = workflowCtx.cwd ?? process.cwd();

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

@@ -37,14 +37,18 @@ export type GoalWorkflowReceipt = {
 };
 export type GoalWorkflowInputs = WorkflowInputValues & {
   readonly objective: string;
+  readonly acceptance_criteria?: string;
   readonly max_turns: number;
   readonly base_branch: string;
+  readonly git_worktree_dir: string;
   readonly create_pr: boolean;
 };
 export type GoalWorkflowRunInputs = WorkflowInputValues & {
   readonly objective: string;
+  readonly acceptance_criteria?: string;
   readonly max_turns?: number;
   readonly base_branch?: string;
+  readonly git_worktree_dir?: string;
   readonly create_pr?: boolean;
 };
 export type GoalWorkflowOutputs = WorkflowOutputValues & {
@@ -53,6 +57,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 +75,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 +83,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 +96,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;