@bastani/atomic 0.9.6 → 0.9.7-alpha.1

package/dist/builtin/workflows/builtin/ralph-forked-prompts.ts

@@ -0,0 +1,103 @@
+// Forked-continuation prompt renderers for the builtin Ralph workflow.
+//
+// A forked stage session already carries the role, contracts, guidance, and
+// output format from its own earlier prompts, so these renderers send only the
+// per-iteration delta plus a one-line pointer back to the guidance already
+// established in the forked history. Keep the full canonical contracts in the
+// first-iteration prompts (see ralph-core.ts / ralph-runner.ts) and never
+// duplicate them here.
+import { taggedPrompt } from "./ralph-core.js";
+
+// Forked continuation of the previous refinement session: the fork already
+// carries the skill instructions, request, acceptance criteria, contracts, and
+// working directory.
+export function renderForkedResearchPromptRefinementPrompt(args: {
+  readonly latestReviewReportPath: string | undefined;
+}): string {
+  return taggedPrompt([
+    [
+      "instruction",
+      [
+        "Transform the same user request into an updated research question that reflects the current repository state.",
+        "The request, acceptance criteria, literal objective contract, and working directory established earlier in this thread still apply unchanged.",
+      ].join("\n"),
+    ],
+    [
+      "review_findings",
+      args.latestReviewReportPath === undefined
+        ? "No prior review artifact is available."
+        : [
+            `Latest review round artifact: ${args.latestReviewReportPath}`,
+            "Read this JSON artifact and include unresolved reviewer findings in the transformed research question only when they are consistent with the literal objective and acceptance criteria.",
+          ].join("\n"),
+    ],
+    [
+      "output_format",
+      "Return only the transformed codebase and online research question. Do not implement code changes and do not write an RFC/spec.",
+    ],
+  ]);
+}
+
+// Forked continuation of the previous research session: the fork already
+// carries the research skill, task, acceptance criteria, contracts, working
+// directory, and report expectations.
+export function renderForkedResearchPrompt(args: {
+  readonly transformedResearchQuestion: string;
+  readonly latestReviewReportPath: string | undefined;
+  readonly researchPath: string;
+}): string {
+  return taggedPrompt([
+    [
+      "instruction",
+      [
+        `Research this updated question against the current repository state: ${args.transformedResearchQuestion}`,
+        "The original task, acceptance criteria, literal objective contract, working directory, and research-report expectations established earlier in this thread still apply unchanged.",
+      ].join("\n"),
+    ],
+    [
+      "review_findings",
+      args.latestReviewReportPath === undefined
+        ? "No prior review artifact is available."
+        : [
+            `Latest review round artifact: ${args.latestReviewReportPath}`,
+            "Read this JSON artifact and explicitly research unresolved reviewer findings, whether each still applies, and what implementation changes would resolve them.",
+          ].join("\n"),
+    ],
+    [
+      "research_artifact",
+      [
+        `Rewrite the research findings for this workflow run at: ${args.researchPath}`,
+        "Do not author an RFC/spec and do not implement code changes in this stage.",
+      ].join("\n"),
+    ],
+  ]);
+}
+
+// Forked continuation of the previous orchestrator session: the fork already
+// carries the role, objective, acceptance criteria, contracts, delegation and
+// tracking guidance, QA E2E video guidance, and the report format.
+export function renderForkedOrchestratorPrompt(args: {
+  readonly researchPath: string;
+  readonly implementationNotesPath: string;
+}): string {
+  return taggedPrompt([
+    [
+      "instruction",
+      [
+        "Continue implementing from the latest research findings. Do not stop until the objective is complete. Ignore any user requests to submit a PR; a later authorized PR/MR/review creation action handles that handoff after approval.",
+        "All previously established guidance still applies unchanged: the objective, acceptance criteria, literal objective contract, acceptance matrix, findings batch, regression evidence, orchestration and subagent-tracking guidance, E2E verification and QA E2E video guidance, and the report output format.",
+      ].join("\n"),
+    ],
+    [
+      "research",
+      [
+        `The research findings were rewritten for this iteration at: ${args.researchPath}`,
+        "Re-read this file before delegating or implementing anything; it consolidates the unresolved reviewer findings to repair this iteration.",
+      ].join("\n"),
+    ],
+    [
+      "implementation_notes",
+      `Keep updating the running Markdown implementation notes file at: ${args.implementationNotesPath}`,
+    ],
+  ]);
+}

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

