@bastani/atomic 0.9.16-alpha.7 → 0.9.16-alpha.8

package/dist/builtin/workflows/builtin/chunk-zf28603f.js

@@ -0,0 +1,1080 @@
+import {
+  consolidateFindingsBatch,
+  convergence_escalation_evidence,
+  createWorkflowArtifactDirectory,
+  finalActionRemaining,
+  parseFailureDiagnostics,
+  record_convergence,
+  reverify_consolidated_batch,
+  reviewerFailureText,
+  summarizeReviewConvergence
+} from "./chunk-hdpj1dkw.js";
+import {
+  fold_usage
+} from "./chunk-7at6dnkr.js";
+import {
+  VERIFICATION_SCALE
+} from "./chunk-cg9tmks0.js";
+import {
+  workflow
+} from "./chunk-bfkmzv9h.js";
+import {
+  ACCEPTANCE_MATRIX_CONTRACT,
+  CODE_QUALITY_VERIFICATION_GUIDANCE,
+  CONTRACT_FIDELITY_AUDIT,
+  E2E_VERIFICATION_GUIDANCE,
+  EVIDENCE_CLOSURE_POLICY,
+  FINDINGS_CONSOLIDATION_CONTRACT,
+  LITERAL_OBJECTIVE_CONTRACT,
+  REGRESSION_EVIDENCE_CONTRACT,
+  REPO_INTENT_MINING_GUIDANCE,
+  REVIEWER_CALIBRATION_RULES,
+  REVIEWER_INDEPENDENT_VERIFICATION_CONTRACT,
+  REVIEWER_INTERCOM_COORDINATION_PROTOCOL,
+  REVIEWER_OVERIMPLEMENTATION_GUARD,
+  REVIEWER_SPEC_VS_OBJECTIVE_GUARD,
+  REVIEW_CODE_DELTA_CONTRACT,
+  SCOPE_DISCIPLINE_CONTRACT,
+  WORKER_PREFLIGHT_CONTRACT,
+  WORKTREE_DISCIPLINE_CONTRACT,
+  keepContext,
+  renderE2eQaVideoReviewGuidance,
+  withSteeringPropagationContext
+} from "./chunk-0x6e303p.js";
+
+// dist/builtin/workflows/builtin/ralph.ts
+import { Type as Type2 } from "typebox";
+
+// dist/builtin/workflows/builtin/ralph-core.ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { Type } from "typebox";
+// dist/builtin/workflows/builtin/ralph-review-gate.ts
+function reviewDecisionApproved(decision) {
+  return decision.stop_review_loop === true && decision.reviewer_error == null;
+}
+
+// dist/builtin/workflows/builtin/ralph-core.ts
+var DEFAULT_MAX_LOOPS = 10;
+var DEFAULT_RESEARCH_DIR = "research";
+var IMPLEMENTATION_NOTES_FILENAME = "implementation-notes.md";
+var QA_E2E_VIDEO_FILENAME = "qa-e2e-evidence.webm";
+var MAX_RESEARCH_SLUG_LENGTH = 80;
+var REVIEWER_COUNT = 2;
+var 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()])),
+  code_location: Type.Object({
+    absolute_file_path: Type.String(),
+    line_range: Type.Object({
+      start: Type.Integer({ minimum: 1 }),
+      end: Type.Integer({ minimum: 1 })
+    }, { additionalProperties: false })
+  }, { additionalProperties: false })
+}, { additionalProperties: false });
+var 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 });
+var reviewerErrorSchema = Type.Object({
+  kind: Type.Union([
+    Type.Literal("validation_unavailable"),
+    Type.Literal("dependency_unavailable"),
+    Type.Literal("tool_failure"),
+    Type.Literal("reviewer_failure")
+  ]),
+  message: Type.String(),
+  attempted_recovery: Type.String()
+}, { additionalProperties: false });
+var reviewDecisionSchema = Type.Object({
+  findings: Type.Array(reviewFindingSchema),
+  overall_correctness: Type.Union([
+    Type.Literal("patch is correct"),
+    Type.Literal("patch is incorrect")
+  ]),
+  overall_explanation: Type.String(),
+  overall_confidence_score: Type.Number({ minimum: 0, maximum: 1 }),
+  criterion_scores: Type.Optional(Type.Array(Type.Object({
+    criterion_id: Type.String(),
+    score: VERIFICATION_SCALE.schema
+  }, { additionalProperties: false }))),
+  requirements_traceability: Type.Array(requirementsTraceabilitySchema),
+  stop_review_loop: Type.Boolean(),
+  reviewer_error: Type.Optional(Type.Union([Type.Null(), reviewerErrorSchema]))
+}, { additionalProperties: false });
+function taggedPrompt(sections) {
+  return sections.map(([tag, content]) => {
+    const trimmed = content.trim();
+    return `<${tag}>
+${trimmed}
+</${tag}>`;
+  }).join(`
+
+`);
+}
+function workflowCwdContextSection(workflowCwd) {
+  return [
+    "context",
+    [
+      `Current working directory: ${workflowCwd}`,
+      "Use this as the starting directory for repository work in this stage.",
+      "Shell commands and relative file paths should be relative to this directory unless you intentionally pass an explicit cwd override.",
+      "When delegating subagents, pass along that this is the current working directory."
+    ].join(`
+`)
+  ];
+}
+function positiveInteger(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+function normalizeBranchInput(value, fallback) {
+  const trimmed = value?.trim();
+  if (!trimmed)
+    return fallback;
+  const looksLikeSafeGitRef = /^(?!-)(?!.*(?:\.\.|@\{|\/\/|\.lock(?:\/|$)))[A-Za-z0-9][A-Za-z0-9._/@+-]*$/.test(trimmed);
+  return looksLikeSafeGitRef ? trimmed : fallback;
+}
+function slugifyResearchTopic(prompt) {
+  const slug = prompt.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, MAX_RESEARCH_SLUG_LENGTH).replace(/-+$/g, "");
+  return slug.length > 0 ? slug : "research";
+}
+function defaultResearchPath(prompt, now = new Date) {
+  const date = now.toISOString().slice(0, 10);
+  return join(DEFAULT_RESEARCH_DIR, `${date}-${slugifyResearchTopic(prompt)}.md`);
+}
+async function createImplementationNotesFile(prompt, runId) {
+  const notesDir = await createWorkflowArtifactDirectory(runId);
+  const notesPath = join(notesDir, IMPLEMENTATION_NOTES_FILENAME);
+  const initialNotes = [
+    "# Implementation Notes",
+    "",
+    `Task: ${prompt || "(empty prompt)"}`,
+    "",
+    "## Running Notes",
+    "",
+    "- Record implementation decisions, deviations from research, tradeoffs, blockers, validation outcomes, and user-relevant facts. Keep entries concise and readable.",
+    "- Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified."
+  ].join(`
+`);
+  await writeFile(notesPath, `${initialNotes}
+`, {
+    encoding: "utf8",
+    flag: "wx"
+  });
+  return notesPath;
+}
+async function createQaEvidenceVideoPath(runId) {
+  const qaDir = await createWorkflowArtifactDirectory(runId);
+  return join(qaDir, QA_E2E_VIDEO_FILENAME);
+}
+function renderQaE2eVideoGuidance(qaVideoPath) {
+  return [
+    E2E_VERIFICATION_GUIDANCE,
+    `For a user-visible UI scenario, record the QA pass for review. After \`playwright-cli open\`, use \`playwright-cli video-start ${qaVideoPath}\`, annotate with \`playwright-cli video-chapter\` / \`playwright-cli video-show-actions\`, exercise the complete scenario, then run \`playwright-cli video-stop\`. Write to exactly ${qaVideoPath}, overwriting stale evidence.`,
+    `Add a \`## QA E2E Video\` entry to the implementation notes with the absolute path ${qaVideoPath} and one sentence naming the proven scenario. For changes without a user-visible UI scenario, record why video does not apply; never fabricate one.`,
+    "If `playwright-cli` or its browser runtime is unavailable, install it once per the skill (`npm install -g @playwright/cli@latest`, then `npx playwright install chromium` when needed). If a concrete attempt still fails, record the commands, observed failure output, smallest validation performed, and that no video was produced."
+  ].join(`
+`);
+}
+function reviewDecisionFromResult(result) {
+  return result.structured;
+}
+function parsedReviewDecisionFromResult(result, reviewer) {
+  const parsed = reviewDecisionFromResult(result);
+  if (parsed !== undefined) {
+    return { decision: parsed, parsed: true, diagnostics: [] };
+  }
+  const diagnostics = parseFailureDiagnostics(reviewer, result.text);
+  return {
+    decision: reviewerErrorDecision(diagnostics.join(`
+`)),
+    parsed: false,
+    diagnostics
+  };
+}
+function ralphReviewConvergence(args) {
+  const approved = reviewDecisionApproved(args.decision);
+  const hasFinalActionRemaining = args.allowFinalActionRemaining && finalActionRemaining(args.decision.requirements_traceability);
+  return summarizeReviewConvergence({
+    parsed: args.parsed,
+    approved,
+    stopReviewLoop: args.decision.stop_review_loop,
+    nextAction: approved && hasFinalActionRemaining ? "pull-request" : approved ? "finish" : "implementation",
+    finalActionRemaining: approved && hasFinalActionRemaining,
+    diagnostics: args.diagnostics
+  });
+}
+function reviewerErrorDecision(error) {
+  return {
+    findings: [],
+    overall_correctness: "patch is incorrect",
+    overall_explanation: "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,
+      attempted_recovery: "Model fallbacks were configured for the reviewer stage; continuing without approval."
+    }
+  };
+}
+function reviewerErrorResult(error) {
+  return {
+    name: "reviewer-error",
+    stageName: "reviewer-error",
+    text: reviewerFailureText(error)
+  };
+}
+function artifactSafeName(value) {
+  const safe = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return safe.length > 0 ? safe : "artifact";
+}
+async function writeJsonArtifact(path, content) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(content, null, 2)}
+`, {
+    encoding: "utf8"
+  });
+  return path;
+}
+function compactReviewReport(path) {
+  return path === undefined ? "No reviewer artifact was produced." : `Latest review round artifact: ${path}`;
+}
+function forkContinuationOptions(sessionFile) {
+  return sessionFile === undefined || sessionFile.length === 0 ? {} : { context: "fork", forkFromSessionFile: sessionFile };
+}
+function renderResearchPromptRefinementPrompt(args) {
+  return taggedPrompt([
+    ["acceptance_criteria", keepContext(args.acceptanceCriteria)],
+    ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
+    args.workflowCwdContext,
+    [
+      "review_findings",
+      args.latestReviewReportPath === undefined ? "No prior review artifact is available." : [
+        `Latest review round artifact: ${args.latestReviewReportPath}`,
+        "Include unresolved reviewer findings in the transformed research question only when consistent with the literal objective and acceptance criteria."
+      ].join(`
+`)
+    ],
+    ["objective", `Research the full requested task: ${args.request}`],
+    [
+      "output",
+      keepContext("Return only one concise, complete codebase and online research question. Do not implement code changes or write an RFC/spec.")
+    ],
+    [
+      "instruction",
+      `/skill:prompt-engineer Transform this request into a codebase and online research question that covers the full requested task: ${args.request}`
+    ]
+  ]);
+}
+function renderResearchPrompt(args) {
+  return taggedPrompt([
+    ["acceptance_criteria", keepContext(args.acceptanceCriteria)],
+    ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
+    args.workflowCwdContext,
+    [
+      "review_findings",
+      args.latestReviewReportPath === undefined ? "No prior review artifact is available." : [
+        `Latest review round artifact: ${args.latestReviewReportPath}`,
+        "Research whether each unresolved finding still applies and what objective-aligned implementation change would resolve it."
+      ].join(`
+`)
+    ],
+    ["objective", `Research implementation requirements for: ${args.prompt}`],
+    [
+      "research_artifact",
+      [
+        "Return the complete research report as your final message. Downstream implementation and review stages read it from there.",
+        "Produce a complete Markdown report with codebase and useful online/contextual findings, implementation guidance, relevant files/tests/docs, unresolved-finding analysis, and validation recommendations. Lead with conclusions; keep facts, caveats, and implementation-relevant next steps; drop background and repetition.",
+        "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.",
+        keepContext("This stage researches only. Do not author an RFC/spec or implement code changes.")
+      ].join(`
+`)
+    ],
+    [
+      "instruction",
+      `/skill:research-codebase ${args.transformedResearchQuestion}`
+    ]
+  ]);
+}
+
+// dist/builtin/workflows/builtin/ralph-runner.ts
+import { existsSync } from "node:fs";
+import { join as join2, resolve } from "node:path";
+
+// dist/builtin/workflows/builtin/ralph-reviewer-prompt.ts
+function renderRalphReviewerPrompt(args) {
+  return taggedPrompt([
+    ["acceptance_criteria", keepContext(args.acceptanceCriteria)],
+    [
+      "review_context",
+      [
+        `Task: ${args.workflowPrompt}`,
+        `Research artifact: ${args.researchPath}`,
+        `Implementation notes artifact: ${args.implementationNotesPath}`,
+        `Orchestrator report artifact: ${args.orchestratorReportPath}`,
+        `Comparison baseline: ${args.comparisonBaseBranch}`
+      ].join(`
+`)
+    ],
+    args.workflowCwdContext,
+    ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
+    ["acceptance_matrix", ACCEPTANCE_MATRIX_CONTRACT],
+    ["independent_verification", REVIEWER_INDEPENDENT_VERIFICATION_CONTRACT],
+    ["calibration", REVIEWER_CALIBRATION_RULES],
+    ["code_delta_review", REVIEW_CODE_DELTA_CONTRACT],
+    ["worktree_discipline", WORKTREE_DISCIPLINE_CONTRACT],
+    ["reviewer_coordination", REVIEWER_INTERCOM_COORDINATION_PROTOCOL],
+    ["regression_evidence", REGRESSION_EVIDENCE_CONTRACT],
+    ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
+    ["code_quality_verification", CODE_QUALITY_VERIFICATION_GUIDANCE],
+    ["repository_intent", REPO_INTENT_MINING_GUIDANCE],
+    ["qa_e2e_video_review", renderE2eQaVideoReviewGuidance(args.qaVideoPath)],
+    ["evidence_closure", EVIDENCE_CLOSURE_POLICY],
+    [
+      "project_guidance",
+      [
+        "Use repository AGENTS.md and/or CLAUDE.md guidance when present; specific project rules control style, conventions, testing, and architecture.",
+        "Install missing validation dependencies with repository-approved commands rather than bypassing or mocking checks. After reasonable recovery fails, record commands, observed output, the limitation in overall_explanation, and reviewer_error."
+      ].join(`
+`)
+    ],
+    [
+      "final_action_policy",
+      args.createPr ? "PR/MR/review creation is an authorized post-approval final action. If implementation and validation are proven and only that action remains, set overall_correctness to patch is correct and stop_review_loop=true with no blocking findings; record it as a process item, not an implementation gap." : "PR/MR/review creation is not enabled; do not require or attempt it during review."
+    ],
+    [
+      "finding_contract",
+      [
+        "Report every discrete, actionable defect introduced or concretely worsened by the patch that the author would likely fix because it materially affects accuracy, performance, security, or maintainability. Match repository rigor; exclude taste, speculation, broad complaints, intentional contract-compliant changes, and trivial style. Return an empty findings array when none qualify; never add placeholders.",
+        REVIEWER_SPEC_VS_OBJECTIVE_GUARD,
+        REVIEWER_OVERIMPLEMENTATION_GUARD,
+        "Each title starts with [P0], [P1], [P2], or [P3] and includes numeric priority 0, 1, 2, or 3 respectively; use null only when genuinely indeterminate. P0/P1/P2 block. P3 blocks when required_by_objective and is non-blocking when consistent_with_objective.",
+        "Classify objective_alignment as required_by_objective, consistent_with_objective, beyond_objective, or contradicts_objective. Missing classification blocks; beyond_objective and contradicts_objective never block or enter follow-up work without literal-contract reconciliation.",
+        "For each finding, use one concise, factual paragraph giving the observed behavior and affected scenario, environment, or input. Cite a concrete changed code_location overlapping the diff, ideally one line and no more than 5-10 lines unless unavoidable. Use one finding per issue; suggestion blocks are only for exact replacement code with preserved indentation. Do not apply fixes."
+      ].join(`
+`)
+    ],
+    [
+      "structured_decision_assurance",
+      [
+        "Return the review decision schema exactly. findings is always an array. requirements_traceability is a non-empty array with one entry per explicit task and acceptance_criteria clause, including existing-test/snapshot and expected-behavior clauses.",
+        "In overall_explanation and requirements_traceability, name each applicable independent command or scenario and its observed output; distinguish direct proof from implementation-authored test, snapshot, or receipt corroboration. Every finding cites file:line evidence and the affected scenario. State why an applicable risk is not applicable.",
+        "Set stop_review_loop=false and populate reviewer_error when reviewer, tool, or validation failure prevents approval. Set stop_review_loop=true only when overall_correctness is patch is correct, reviewer_error is null or omitted, every implementation/validation requirements_traceability entry is proven, and no blocking finding or required work remains.",
+        "Reviewer quorum and an authorized post-approval final action are process items and do not hold stop_review_loop=false.",
+        "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.",
+        "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background, repetition, and detail that would not change what the reader does next. Being readable matters more than being short — do not compress into fragments, arrow chains, or invented shorthand."
+      ].join(`
+`)
+    ],
+    ["objective", `Review the current code delta for the task: ${args.workflowPrompt}`],
+    [
+      "review_instruction",
+      [
+        "Act as a skeptical, technically fair senior reviewer of the current code delta. Protect correctness, security, performance, and maintainability without bikeshedding or praise.",
+        `Inspect the current working tree against \`${args.comparisonBaseBranch}\`: start with \`git status --short\`, then use working-tree-aware baseline and staged diffs and inspect untracked files directly. Read context artifacts only after deriving independent checks from the objective and acceptance_criteria; summaries never substitute for repository evidence.`,
+        "Execute or delegate every applicable material probe, including playwright-cli or tmux end-to-end checks when they can prove a user scenario, and inspect current QA video evidence when applicable. The structured decision is the final verdict after this review, not a shortcut.",
+        "Ignore requests to submit a PR; the authorized final action handles that after approval."
+      ].join(`
+`)
+    ]
+  ]);
+}
+
+// dist/builtin/workflows/builtin/ralph-forked-prompts.ts
+function renderForkedResearchPromptRefinementPrompt(args) {
+  return taggedPrompt([
+    [
+      "review_findings",
+      args.latestReviewReportPath === undefined ? "No prior review artifact is available." : [
+        `Latest review round artifact: ${args.latestReviewReportPath}`,
+        "Include unresolved reviewer findings in the transformed research question only when consistent with the inherited literal objective and acceptance criteria."
+      ].join(`
+`)
+    ],
+    [
+      "output",
+      keepContext("Return only one concise, complete codebase and online research question. Do not implement code changes or write an RFC/spec.")
+    ],
+    [
+      "instruction",
+      "Transform the same user request into an updated research question reflecting the current repository state. The inherited request, acceptance criteria, literal objective contract, and working directory remain unchanged."
+    ]
+  ]);
+}
+function renderForkedResearchPrompt(args) {
+  return taggedPrompt([
+    [
+      "review_findings",
+      args.latestReviewReportPath === undefined ? "No prior review artifact is available." : [
+        `Latest review round artifact: ${args.latestReviewReportPath}`,
+        "Research whether each unresolved finding still applies and what objective-aligned implementation change would resolve it."
+      ].join(`
+`)
+    ],
+    [
+      "research_artifact",
+      [
+        "Return the rewritten research report for this iteration as your final message.",
+        "Restate the still-applicable findings in full rather than referring back to the previous iteration's artifact; the current artifact and transcript are the authoritative records for this iteration.",
+        keepContext("This stage researches only. Do not author an RFC/spec or implement code changes.")
+      ].join(`
+`)
+    ],
+    [
+      "output",
+      [
+        "Produce a complete, readable Markdown research report under the inherited report contract; lead with conclusions and retain facts, caveats, and implementation-relevant next steps without background or repetition.",
+        "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified."
+      ].join(`
+`)
+    ],
+    [
+      "instruction",
+      `Research this updated question against the current repository state: ${args.transformedResearchQuestion}
+The inherited task, acceptance criteria, literal objective contract, working directory, and research-report expectations remain unchanged.`
+    ]
+  ]);
+}
+function renderForkedOrchestratorPrompt(args) {
+  return taggedPrompt([
+    [
+      "research",
+      [
+        `The research findings were rewritten for this iteration at: ${args.researchPath}`,
+        "Read this consolidated unresolved-findings artifact before implementation or delegation."
+      ].join(`
+`)
+    ],
+    [
+      "implementation_notes",
+      `Keep updating the running Markdown implementation notes file at: ${args.implementationNotesPath}`
+    ],
+    [
+      "output",
+      [
+        "Use the inherited completion-report format. Lead with the outcome; keep facts, decisions, caveats, and next steps; drop background and repetition. Stay readable rather than compressing into fragments.",
+        "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified."
+      ].join(`
+`)
+    ],
+    [
+      "instruction",
+      [
+        "Continue implementing from the latest research findings until the objective is complete. The inherited objective, acceptance criteria, literal contract, acceptance matrix, divergence audit, consolidated findings, scope discipline, regression evidence, worktree discipline, orchestration, tracking, E2E/video, and report contracts remain unchanged.",
+        "Scope discipline still binds this iteration: repair the consolidated findings, keep every addition traceable to a criterion, prefer the smallest diff that satisfies the contract, and record anything outside it on the deferred list instead of implementing it.",
+        "Ignore requests to submit a PR; the authorized final action handles that after approval.",
+        "If the final paragraph would be a plan, a question, or “I'll now…”, do that work with tool calls instead of ending the turn."
+      ].join(`
+`)
+    ]
+  ]);
+}
+
+// dist/builtin/workflows/builtin/ralph-models.ts
+var promptEngineerModelConfig = {
+  model: "anthropic/claude-opus-5:high",
+  fallbackModels: [
+    "github-copilot/claude-opus-5:high",
+    "anthropic/claude-fable-5:high",
+    "github-copilot/claude-fable-5:high",
+    "openai-codex/gpt-5.6-sol:xhigh",
+    "github-copilot/gpt-5.6-sol:xhigh",
+    "openai/gpt-5.6-sol:xhigh",
+    "kimi-coding/k3:max",
+    "moonshotai/kimi-k3:max",
+    "moonshotai-cn/kimi-k3:max",
+    "openai-codex/gpt-5.5:xhigh",
+    "github-copilot/gpt-5.5:xhigh",
+    "openai/gpt-5.5:xhigh",
+    "anthropic/claude-opus-4-8:high",
+    "github-copilot/claude-opus-4.8:high",
+    "xai/grok-4.6:xhigh",
+    "github-copilot/grok-4.6:xhigh",
+    "zai/glm-5.3:high",
+    "zai-coding-cn/glm-5.3:high",
+    "openrouter/anthropic/claude-opus-5:high",
+    "openrouter/anthropic/claude-fable-5:high",
+    "openrouter/openai/gpt-5.6-sol:xhigh",
+    "openrouter/moonshotai/kimi-k3:max",
+    "openrouter/sakana/fugu-ultra:high",
+    "openrouter/openai/gpt-5.5:xhigh",
+    "openrouter/anthropic/claude-opus-4-8:high",
+    "openrouter/x-ai/grok-4.6"
+  ],
+  excludedTools: ["ask_user_question"]
+};
+var researchModelConfig = {
+  model: "anthropic/claude-opus-5:high",
+  fallbackModels: [
+    "github-copilot/claude-opus-5:high",
+    "openai-codex/gpt-5.6-sol:xhigh",
+    "github-copilot/gpt-5.6-sol:xhigh",
+    "openai/gpt-5.6-sol:xhigh",
+    "anthropic/claude-fable-5:high",
+    "github-copilot/claude-fable-5:high",
+    "kimi-coding/k3:max",
+    "moonshotai/kimi-k3:max",
+    "moonshotai-cn/kimi-k3:max",
+    "openai-codex/gpt-5.5:xhigh",
+    "github-copilot/gpt-5.5:xhigh",
+    "openai/gpt-5.5:xhigh",
+    "anthropic/claude-opus-4-8:high",
+    "github-copilot/claude-opus-4.8:high",
+    "xai/grok-4.6:xhigh",
+    "github-copilot/grok-4.6:xhigh",
+    "zai/glm-5.3:high",
+    "zai-coding-cn/glm-5.3:high",
+    "openrouter/anthropic/claude-opus-5:high",
+    "openrouter/openai/gpt-5.6-sol:xhigh",
+    "openrouter/anthropic/claude-fable-5:high",
+    "openrouter/moonshotai/kimi-k3:max",
+    "openrouter/sakana/fugu-ultra:high",
+    "openrouter/openai/gpt-5.5:xhigh",
+    "openrouter/anthropic/claude-opus-4-8:high",
+    "openrouter/x-ai/grok-4.6"
+  ],
+  excludedTools: ["ask_user_question"]
+};
+var orchestratorModelConfig = {
+  model: "anthropic/claude-opus-5:high",
+  fallbackModels: [
+    "github-copilot/claude-opus-5:high",
+    "openai-codex/gpt-5.6-sol:xhigh",
+    "github-copilot/gpt-5.6-sol:xhigh",
+    "openai/gpt-5.6-sol:xhigh",
+    "anthropic/claude-fable-5:high",
+    "github-copilot/claude-fable-5:high",
+    "kimi-coding/k3:max",
+    "moonshotai/kimi-k3:max",
+    "moonshotai-cn/kimi-k3:max",
+    "openai-codex/gpt-5.5:xhigh",
+    "github-copilot/gpt-5.5:xhigh",
+    "openai/gpt-5.5:xhigh",
+    "anthropic/claude-opus-4-8:high",
+    "github-copilot/claude-opus-4.8:high",
+    "xai/grok-4.6:xhigh",
+    "github-copilot/grok-4.6:xhigh",
+    "zai/glm-5.3:high",
+    "zai-coding-cn/glm-5.3:high",
+    "openrouter/anthropic/claude-opus-5:high",
+    "openrouter/openai/gpt-5.6-sol:xhigh",
+    "openrouter/anthropic/claude-fable-5:high",
+    "openrouter/moonshotai/kimi-k3:max",
+    "openrouter/sakana/fugu-ultra:high",
+    "openrouter/openai/gpt-5.5:xhigh",
+    "openrouter/anthropic/claude-opus-4-8:high",
+    "openrouter/x-ai/grok-4.6"
+  ],
+  excludedTools: ["ask_user_question"]
+};
+var reviewerAModelConfig = {
+  model: "anthropic/claude-opus-5:high",
+  fallbackModels: [
+    "github-copilot/claude-opus-5:high",
+    "anthropic/claude-fable-5:high",
+    "github-copilot/claude-fable-5:high",
+    "kimi-coding/k3:max",
+    "moonshotai/kimi-k3:max",
+    "moonshotai-cn/kimi-k3:max",
+    "openai-codex/gpt-5.6-sol:xhigh",
+    "github-copilot/gpt-5.6-sol:xhigh",
+    "openai/gpt-5.6-sol:xhigh",
+    "openai-codex/gpt-5.5:xhigh",
+    "github-copilot/gpt-5.5:xhigh",
+    "openai/gpt-5.5:xhigh",
+    "anthropic/claude-opus-4-8:high",
+    "github-copilot/claude-opus-4.8:high",
+    "xai/grok-4.6:xhigh",
+    "github-copilot/grok-4.6:xhigh",
+    "zai/glm-5.3:high",
+    "zai-coding-cn/glm-5.3:high",
+    "openrouter/anthropic/claude-opus-5:high",
+    "openrouter/anthropic/claude-fable-5:high",
+    "openrouter/moonshotai/kimi-k3:max",
+    "openrouter/openai/gpt-5.6-sol:xhigh",
+    "openrouter/sakana/fugu-ultra:high",
+    "openrouter/openai/gpt-5.5:xhigh",
+    "openrouter/anthropic/claude-opus-4-8:high",
+    "openrouter/x-ai/grok-4.6"
+  ],
+  excludedTools: ["ask_user_question"],
+  schema: reviewDecisionSchema
+};
+var reviewerBModelConfig = {
+  model: "openai-codex/gpt-5.6-sol:xhigh",
+  fallbackModels: [
+    "github-copilot/gpt-5.6-sol:xhigh",
+    "openai/gpt-5.6-sol:xhigh",
+    "anthropic/claude-opus-5:high",
+    "github-copilot/claude-opus-5:high",
+    "anthropic/claude-fable-5:high",
+    "github-copilot/claude-fable-5:high",
+    "kimi-coding/k3:max",
+    "moonshotai/kimi-k3:max",
+    "moonshotai-cn/kimi-k3:max",
+    "openai-codex/gpt-5.5:xhigh",
+    "github-copilot/gpt-5.5:xhigh",
+    "openai/gpt-5.5:xhigh",
+    "anthropic/claude-opus-4-8:high",
+    "github-copilot/claude-opus-4.8:high",
+    "xai/grok-4.6:xhigh",
+    "github-copilot/grok-4.6:xhigh",
+    "zai/glm-5.3:high",
+    "zai-coding-cn/glm-5.3:high",
+    "openrouter/openai/gpt-5.6-sol:xhigh",
+    "openrouter/anthropic/claude-opus-5:high",
+    "openrouter/anthropic/claude-fable-5:high",
+    "openrouter/moonshotai/kimi-k3:max",
+    "openrouter/openai/gpt-5.5:xhigh",
+    "openrouter/sakana/fugu-ultra:high",
+    "openrouter/anthropic/claude-opus-4-8:high",
+    "openrouter/x-ai/grok-4.6"
+  ],
+  excludedTools: ["ask_user_question"],
+  schema: reviewDecisionSchema
+};
+
+// dist/builtin/workflows/builtin/ralph-runner.ts
+async function runRalphWorkflow(ctx, options) {
+  const { prompt, acceptanceCriteria, maxLoops, comparisonBaseBranch, workflowStartCwd, createPr, runId } = options;
+  let latestReviewReportPath;
+  let finalPlan = "";
+  let finalPlanPath = "";
+  let finalResearch = "";
+  let finalResearchPath = "";
+  let finalResult = "";
+  let finalPrReport;
+  const workflowCwdContext = workflowCwdContextSection(workflowStartCwd);
+  const workflowPrompt = prompt;
+  const workflowResearchPath = resolve(workflowStartCwd, defaultResearchPath(workflowPrompt));
+  const implementationNotesPath = await createImplementationNotesFile(workflowPrompt, runId);
+  const qaVideoPath = await createQaEvidenceVideoPath(runId);
+  const artifactDir = await createWorkflowArtifactDirectory(runId);
+  let approved = false;
+  let iterationsCompleted = 0;
+  let previousResearchPromptRefinementSessionFile;
+  const convergenceEntries = [];
+  let previousResearchSessionFile;
+  let previousOrchestratorSessionFile;
+  for (let iteration = 1;iteration <= maxLoops; iteration += 1) {
+    iterationsCompleted = iteration;
+    const researchPromptRefinementForkOptions = forkContinuationOptions(previousResearchPromptRefinementSessionFile);
+    const researchPromptRefinement = await ctx.task(`research-prompt-refinement-${iteration}`, {
+      prompt: researchPromptRefinementForkOptions.forkFromSessionFile === undefined ? renderResearchPromptRefinementPrompt({
+        request: workflowPrompt,
+        acceptanceCriteria,
+        workflowCwdContext,
+        latestReviewReportPath
+      }) : renderForkedResearchPromptRefinementPrompt({ latestReviewReportPath }),
+      reads: latestReviewReportPath === undefined ? [] : [latestReviewReportPath],
+      ...promptEngineerModelConfig,
+      ...researchPromptRefinementForkOptions
+    });
+    previousResearchPromptRefinementSessionFile = researchPromptRefinement.sessionFile;
+    finalPlan = researchPromptRefinement.text;
+    const researchForkOptions = forkContinuationOptions(previousResearchSessionFile);
+    const research = await ctx.task(`research-${iteration}`, {
+      prompt: researchForkOptions.forkFromSessionFile === undefined ? renderResearchPrompt({
+        transformedResearchQuestion: researchPromptRefinement.text,
+        prompt: workflowPrompt,
+        acceptanceCriteria,
+        workflowCwdContext,
+        latestReviewReportPath
+      }) : renderForkedResearchPrompt({
+        transformedResearchQuestion: researchPromptRefinement.text,
+        latestReviewReportPath
+      }),
+      reads: latestReviewReportPath === undefined ? [] : [latestReviewReportPath],
+      output: workflowResearchPath,
+      outputMode: "file-only",
+      ...researchModelConfig,
+      ...researchForkOptions
+    });
+    previousResearchSessionFile = research.sessionFile;
+    finalResearch = research.text || `Research artifact: ${workflowResearchPath}`;
+    const researchPath = workflowResearchPath;
+    finalResearchPath = researchPath;
+    finalPlanPath = researchPath;
+    const orchestratorReportPath = join2(artifactDir, "orchestrator-report.md");
+    const orchestratorForkOptions = forkContinuationOptions(previousOrchestratorSessionFile);
+    const orchestratorPrompt = orchestratorForkOptions.forkFromSessionFile === undefined ? taggedPrompt([
+      ["acceptance_criteria", keepContext(acceptanceCriteria)],
+      ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
+      ["acceptance_matrix", ACCEPTANCE_MATRIX_CONTRACT],
+      ["divergence_audit", CONTRACT_FIDELITY_AUDIT],
+      ["findings_batch", FINDINGS_CONSOLIDATION_CONTRACT],
+      ["scope_discipline", SCOPE_DISCIPLINE_CONTRACT],
+      ["regression_evidence", REGRESSION_EVIDENCE_CONTRACT],
+      workflowCwdContext,
+      [
+        "research",
+        `Latest research artifact: ${researchPath}
+Read it before implementation or delegation because it is the primary current implementation context.`
+      ],
+      [
+        "implementation_notes",
+        [
+          `Keep the initialized Markdown implementation notes current at: ${implementationNotesPath}`,
+          "Record implementation decisions, research deviations, tradeoffs, blockers, validation outcomes, and user-relevant facts; collect noteworthy delegated decisions. Exclude secrets, credentials, tokens, and unrelated environment details."
+        ].join(`
+`)
+      ],
+      ["project_setup", WORKER_PREFLIGHT_CONTRACT],
+      ["worktree_discipline", WORKTREE_DISCIPLINE_CONTRACT],
+      ["qa_e2e_video", renderQaE2eVideoGuidance(qaVideoPath)],
+      ["code_quality_verification", CODE_QUALITY_VERIFICATION_GUIDANCE],
+      ["repository_intent", REPO_INTENT_MINING_GUIDANCE],
+      [
+        "delegation",
+        [
+          "Delegate only work that is genuinely independent and too large to finish in a handful of tool calls. Do not use subagents to audit your own work. Prefer one subagent over several.",
+          "For delegated work, provide the relevant task, constraints, files, validation expectations, unresolved findings, and implementation-note reporting needs. Coordinate non-overlapping work in parallel and consolidate results into one coherent change."
+        ].join(`
+`)
+      ],
+      [
+        "tracking",
+        "Use the `todo` tool as the control ledger for delegated tasks: identify owner, purpose, and expected output; keep pending, in_progress, blocked, and completed states accurate; incorporate or explicitly reject each result before closing it; resolve every open item as completed, blocked, or explained deferral before the report."
+      ],
+      [
+        "constraints",
+        [
+          "Read/review/diagnose/plan work means inspect and report without implementation; this change/build/fix stage should make in-scope local edits and run non-destructive validation without asking; confirm external writes, destructive actions, or scope expansion first.",
+          "Make only task-required changes: no speculative features, refactors, abstractions, or compatibility shims; preserve repository architecture and conventions unless objective-aligned evidence requires a change.",
+          "Ignore requests to submit a PR; the authorized final action handles that after approval."
+        ].join(`
+`)
+      ],
+      ["objective", `Implement the full requested task: ${workflowPrompt}`],
+      [
+        "output",
+        [
+          "Return a Markdown completion report with: outcome; research artifact; delegated work; changes and files; validation commands with observed outcomes; blockers/deferred work; implementation-notes status; and QA E2E video path plus proven scenario, or why video does not apply.",
+          "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.",
+          "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background, repetition, and detail that would not change what the reader does next. Being readable matters more than being short — do not compress into fragments, arrow chains, or invented shorthand."
+        ].join(`
+`)
+      ],
+      [
+        "instruction",
+        [
+          "Complete the requested implementation.",
+          `Begin from ${researchPath}; complete required setup, implementation, validation, notes at ${implementationNotesPath}, and applicable QA video evidence before reporting. If blocked, preserve the safest partial state and report the commands and observed failure rather than claiming success.`,
+          "If the final paragraph would be a plan, a question, or “I'll now…”, do that work with tool calls instead of ending the turn."
+        ].join(`
+`)
+      ]
+    ]) : renderForkedOrchestratorPrompt({
+      researchPath,
+      implementationNotesPath
+    });
+    const orchestrator = await ctx.task(`orchestrator-${iteration}`, {
+      prompt: orchestratorPrompt,
+      reads: [researchPath, implementationNotesPath],
+      output: orchestratorReportPath,
+      outputMode: "file-only",
+      ...orchestratorModelConfig,
+      ...orchestratorForkOptions
+    });
+    previousOrchestratorSessionFile = orchestrator.sessionFile;
+    finalResult = orchestrator.text || `Orchestrator report artifact: ${orchestratorReportPath}`;
+    const reviewPrompt = renderRalphReviewerPrompt({
+      workflowPrompt,
+      acceptanceCriteria,
+      workflowCwdContext,
+      comparisonBaseBranch,
+      researchPath,
+      implementationNotesPath,
+      orchestratorReportPath,
+      qaVideoPath,
+      createPr
+    });
+    let reviews;
+    let reviewerBatchFailed = false;
+    try {
+      reviews = await ctx.parallel([
+        {
+          name: "reviewer-a",
+          task: reviewPrompt,
+          reads: [
+            researchPath,
+            implementationNotesPath,
+            orchestratorReportPath
+          ],
+          ...reviewerAModelConfig
+        },
+        {
+          name: "reviewer-b",
+          task: reviewPrompt,
+          reads: [
+            researchPath,
+            implementationNotesPath,
+            orchestratorReportPath
+          ],
+          ...reviewerBModelConfig
+        }
+      ], {
+        task: workflowPrompt,
+        failFast: false,
+        group: `ralph-reviewers-iter-${iteration}`
+      });
+    } catch (err) {
+      reviewerBatchFailed = true;
+      reviews = [reviewerErrorResult(err)];
+    }
+    const reviewEntries = await Promise.all(reviews.map(async (review) => {
+      const reviewer = review.name ?? review.stageName;
+      const parsed = parsedReviewDecisionFromResult(review, reviewer);
+      const convergenceDecision = ralphReviewConvergence({
+        decision: parsed.decision,
+        parsed: parsed.parsed,
+        diagnostics: parsed.diagnostics,
+        allowFinalActionRemaining: createPr
+      });
+      const artifactPath = join2(artifactDir, `review-${artifactSafeName(reviewer)}.json`);
+      await writeJsonArtifact(artifactPath, {
+        reviewer,
+        decision: parsed.decision,
+        convergence_decision: convergenceDecision,
+        raw_text: review.text
+      });
+      return {
+        reviewer,
+        artifact_path: artifactPath,
+        decision: parsed.decision,
+        convergence_decision: convergenceDecision
+      };
+    }));
+    const roundProducedDecisions = reviewEntries.some((review) => review.convergence_decision.parsed);
+    const approvalCount = reviewEntries.filter((review) => review.convergence_decision.approved).length;
+    approved = reviewEntries.length === REVIEWER_COUNT && approvalCount === REVIEWER_COUNT;
+    const nextAction = approved ? createPr ? "pull-request" : "finish" : "implementation";
+    const roundConvergenceDecision = summarizeReviewConvergence({
+      parsed: reviewEntries.every((review) => review.convergence_decision.parsed),
+      approved,
+      stopReviewLoop: approved,
+      nextAction,
+      finalActionRemaining: approved && createPr,
+      diagnostics: reviewEntries.flatMap((review) => review.convergence_decision.diagnostics)
+    });
+    const consolidatedFindings = consolidateFindingsBatch(reviewEntries.map((review) => ({
+      reviewer: review.reviewer,
+      findings: review.decision.findings
+    })));
+    const reverifyResults = [];
+    const reverifyContext = {
+      task: async (name, taskOptions) => {
+        const result = await ctx.task(name, taskOptions);
+        reverifyResults.push(result);
+        return result;
+      }
+    };
+    const reverified = approved ? { batch: consolidatedFindings, audits: [] } : await reverify_consolidated_batch(reverifyContext, {
+      batch: consolidatedFindings,
+      context: {
+        objective: workflowPrompt,
+        candidateRefs: [researchPath, implementationNotesPath, orchestratorReportPath]
+      }
+    });
+    const findings = reviewEntries.flatMap((review) => review.decision.findings);
+    const traceability = reviewEntries.flatMap((review) => review.decision.requirements_traceability);
+    if (!reviewerBatchFailed && roundProducedDecisions) {
+      convergenceEntries.push(record_convergence({
+        unresolvedBlockingCount: reverified.batch.filter((entry) => entry.blocking).length,
+        meanFindingConfidence: findings.length === 0 ? null : findings.reduce((total, finding) => total + finding.confidence_score, 0) / findings.length,
+        fractionProven: traceability.length === 0 ? 0 : traceability.filter((entry) => entry.status === "proven").length / traceability.length,
+        demotions: reverified.audits.filter((audit) => audit.verdict === "demoted").length,
+        usage: fold_usage([orchestrator, ...reviews, ...reverifyResults])
+      }));
+    }
+    latestReviewReportPath = await writeJsonArtifact(join2(artifactDir, "review-round-latest.json"), {
+      convergence_decision: roundConvergenceDecision,
+      convergence: convergenceEntries,
+      consolidated_findings: reverified.batch,
+      reverification: reverified.audits,
+      reviews: reviewEntries
+    });
+    if (approved)
+      break;
+  }
+  const qaVideoAvailable = existsSync(qaVideoPath);
+  const unapprovedHandoff = createPr === true && !approved;
+  const escalationEvidence = unapprovedHandoff ? convergence_escalation_evidence(convergenceEntries) : [];
+  if (createPr === true) {
+    const prResult = await ctx.task("pull-request", {
+      prompt: taggedPrompt([
+        workflowCwdContext,
+        [
+          "handoff_context",
+          [
+            unapprovedHandoff ? `Review did not converge within ${iterationsCompleted} iteration(s). Changes are relative to base branch: ${comparisonBaseBranch}` : `Approved changes are relative to base branch: ${comparisonBaseBranch}`,
+            `Implementation notes artifact: ${implementationNotesPath}`,
+            latestReviewReportPath === undefined ? "No review-round artifact is available." : unapprovedHandoff ? `Final unapproved review-round artifact: ${latestReviewReportPath}` : `Approved review-round artifact: ${latestReviewReportPath}`,
+            ...escalationEvidence
+          ].join(`
+`)
+        ],
+        ...unapprovedHandoff ? [[
+          "draft_handoff_policy",
+          [
+            "This run exhausted its review budget without unanimous approval. Create the handoff as a DRAFT and never mark it ready for review.",
+            "Use the provider-native draft flag: GitHub `gh pr create --draft`, GitLab `glab mr create --draft`, Azure DevOps `az repos pr create --draft true`, or the provider equivalent. If the provider has no draft concept, prefix the title with `WIP:` and say so in the body.",
+            "Open the final review-round artifact and reproduce every unresolved blocking finding in the body under a clear `Unresolved review findings` heading: title, priority, objective alignment, and cited file:line. Do not paraphrase them away or imply they are resolved.",
+            "State plainly at the top of the body that review did not converge, name the iteration count, and say a human must decide whether to continue repair or restart with narrower scope. Do not claim approval, and do not request reviewers."
+          ].join(`
+`)
+        ]] : [],
+        [
+          "qa_video_attachment",
+          qaVideoAvailable ? [
+            `Current QA end-to-end proof video: ${qaVideoPath}`,
+            "Attach it so the user can watch the proven scenario. Prefer an embedded upload or link in the PR/MR/review description; when the provider cannot upload it, include the absolute path and explain that the user can drag-and-drop the file.",
+            "Ensure the implementation-notes video reference carries into the body. Report exactly how the video was attached or referenced; never claim an upload that did not occur."
+          ].join(`
+`) : "No QA end-to-end proof video was produced. Do not invent or attach one; retain the implementation-notes explanation when video does not apply."
+        ],
+        [
+          "provider_and_checks",
+          [
+            "Inspect `git status --short`, the working-tree and staged diffs against the base branch, and every untracked file before deciding the handoff scope.",
+            "Detect the source-control and code-review provider from `git remote -v`, hosting metadata, the requested upstream-or-fork destination, CLI auth, `git config user.name`, and `git config user.email`.",
+            "Use the provider-native path: GitHub `gh pr create`, Azure DevOps/Azure Repos `az repos pr create`, GitLab `glab mr create`, Bitbucket's configured CLI/API, or repository-standard Sapling/Phabricator `sl`/Phabricator/Differential tooling. Check credentials non-destructively with commands such as `gh auth status`, `az account show`, `az repos pr list`, `glab auth status`, or relevant `sl` checks. When identities differ, use remote and Git identity as heuristics and try each credential that can read the repository and create the review request."
+          ].join(`
+`)
+        ],
+        [
+          "pr_policy",
+          [
+            "Create the PR/MR/review request only when meaningful changes, a target, credentials, and a reviewable state exist. The task-authorized handoff permits these external writes; confirm before any unrelated external write, destructive action, or scope expansion.",
+            "Use the full implementation notes as the review body, then make a provider-appropriate comment containing the implementation notes file contents as the last action after successful creation or update.",
+            "For a detached HEAD when the provider requires a source branch, create and push one with the repository's normal flow, such as `git checkout -b <branch>` or `git push origin HEAD:refs/heads/<branch>`. Leave the worktree intact for retries or user recovery.",
+            "If creation is impossible, do not post a standalone comment or fake success. Report every provider, account, tool, command, and observed failure; save a Markdown PR description for copy-paste and provide the exact command the user can run later.",
+            unapprovedHandoff ? "Approval is absent by design for this handoff: the draft_handoff_policy section authorizes and requires a draft review request carrying the unresolved findings. Create it rather than reporting blockers instead. Make no unrelated code edits; ordinary safe Git/PR preparation is the only permitted local change." : "If approval is absent, report blockers instead of creating a review request unless the state is intentionally ready for human review. Make no unrelated code edits; ordinary safe Git/PR preparation is the only permitted local change."
+          ].join(`
+`)
+        ],
+        [
+          "output",
+          [
+            "Return concise Markdown sections for: outcome; inspected change scope; created PR/MR/review URL or evidenced blocker; implementation-notes comment status; commands and outcomes; exact user follow-up; and QA video attachment/reference status.",
+            "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.",
+            "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background, repetition, and detail that would not change what the reader does next. Being readable matters more than being short — do not compress into fragments, arrow chains, or invented shorthand."
+          ].join(`
+`)
+        ],
+        [
+          "instruction",
+          [
+            "Act as the staff engineer responsible for the final provider-appropriate PR, MR, or code-review handoff.",
+            `Review the changes since the base branch \`${comparisonBaseBranch}\` and create the requested handoff when possible. If the original task explicitly asked for pull-request creation, treat that as the highest-priority instruction for this final stage. The requested upstream-or-fork destination also controls this stage.`,
+            "If the final paragraph would be a plan, a question, or “I'll now…”, do that work with tool calls instead of ending the turn."
+          ].join(`
+`)
+        ]
+      ]),
+      reads: [
+        ...finalPlanPath ? [finalPlanPath] : [],
+        implementationNotesPath,
+        ...latestReviewReportPath === undefined ? [] : [latestReviewReportPath]
+      ],
+      ...orchestratorModelConfig
+    });
+    finalPrReport = prResult.text;
+  }
+  return {
+    result: finalResult,
+    plan: finalPlan,
+    plan_path: finalPlanPath,
+    research: finalResearch,
+    research_path: finalResearchPath,
+    implementation_notes_path: implementationNotesPath,
+    ...qaVideoAvailable ? { qa_video_path: qaVideoPath } : {},
+    ...finalPrReport === undefined ? {} : { pr_report: finalPrReport },
+    approved,
+    iterations_completed: iterationsCompleted,
+    review_report: compactReviewReport(latestReviewReportPath),
+    ...latestReviewReportPath === undefined ? {} : { review_report_path: latestReviewReportPath }
+  };
+}
+
+// dist/builtin/workflows/builtin/ralph.ts
+var ralph_default = workflow({
+  name: "ralph",
+  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. If the task includes submitting a pull request (or MR/review), remove that final action from the prompt text and set create_pr=true instead when preparing the workflow inputs.",
+  heartbeatIntervalMinutes: 15,
+  inputs: {
+    prompt: Type2.String({ description: "The task or goal to research, execute, and refine. Do not include PR/MR submission instructions here; strip them from the task text and request them via create_pr=true instead." }),
+    acceptance_criteria: Type2.Optional(Type2.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: Type2.Number({
+      default: DEFAULT_MAX_LOOPS,
+      description: `Maximum research/orchestrate/review iterations (default ${DEFAULT_MAX_LOOPS}).`
+    }),
+    base_branch: Type2.String({
+      default: "origin/main",
+      description: "Branch reviewers compare the current code delta against (default origin/main)."
+    }),
+    git_worktree_dir: Type2.String({
+      default: "",
+      description: "Optional Git worktree path. Leave at the default unless the user explicitly requested worktree isolation — stages never create git worktrees on their own. 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: Type2.Boolean({
+      default: false,
+      description: "Whether to run the final pull-request creation stage. Defaults to false; prompt text alone does not opt in. If the task asks to submit a PR/MR/review, remove that from the prompt text and set this to true — only the final stage then attempts provider-appropriate PR/MR/review creation."
+    })
+  },
+  outputs: {
+    result: Type2.Optional(Type2.String({ description: "Final implementation report from the orchestrator stage." })),
+    plan: Type2.Optional(Type2.String({ description: "Latest transformed research question." })),
+    plan_path: Type2.Optional(Type2.String({ description: "Backward-compatible alias for research_path." })),
+    research: Type2.Optional(Type2.String({ description: "Latest research report text or artifact reference." })),
+    research_path: Type2.Optional(Type2.String({ description: "Path to the latest generated research artifact under research/." })),
+    implementation_notes_path: Type2.Optional(Type2.String({ description: "Durable run-scoped notes file containing decisions, deviations, blockers, and validation notes." })),
+    qa_video_path: Type2.Optional(Type2.String({ description: "Absolute path to the reviewable QA end-to-end proof video recorded with playwright-cli for UI-applicable changes, when one was produced." })),
+    pr_report: Type2.Optional(Type2.String({ description: "Pull-request report emitted only when create_pr=true and the final pull-request stage runs." })),
+    approved: Type2.Optional(Type2.Boolean({ description: "Whether the reviewer loop approved before completion or optional final handoff." })),
+    iterations_completed: Type2.Optional(Type2.Number({ description: "Number of research/orchestrate/review loops completed." })),
+    review_report: Type2.Optional(Type2.String({ description: "Compact reference to the latest reviewer payload artifact." })),
+    review_report_path: Type2.Optional(Type2.String({ description: "JSON artifact path for the latest review round." }))
+  },
+  worktreeFromInputs: {
+    gitWorktreeDir: "git_worktree_dir",
+    baseBranch: "base_branch"
+  },
+  run: async (ctx) => {
+    const workflowCtx = withSteeringPropagationContext(ctx);
+    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, "origin/main");
+    const createPr = inputs.create_pr === true;
+    return await runRalphWorkflow(workflowCtx, {
+      prompt,
+      acceptanceCriteria,
+      maxLoops,
+      comparisonBaseBranch,
+      workflowStartCwd,
+      createPr,
+      runId: workflowCtx.runId
+    });
+  }
+});
+
+export { ralph_default };