@bastani/atomic 0.8.31-alpha.4 → 0.9.0-alpha.1

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

@@ -0,0 +1,84 @@
+import type { WorkflowTaskResult } from "../src/shared/types.js";
+import type { ReviewDecision, ReviewRecord } from "./goal-types.js";
+
+export function reviewDecisionFromResult(result: WorkflowTaskResult): ReviewDecision | undefined {
+  return result.structured as ReviewDecision | undefined;
+}
+
+export function reviewApproved(decision: ReviewDecision): boolean {
+  const hasBlockingFindings = decision.findings.some(
+    (finding) => finding.priority !== 3,
+  );
+  return (
+    decision.stop_review_loop === true &&
+    decision.overall_correctness === "patch is correct" &&
+    decision.goal_oracle_satisfied === true &&
+    !hasBlockingFindings &&
+    decision.reviewer_error == null
+  );
+}
+
+export function reviewerErrorDecision(message: string): ReviewDecision {
+  return {
+    findings: [],
+    overall_correctness: "patch is incorrect",
+    overall_explanation:
+      "Reviewer execution failed, so the review gate cannot safely approve this turn.",
+    overall_confidence_score: 0,
+    goal_oracle_satisfied: false,
+    receipt_assessment:
+      "No reviewer receipt could be produced because reviewer execution failed.",
+    verification_remaining: "Recover reviewer execution and re-run oracle validation.",
+    stop_review_loop: false,
+    reviewer_error: {
+      kind: "reviewer_failure",
+      message,
+      attempted_recovery:
+        "Model fallbacks were configured for the reviewer stage; continuing the bounded loop without approval.",
+    },
+  };
+}
+
+export function blockerFromReviewDecision(decision: ReviewDecision): string | null {
+  const reviewerError = decision.reviewer_error;
+  if (reviewerError == null) return null;
+  if (
+    reviewerError.kind !== "dependency_unavailable" &&
+    reviewerError.kind !== "tool_failure"
+  ) {
+    return null;
+  }
+  const blocker = reviewerError.message.trim();
+  return blocker.length > 0 ? blocker : null;
+}
+
+export function reviewDecisionToRecord(args: {
+  readonly turn: number;
+  readonly reviewer: string;
+  readonly artifactPath: string;
+  readonly decision: ReviewDecision;
+}): ReviewRecord {
+  const blocker = blockerFromReviewDecision(args.decision);
+  const approved = reviewApproved(args.decision);
+  const verificationGap = args.decision.verification_remaining.trim();
+  const gaps = [
+    ...args.decision.findings.map((finding) => `${finding.title}: ${finding.body}`),
+    ...(approved || verificationGap.length === 0 ? [] : [verificationGap]),
+    ...(args.decision.reviewer_error == null
+      ? []
+      : [`${args.decision.reviewer_error.kind}: ${args.decision.reviewer_error.message}`]),
+  ];
+
+  return {
+    ...args.decision,
+    decision: approved ? "complete" : blocker === null ? "continue" : "blocked",
+    evidence: [args.decision.receipt_assessment, args.decision.overall_explanation],
+    gaps,
+    blocker,
+    confidence_score: args.decision.overall_confidence_score,
+    explanation: args.decision.overall_explanation,
+    turn: args.turn,
+    reviewer: args.reviewer,
+    artifact_path: args.artifactPath,
+  };
+}

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