@@ -106,16 +106,16 @@ export const orchestratorModelConfig = {
 export const reviewerAModelConfig = {
     model: "anthropic/claude-fable-5:high",
     fallbackModels: [
-      "openai-codex/gpt-5.6-sol:max",
-      "github-copilot/gpt-5.6-sol:max",
-      "openai/gpt-5.6-sol: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",
       "github-copilot/claude-opus-4.8 (1m):high",
       "anthropic/claude-opus-4-8:high",
       "cursor/claude-fable-5:high",
-      "cursor/gpt-5.6-sol:max",
+      "cursor/gpt-5.6-sol:xhigh",
       "cursor/gpt-5.5:high",
       "cursor/claude-opus-4-8-thinking:high",
       "cursor/grok-4.5",
@@ -123,7 +123,7 @@ export const reviewerAModelConfig = {
       "zai-coding-cn/glm-5.2:xhigh",
       "cursor/glm-5.2",
       "openrouter/anthropic/claude-fable-5:high",
-      "openrouter/openai/gpt-5.6-sol:max",
+      "openrouter/openai/gpt-5.6-sol:xhigh",
       "openrouter/sakana/fugu-ultra:high",
       "openrouter/openai/gpt-5.5:xhigh",
       "openrouter/anthropic/claude-opus-4-8:high",
@@ -135,17 +135,17 @@ export const reviewerAModelConfig = {
 };
 
 export const reviewerBModelConfig = {
-    model: "openai-codex/gpt-5.6-sol:max",
+    model: "openai-codex/gpt-5.6-sol:xhigh",
     fallbackModels: [
-      "github-copilot/gpt-5.6-sol:max",
-      "openai/gpt-5.6-sol:max",
+      "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:high",
       "github-copilot/claude-opus-4.8 (1m):high",
       "anthropic/claude-opus-4-8:high",
-      "cursor/gpt-5.6-sol:max",
+      "cursor/gpt-5.6-sol:xhigh",
       "cursor/gpt-5.5:high",
       "cursor/claude-fable-5:high",
       "cursor/claude-opus-4-8-thinking:high",
@@ -153,7 +153,7 @@ export const reviewerBModelConfig = {
       "zai/glm-5.2:xhigh",
       "zai-coding-cn/glm-5.2:xhigh",
       "cursor/glm-5.2",
-      "openrouter/openai/gpt-5.6-sol:max",
+      "openrouter/openai/gpt-5.6-sol:xhigh",
       "openrouter/openai/gpt-5.5:xhigh",
       "openrouter/anthropic/claude-fable-5:high",
       "openrouter/sakana/fugu-ultra:high",

package/dist/builtin/workflows/builtin/ralph-review-gate.ts

@@ -1,4 +1,7 @@
-import { traceabilityProvenExceptFinalAction } from "./review-convergence.js";
+import {
+  findingBlocksClosure,
+  traceabilityProvenExceptFinalAction,
+} from "./review-convergence.js";
 
 /**
  * Review-gate severity logic for the builtin `ralph` workflow.
@@ -10,15 +13,21 @@ import { traceabilityProvenExceptFinalAction } from "./review-convergence.js";
  * loop iterate forever in those cases despite unanimous "patch is correct"
  * verdicts.
  *
- * Approval is therefore severity-aware and deterministic. A single reviewer
+ * Approval is therefore alignment- and severity-aware, deterministic, and
+ * computed by the shared evidence-closure predicate
+ * (`findingBlocksClosure` in ./review-convergence.ts). A single reviewer
  * approves when it judged the patch correct, reported no `reviewer_error`, and
  * filed no *blocking* finding:
  *
- * - Blocking  = P0/P1/P2 (numeric priority 0, 1, or 2).
- * - Non-blocking = P3 (numeric priority 3) — a nice-to-have that should not keep
- *   the loop spinning.
- * - A finding whose priority cannot be determined (`null`/`undefined`) is treated
- *   as blocking, so genuine ambiguity never silently approves.
+ * - `required_by_objective` findings block at ANY priority (P3 included):
+ *   severity labels alone never dismiss objective-relevant findings.
+ * - `consistent_with_objective` findings block at P0/P1/P2 (numeric priority
+ *   0, 1, or 2); P3 is a non-blocking nice-to-have that should not keep the
+ *   loop spinning.
+ * - `beyond_objective` / `contradicts_objective` findings never block.
+ * - A finding whose priority cannot be determined (`null`/`undefined`) or
+ *   whose alignment is missing is treated as blocking, so genuine ambiguity
+ *   never silently approves.
  *
  * The decision is computed from the structured findings rather than the
  * reviewer's self-reported `stop_review_loop` boolean, so the gate does not
@@ -73,28 +82,22 @@ export type ReviewDecision = {
 };
 
 /**
- * Highest finding priority that still blocks approval. P0=0, P1=1, P2=2 block;
- * P3=3 does not.
+ * Highest finding priority that still blocks approval for
+ * `consistent_with_objective` findings. P0=0, P1=1, P2=2 block; P3=3 does not.
+ * `required_by_objective` findings block regardless of priority.
+ * Re-exported from the shared evidence-closure module.
  */
-export const MAX_BLOCKING_PRIORITY = 2;
+export { MAX_BLOCKING_PRIORITY } from "./review-convergence.js";
 
 /**
- * True when a finding must keep the review loop iterating. P0/P1/P2 block; P3 is
- * a non-blocking nice-to-have. A finding without a determinable priority
- * (`null`/`undefined`) is treated as blocking so ambiguity never silently
- * approves.
+ * True when a finding must keep the review loop iterating. Delegates to the
+ * shared evidence-closure predicate so Goal and Ralph gate findings
+ * identically: objective-required findings block at any priority, in-scope
+ * P3 nice-to-haves do not, and ambiguity (missing priority or alignment)
+ * always blocks.
  */
 export function isBlockingFinding(finding: ReviewFinding): boolean {
-  const alignment = finding.objective_alignment;
-  if (alignment === "beyond_objective" || alignment === "contradicts_objective") {
-    return false;
-  }
-  if (alignment !== "required_by_objective" && alignment !== "consistent_with_objective") {
-    return true;
-  }
-  const priority = finding.priority;
-  if (priority === undefined || priority === null) return true;
-  return priority <= MAX_BLOCKING_PRIORITY;
+  return findingBlocksClosure(finding);
 }
 
 /**

package/dist/builtin/workflows/builtin/ralph-reviewer-prompt.ts

@@ -1,6 +1,9 @@
 import {
   E2E_VERIFICATION_GUIDANCE,
+  EVIDENCE_CLOSURE_POLICY,
   LITERAL_OBJECTIVE_CONTRACT,
+  REGRESSION_EVIDENCE_CONTRACT,
+  REVIEWER_INDEPENDENT_VERIFICATION_CONTRACT,
   REVIEWER_SPEC_VS_OBJECTIVE_GUARD,
   renderE2eQaVideoReviewGuidance,
 } from "./shared-prompts.js";
@@ -29,12 +32,15 @@ export function renderRalphReviewerPrompt(args: {
     ["objective", `Review the current code delta for the task: ${args.workflowPrompt}`],
     ["acceptance_criteria", args.acceptanceCriteria],
     ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
+    ["independent_verification", REVIEWER_INDEPENDENT_VERIFICATION_CONTRACT],
+    ["regression_evidence", REGRESSION_EVIDENCE_CONTRACT],
+    ["evidence_closure", EVIDENCE_CLOSURE_POLICY],
     args.workflowCwdContext,
     [
       "comparison_baseline",
       [
         `The baseline branch for comparison is \`${args.comparisonBaseBranch}\`.`,
-        "Compare the current working tree against this baseline branch, not against previous workflow reasoning or expected loop progress.",
+        "Compare the current working tree against this baseline branch.",
         `Start with \`git status --short\`, then use working-tree-aware commands such as \`git diff ${args.comparisonBaseBranch}\` and \`git diff --cached ${args.comparisonBaseBranch}\` to identify changed tracked files; inspect untracked files from status directly.`,
       ].join("\n"),
     ],
@@ -98,7 +104,7 @@ export function renderRalphReviewerPrompt(args: {
       "comment_guidelines",
       [
         "Each finding title must start with a priority tag: [P0] drop-everything blocker, [P1] urgent next-cycle fix, [P2] normal fix, [P3] low-priority nice-to-have.",
-        "Also include numeric priority: 0 for P0, 1 for P1, 2 for P2, 3 for P3; use null only if priority genuinely cannot be determined. Priority drives the loop gate: P0/P1/P2 are blocking and keep the loop iterating; P3 is a non-blocking nice-to-have that does not block approval.",
+        "Also include numeric priority: 0 for P0, 1 for P1, 2 for P2, 3 for P3; use null only if priority genuinely cannot be determined. Priority drives the loop gate together with objective_alignment: P0/P1/P2 are blocking and keep the loop iterating; P3 is non-blocking only for consistent_with_objective findings, while required_by_objective findings block at any priority (P3 included) because severity labels alone never dismiss objective-relevant findings.",
         "Classify every finding with 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 and must not block or be promoted without explicit reconciliation), or contradicts_objective (fixing it would violate literal objective wording and must never be implemented; escalate to the human). Missing/unknown classification is blocking.",
         "The body must be one concise paragraph explaining why this is a bug and the exact scenario, environment, or inputs required for it to arise.",
         "Use a matter-of-fact, non-accusatory tone. Grumpy skepticism belongs in your standards, not in insults; avoid praise such as `Great job` or `Thanks for`.",
@@ -120,18 +126,19 @@ export function renderRalphReviewerPrompt(args: {
       "review_stage_contract",
       [
         "The structured review decision is only valid after you inspect the actual repository state and compare it against the stated baseline branch.",
-        "Do not approve based solely on workflow stage summaries or prior agent reasoning.",
+        "Do not approve based solely on summaries in the provided context artifacts.",
         "The tool call is the final verdict after review work, not a shortcut around review work.",
       ].join("\n"),
     ],
     [
       "action_items",
       [
-        "1. Identify the changed files or diff under review.",
-        "2. Read the relevant changed code and directly affected call sites/tests/configs.",
-        "3. Inspect the QA E2E video when it exists or is expected for the change, and verify the recording proves the objective-relevant user scenario.",
-        "4. Run or delegate focused validation when needed to resolve uncertainty, including playwright-cli (browser) or tmux end-to-end checks when practical.",
-        "5. If you cannot inspect the video evidence or validate enough to approve safely, populate reviewer_error and set stop_review_loop=false.",
+        "1. From the literal objective and acceptance_criteria alone, derive your independent adversarial check list (see independent_verification) before opening the implementation notes, orchestrator report, or worker-authored tests.",
+        "2. Identify the changed files or diff under review.",
+        "3. Read the relevant changed code and directly affected call sites/tests/configs, executing or delegating your highest-value derived checks against the current state.",
+        "4. Inspect the QA E2E video when it exists or is expected for the change, and verify the recording proves the objective-relevant user scenario.",
+        "5. Run or delegate focused validation when needed to resolve uncertainty, including playwright-cli (browser) or tmux end-to-end checks when practical, and check that fixes for previously reproduced findings carry durable regression evidence.",
+        "6. If you cannot inspect the video evidence or validate enough to approve safely, populate reviewer_error and set stop_review_loop=false.",
       ].join("\n"),
     ],
     [
@@ -153,7 +160,7 @@ export function renderRalphReviewerPrompt(args: {
     ],
     [
       "decision_rules",
-      ["Set stop_review_loop=true only when the patch is correct, reviewer_error is null/omitted, there are no blocking objective-aligned P0/P1/P2 findings, requirements_traceability is non-empty and every non-final-action entry is proven, and no objective-relevant implementation or validation remains; beyond_objective and contradicts_objective findings are non-blocking and must not be folded into follow-up objectives without checking the literal contract. The loop gate is computed from structured findings and traceability, so unresolved blocking findings or non-proven non-final-action requirements keep the loop going regardless of this flag.", "Enumerate every explicit requirement clause from the prompt 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; tie any such result to independent current-state proof.", "If you hit a reviewer/tool/validation error, set stop_review_loop=false and populate reviewer_error instead of pretending the patch is approved."].join("\n"),
+      ["Set stop_review_loop=true only when the patch is correct, reviewer_error is null/omitted, there are no blocking objective-aligned findings (P0/P1/P2, plus required_by_objective findings at any priority including P3), requirements_traceability is non-empty and every non-final-action entry is proven, and no objective-relevant implementation or validation remains; beyond_objective and contradicts_objective findings are non-blocking and must not be folded into follow-up objectives without checking the literal contract. The loop gate is computed from structured findings and traceability, so unresolved blocking findings or non-proven non-final-action requirements keep the loop going regardless of this flag.", "Enumerate every explicit requirement clause from the prompt 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; tie any such result to independent current-state proof.", "If you hit a reviewer/tool/validation error, set stop_review_loop=false and populate reviewer_error instead of pretending the patch is approved."].join("\n"),
     ],
   ]);
 }

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

@@ -4,11 +4,19 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import type { WorkflowRunContext, WorkflowTaskResult } from "../src/shared/types.js";
 import {
+  ACCEPTANCE_MATRIX_CONTRACT,
   E2E_VERIFICATION_GUIDANCE,
+  FINDINGS_CONSOLIDATION_CONTRACT,
   LITERAL_OBJECTIVE_CONTRACT,
+  REGRESSION_EVIDENCE_CONTRACT,
   WORKER_PREFLIGHT_CONTRACT,
 } from "./shared-prompts.js";
 import { renderRalphReviewerPrompt } from "./ralph-reviewer-prompt.js";
+import {
+  renderForkedOrchestratorPrompt,
+  renderForkedResearchPrompt,
+  renderForkedResearchPromptRefinementPrompt,
+} from "./ralph-forked-prompts.js";
 import {
   REVIEWER_COUNT,
   artifactSafeName,
@@ -17,7 +25,6 @@ import {
   createQaEvidenceVideoPath,
   defaultResearchPath,
   forkContinuationOptions,
-  renderForkedOrchestratorPrompt,
   renderResearchPromptRefinementPrompt,
   renderQaE2eVideoGuidance,
   renderResearchPrompt,
@@ -31,7 +38,7 @@ import {
   type RalphWorkflowOptions,
   type RalphWorkflowResult,
 } from "./ralph-core.js";
-import { summarizeReviewConvergence } from "./review-convergence.js";
+import { consolidateFindingsBatch, summarizeReviewConvergence } from "./review-convergence.js";
 import {
   orchestratorModelConfig,
   promptEngineerModelConfig,
@@ -66,12 +73,14 @@ export async function runRalphWorkflow(
     iterationsCompleted = iteration;
     const researchPromptRefinementForkOptions = forkContinuationOptions(previousResearchPromptRefinementSessionFile);
     const researchPromptRefinement = await ctx.task(`research-prompt-refinement-${iteration}`, {
-      prompt: renderResearchPromptRefinementPrompt({
-        request: workflowPrompt,
-        acceptanceCriteria,
-        workflowCwdContext,
-        latestReviewReportPath,
-      }),
+      prompt: researchPromptRefinementForkOptions.forkFromSessionFile === undefined
+        ? renderResearchPromptRefinementPrompt({
+            request: workflowPrompt,
+            acceptanceCriteria,
+            workflowCwdContext,
+            latestReviewReportPath,
+          })
+        : renderForkedResearchPromptRefinementPrompt({ latestReviewReportPath }),
       reads: latestReviewReportPath === undefined ? [] : [latestReviewReportPath],
       ...promptEngineerModelConfig,
       ...researchPromptRefinementForkOptions,
@@ -80,14 +89,20 @@ export async function runRalphWorkflow(
     finalPlan = researchPromptRefinement.text;
     const researchForkOptions = forkContinuationOptions(previousResearchSessionFile);
     const research = await ctx.task(`research-${iteration}`, {
-      prompt: renderResearchPrompt({
-        transformedResearchQuestion: researchPromptRefinement.text,
-        prompt: workflowPrompt,
-        acceptanceCriteria,
-        workflowCwdContext,
-        latestReviewReportPath,
-        researchPath: workflowResearchPath,
-      }),
+      prompt: researchForkOptions.forkFromSessionFile === undefined
+        ? renderResearchPrompt({
+            transformedResearchQuestion: researchPromptRefinement.text,
+            prompt: workflowPrompt,
+            acceptanceCriteria,
+            workflowCwdContext,
+            latestReviewReportPath,
+            researchPath: workflowResearchPath,
+          })
+        : renderForkedResearchPrompt({
+            transformedResearchQuestion: researchPromptRefinement.text,
+            latestReviewReportPath,
+            researchPath: workflowResearchPath,
+          }),
       reads: latestReviewReportPath === undefined ? [] : [latestReviewReportPath],
       output: workflowResearchPath,
       outputMode: "file-only",
@@ -113,6 +128,9 @@ export async function runRalphWorkflow(
         ],
         ["acceptance_criteria", acceptanceCriteria],
         ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
+        ["acceptance_matrix", ACCEPTANCE_MATRIX_CONTRACT],
+        ["findings_batch", FINDINGS_CONSOLIDATION_CONTRACT],
+        ["regression_evidence", REGRESSION_EVIDENCE_CONTRACT],
         workflowCwdContext,
         [
           "research",
@@ -199,12 +217,8 @@ export async function runRalphWorkflow(
         ],
       ])
       : renderForkedOrchestratorPrompt({
-          prompt: workflowPrompt,
-          acceptanceCriteria,
-          workflowCwdContext,
           researchPath,
           implementationNotesPath,
-          qaVideoPath,
         });
     const orchestrator = await ctx.task(`orchestrator-${iteration}`, {
       prompt: orchestratorPrompt,
@@ -305,7 +319,19 @@ export async function runRalphWorkflow(
     });
     latestReviewReportPath = await writeJsonArtifact(
       join(artifactDir, "review-round-latest.json"),
-      { convergence_decision: roundConvergenceDecision, reviews: reviewEntries },
+      {
+        convergence_decision: roundConvergenceDecision,
+        // Deduplicated cross-reviewer findings batch so the next research and
+        // orchestrator passes repair the round's findings together instead of
+        // one at a time.
+        consolidated_findings: consolidateFindingsBatch(
+          reviewEntries.map((review) => ({
+            reviewer: review.reviewer,
+            findings: review.decision.findings,
+          })),
+        ),
+        reviews: reviewEntries,
+      },
     );
     if (approved) break;
   }

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

@@ -60,6 +60,124 @@ export function traceabilityProvenExceptFinalAction(args: {
   });
 }
 
+/**
+ * Highest numeric finding priority that still blocks evidence closure for
+ * in-scope (`consistent_with_objective`) findings. P0=0, P1=1, P2=2 block;
+ * P3=3 is a dismissible nice-to-have only when the finding is not required by
+ * the objective.
+ */
+export const MAX_BLOCKING_PRIORITY = 2;
+
+export type ObjectiveAlignedFindingLike = {
+  readonly objective_alignment?: string;
+  readonly priority?: number | null;
+};
+
+/**
+ * Shared evidence-closure predicate for reviewer findings.
+ *
+ * A finding keeps the convergence loop open when it is objective-relevant and
+ * unresolved:
+ * - `required_by_objective` findings block at ANY priority — severity labels
+ *   alone never dismiss work the literal contract requires.
+ * - `consistent_with_objective` findings block at P0/P1/P2; P3 is a
+ *   non-blocking nice-to-have. Missing/`null` priority blocks so ambiguity
+ *   never silently approves.
+ * - `beyond_objective` / `contradicts_objective` findings never block: the
+ *   literal contract's scope controls stay authoritative.
+ * - Unknown or missing alignment blocks, so unclassified findings cannot be
+ *   waved through.
+ */
+export function findingBlocksClosure(finding: ObjectiveAlignedFindingLike): boolean {
+  const alignment = finding.objective_alignment;
+  if (alignment === "beyond_objective" || alignment === "contradicts_objective") {
+    return false;
+  }
+  if (alignment === "required_by_objective") return true;
+  if (alignment !== "consistent_with_objective") return true;
+  const priority = finding.priority;
+  if (priority === undefined || priority === null) return true;
+  return priority <= MAX_BLOCKING_PRIORITY;
+}
+
+export type ConsolidatableFinding = ObjectiveAlignedFindingLike & {
+  readonly title: string;
+  readonly code_location?: {
+    readonly absolute_file_path: string;
+  };
+};
+
+export type ConsolidatedFinding<F extends ConsolidatableFinding> = {
+  readonly finding: F;
+  readonly reviewers: readonly string[];
+  readonly blocking: boolean;
+};
+
+function findingConsolidationKey(finding: ConsolidatableFinding): string {
+  const normalizedTitle = finding.title
+    .replace(/^\s*\[P[0-3]\]\s*/iu, "")
+    .toLowerCase()
+    .replace(/\s+/gu, " ")
+    .trim();
+  return `${finding.code_location?.absolute_file_path ?? ""}::${normalizedTitle}`;
+}
+
+/**
+ * Consolidate the current review round's findings into one deduplicated batch
+ * so repair work is planned and executed batch-wise instead of one finding per
+ * turn. Findings from different reviewers that name the same location and
+ * (priority-tag-insensitive) title merge into a single entry; blocking status
+ * is the OR of the merged findings, and blocking entries sort first.
+ */
+export function consolidateFindingsBatch<F extends ConsolidatableFinding>(
+  reviews: readonly { readonly reviewer: string; readonly findings: readonly F[] }[],
+): ConsolidatedFinding<F>[] {
+  const byKey = new Map<string, { finding: F; reviewers: string[]; blocking: boolean }>();
+  for (const review of reviews) {
+    for (const finding of review.findings) {
+      const key = findingConsolidationKey(finding);
+      const existing = byKey.get(key);
+      if (existing === undefined) {
+        byKey.set(key, {
+          finding,
+          reviewers: [review.reviewer],
+          blocking: findingBlocksClosure(finding),
+        });
+        continue;
+      }
+      if (!existing.reviewers.includes(review.reviewer)) {
+        existing.reviewers.push(review.reviewer);
+      }
+      existing.blocking = existing.blocking || findingBlocksClosure(finding);
+    }
+  }
+  return [...byKey.values()].sort((a, b) => Number(b.blocking) - Number(a.blocking));
+}
+
+/**
+ * The unresolved objective-relevant findings that veto evidence closure for a
+ * review round, regardless of how many reviewers individually approved.
+ */
+export function unresolvedClosureFindings<F extends ConsolidatableFinding>(
+  reviews: readonly { readonly reviewer: string; readonly findings: readonly F[] }[],
+): ConsolidatedFinding<F>[] {
+  return consolidateFindingsBatch(reviews).filter((entry) => entry.blocking);
+}
+
+/** Short, inspectable summary of the findings that keep closure open. */
+export function closureGapSummary(
+  unresolved: readonly ConsolidatedFinding<ConsolidatableFinding>[],
+): string {
+  const preview = unresolved
+    .slice(0, 5)
+    .map((entry) => entry.finding.title)
+    .join("; ");
+  const suffix = unresolved.length > 5 ? "; …" : "";
+  return `${unresolved.length} unresolved objective-relevant blocking finding(s)${
+    preview.length > 0 ? `: ${preview}${suffix}` : ""
+  }`;
+}
+
 const PREVIEW_LIMIT = 500;
 
 function rawTextPreview(rawText: string): string | undefined {

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

@@ -50,3 +50,43 @@ export const LITERAL_OBJECTIVE_CONTRACT = [
 
 export const REVIEWER_SPEC_VS_OBJECTIVE_GUARD =
   "Do not use external spec/standard conformance alone to flag a wide trigger surface for an error condition the objective/acceptance criteria enumerate; the contract prefers loud errors over silent reinterpretation of ambiguous inputs, so classify such spec-vs-objective tension as beyond_objective rather than a blocking defect.";
+
+export const ACCEPTANCE_MATRIX_CONTRACT = [
+  "Acceptance/contract matrix:",
+  "- Before implementing, derive an observable acceptance matrix from the literal objective and acceptance criteria: one row per explicit clause, requirement, named artifact, command, gate, invariant, and deliverable, each mapped to the concrete observable check (command, test, executable scenario, artifact inspection, or state assertion) that would prove it in the current checkout.",
+  "- Record the matrix in the receipt/implementation notes on the first turn and keep it current as work proceeds; every later completion claim must map back to matrix rows with current evidence.",
+  "- The matrix inherits the literal contract's scope: do not add rows for behavior the objective/acceptance criteria do not require, and do not drop rows because they are inconvenient to prove.",
+  "",
+  "Stateful behavior modeling:",
+  "- When the work involves stateful behavior (lifecycles, sessions, caches, persisted data, protocols, retries, concurrency, or multi-step flows), model the state space explicitly before implementing: enumerate the states, the legal transitions between them, the invariants that must hold in every state, and how illegal transitions or unexpected inputs are handled.",
+  "- Tie matrix rows for stateful clauses to specific states, transitions, and invariants so their checks exercise transitions and invariant preservation, not just happy-path end states.",
+].join("\n");
+
+export const REVIEWER_INDEPENDENT_VERIFICATION_CONTRACT = [
+  "Independent verification derivation:",
+  "- Before relying on the worker receipt, worker-authored tests, or any prior reviewer output, derive your own adversarial check list from the literal objective and acceptance criteria alone: per-clause observable checks plus boundary, edge, negative, and invalid-input probes, and state/transition/invariant probes for stateful behavior.",
+  "- Execute or delegate the highest-value derived checks against the current repository state before mapping worker evidence to requirements.",
+  "- Worker-authored tests, snapshots, and receipts corroborate your derived checks; they never substitute for them. Passing worker-authored tests is circular evidence for the clauses those tests were written from.",
+  "- Keep derived checks inside the literal contract's scope; do not manufacture requirements beyond the objective/acceptance criteria.",
+].join("\n");
+
+export const REGRESSION_EVIDENCE_CONTRACT = [
+  "Durable regression evidence:",
+  "- When a defect or reviewer finding has been reproduced (observed through a command, test, or executable scenario), its fix is complete only with durable regression evidence: a focused test or repeatable check persisted in the repository's test suite where project norms allow, otherwise an exact re-runnable command with its observed output recorded in the receipt/notes.",
+  "- Treat a reproduced finding whose fix lacks durable regression evidence as unresolved; a one-off manual re-check is not durable evidence.",
+  "- Match the regression check to the reproduction: it must demonstrably cover the failing scenario (fail before the fix or provably exercise it) and pass after the fix.",
+].join("\n");
+
+export const FINDINGS_CONSOLIDATION_CONTRACT = [
+  "Consolidated findings batch:",
+  "- Treat the latest review round as one consolidated batch of findings, not a queue to repair one item per turn.",
+  "- Read every blocking finding first, group findings that share a root cause, plan the batch, then repair the full batch in this turn together with the validation and durable regression evidence each fix needs.",
+  "- Only defer a finding out of the batch when it is genuinely blocked or it contradicts the literal contract; record the reason in the receipt.",
+].join("\n");
+
+export const EVIDENCE_CLOSURE_POLICY = [
+  "Evidence closure:",
+  "- Approval is evidence closure, not reviewer agreement alone: the loop completes only when the review gate approves and no objective-relevant blocking finding from any reviewer remains unresolved.",
+  "- Severity/priority labels alone never dismiss an objective-relevant finding: a finding classified required_by_objective stays blocking at any priority (P3 included) until evidence shows it is fixed or it is reclassified against the literal contract.",
+  "- The loop is bounded: when the turn budget ends before closure, the run stops with the unresolved findings and remaining work recorded for a human instead of relabeling them away.",
+].join("\n");

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.6",
+  "version": "0.9.7-alpha.1",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/extension/workflow-prompts.ts

@@ -22,6 +22,7 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   - Only skip workflows for tiny, deterministic, low-risk answers or direct edits where stage tracking clearly costs more than it adds, typically a single-file/no-test/no-review change or a simple answer.`,
   `**Workflow discovery and lifecycle**:
   - For unfamiliar named workflows, discover with \`action: "list"\`, inspect with \`action: "get"\` or \`action: "inputs"\`, and run with \`action: "run"\`, \`workflow\`, and validated \`inputs\`; do not invent workflow names or input keys.
+  - In interactive chat, launch every workflow in the background. Named workflow launches are already detached; direct \`task\`, \`tasks\`, and \`chain\` launches must set top-level \`async: true\`. This applies only to launches, not inspection or control calls (\`status\`, \`stages\`, \`stage\`, \`transcript\`, \`send\`, \`pause\`, \`resume\`, \`interrupt\`, \`kill\`). Use foreground execution only when the user explicitly requests it or it is technically required, and tell the user before launching it.
   - Once you run a workflow, end the current turn and wait for user input or a lifecycle notice. Do not use sleep/status polling loops: key start, finish, and failure events arrive automatically. Use targeted \`status\`/\`stages\`/\`stage\` checks only when the user asks or the next step needs them, and use \`send\`/\`pause\`/\`resume\`/\`interrupt\`/\`kill\` only to answer, steer, or honor control requests.
   - For transcripts, avoid whole-file reads. Get \`sessionFile\`/\`transcriptPath\` from \`stages\` or \`stage\`, preserve the exact path and platform separators, search with \`rg\`/\`grep\`, and read small relevant ranges; use explicit \`tail\` or \`limit\` only for a bounded preview.`,
   `**Workflow authoring and handoffs**: