@bastani/atomic 0.9.5-alpha.1 → 0.9.5-alpha.10

package/dist/builtin/workflows/README.md

@@ -5,7 +5,7 @@
   An open-source Atomic workflow extension: install it, author workflows in TypeScript, run them from chat.
 </p>
 
-Use workflows by default for non-trivial tasks, structured requests, and objectives with verifiable done criteria, including implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, and validation-heavy docs/code work. Prompt language such as `do X until Y`, `repeat until`, `iterate until`, `review/fix until passing`, or `run checks and fix until green` is a strong signal to map the work to a workflow with an explicit stop condition rather than a direct chat turn.
+Use the least orchestration that fits the user's intent: keep interactive/exploratory work inline, use bounded single/chain/parallel subagents while the parent remains in control, and use workflows for clearly delegated, well-defined autonomous jobs that are likely long-running/background-oriented or materially need durable stages, artifacts/checkpoints, resumability, HIL, gates, retries, or bounded loops. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow. Loop or stop-condition requests such as `do X until Y`, `repeat until`, `iterate until`, `review/fix until passing`, `run checks and fix until green`, or `keep going until done` are key workflow signals when the user delegates execution because they already define control flow and a completion condition. When workflow execution fits, Atomic may always author a custom TypeScript `workflow({...})` inline with normal coding tools if that shape best achieves the task; it is not limited to installed workflows or direct modes. Named workflows can be builtin, project, user, or package supplied, and direct task/tasks/chain modes cover one-off tracked shapes.
 
 <p align="center">
   <a href="#authoring-api">Authoring API</a>
@@ -300,7 +300,7 @@ Worktree semantics:
 - Symlinked repo/worktree paths preserve their logical spelling in the default cwd, matching Codex-style worktree behavior.
 - Explicit `cwd` still wins. Relative `cwd` values are resolved against the worktree default cwd; absolute `cwd` values are used as provided.
 
-`worktree: true` is different: it creates temporary isolated worktrees for direct task/parallel/chain execution and cleans them up afterward. It is mutually exclusive with `gitWorktreeDir`, which is intended for named/reusable worktrees that remain available across retries.
+`worktree: true` is different: it creates temporary isolated worktrees for direct task/parallel/chain execution and cleans them up afterward. It is mutually exclusive with `gitWorktreeDir`, which is intended for named/reusable worktrees that remain available across retries and `/workflow resume`. Durable resume records the original invocation cwd and resolved reusable-worktree metadata, then replays from that original repository context rather than whichever cwd the resumed interactive session currently has. Reusable worktree setup is cached within a workflow run, read-only Git repository probes retry a transient timeout once, and slow Git subprocess failures include the exact command, cwd, timeout, elapsed time, exit status/signal, and spawn error details.
 
 For advanced integrations, the SDK also exports `setupGitWorktree(options)`, which returns `{ worktreeRoot, cwd, repositoryRoot, created }` and uses the same validation/path behavior as the executor.
 
@@ -326,7 +326,7 @@ Atomic registers the canonical `structured_output` tool only for schema-enabled
 
 ### Model fallbacks
 