@@ -0,0 +1,343 @@
+import { join } from "node:path";
+import type { WorkflowTaskResult } from "../src/shared/types.js";
+import { reviewDecisionSchema } from "./goal-schemas.js";
+import {
+  DEFAULT_BLOCKER_THRESHOLD,
+  DEFAULT_MAX_TURNS,
+  DEFAULT_REVIEW_QUORUM,
+  type GoalWorkflowOutputs,
+  type ReviewRecord,
+} from "./goal-types.js";
+import { writeReviewArtifact, writeReviewRoundArtifact } from "./goal-artifacts.js";
+import { appendLifecycleEvent, createGoalLedger, writeGoalLedger } from "./goal-ledger.js";
+import {
+  collectRemainingWork,
+  reduceGoalDecision,
+} from "./goal-reducer.js";
+import { formatReviewReport, renderFinalReport } from "./goal-reports.js";
+import {
+  reviewDecisionFromResult,
+  reviewerErrorDecision,
+  reviewDecisionToRecord,
+} from "./goal-review.js";
+import {
+  WORKER_PREFLIGHT_CONTRACT,
+  WORKER_RECEIPT_CONTRACT,
+  goalRunnerTools,
+  renderForkedGoalWorkerPrompt,
+  renderGoalContinuationPrompt,
+  renderReviewerPrompt,
+} from "./goal-prompts.js";
+
+function positiveInteger(value: number | undefined, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return fallback;
+  }
+  const floored = Math.floor(value);
+  return floored >= 1 ? floored : fallback;
+}
+
+type ForkContinuationOptions = {
+  readonly context?: "fork";
+  readonly forkFromSessionFile?: string;
+};
+
+function forkContinuationOptions(
+  sessionFile: string | undefined,
+): ForkContinuationOptions {
+  return sessionFile === undefined || sessionFile.length === 0
+    ? {}
+    : { context: "fork", forkFromSessionFile: sessionFile };
+}
+
+function normalizeBranchInput(
+  value: string | undefined,
+  fallback: string,
+): string {
+  const trimmed = value?.trim();
+  if (!trimmed) return fallback;
+
+  const looksLikeSafeGitRef =
+    /^(?!-)(?!.*(?:\.\.|@\{|\/\/|\.lock(?:\/|$)))[A-Za-z0-9][A-Za-z0-9._/@+-]*$/.test(
+      trimmed,
+    );
+  return looksLikeSafeGitRef ? trimmed : fallback;
+}
+  type GoalRunnerContext = {
+  readonly inputs: {
+    readonly objective: string;
+    readonly max_turns?: number;
+    readonly base_branch?: string;
+  };
+  task(name: string, options: object): Promise<WorkflowTaskResult>;
+  parallel(
+    steps: readonly object[],
+    options: { readonly task: string; readonly failFast: false },
+  ): Promise<WorkflowTaskResult[]>;
+};
+
+export async function runGoalWorkflow(ctx: unknown): Promise<GoalWorkflowOutputs> {
+  const goalContext = ctx as GoalRunnerContext;
+    const inputs = goalContext.inputs;
+    const objective = inputs.objective.trim();
+    if (!objective) {
+      throw new Error("goal requires an objective input.");
+    }
+
+    const maxTurns = positiveInteger(inputs.max_turns, DEFAULT_MAX_TURNS);
+    const reviewQuorum = DEFAULT_REVIEW_QUORUM;
+    const blockerThreshold = Math.min(DEFAULT_BLOCKER_THRESHOLD, maxTurns);
+    const comparisonBaseBranch = normalizeBranchInput(inputs.base_branch, "origin/main");
+    const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective);
+
+    const workerModelConfig = {
+      model: "openai-codex/gpt-5.5:medium",
+      fallbackModels: [
+          "github-copilot/gpt-5.5:medium",
+          "openai/gpt-5.5:medium",
+          "github-copilot/claude-opus-4.8 (1m):medium",
+          "anthropic/claude-opus-4-8:medium",
+          "zai/glm-5.2:medium",
+          "zai-coding-cn/glm-5.2:medium",
+          "github-copilot/gemini-3.5-flash (1m):medium",
+          "google/gemini-3.5-flash:medium",
+          "google-vertex/gemini-3.5-flash:medium"
+      ],
+      tools: goalRunnerTools,
+    };
+
+    const reviewerModelConfig = {
+      model: "anthropic/claude-fable-5:xhigh",
+      fallbackModels: [
+          "openai-codex/gpt-5.5:xhigh",
+          "github-copilot/gpt-5.5:xhigh",
+          "openai/gpt-5.5:xhigh",
+          "github-copilot/claude-opus-4.8 (1m):xhigh",
+          "anthropic/claude-opus-4-8:xhigh",
+          "zai/glm-5.2:xhigh",
+          "zai-coding-cn/glm-5.2:xhigh",
+          "github-copilot/gemini-3.5-flash (1m):high",
+          "google/gemini-3.5-flash:high",
+          "google-vertex/gemini-3.5-flash:high",
+          "github-copilot/gemini-3.1-pro-preview (1m):high",
+          "google/gemini-3.1-pro-preview:high",
+          "google-vertex/gemini-3.1-pro-preview:high",
+      ],
+      tools: goalRunnerTools,
+      schema: reviewDecisionSchema,
+    };
+
+    let latestReviews: ReviewRecord[] = [];
+    let latestReviewArtifactPaths: string[] = [];
+    let latestReviewReportPath: string | undefined;
+    let terminalRemainingWork: string | undefined;
+    let previousWorkerSessionFile: string | undefined;
+
+    for (let turn = 1; turn <= maxTurns && ledger.status === "active"; turn += 1) {
+      appendLifecycleEvent(ledger, "work_turn_started", `Worker turn ${turn} started.`, turn);
+      await writeGoalLedger(ledgerPath, ledger);
+
+      const workTurnPath = join(artifactDir, `work-turn-${turn}.md`);
+      const workerForkOptions = forkContinuationOptions(previousWorkerSessionFile);
+      const workerPrompt = workerForkOptions.forkFromSessionFile === undefined
+        ? [
+            renderGoalContinuationPrompt(
+              ledger,
+              ledgerPath,
+              turn,
+              maxTurns,
+              blockerThreshold,
+              latestReviewArtifactPaths,
+            ),
+            "",
+            "Project setup guidance:",
+            WORKER_PREFLIGHT_CONTRACT,
+            "",
+            "Guidance:",
+            WORKER_RECEIPT_CONTRACT,
+            "",
+            "Return Markdown with headings: Progress made, Files changed, Commands run, Evidence, Blockers, Ready for review, Remaining work.",
+          ].join("\n")
+        : renderForkedGoalWorkerPrompt(
+            ledger,
+            ledgerPath,
+            turn,
+            maxTurns,
+            blockerThreshold,
+            latestReviewArtifactPaths,
+          );
+
+      let worker: WorkflowTaskResult;
+      try {
+        worker = await goalContext.task(`work-turn-${turn}`, {
+          prompt: workerPrompt,
+          reads: [ledgerPath, ...latestReviewArtifactPaths],
+          output: workTurnPath,
+          outputMode: "file-only",
+          ...workerModelConfig,
+          ...workerForkOptions,
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        terminalRemainingWork = `Worker turn ${turn} failed before producing a receipt: ${message}`;
+        latestReviews = [];
+        latestReviewArtifactPaths = [];
+        latestReviewReportPath = undefined;
+        ledger.turns = turn;
+        ledger.status = "needs_human";
+        ledger.decisions.push({
+          turn,
+          decision: "needs_human",
+          reason: terminalRemainingWork,
+          complete_votes: 0,
+          review_quorum: reviewQuorum,
+        });
+        appendLifecycleEvent(ledger, "status_decided", terminalRemainingWork, turn);
+        await writeGoalLedger(ledgerPath, ledger);
+        break;
+      }
+
+      previousWorkerSessionFile = worker.sessionFile;
+      ledger.turns = turn;
+      ledger.receipts.push({
+        turn,
+        stage: worker.name ?? worker.stageName,
+        artifact_path: workTurnPath,
+        summary: `Worker receipt artifact for turn ${turn}: ${workTurnPath}`,
+      });
+      appendLifecycleEvent(ledger, "receipt_recorded", `Worker turn ${turn} receipt recorded.`, turn);
+      await writeGoalLedger(ledgerPath, ledger);
+
+      const reviewerStep = (
+        name: string,
+        reviewerRole: string,
+        focus: string,
+      ) => ({
+        name,
+        task: renderReviewerPrompt({
+          reviewerRole,
+          focus,
+          objective,
+          ledgerPath,
+          workTurnPath,
+          comparisonBaseBranch,
+          turn,
+          reviewQuorum,
+          blockerThreshold,
+        }),
+        reads: [ledgerPath, workTurnPath],
+        ...reviewerModelConfig,
+      });
+
+      const reviewerSteps = [
+        reviewerStep(
+          `completion-reviewer-${turn}`,
+          "Completion Reviewer: verify the full objective and every explicit requirement are satisfied by current state.",
+          "Map the objective to concrete requirements. Mark complete only if every required deliverable, invariant, command, artifact, and referenced spec item is proven by current evidence.",
+        ),
+        reviewerStep(
+          `evidence-reviewer-${turn}`,
+          "Evidence Reviewer: validate receipts, commands, tests, and artifacts rather than trusting summaries.",
+          "Inspect whether receipts are current, relevant, and broad enough. Mark continue when validation is missing, stale, indirect, or narrower than the objective.",
+        ),
+        reviewerStep(
+          `risk-reviewer-${turn}`,
+          "Risk Reviewer: hunt for hidden gaps, regressions, unresolved blockers, and unsafe completion claims.",
+          "Look for untested edge cases, scope shrinkage, repository convention violations, unsafe assumptions, and blockers that are real repeated impasses rather than ordinary remaining work.",
+        ),
+      ];
+
+      let reviewResults: WorkflowTaskResult[];
+      try {
+        reviewResults = await goalContext.parallel(reviewerSteps, {
+          task: objective,
+          failFast: false,
+        });
+      } 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(structured, null, 2),
+            structured,
+          },
+        ];
+      }
+
+      latestReviews = await Promise.all(reviewResults.map(async (result) => {
+        const reviewerName = result.name ?? result.stageName;
+        const parsed = reviewDecisionFromResult(result) ??
+          reviewerErrorDecision(
+            `Reviewer ${reviewerName} returned no structured decision.`,
+          );
+        const reviewArtifactPath = await writeReviewArtifact(
+          artifactDir,
+          turn,
+          reviewerName,
+          parsed,
+          result.text,
+        );
+        return reviewDecisionToRecord({
+          turn,
+          reviewer: reviewerName,
+          artifactPath: reviewArtifactPath,
+          decision: parsed,
+        });
+      }));
+      latestReviewArtifactPaths = latestReviews.map((review) => review.artifact_path);
+      latestReviewReportPath = await writeReviewRoundArtifact(
+        artifactDir,
+        turn,
+        latestReviews,
+      );
+      ledger.reviews.push(...latestReviews);
+      appendLifecycleEvent(
+        ledger,
+        "reviews_recorded",
+        `Recorded ${latestReviews.length} reviewer decisions for turn ${turn}.`,
+        turn,
+      );
+
+      const reducerOutcome = reduceGoalDecision(ledger, latestReviews, {
+        turn,
+        maxTurns,
+        reviewQuorum,
+        blockerThreshold,
+      });
+      if (reducerOutcome.blockerObservation !== undefined) {
+        ledger.blockers.push(reducerOutcome.blockerObservation);
+      }
+      ledger.decisions.push(reducerOutcome.decision);
+      ledger.status = reducerOutcome.status;
+      appendLifecycleEvent(
+        ledger,
+        "status_decided",
+        reducerOutcome.decision.reason,
+        turn,
+      );
+      await writeGoalLedger(ledgerPath, ledger);
+    }
+
+    const remainingWork = ledger.status === "complete"
+      ? "none"
+      : terminalRemainingWork ?? collectRemainingWork(latestReviews);
+    const finalReport = renderFinalReport(ledger, ledgerPath, remainingWork);
+    const reviewReport = formatReviewReport(latestReviews);
+
+    return {
+      result: finalReport,
+      status: ledger.status,
+      approved: ledger.status === "complete",
+      goal_id: ledger.goal_id,
+      objective: ledger.objective,
+      ledger_path: ledgerPath,
+      turns_completed: ledger.turns,
+      iterations_completed: ledger.turns,
+      receipts: ledger.receipts,
+      remaining_work: remainingWork,
+      review_report: reviewReport,
+      ...(latestReviewReportPath !== undefined ? { review_report_path: latestReviewReportPath } : {}),
+    };
+}

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

@@ -0,0 +1,60 @@
+import { Type } from "typebox";
+
+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 },
+        ),
+      },
+      { additionalProperties: false },
+    ),
+  },
+  { 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 },
+);
+
+export 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 },
+);

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

@@ -0,0 +1,132 @@
+export const DEFAULT_MAX_TURNS = 10;
+// Goal Runner runs three independent reviewer personas; two approvals form a majority.
+export const DEFAULT_REVIEW_QUORUM = 2;
+export const DEFAULT_BLOCKER_THRESHOLD = 3;
+export const LEDGER_FILENAME = "goal-ledger.json";
+
+export type GoalStatus = "active" | "complete" | "blocked" | "needs_human";
+export type ReviewGateDecisionValue = "complete" | "continue" | "blocked";
+
+export type WorkReceipt = {
+  readonly turn: number;
+  readonly stage: string;
+  readonly artifact_path: string;
+  readonly summary: string;
+};
+
+export type ReviewFinding = {
+  readonly title: string;
+  readonly body: string;
+  readonly confidence_score: number;
+  readonly priority?: number | null;
+  readonly code_location: {
+    readonly absolute_file_path: string;
+    readonly line_range: {
+      readonly start: number;
+      readonly end: number;
+    };
+  };
+};
+
+export type ReviewerError = {
+  readonly kind:
+    | "validation_unavailable"
+    | "dependency_unavailable"
+    | "tool_failure"
+    | "reviewer_failure";
+  readonly message: string;
+  readonly attempted_recovery: string;
+};
+
+export type ReviewDecision = {
+  readonly findings: readonly ReviewFinding[];
+  readonly overall_correctness: "patch is correct" | "patch is incorrect";
+  readonly overall_explanation: string;
+  readonly overall_confidence_score: number;
+  readonly goal_oracle_satisfied: boolean;
+  readonly receipt_assessment: string;
+  readonly verification_remaining: string;
+  readonly stop_review_loop: boolean;
+  readonly reviewer_error?: ReviewerError | null;
+};
+
+export type ReviewRecord = ReviewDecision & {
+  readonly decision: ReviewGateDecisionValue;
+  readonly evidence: readonly string[];
+  readonly gaps: readonly string[];
+  readonly blocker: string | null;
+  readonly confidence_score: number;
+  readonly explanation: string;
+  readonly turn: number;
+  readonly reviewer: string;
+  readonly artifact_path: string;
+};
+
+export type BlockerObservation = {
+  readonly turn: number;
+  readonly blocker: string;
+  readonly reviewers: readonly string[];
+};
+
+export type ReducerDecision = {
+  readonly turn: number;
+  readonly decision: "complete" | "continue" | "blocked" | "needs_human";
+  readonly reason: string;
+  readonly complete_votes: number;
+  readonly review_quorum: number;
+  readonly blocker?: string;
+};
+
+export type GoalLifecycleEvent = {
+  readonly turn: number;
+  readonly event:
+    | "created"
+    | "work_turn_started"
+    | "receipt_recorded"
+    | "reviews_recorded"
+    | "status_decided";
+  readonly status: GoalStatus;
+  readonly at: string;
+  readonly summary: string;
+};
+
+export type GoalLedger = {
+  readonly goal_id: string;
+  readonly objective: string;
+  status: GoalStatus;
+  turns: number;
+  readonly created_at: string;
+  updated_at: string;
+  receipts: WorkReceipt[];
+  reviews: ReviewRecord[];
+  blockers: BlockerObservation[];
+  decisions: ReducerDecision[];
+  lifecycle: GoalLifecycleEvent[];
+};
+
+export type ReducerOutcome = {
+  readonly status: GoalStatus;
+  readonly decision: ReducerDecision;
+  readonly blockerObservation?: BlockerObservation;
+};
+
+export type GoalWorkflowInputs = {
+  readonly objective: string;
+  readonly max_turns: number;
+  readonly base_branch: string;
+};
+
+export type GoalWorkflowOutputs = {
+  readonly result?: string;
+  readonly status?: GoalStatus;
+  readonly approved?: boolean;
+  readonly goal_id?: string;
+  readonly objective?: string;
+  readonly ledger_path?: string;
+  readonly turns_completed?: number;
+  readonly iterations_completed?: number;
+  readonly receipts?: WorkReceipt[];
+  readonly remaining_work?: string;
+  readonly review_report?: string;
+  readonly review_report_path?: string;
+};