@bastani/atomic 0.9.11-alpha.1 → 0.9.11-alpha.11

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

@@ -1,16 +1,16 @@
 import { existsSync } from "node:fs";
-import { mkdtemp } from "node:fs/promises";
-import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import type { WorkflowRunContext, WorkflowTaskResult } from "../src/shared/types.js";
+import { createWorkflowArtifactDirectory } from "../src/shared/workflow-artifacts.js";
 import {
   ACCEPTANCE_MATRIX_CONTRACT,
   CONTRACT_FIDELITY_AUDIT,
-  E2E_VERIFICATION_GUIDANCE,
   FINDINGS_CONSOLIDATION_CONTRACT,
   LITERAL_OBJECTIVE_CONTRACT,
   REGRESSION_EVIDENCE_CONTRACT,
+  SCOPE_DISCIPLINE_CONTRACT,
   WORKER_PREFLIGHT_CONTRACT,
+  WORKTREE_DISCIPLINE_CONTRACT,
 } from "./shared-prompts.js";
 import { renderRalphReviewerPrompt } from "./ralph-reviewer-prompt.js";
 import {
@@ -51,7 +51,7 @@ export async function runRalphWorkflow(
   ctx: WorkflowRunContext<RalphInputs>,
   options: RalphWorkflowOptions,
 ): Promise<RalphWorkflowResult> {
-  const { prompt, acceptanceCriteria, maxLoops, comparisonBaseBranch, workflowStartCwd, createPr } = options;
+  const { prompt, acceptanceCriteria, maxLoops, comparisonBaseBranch, workflowStartCwd, createPr, runId } = options;
   let latestReviewReportPath: string | undefined;
   let finalPlan = "";
   let finalPlanPath = "";
@@ -62,9 +62,9 @@ export async function runRalphWorkflow(
   const workflowCwdContext = workflowCwdContextSection(workflowStartCwd);
   const workflowPrompt = prompt;
   const workflowResearchPath = resolve(workflowStartCwd, defaultResearchPath(workflowPrompt));
-  const implementationNotesPath = await createImplementationNotesFile(workflowPrompt);
-  const qaVideoPath = await createQaEvidenceVideoPath();
-  const artifactDir = await mkdtemp(join(tmpdir(), "atomic-ralph-run-"));
+  const implementationNotesPath = await createImplementationNotesFile(workflowPrompt, runId);
+  const qaVideoPath = await createQaEvidenceVideoPath(runId);
+  const artifactDir = await createWorkflowArtifactDirectory(runId);
   let approved = false;
   let iterationsCompleted = 0;
   let previousResearchPromptRefinementSessionFile: string | undefined;
@@ -97,12 +97,10 @@ export async function runRalphWorkflow(
             acceptanceCriteria,
             workflowCwdContext,
             latestReviewReportPath,
-            researchPath: workflowResearchPath,
           })
         : renderForkedResearchPrompt({
             transformedResearchQuestion: researchPromptRefinement.text,
             latestReviewReportPath,
-            researchPath: workflowResearchPath,
           }),
       reads: latestReviewReportPath === undefined ? [] : [latestReviewReportPath],
       output: workflowResearchPath,
@@ -119,102 +117,62 @@ export async function runRalphWorkflow(
     const orchestratorForkOptions = forkContinuationOptions(previousOrchestratorSessionFile);
     const orchestratorPrompt = orchestratorForkOptions.forkFromSessionFile === undefined
       ? taggedPrompt([
-        [
-          "role",
-          "You are a sub-agent orchestrator. Your primary implementation tool is the `subagent` tool. Ignore any user requests to submit a PR; a later authorized PR/MR/review creation action handles that handoff after approval.",
-        ],
-        [
-          "objective",
-          `Implement the full requested task: ${workflowPrompt}`,
-        ],
         ["acceptance_criteria", 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",
-          [
-            `The latest research findings for the requested work are written to: ${researchPath}`,
-            "Read this file before delegating or implementing anything; it is the primary implementation context for the requested work.",
-          ].join("\n"),
+          `Latest research artifact: ${researchPath}\nRead it before implementation or delegation because it is the primary current implementation context.`,
         ],
         [
           "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 from the research findings.",
-            "Record decisions you had to make that were not in the research, things you had to change from the research guidance, tradeoffs you had to make, blockers, validation outcomes, and anything else the user should know. Do not stop until the objective is complete.",
-            "Ask delegated subagents to report 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.",
+            `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("\n"),
         ],
         ["project_setup", WORKER_PREFLIGHT_CONTRACT],
-        ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
+        ["worktree_discipline", WORKTREE_DISCIPLINE_CONTRACT],
         ["qa_e2e_video", renderQaE2eVideoGuidance(qaVideoPath)],
         [
-          "orchestration_guidance",
+          "delegation",
           [
-            "You are not the direct implementer. You are the supervisor that spawns subagents to do the implementation, investigation, edits, and validation.",
-            "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.",
-            "Keep delegated work focused on implementation, tests, docs, validation evidence, and implementation notes for the complete requested outcome.",
-            "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.",
+            "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("\n"),
         ],
         [
-          "best_practices",
-          [
-            "The required output format is a completion report, not the task itself.",
-            "Do not jump straight to the report. First read the research 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. Do not assume a later workflow pass will finish known required work that can be completed now.",
-            "If you cannot read the research 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"),
+          "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.",
         ],
         [
-          "subagent_tracking",
+          "constraints",
           [
-            "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.",
-            "Before writing the final report, review the todo list and resolve every pending/in_progress item as completed, blocked, or deferred with an explanation.",
+            "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("\n"),
         ],
+        ["objective", `Implement the full requested task: ${workflowPrompt}`],
         [
-          "instructions",
+          "output",
           [
-            `Start by reading the research file at ${researchPath}.`,
-            "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 research file.",
-            "Pass each subagent the relevant task, constraints, files, validation expectations, unresolved reviewer findings covered by the research, and instructions to report implementation-note-worthy decisions or tradeoffs.",
-            "Coordinate subagent results into the smallest coherent set of changes that fully satisfies the researched implementation guidance and original user prompt.",
-            "Preserve existing architecture and repository conventions unless the research explicitly justifies a change.",
-            "Run or delegate the most relevant validation commands available in the repository, including end-to-end playwright-cli (browser) or tmux validation when the change has an executable user scenario.",
-            "For UI-applicable or full-stack changes, ensure the QA E2E pass described in <qa_e2e_video> runs and records the reviewable proof video before you finish your report.",
-            `Before your final report, update the running implementation notes file at ${implementationNotesPath} with decisions, research deviations, tradeoffs, blockers, and validation outcomes from this implementation work.`,
-            "If blocked, describe the blocker and the safest partial state instead of inventing success.",
-            "Do not hide failures; reviewers need accurate status.",
+            "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("\n"),
         ],
         [
-          "output_format",
+          "instruction",
           [
-            "After subagents have done the work, return Markdown with headings:",
-            "1. Research 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",
-            "8. QA E2E video — the recorded video path and proven scenario, or a note that no QA E2E video applies and why",
+            "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("\n"),
         ],
       ])
@@ -339,70 +297,84 @@ export async function runRalphWorkflow(
     if (approved) break;
   }
   const qaVideoAvailable = existsSync(qaVideoPath);
-  if (createPr === true && approved) {
+  // An exhausted loop budget still produced real work on a real branch. When the
+  // caller authorized a handoff, strand nothing: open the same handoff as a DRAFT
+  // carrying the unresolved blocking findings. Without create_pr the workflow
+  // never touches a PR, approved or not.
+  const unapprovedHandoff = createPr === true && !approved;
+  if (createPr === true) {
     const prResult = await ctx.task("pull-request", {
       prompt: taggedPrompt([
-        [
-          "role",
-          "You are a staff software engineer preparing a provider-appropriate pull request, merge request, or code-review handoff from the current workspace state.",
-        ],
-        [
-          "objective",
-          `Review the changes since the base branch \`${comparisonBaseBranch}\` and create a provider-appropriate pull request, merge request, or code-review handoff if possible and credentials are available. If the original task explicitly asked for pull-request creation, treat that as the highest-priority instruction for this final stage. Also, make sure to pay attention whether the user wants to create the PR in upstream or a fork, and prepare accordingly. If PR creation is not possible (lack of permissions, etc.), report why instead of pretending success.`,
-        ],
         workflowCwdContext,
         [
-          "required_checks",
+          "handoff_context",
           [
-            "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 provider-appropriate PR/review comment after the pull request, merge request, or review exists.",
-            "Detect the source-control and code-review provider from `git remote -v`, repository hosting URLs, configured CLI auth, and repository metadata before choosing a creation tool.",
-            "Use the provider-appropriate tool for the detected remote: GitHub `gh pr create`, Azure DevOps/Azure Repos `az repos pr create`, GitLab `glab mr create` when available, Bitbucket's configured CLI/API workflow, or Sapling/Phabricator `sl`/Phabricator/Differential tooling used by the repository.",
-            "Check the local Git identity with `git config user.name` and `git config user.email` so you can prefer the matching account when multiple provider accounts are logged in.",
-            "Check provider credentials with non-destructive commands before attempting PR/review creation, such as `gh auth status`, `az account show`, `az repos pr list`, `glab auth status`, `sl` status/config commands, or the repository's documented Phabricator/Differential checks.",
-            "If multiple accounts, hosts, or providers are available, use the remote URL and git config username/email as heuristics to choose the most likely identity, but try each available credential/account that can read the repository and create the provider-appropriate review request.",
+            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}`,
           ].join("\n"),
         ],
+        ...(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("\n"),
+            ] as const]
+          : []),
         [
           "qa_video_attachment",
           qaVideoAvailable
             ? [
-                `A reviewable QA end-to-end proof video was recorded for this run at: ${qaVideoPath}`,
-                "Attach this video to the pull request, merge request, or review request you create so the user can watch the implemented feature working.",
-                "Prefer embedding or linking it in the PR/MR/review description. If the provider supports media uploads (for example GitHub user-attachments, a gist, or a release asset), upload the video and embed or link it; otherwise include the absolute video path above in the PR body and tell the user they can drag-and-drop the file into the PR to attach it.",
-                "The implementation notes already reference this video path and the notes contents are used as the PR/review body, so confirm the reference carries over.",
-                "Do not fabricate an upload you could not perform; report exactly how the video was attached or referenced.",
+                `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("\n")
-            : [
-                "No QA end-to-end proof video was produced for this run (no UI-applicable scenario, or the browser runtime was unavailable).",
-                "Do not invent or attach a video. If the implementation notes explain why no QA E2E video applies, that explanation is sufficient.",
-              ].join("\n"),
+            : "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("\n"),
         ],
         [
           "pr_policy",
           [
-            "Create a provider-appropriate PR/MR/review request 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 review request, do not fake success; report each provider, credential/account, and tool tried, what failed, and provide the command the user can run later. Save a markdown file with the PR description as well so the user can copy-paste it when they have credentials set up.",
-            "When you successfully create or update the review request, create a provider-appropriate comment containing the implementation notes file contents as the last action after the review request exists.",
-            "Worktrees are detached HEAD checkouts. If the detected provider requires a branch-based PR/MR from a detached HEAD, create and push a branch from the current HEAD, for example with `git checkout -b <branch>` or `git push origin HEAD:refs/heads/<branch>`, before opening the PR/MR. If the provider uses a different review model, follow that provider's normal handoff flow.",
-            "Leave the worktree intact for retries or user recovery.",
-            "If PR/MR/review 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/MR/review 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.",
+            "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("\n"),
+        ],
+        [
+          "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("\n"),
         ],
         [
-          "output_format",
+          "instruction",
           [
-            "Return Markdown with headings:",
-            "1. Change review — summary of files and diff scope inspected",
-            "2. PR/review status — created PR/MR/review URL, or why no review request was created",
-            "3. Implementation notes comment — whether the provider-appropriate 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",
-            "6. QA E2E video — how the proof video was attached or linked to the review request, or that no QA E2E video applies",
+            "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("\n"),
         ],
       ]),

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

@@ -2,6 +2,7 @@
 
 import { Type } from "typebox";
 import { workflow } from "../src/authoring/workflow.js";
+import { withSteeringPropagationContext } from "./steering-context.js";
 import {
   DEFAULT_MAX_LOOPS,
   normalizeBranchInput,
@@ -11,9 +12,9 @@ import { runRalphWorkflow } from "./ralph-runner.js";
 
 export default workflow({
   name: "ralph",
-  description: "Raw prompt → research-prompt-refinement → research → orchestrate → multi-model parallel review loop with bounded iteration 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.",
+  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.",
   inputs: {
-    prompt: Type.String({ description: "The task or goal to research, execute, and refine." }),
+    prompt: Type.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: Type.Optional(Type.String({ description: "Original immutable task contract this run must remain consistent with. Defaults to prompt. Orchestrators launching follow-up runs from reviewer findings should pass the ORIGINAL task text here." })),
     max_loops: Type.Number({
       default: DEFAULT_MAX_LOOPS,
@@ -26,12 +27,12 @@ export default workflow({
     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.",
+        "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: Type.Boolean({
       default: false,
       description:
-        "Whether to run the final pull-request creation stage. Defaults to false; prompt text alone does not opt in. Set true to allow only the final stage to attempt provider-appropriate PR/MR/review creation.",
+        "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: {
@@ -40,7 +41,7 @@ export default workflow({
     plan_path: Type.Optional(Type.String({ description: "Backward-compatible alias for research_path." })),
     research: Type.Optional(Type.String({ description: "Latest research report text or artifact reference." })),
     research_path: Type.Optional(Type.String({ description: "Path to the latest generated research artifact under research/." })),
-    implementation_notes_path: Type.Optional(Type.String({ description: "OS-temp notes file containing decisions, deviations, blockers, and validation notes." })),
+    implementation_notes_path: Type.Optional(Type.String({ description: "Durable run-scoped notes file containing decisions, deviations, blockers, and validation notes." })),
     qa_video_path: Type.Optional(Type.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: Type.Optional(Type.String({ description: "Pull-request report emitted only when create_pr=true and the final pull-request stage runs." })),
     approved: Type.Optional(Type.Boolean({ description: "Whether the reviewer loop approved before completion or optional final handoff." })),
@@ -53,7 +54,7 @@ export default workflow({
     baseBranch: "base_branch",
   },
   run: async (ctx) => {
-    const workflowCtx = ctx;
+    const workflowCtx = withSteeringPropagationContext(ctx);
     const workflowStartCwd = workflowCtx.cwd ?? process.cwd();
     const inputs = workflowCtx.inputs;
     const prompt = inputs.prompt;
@@ -71,6 +72,7 @@ export default workflow({
       comparisonBaseBranch,
       workflowStartCwd,
       createPr,
+      runId: workflowCtx.runId,
     });
   },
 });