@bastani/atomic 0.8.29-alpha.2 → 0.8.29-alpha.4

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

@@ -13,7 +13,7 @@ import { join } from "node:path";
 import { defineWorkflow } from "../src/workflows/define-workflow.js";
 import { Type } from "typebox";
 import type { WorkflowTaskResult } from "../src/shared/types.js";
-import { WORKER_PREFLIGHT_CONTRACT } from "./shared-prompts.js";
+import { E2E_VERIFICATION_GUIDANCE, WORKER_PREFLIGHT_CONTRACT } from "./shared-prompts.js";
 
 const DEFAULT_MAX_TURNS = 10;
 // Goal Runner runs three independent reviewer personas; two approvals form a majority.
@@ -135,108 +135,64 @@ function positiveInteger(value: number | undefined, fallback: number): number {
   return floored >= 1 ? floored : fallback;
 }
 
-const reviewDecisionSchema = {
-  type: "object",
-  additionalProperties: false,
-  required: [
-    "findings",
-    "overall_correctness",
-    "overall_explanation",
-    "overall_confidence_score",
-    "goal_oracle_satisfied",
-    "receipt_assessment",
-    "verification_remaining",
-    "stop_review_loop",
-  ],
-  properties: {
-    findings: {
-      type: "array",
-      items: {
-        type: "object",
-        additionalProperties: false,
-        required: ["title", "body", "confidence_score", "code_location"],
-        properties: {
-          title: { type: "string" },
-          body: { type: "string" },
-          confidence_score: { type: "number", minimum: 0, maximum: 1 },
-          priority: { type: ["integer", "null"], minimum: 0, maximum: 3 },
-          code_location: {
-            type: "object",
-            additionalProperties: false,
-            required: ["absolute_file_path", "line_range"],
-            properties: {
-              absolute_file_path: { type: "string" },
-              line_range: {
-                type: "object",
-                additionalProperties: false,
-                required: ["start", "end"],
-                properties: {
-                  start: { type: "integer", minimum: 1 },
-                  end: { type: "integer", minimum: 1 },
-                },
-              },
-            },
+const reviewFindingSchema = Type.Object(
+  {
+    title: Type.String(),
+    body: Type.String(),
+    confidence_score: Type.Number({ minimum: 0, maximum: 1 }),
+    priority: Type.Optional(
+      Type.Union([Type.Integer({ minimum: 0, maximum: 3 }), Type.Null()]),
+    ),
+    code_location: Type.Object(
+      {
+        absolute_file_path: Type.String(),
+        line_range: Type.Object(
+          {
+            start: Type.Integer({ minimum: 1 }),
+            end: Type.Integer({ minimum: 1 }),
           },
-        },
+          { additionalProperties: false },
+        ),
       },
-    },
-    overall_correctness: {
-      type: "string",
-      enum: ["patch is correct", "patch is incorrect"],
-    },
-    overall_explanation: { type: "string" },
-    overall_confidence_score: { type: "number", minimum: 0, maximum: 1 },
-    goal_oracle_satisfied: { type: "boolean" },
-    receipt_assessment: { type: "string" },
-    verification_remaining: { type: "string" },
-    stop_review_loop: { type: "boolean" },
-    reviewer_error: {
-      anyOf: [
-        { type: "null" },
-        {
-          type: "object",
-          additionalProperties: false,
-          required: ["kind", "message", "attempted_recovery"],
-          properties: {
-            kind: {
-              type: "string",
-              enum: [
-                "validation_unavailable",
-                "dependency_unavailable",
-                "tool_failure",
-                "reviewer_failure",
-              ],
-            },
-            message: { type: "string" },
-            attempted_recovery: { type: "string" },
-          },
-        },
-      ],
-    },
+      { additionalProperties: false },
+    ),
   },
-} as const;
-
-const reviewDecisionTool = {
-  name: "review_decision",
-  label: "Review Decision",
-  description:
-    "Emit the final structured review verdict after inspecting the patch.",
-  promptSnippet: "Emit the final review verdict as structured data",
-  promptGuidelines: [
-    "Call review_decision after completing review investigation and validation.",
-    "This is a terminating structured-output tool; do not emit another assistant response after calling it.",
-  ],
-  parameters: reviewDecisionSchema,
-  async execute(_toolCallId: string, params: ReviewDecision) {
-    return {
-      content: [
-        { type: "text" as const, text: JSON.stringify(params, null, 2) },
-      ],
-      details: params,
-      terminate: true,
-    };
+  { additionalProperties: false },
+);
+
+const reviewerErrorSchema = Type.Object(
+  {
+    kind: Type.Union([
+      Type.Literal("validation_unavailable"),
+      Type.Literal("dependency_unavailable"),
+      Type.Literal("tool_failure"),
+      Type.Literal("reviewer_failure"),
+    ]),
+    message: Type.String(),
+    attempted_recovery: Type.String(),
   },
-};
+  { additionalProperties: false },
+);
+
+const reviewDecisionSchema = Type.Object(
+  {
+    findings: Type.Array(reviewFindingSchema),
+    overall_correctness: Type.Union([
+      Type.Literal("patch is correct"),
+      Type.Literal("patch is incorrect"),
+    ]),
+    overall_explanation: Type.String(),
+    overall_confidence_score: Type.Number({ minimum: 0, maximum: 1 }),
+    goal_oracle_satisfied: Type.Boolean(),
+    receipt_assessment: Type.String(),
+    verification_remaining: Type.String(),
+    stop_review_loop: Type.Boolean(),
+    reviewer_error: Type.Optional(
+      Type.Union([Type.Null(), reviewerErrorSchema]),
+    ),
+  },
+  { additionalProperties: false },
+);
 
 const GOAL_CONTINUATION_REFERENCE = [
   "Continuation behavior:",
@@ -358,26 +314,8 @@ function normalizeBranchInput(
   return looksLikeSafeGitRef ? trimmed : fallback;
 }
 
-function parseReviewDecision(text: string): ReviewDecision | undefined {
-  try {
-    const parsed = JSON.parse(text) as Partial<ReviewDecision>;
-    if (
-      parsed.overall_correctness !== "patch is correct" &&
-      parsed.overall_correctness !== "patch is incorrect"
-    ) {
-      return undefined;
-    }
-    if (!Array.isArray(parsed.findings)) return undefined;
-    if (typeof parsed.stop_review_loop !== "boolean") return undefined;
-    if (typeof parsed.overall_explanation !== "string") return undefined;
-    if (typeof parsed.overall_confidence_score !== "number") return undefined;
-    if (typeof parsed.goal_oracle_satisfied !== "boolean") return undefined;
-    if (typeof parsed.receipt_assessment !== "string") return undefined;
-    if (typeof parsed.verification_remaining !== "string") return undefined;
-    return parsed as ReviewDecision;
-  } catch {
-    return undefined;
-  }
+function reviewDecisionFromResult(result: WorkflowTaskResult): ReviewDecision | undefined {
+  return result.structured as ReviewDecision | undefined;
 }
 
 function reviewApproved(decision: ReviewDecision): boolean {
@@ -589,6 +527,7 @@ function renderGoalContinuationPrompt(
       ].join("\n"),
     ],
     ["goal_guidelines", GOAL_CONTINUATION_REFERENCE],
+    ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
   ]);
 }
 
@@ -619,6 +558,7 @@ function renderForkedGoalWorkerPrompt(
         renderLatestReviewArtifacts(latestReviewArtifactPaths),
       ].join("\n"),
     ],
+    ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
   ]);
 }
 
@@ -795,6 +735,7 @@ function renderReviewerPrompt(args: {
     ["goal_framework", GOAL_METHOD_REFERENCE],
     ["goal_guidelines", GOAL_CONTINUATION_REFERENCE],
     ["auditability", RECEIPT_EXPECTATIONS],
+    ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
     [
       "goal_context",
       [
@@ -829,8 +770,6 @@ function renderReviewerPrompt(args: {
       [
         "Inspect the actual diff/repository state rather than trusting stage summaries.",
         "Identify the smallest relevant validation set from repository evidence: targeted tests, lint, typecheck, build, generated-artifact checks, CI-equivalent scripts, or user-flow proof.",
-        "When practical, include an end-to-end QA check that exercises the app the way a user would: use the tmux skill for terminal app environments and browser for web app environments.",
-        "For web app environments, capture a screenshot as a certificate of correct completion when the UI state proves the objective; for terminal app environments, capture the terminal window/output that shows proof of correctness.",
         "Run or delegate focused validation when it is necessary to distinguish a real bug from a hunch.",
         "If tests or typechecks fail because dependencies are missing, install/download the missing dependencies with the repo's documented package manager instead of bypassing the check.",
         "If validation cannot be completed after reasonable recovery, record the limitation in overall_explanation and reviewer_error; do not use missing dependencies as a reason to approve.",
@@ -915,37 +854,9 @@ function renderReviewerPrompt(args: {
     [
       "output_format",
       [
-        "You have a structured-output tool named review_decision. Use it after your investigation and validation attempts.",
-        "The tool terminates the turn and provides the structured data; do not emit a separate final assistant response after calling it.",
-        "The review gate decides completion only by parsing the JSON object returned by this tool; invalid JSON, missing fields, reviewer_error, or stop_review_loop=false are treated as not approved for safety.",
         "Set stop_review_loop=true only when there are no P0/P1/P2 findings, overall_correctness is patch is correct, goal_oracle_satisfied is true, no objective-relevant verification remains, and reviewer_error is null/omitted.",
         "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.",
-        "If you hit a reviewer/tool/validation error, still return the object with stop_review_loop=false and reviewer_error populated instead of pretending the patch is approved.",
-        [
-          "The review_decision tool schema is authoritative; do not copy a hand-written JSON blob into the final response. Here is an example output:",
-          "{",
-          '  "findings": [',
-          "    {",
-          '      "title": "<≤ 80 chars, imperative, starts with [P0]/[P1]/[P2]/[P3]>",',
-          '      "body": "<one paragraph of valid Markdown explaining why this is a problem; cite files/lines/functions>",',
-          '      "confidence_score": <float 0.0-1.0>,',
-          '      "priority": <int 0-3 or null>,',
-          '      "code_location": {',
-          '        "absolute_file_path": "<absolute file path>",',
-          '        "line_range": {"start": <int>, "end": <int>}',
-          "      }",
-          "    }",
-          "  ],",
-          '  "overall_correctness": "patch is correct" | "patch is incorrect",',
-          '  "overall_explanation": "<1-3 sentence explanation justifying the verdict>",',
-          '  "overall_confidence_score": <float 0.0-1.0>,',
-          '  "goal_oracle_satisfied": <boolean>,',
-          '  "receipt_assessment": "<how receipts/current evidence map to the verification oracle>",',
-          '  "verification_remaining": "<oracle-relevant verification still missing, or none>",',
-          '  "stop_review_loop": <boolean>,',
-          '  "reviewer_error": null | {"kind": "validation_unavailable" | "dependency_unavailable" | "tool_failure" | "reviewer_failure", "message": "<what failed>", "attempted_recovery": "<what you tried>"}',
-          "}",
-        ].join("\n"),
+        "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"),
     ],
   ]);
@@ -1080,8 +991,8 @@ export default defineWorkflow("goal")
           "github-copilot/claude-opus-4.8:xhigh",
           "anthropic/claude-opus-4-8:xhigh"
       ],
-      tools: [...goalRunnerTools, reviewDecisionTool.name],
-      customTools: [reviewDecisionTool],
+      tools: goalRunnerTools,
+      schema: reviewDecisionSchema,
     };
 
     let latestReviews: ReviewRecord[] = [];
@@ -1212,20 +1123,22 @@ export default defineWorkflow("goal")
         });
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        const structured = reviewerErrorDecision(message);
         reviewResults = [
           {
             name: `reviewer-error-${turn}`,
             stageName: `reviewer-error-${turn}`,
-            text: JSON.stringify(reviewerErrorDecision(message), null, 2),
+            text: JSON.stringify(structured, null, 2),
+            structured,
           },
         ];
       }
 
       latestReviews = await Promise.all(reviewResults.map(async (result) => {
         const reviewerName = result.name ?? result.stageName;
-        const parsed = parseReviewDecision(result.text) ??
+        const parsed = reviewDecisionFromResult(result) ??
           reviewerErrorDecision(
-            `Reviewer ${reviewerName} returned invalid structured JSON.`,
+            `Reviewer ${reviewerName} returned no structured decision.`,
           );
         const reviewArtifactPath = await writeReviewArtifact(
           artifactDir,

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

@@ -83,6 +83,8 @@ export type RalphWorkflowOutputs = WorkflowOutputValues & {
   readonly result?: string;
   readonly plan?: string;
   readonly plan_path?: string;
+  readonly research?: string;
+  readonly research_path?: string;
   readonly implementation_notes_path?: string;
   readonly pr_report?: string;
   readonly approved?: boolean;

package/dist/builtin/workflows/builtin/open-claude-design.ts

@@ -115,115 +115,49 @@ type ExportGateDecision = {
   readonly blocking_findings: readonly ExportGateFinding[];
 };
 
-const refinementDecisionSchema = {
-  type: "object",
-  additionalProperties: false,
-  required: ["ready_for_export", "rationale", "required_changes"],
-  properties: {
-    ready_for_export: { type: "boolean" },
-    rationale: { type: "string" },
-    required_changes: { type: "array", items: { type: "string" } },
+const refinementDecisionSchema = Type.Object(
+  {
+    ready_for_export: Type.Boolean(),
+    rationale: Type.String(),
+    required_changes: Type.Array(Type.String()),
   },
-} as const;
+  { additionalProperties: false },
+);
 
-const refinementDecisionTool = {
-  name: "refinement_decision",
-  label: "Refinement Decision",
-  description: "Emit the structured design refinement decision.",
-  promptSnippet: "Emit the final refinement decision as structured data",
-  promptGuidelines: [
-    "Call refinement_decision after inspecting the preview and deciding whether another refinement iteration is needed.",
-    "This is a terminating structured-output tool; do not emit another assistant response after calling it.",
-  ],
-  parameters: refinementDecisionSchema,
-  async execute(_toolCallId: string, params: RefinementDecision) {
-    return {
-      content: [{ type: "text" as const, text: JSON.stringify(params, null, 2) }],
-      details: params,
-      terminate: true,
-    };
+const exportGateFindingSchema = Type.Object(
+  {
+    finding: Type.String(),
+    evidence: Type.String(),
+    why_blocking: Type.String(),
+    must_fix_action: Type.String(),
+    severity: Type.Literal("P0"),
   },
-};
+  { additionalProperties: false },
+);
 
-const exportGateDecisionSchema = {
-  type: "object",
-  additionalProperties: false,
-  required: ["has_blocking_findings", "rationale", "blocking_findings"],
-  properties: {
-    has_blocking_findings: { type: "boolean" },
-    rationale: { type: "string" },
-    blocking_findings: {
-      type: "array",
-      items: {
-        type: "object",
-        additionalProperties: false,
-        required: ["finding", "evidence", "why_blocking", "must_fix_action", "severity"],
-        properties: {
-          finding: { type: "string" },
-          evidence: { type: "string" },
-          why_blocking: { type: "string" },
-          must_fix_action: { type: "string" },
-          severity: { type: "string", enum: ["P0"] },
-        },
-      },
-    },
+const exportGateDecisionSchema = Type.Object(
+  {
+    has_blocking_findings: Type.Boolean(),
+    rationale: Type.String(),
+    blocking_findings: Type.Array(exportGateFindingSchema),
   },
-} as const;
+  { additionalProperties: false },
+);
 
-const exportGateDecisionTool = {
-  name: "export_gate_decision",
-  label: "Export Gate Decision",
-  description: "Emit the structured pre-export gate decision.",
-  promptSnippet: "Emit the final export gate decision as structured data",
-  promptGuidelines: [
-    "Call export_gate_decision after auditing the preview for blocking findings.",
-    "This is a terminating structured-output tool; do not emit another assistant response after calling it.",
-  ],
-  parameters: exportGateDecisionSchema,
-  async execute(_toolCallId: string, params: ExportGateDecision) {
-    return {
-      content: [{ type: "text" as const, text: JSON.stringify(params, null, 2) }],
-      details: params,
-      terminate: true,
-    };
-  },
-};
-
-function parseRefinementDecision(text: string): RefinementDecision {
-  const parsed = JSON.parse(text) as Partial<RefinementDecision>;
-  if (typeof parsed.ready_for_export !== "boolean") {
-    throw new Error("open-claude-design refinement decision missing ready_for_export.");
+function refinementDecisionFromResult(result: WorkflowTaskResult): RefinementDecision {
+  const decision = result.structured as RefinementDecision | undefined;
+  if (!decision) {
+    throw new Error("open-claude-design refinement decision missing structured result.");
   }
-  return {
-    ready_for_export: parsed.ready_for_export,
-    rationale: typeof parsed.rationale === "string" ? parsed.rationale : "",
-    required_changes: Array.isArray(parsed.required_changes)
-      ? parsed.required_changes.filter((item): item is string => typeof item === "string")
-      : [],
-  };
+  return decision;
 }
 
-function parseExportGateDecision(text: string): ExportGateDecision {
-  const parsed = JSON.parse(text) as Partial<ExportGateDecision>;
-  if (typeof parsed.has_blocking_findings !== "boolean") {
-    throw new Error("open-claude-design export gate decision missing has_blocking_findings.");
+function exportGateDecisionFromResult(result: WorkflowTaskResult): ExportGateDecision {
+  const decision = result.structured as ExportGateDecision | undefined;
+  if (!decision) {
+    throw new Error("open-claude-design export gate decision missing structured result.");
   }
-  return {
-    has_blocking_findings: parsed.has_blocking_findings,
-    rationale: typeof parsed.rationale === "string" ? parsed.rationale : "",
-    blocking_findings: Array.isArray(parsed.blocking_findings)
-      ? parsed.blocking_findings.filter(
-          (item): item is ExportGateFinding =>
-            typeof item === "object" &&
-            item !== null &&
-            "finding" in item &&
-            "evidence" in item &&
-            "why_blocking" in item &&
-            "must_fix_action" in item &&
-            "severity" in item,
-        )
-      : [],
-  };
+  return decision;
 }
 
 function joinResults(results: readonly WorkflowTaskResult[]): string {
@@ -481,13 +415,13 @@ export default defineWorkflow("open-claude-design")
     };
     const refinementDecisionConfig = {
       ...designModelConfig,
-      tools: [...READ_ONLY_TOOLS, refinementDecisionTool.name],
-      customTools: [refinementDecisionTool],
+      tools: [...READ_ONLY_TOOLS],
+      schema: refinementDecisionSchema,
     };
     const exportGateDecisionConfig = {
       ...designModelConfig,
-      tools: [...READ_ONLY_TOOLS, exportGateDecisionTool.name],
-      customTools: [exportGateDecisionTool],
+      tools: [...READ_ONLY_TOOLS],
+      schema: exportGateDecisionSchema,
     };
 
     let designSystem: string;
@@ -850,7 +784,7 @@ export default defineWorkflow("open-claude-design")
             [
               "1. If a previous `preview-display-*` step captured annotated user feedback or notes, honor them as the primary signal.",
               "2. Otherwise, you may inspect the HTML file at preview_path directly (read it from disk) and run an impeccable `critique` against it.",
-              "3. Decide whether the current design is ready for export using the refinement_decision structured-output tool.",
+              "3. Decide whether the current design is ready for export.",
               "4. If refinement is still needed, put specific changes in required_changes ordered by user value and implementation risk.",
               "5. Never request changes that contradict DESIGN.md unless you explicitly identify and explain the conflict.",
             ].join("\n"),
@@ -858,7 +792,6 @@ export default defineWorkflow("open-claude-design")
           [
             "output_format",
             [
-              "Call the refinement_decision tool after your inspection.",
               "Set ready_for_export=true only when the current preview needs no further refinement before export.",
               "Set ready_for_export=false and populate required_changes when another polish iteration is needed.",
             ].join("\n"),
@@ -868,7 +801,7 @@ export default defineWorkflow("open-claude-design")
         ...refinementDecisionConfig,
       });
 
-      const feedbackDecision = parseRefinementDecision(feedback.text);
+      const feedbackDecision = refinementDecisionFromResult(feedback);
       if (feedbackDecision.ready_for_export) {
         approvedForExport = true;
         break;
@@ -1058,14 +991,13 @@ export default defineWorkflow("open-claude-design")
             "1. Read the HTML at preview_path and score it across all five audit dimensions.",
             "2. Scan for banned anti-patterns, accessibility blockers, severe visual regressions, missing critical states, and handoff gaps.",
             "3. Only mark findings as blocking when they would materially harm implementation or user experience (impeccable P0 severity).",
-            "4. Decide whether export is blocked using the export_gate_decision structured-output tool.",
+            "4. Decide whether export is blocked.",
             "5. Every blocking finding must include selector-level evidence and a must-fix action.",
           ].join("\n"),
         ],
         [
-          "output_format",
+          "decision_rules",
           [
-            "Call the export_gate_decision tool after the audit.",
             "Set has_blocking_findings=true only when one or more P0 findings block export.",
             "Populate blocking_findings with every blocking P0 issue; leave it empty when export is safe.",
           ].join("\n"),
@@ -1075,7 +1007,7 @@ export default defineWorkflow("open-claude-design")
       ...exportGateDecisionConfig,
     });
 
-    const exportGateDecision = parseExportGateDecision(preExport.text);
+    const exportGateDecision = exportGateDecisionFromResult(preExport);
     if (exportGateDecision.has_blocking_findings) {
       const forcedFix = await ctx.task("forced-fix", {
         prompt: taggedPrompt([

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

@@ -20,6 +20,8 @@ export type RalphWorkflowOutputs = WorkflowOutputValues & {
   readonly result?: string;
   readonly plan?: string;
   readonly plan_path?: string;
+  readonly research?: string;
+  readonly research_path?: string;
   readonly implementation_notes_path?: string;
   readonly pr_report?: string;
   readonly approved?: boolean;