-Stages and high-level task helpers can retry transient provider/model failures with an ordered `fallbackModels` list. The primary `model` is tried first, then each fallback, and finally the current Atomic-selected model when available. Fallbacks are only used for retryable model/provider failures such as rate limits, quota/auth/provider outages, unavailable models, network timeouts, and 5xx errors — ordinary tool, shell, validation, cancellation, and workflow-code failures are not retried.
+Stages and high-level task helpers can retry transient provider/model failures with an ordered `fallbackModels` list. The primary `model` is tried first, then each fallback, and finally the current Atomic-selected model when available. Fallbacks are only used for retryable model/provider failures such as rate limits, quota/auth/provider outages, unavailable models, network timeouts, context-window overflows that Atomic's auto-compaction cannot resolve on the current model, and 5xx errors — ordinary tool, shell, validation, cancellation, and workflow-code failures are not retried.
 
 ```typescript
 import { workflow } from "@bastani/workflows";
@@ -542,7 +542,9 @@ Tradeoff: `Type.Unsafe<T>()` does not deeply validate at runtime — it trusts t
 
 Input overrides are bare `key=value` tokens (no leading `--`). Values are JSON-parsed when possible, so numbers, booleans, and quoted strings work as expected (e.g. `count=3`, `flag=true`, `prompt="multi word value"`). A whole-object override can be passed as a single JSON token (e.g. `{"prompt":"...","count":3}`). Runtime validation is strict: unknown input keys, missing required values, type mismatches, and invalid `select` choices fail before a named workflow run starts.
 
-Workflows always run as **background tasks** in interactive sessions — the chat editor stays free while a run executes. Press **F2** (or `/workflow connect <run-id>`) to attach to the live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor/custom`) appear as awaiting-input graph nodes. Press Enter on a focused node, or click a visible graph node directly, to open that stage and answer locally, never as a modal dialog over the chat. Attached stage chats capture mouse/trackpad wheel events by default so scrolling stays inside the active stage transcript or prompt instead of falling through to terminal/main-chat scrollback. Press `ctrl+t` to toggle **copy mode**: copy mode disables workflow-chat mouse reporting so normal terminal/tmux text selection can work; press `ctrl+t` again to leave copy mode and restore workflow-chat scrolling. While copy mode is on, wheel/trackpad gestures are handled by the terminal/tmux and may scroll terminal scrollback, so leave copy mode before using the wheel again. Human input is detected when those runtime `ctx.ui.*` calls execute; workflows no longer have a declaration-time HIL flag.
+Workflows always run as **background tasks** in interactive sessions — the chat editor stays free while a run executes. Press **F2** (or `/workflow connect <run-id>`) to attach to the live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor/custom`) appear as awaiting-input graph nodes. Press Enter on a focused node, or click a visible graph node directly, to open that stage and answer locally, never as a modal dialog over the chat. Attached stage chats capture mouse/trackpad wheel events by default so scrolling stays inside the active stage transcript or prompt instead of falling through to terminal/main-chat scrollback. Press `ctrl+t` to toggle **copy mode**: copy mode disables workflow-chat mouse reporting so normal terminal/tmux text selection can work; press `ctrl+t` again to leave copy mode and restore workflow-chat scrolling. Archived read-only stage transcripts show the same copy-mode footer/status, allowing their transcript text to be selected and copied while preserving `esc` close and `ctrl+d` graph navigation. While copy mode is on, wheel/trackpad gestures are handled by the terminal/tmux and may scroll terminal scrollback, so leave copy mode before using the wheel again. Human input is detected when those runtime `ctx.ui.*` calls execute; workflows no longer have a declaration-time HIL flag.
+
+Durable resume preserves the original completed-stage shape: replayed stage/task/parallel/child checkpoints retain summaries, durations, session/model metadata, and parallel branch parentage in the graph instead of flattening fanout branches into a sequential replay chain.
 
 Nested `ctx.workflow(...)` calls are displayed as an expanded graph within the top-level run. `/workflow status` and run pickers list only top-level user-launched workflows, not implementation-owned child runs. The `workflow` tool's `stages`, `stage`, `transcript`, `send`, `pause`, `interrupt`, and `resume` actions can still target visible child stage ids, prefixes, or names from the expanded graph; Atomic routes the control action to the owning nested run internally. (`stages`, `stage`, `transcript`, and `send` are `workflow` tool actions, not `/workflow` slash subcommands; the slash command exposes `connect`, `attach`, `pause`, `list`, `status`, `interrupt`, `kill`, `resume`, `reload`, and `inputs`.)
 
@@ -555,7 +557,7 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
 ```json
 {
   "name": "workflow",
-  "description": "Run named workflows or direct one-off task/tasks/chain workflows; discover with list/get/inputs, inspect status/stages/stage details, send prompt answers or steering, pause/resume/interrupt/kill runs, and reload workflow resources. For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.",
+  "description": "Run named builtin, project, user, or package workflows, or direct one-off task/tasks/chain workflows; when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; discover with list/get/inputs, inspect status/stages/stage details, send prompt answers or steering, pause/resume/interrupt/kill runs, and reload workflow resources. For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.",
   "parameters": {
     "workflow": "string (optional) — workflow ID or normalized name",
     "inputs": "object (optional) — key/value map of workflow inputs",
@@ -681,7 +683,7 @@ Child workflow outputs: `result`, `status`, `approved`, `goal_id`, `objective`,
 
 ### `ralph`
 
-Raw prompt → prompt-engineering research → orchestrate → review workflow with optional final-stage PR handoff: use the raw prompt as the operative objective, keep optional `acceptance_criteria` as the immutable original task contract (defaulting to `prompt`), transform the prompt into a codebase and online research question with `/skill:prompt-engineer`, run `/skill:research-codebase` against it, write findings under `research/`, delegate implementation through sub-agents from that research, run parallel reviewers across Claude Fable 5, GPT-5.5 Codex, and Gemini 3.1 Pro model families, and iterate until approval or the loop limit. Ralph's research, orchestrator, and reviewer prompts receive the objective next to the literal acceptance contract; when launching follow-up Ralph runs from reviewer findings, pass the ORIGINAL task text as `acceptance_criteria` so deltas cannot drift from the contract. Ralph's orchestrator and reviewers are prompted to verify user-visible behavior end-to-end when practical with `playwright-cli`-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios. They must assume credentials/auth/environment access exists until concrete non-destructive checks plus an actual launch/flow attempt prove otherwise; skipped E2E is valid only when exact attempted commands and observed failure output are recorded. For UI-applicable or full-stack changes, the orchestrator runs a `playwright-cli` end-to-end QA pass and records a reviewable proof video, references it in the implementation notes, and exposes it as the `qa_video_path` output; reviewers receive that path and inspect the actual video before treating it as proof. Review decisions include `requirements_traceability`, a non-empty clause-by-clause map over every prompt/acceptance-criteria requirement, and Ralph approval requires every entry to be `proven`; worker-authored tests/snapshots passing are circular evidence unless tied to independent current-state proof. When `create_pr=true`, the final `pull-request` stage attaches or links that video to the created PR/MR/review. Follow-up iterations pass unresolved review artifacts into prompt-engineering/research and fork research from prior research session data when available. Ralph skips PR creation by default; prompt text alone does not opt in. Pass `create_pr=true` to authorize only the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation (for example GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling). Ralph's own PR-creation instructions live in that final stage. Reviewers inspect repository infrastructure directly as needed; Ralph no longer runs separate `infra-*` discovery stages.
+Raw prompt → prompt-engineering research → orchestrate → review workflow with optional final-stage PR handoff: use the raw prompt as the operative objective, keep optional `acceptance_criteria` as the immutable original task contract (defaulting to `prompt`), transform the prompt into a codebase and online research question with `/skill:prompt-engineer`, run `/skill:research-codebase` against it, write findings under `research/`, delegate implementation through sub-agents from that research, run parallel reviewers across Claude Fable 5 and GPT-5.5 Codex model families, and iterate until approval or the loop limit. Ralph's research, orchestrator, and reviewer prompts receive the objective next to the literal acceptance contract; when launching follow-up Ralph runs from reviewer findings, pass the ORIGINAL task text as `acceptance_criteria` so deltas cannot drift from the contract. Ralph's orchestrator and reviewers are prompted to verify user-visible behavior end-to-end when practical with `playwright-cli`-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios. They must assume credentials/auth/environment access exists until concrete non-destructive checks plus an actual launch/flow attempt prove otherwise; skipped E2E is valid only when exact attempted commands and observed failure output are recorded. For UI-applicable or full-stack changes, the orchestrator runs a `playwright-cli` end-to-end QA pass and records a reviewable proof video, references it in the implementation notes, and exposes it as the `qa_video_path` output; reviewers receive that path and inspect the actual video before treating it as proof. Review decisions include `requirements_traceability`, a non-empty clause-by-clause map over every prompt/acceptance-criteria requirement, and Ralph approval requires every entry to be `proven`; worker-authored tests/snapshots passing are circular evidence unless tied to independent current-state proof. When `create_pr=true`, the final `pull-request` stage attaches or links that video to the created PR/MR/review. Follow-up iterations pass unresolved review artifacts into prompt-engineering/research and fork research from prior research session data when available. Ralph skips PR creation by default; prompt text alone does not opt in. Pass `create_pr=true` to authorize only the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation (for example GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling). Ralph's own PR-creation instructions live in that final stage. Reviewers inspect repository infrastructure directly as needed; Ralph no longer runs separate `infra-*` discovery stages.
 
 ```text
 /workflow ralph prompt="Migrate the database layer to Drizzle ORM" max_loops=3 base_branch=develop

package/dist/builtin/workflows/builtin/deep-research-codebase-utils.ts

@@ -32,22 +32,34 @@ export interface DeepResearchCodebaseResult {
 export const FILE_ONLY_OUTPUT = "file-only" satisfies WorkflowOutputMode;
 
 // Chains curated from Atomic's agentic-coding benchmark (see ralph-models.ts
-// for the frontier data and placement principle: only reviewers get
-// best-in-class models; the planner is a perf-per-dollar stage).
+// for the frontier data). This planner uses the high-capacity synthesis roster
+// because it performs cross-codebase planning before partition fan-out.
 export const PLANNER_MODEL_CONFIG = {
-  model: "openai-codex/gpt-5.5:xhigh",
+  model: "anthropic/claude-fable-5:high",
   fallbackModels: [
+    "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-fable-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:xhigh",
+    "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:xhigh",
+    "openrouter/sakana/fugu-ultra:high",
     "openrouter/openai/gpt-5.5:xhigh",
-    "openrouter/anthropic/claude-fable-5:xhigh",
     "openrouter/anthropic/claude-opus-4-8:high",
-    "openrouter/z-ai/glm-5.2:xhigh"
+    "openrouter/x-ai/grok-4.5",
+    "openrouter/z-ai/glm-5.2:xhigh",
   ],
   excludedTools: ["ask_user_question"],
 } as const;
@@ -57,16 +69,26 @@ export const PLANNER_MODEL_CONFIG = {
 // and glm-5.2:high (36%/$2.84) back it up; unbenchmarked minis/haiku/flash
 // are excluded.
 export const EXPLORER_MODEL_CONFIG = {
-  model: "openai-codex/gpt-5.5:low",
+  model: "openai-codex/gpt-5.6-terra:high",
   fallbackModels: [
+    "github-copilot/gpt-5.6-terra:high",
+    "openai/gpt-5.6-terra:high",
+    "openai-codex/gpt-5.5:low",
     "github-copilot/gpt-5.5:low",
     "openai/gpt-5.5:low",
     "github-copilot/claude-opus-4.8 (1m):low",
     "anthropic/claude-opus-4-8:low",
+    "cursor/gpt-5.6-terra:high",
+    "cursor/gpt-5.5:low",
+    "cursor/claude-opus-4-8-thinking:low",
+    "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-terra:high",
     "openrouter/openai/gpt-5.5:low",
     "openrouter/anthropic/claude-opus-4-8:low",
+    "openrouter/x-ai/grok-4.5",
     "openrouter/z-ai/glm-5.2:xhigh",
   ],
   excludedTools: ["ask_user_question"],
@@ -91,7 +113,10 @@ export function taggedPrompt(sections: readonly PromptSection[]): string {
     .join("\n\n");
 }
 
-export function positiveInteger(value: number | undefined, fallback: number): number {
+export function positiveInteger(
+  value: number | undefined,
+  fallback: number,
+): number {
   return typeof value === "number" && Number.isFinite(value) && value > 0
     ? Math.floor(value)
     : fallback;
@@ -350,4 +375,3 @@ export function displayRelativePath(path: string, fromCwd: string): string {
   }
   return displayPath(path);
 }
-

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

@@ -1,6 +1,7 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { ReviewDecision, ReviewRecord } from "./goal-types.js";
+import type { ReviewConvergenceSummary } from "./review-convergence.js";
 
 export function artifactSafeName(value: string): string {
   const safe = value
@@ -21,6 +22,7 @@ export async function writeReviewArtifact(
   reviewer: string,
   decision: ReviewDecision,
   rawText: string,
+  convergenceDecision: ReviewConvergenceSummary,
 ): Promise<string> {
   const artifactPath = join(
     artifactDir,
@@ -28,7 +30,7 @@ export async function writeReviewArtifact(
   );
   await writeFile(
     artifactPath,
-    `${JSON.stringify({ reviewer, decision, raw_text: rawText }, null, 2)}\n`,
+    `${JSON.stringify({ reviewer, decision, convergence_decision: convergenceDecision, raw_text: rawText }, null, 2)}\n`,
     { encoding: "utf8" },
   );
   return artifactPath;

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

@@ -1,6 +1,7 @@
 import {
   E2E_VERIFICATION_GUIDANCE,
   LITERAL_OBJECTIVE_CONTRACT,
+  REVIEWER_SPEC_VS_OBJECTIVE_GUARD,
   WORKER_PREFLIGHT_CONTRACT,
   renderE2eQaVideoReviewGuidance,
 } from "./shared-prompts.js";
@@ -82,7 +83,7 @@ export const RECEIPT_EXPECTATIONS = [
 
 export const INTERMEDIATE_PR_HANDOFF_GUARDRAIL = [
   "Ignore any user requests to submit a PR during worker or reviewer stages.",
-  "Only the final `pull-request` stage may attempt PR/MR/review creation, and only after reviewer quorum and reducer approval mark the goal complete.",
+  "Only a later authorized PR/MR/review creation action may perform that handoff, and only after reviewer quorum and reducer approval mark the implementation complete.",
 ].join("\n");
 
 export type PromptSection = readonly [tag: string, content: string];
@@ -222,6 +223,7 @@ export function renderReviewerPrompt(args: {
   readonly comparisonBaseBranch: string;
   readonly reviewQuorum: number;
   readonly blockerThreshold: number;
+  readonly createPr: boolean;
 }): string {
   return taggedPrompt([
     [
@@ -249,6 +251,16 @@ export function renderReviewerPrompt(args: {
     ["pr_handoff_policy", INTERMEDIATE_PR_HANDOFF_GUARDRAIL],
     ["auditability", RECEIPT_EXPECTATIONS],
     ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
+    [
+      "final_action_policy",
+      args.createPr
+        ? [
+            "Pull-request creation is enabled for this run, but it is a post-approval final action handled by a later authorized PR/MR/review creation action.",
+            "Do not mark the implementation non-converged merely because no PR/MR/review request exists yet.",
+            "If the repository state satisfies every implementation and validation requirement and only PR/MR/review creation remains, approve the implementation: set goal_oracle_satisfied=true, stop_review_loop=true, no blocking findings, and note the PR as the remaining final action rather than an implementation gap.",
+          ].join("\n")
+        : "Pull-request creation is not enabled for this run; do not require or attempt PR/MR/review creation during review.",
+    ],
     ["qa_e2e_video_review", renderE2eQaVideoReviewGuidance()],
     [
       "goal_context",
@@ -301,6 +313,7 @@ export function renderReviewerPrompt(args: {
         "Do not rely on unstated assumptions about author intent or codebase behavior.",
         "Speculation is insufficient: identify the code path, scenario, environment, or input that is provably affected.",
         "Do not flag intentional behavior changes as bugs unless they clearly violate the task or documented contract.",
+        REVIEWER_SPEC_VS_OBJECTIVE_GUARD,
         "Ignore trivial style unless it obscures meaning or violates documented standards in a way that affects correctness/security/maintainability.",
         "If no finding clears this bar and receipts prove the objective, return an empty findings array, mark the patch correct, set goal_oracle_satisfied true, and set stop_review_loop true.",
       ].join("\n"),
@@ -367,10 +380,20 @@ export function renderReviewerPrompt(args: {
         "Every finding must include objective_alignment: required_by_objective (the objective/acceptance criteria require fixing it), consistent_with_objective (valid defect within scope), beyond_objective (real issue but not required by objective/acceptance criteria and must not block completion or become a follow-up requirement without explicit reconciliation), or contradicts_objective (fixing it would violate literal wording and must never be implemented; escalate to the human).",
       ].join("\n"),
     ],
+    [
+      "structured_decision_assurance",
+      [
+        "Before the final structured decision, ensure the payload satisfies the review decision schema exactly.",
+        "Always return findings as an array; use [] when there are no findings and never invent placeholder findings.",
+        "Always return requirements_traceability as a non-empty array that enumerates every explicit objective and acceptance-criteria clause.",
+        "When approving, every non-final-action requirements_traceability entry must be proven, goal_oracle_satisfied must be true, verification_remaining must say no objective-relevant implementation or validation remains, stop_review_loop must be true, and reviewer_error must be null or omitted.",
+        "When create_pr is enabled and only PR/MR/review creation remains, record that as a final action rather than a blocker; approval should hand off to PR/MR/review creation instead of requesting more implementation work.",
+      ].join("\n"),
+    ],
     [
       "output_format",
       [
-        "Set stop_review_loop=true only when there are no blocking findings, overall_correctness is patch is correct, goal_oracle_satisfied is true, requirements_traceability is non-empty and every entry is proven, no objective-relevant verification remains, and reviewer_error is null/omitted.",
+        "Set stop_review_loop=true only when there are no blocking findings, overall_correctness is patch is correct, goal_oracle_satisfied is true, requirements_traceability is non-empty and every non-final-action entry is proven, no objective-relevant implementation or validation remains, and reviewer_error is null/omitted.",
         "Enumerate every explicit requirement clause from the objective and acceptance criteria in requirements_traceability, including clauses about existing tests/snapshots and expected behavior. Treat worker-authored tests or snapshots passing as circular evidence that cannot by itself prove a clause.",
         "P3 nice-to-have findings are non-blocking when the rest of the approval contract is satisfied; do not use P3 for work required by the objective or verification oracle. Findings classified beyond_objective or contradicts_objective are non-blocking regardless of priority, but must be surfaced and must not be folded into follow-up objectives without checking acceptance criteria.",
         "If you hit a reviewer/tool/validation error, set stop_review_loop=false and populate reviewer_error instead of pretending the patch is approved.",

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

@@ -1,4 +1,19 @@
 import type { BlockerObservation, GoalLedger, ReducerOutcome, ReviewRecord } from "./goal-types.js";
+import { summarizeReviewConvergence, type ReviewNextAction } from "./review-convergence.js";
+
+function reducerSummary(
+  reviews: readonly ReviewRecord[],
+  approved: boolean,
+  nextAction: ReviewNextAction,
+) {
+  return summarizeReviewConvergence({
+    parsed: reviews.every((review) => review.parsed),
+    approved,
+    stopReviewLoop: approved,
+    nextAction,
+    diagnostics: reviews.flatMap((review) => review.parse_diagnostics),
+  });
+}
 
 export function normalizeBlocker(blocker: string): string {
   return blocker.toLowerCase().replace(/\s+/g, " ").trim();
@@ -68,6 +83,7 @@ export function reduceGoalDecision(
     readonly maxTurns: number;
     readonly reviewQuorum: number;
     readonly blockerThreshold: number;
+    readonly nextActionOnComplete: ReviewNextAction;
   },
 ): ReducerOutcome {
   const completeVotes = turnReviews.filter(
@@ -75,9 +91,11 @@ export function reduceGoalDecision(
   ).length;
 
   if (completeVotes >= options.reviewQuorum) {
+    const summary = reducerSummary(turnReviews, true, options.nextActionOnComplete);
     return {
       status: "complete",
       decision: {
+        ...summary,
         turn: options.turn,
         decision: "complete",
         reason: `Reviewer quorum met: ${completeVotes}/${options.reviewQuorum} reviewers marked complete.`,
@@ -101,6 +119,7 @@ export function reduceGoalDecision(
       status: "blocked",
       blockerObservation: observation,
       decision: {
+        ...reducerSummary(turnReviews, false, "blocked"),
         turn: options.turn,
         decision: "blocked",
         reason: `Same blocker repeated for ${blockerCount}/${options.blockerThreshold} consecutive controller observations.`,
@@ -116,6 +135,7 @@ export function reduceGoalDecision(
       status: "needs_human",
       blockerObservation: observation,
       decision: {
+        ...reducerSummary(turnReviews, false, "needs_human"),
         turn: options.turn,
         decision: "needs_human",
         reason: `Worker attempt budget reached without reviewer quorum. Remaining work: ${collectRemainingWork(turnReviews)}`,
@@ -130,6 +150,7 @@ export function reduceGoalDecision(
     status: "active",
     blockerObservation: observation,
     decision: {
+      ...reducerSummary(turnReviews, false, "implementation"),
       turn: options.turn,
       decision: "continue",
       reason: `Reviewer quorum not met. Remaining work: ${collectRemainingWork(turnReviews)}`,

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

@@ -1,10 +1,33 @@
 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 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",
@@ -19,18 +42,26 @@ function findingBlocksApproval(finding: ReviewDecision["findings"][number]): boo
   return finding.priority !== 3;
 }
 
-function traceabilityApproves(decision: ReviewDecision): boolean {
-  return decision.requirements_traceability.length > 0 &&
-    decision.requirements_traceability.every((entry) => entry.status === "proven");
+function traceabilityApproves(
+  decision: ReviewDecision,
+  allowFinalActionRemaining: boolean,
+): boolean {
+  return traceabilityProvenExceptFinalAction({
+    traceability: decision.requirements_traceability,
+    allowFinalActionRemaining,
+  });
 }
 
-export function reviewApproved(decision: ReviewDecision): boolean {
+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) &&
+    traceabilityApproves(decision, options.allowFinalActionRemaining === true) &&
     !hasBlockingFindings &&
     decision.reviewer_error == null
   );
@@ -76,9 +107,16 @@ 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")
@@ -94,6 +132,18 @@ export function reviewDecisionToRecord(args: {
       : [`${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",
@@ -105,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,
   };
 }