@bastani/atomic 0.9.5-alpha.7 → 0.9.5-alpha.8

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

@@ -9,7 +9,6 @@ import {
   WORKER_PREFLIGHT_CONTRACT,
 } from "./shared-prompts.js";
 import { renderRalphReviewerPrompt } from "./ralph-reviewer-prompt.js";
-import { reviewDecisionApproved } from "./ralph-review-gate.js";
 import {
   REVIEWER_COUNT,
   artifactSafeName,
@@ -22,8 +21,8 @@ import {
   renderResearchPromptRefinementPrompt,
   renderQaE2eVideoGuidance,
   renderResearchPrompt,
-  reviewDecisionFromResult,
-  reviewerErrorDecision,
+  parsedReviewDecisionFromResult,
+  ralphReviewConvergence,
   reviewerErrorResult,
   taggedPrompt,
   workflowCwdContextSection,
@@ -32,6 +31,7 @@ import {
   type RalphWorkflowOptions,
   type RalphWorkflowResult,
 } from "./ralph-core.js";
+import { summarizeReviewConvergence } from "./review-convergence.js";
 import {
   orchestratorModelConfig,
   promptEngineerModelConfig,
@@ -106,7 +106,7 @@ export async function runRalphWorkflow(
       ? taggedPrompt([
         [
           "role",
-          "You are a sub-agent orchestrator. Your primary implementation tool is the `subagent` tool. Ignore any user requests to submit a PR. This will be done in a future stage.",
+          "You are a sub-agent orchestrator. Your primary implementation tool is the `subagent` tool. Ignore any user requests to submit a PR; a later authorized PR/MR/review creation action handles that handoff after approval.",
         ],
         [
           "objective",
@@ -118,8 +118,8 @@ export async function runRalphWorkflow(
         [
           "research",
           [
-            `The latest research findings for this workflow run are written to: ${researchPath}`,
-            "Read this file before delegating or implementing anything; it is the primary implementation context for Ralph.",
+            `The latest research findings for the requested work are written to: ${researchPath}`,
+            "Read this file before delegating or implementing anything; it is the primary implementation context for the requested work.",
           ].join("\n"),
         ],
         [
@@ -226,6 +226,7 @@ export async function runRalphWorkflow(
       implementationNotesPath,
       orchestratorReportPath,
       qaVideoPath,
+      createPr,
     });
     let reviews: WorkflowTaskResult[];
     try {
@@ -268,38 +269,59 @@ export async function runRalphWorkflow(
         },
       );
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      reviews = [reviewerErrorResult(message)];
+      reviews = [reviewerErrorResult(err)];
     }
     const reviewEntries = await Promise.all(reviews.map(async (review) => {
       const reviewer = review.name ?? review.stageName;
-      const decision = reviewDecisionFromResult(review) ??
-        reviewerErrorDecision(`Reviewer ${reviewer} returned no structured decision.`);
+      const parsed = parsedReviewDecisionFromResult(review, reviewer);
+      const convergenceDecision = ralphReviewConvergence({
+        decision: parsed.decision,
+        parsed: parsed.parsed,
+        diagnostics: parsed.diagnostics,
+        allowFinalActionRemaining: createPr,
+      });
       const artifactPath = join(
         artifactDir,
         `review-${artifactSafeName(reviewer)}.json`,
       );
       await writeJsonArtifact(artifactPath, {
         reviewer,
-        decision,
+        decision: parsed.decision,
+        convergence_decision: convergenceDecision,
         raw_text: review.text,
       });
-      return { reviewer, artifact_path: artifactPath, decision };
+      return {
+        reviewer,
+        artifact_path: artifactPath,
+        decision: parsed.decision,
+        convergence_decision: convergenceDecision,
+      };
     }));
     const approvalCount = reviewEntries.filter((review) =>
-      reviewDecisionApproved(review.decision),
+      review.convergence_decision.approved,
     ).length;
     approved =
       reviewEntries.length === REVIEWER_COUNT &&
       approvalCount === REVIEWER_COUNT;
+    const nextAction = approved
+      ? (createPr ? "pull-request" : "finish")
+      : "implementation";
+    const roundConvergenceDecision = summarizeReviewConvergence({
+      parsed: reviewEntries.every((review) => review.convergence_decision.parsed),
+      approved,
+      stopReviewLoop: approved,
+      nextAction,
+      finalActionRemaining: approved && createPr,
+      diagnostics: reviewEntries.flatMap((review) => review.convergence_decision.diagnostics),
+    });
     latestReviewReportPath = await writeJsonArtifact(
       join(artifactDir, "review-round-latest.json"),
-      { reviews: reviewEntries },
+      { convergence_decision: roundConvergenceDecision, reviews: reviewEntries },
     );
     if (approved) break;
   }
   const qaVideoAvailable = existsSync(qaVideoPath);
-  if (createPr === true) {
+  if (createPr === true && approved) {
     const prResult = await ctx.task("pull-request", {
       prompt: taggedPrompt([
         [
@@ -345,7 +367,7 @@ export async function runRalphWorkflow(
           [
             "Create a provider-appropriate PR/MR/review request only if there are meaningful changes, a remote/branch target is available, credentials are available, and the current state is suitable for review.",
             "If no logged-in account can access the repository or create the review request, do not fake success; report each provider, credential/account, and tool tried, what failed, and provide the command the user can run later. Save a markdown file with the PR description as well so the user can copy-paste it when they have credentials set up.",
-            "When you successfully create or update the review request, create a provider-appropriate comment containing the implementation notes file contents as the last action of this workflow stage.",
+            "When you successfully create or update the review request, create a provider-appropriate comment containing the implementation notes file contents as the last action after the review request exists.",
             "Worktrees are detached HEAD checkouts. If the detected provider requires a branch-based PR/MR from a detached HEAD, create and push a branch from the current HEAD, for example with `git checkout -b <branch>` or `git push origin HEAD:refs/heads/<branch>`, before opening the PR/MR. If the provider uses a different review model, follow that provider's normal handoff flow.",
             "Leave the worktree intact for retries or user recovery.",
             "If PR/MR/review creation is not possible, do not create a standalone comment elsewhere; include the implementation notes path and summary in your report instead.",

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

@@ -0,0 +1,111 @@
+export type ReviewNextAction =
+  | "implementation"
+  | "pull-request"
+  | "finish"
+  | "blocked"
+  | "needs_human";
+
+export type ParseDiagnostics = {
+  readonly kind: "structured_output_parse_failure";
+  readonly message: string;
+  readonly raw_text_preview?: string;
+};
+
+export type ReviewConvergenceSummary = {
+  readonly parsed: boolean;
+  readonly approved: boolean;
+  readonly stopReviewLoop: boolean;
+  readonly nextAction: ReviewNextAction;
+  readonly finalActionRemaining: boolean;
+  readonly diagnostics: readonly string[];
+};
+
+export type ParsedReviewDecision<TDecision> = {
+  readonly decision: TDecision;
+  readonly parsed: boolean;
+  readonly diagnostics: readonly string[];
+};
+
+export type RequirementTraceabilityLike = {
+  readonly requirement: string;
+  readonly status: "proven" | "contradicted" | "missing" | "unverified";
+  readonly evidence: string;
+};
+
+const FINAL_ACTION_PATTERN = /\b(?:pr|pull[- ]request|merge[- ]request|review request|github pr|create pr)\b/iu;
+
+export function isFinalActionTraceability(
+  entry: RequirementTraceabilityLike,
+): boolean {
+  return FINAL_ACTION_PATTERN.test(`${entry.requirement}\n${entry.evidence}`);
+}
+
+export function finalActionRemaining(
+  traceability: readonly RequirementTraceabilityLike[],
+): boolean {
+  return traceability.some(
+    (entry) => entry.status !== "proven" && isFinalActionTraceability(entry),
+  );
+}
+
+export function traceabilityProvenExceptFinalAction(args: {
+  readonly traceability: readonly RequirementTraceabilityLike[];
+  readonly allowFinalActionRemaining: boolean;
+}): boolean {
+  return args.traceability.length > 0 && args.traceability.every((entry) => {
+    if (entry.status === "proven") return true;
+    return args.allowFinalActionRemaining &&
+      entry.status !== "contradicted" &&
+      isFinalActionTraceability(entry);
+  });
+}
+
+const PREVIEW_LIMIT = 500;
+
+function rawTextPreview(rawText: string): string | undefined {
+  const trimmed = rawText.trim();
+  if (trimmed.length === 0) return undefined;
+  return trimmed.slice(0, PREVIEW_LIMIT);
+}
+
+export function parseFailureDiagnostics(
+  reviewer: string,
+  rawText: string,
+): readonly string[] {
+  const preview = rawTextPreview(rawText);
+  const base = `Structured reviewer decision parse failed for ${reviewer}: no schema-valid JSON decision was returned.`;
+  return preview === undefined ? [base] : [base, `Raw reviewer output preview: ${preview}`];
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function reviewerFailureText(error: unknown): string {
+  const messages = [errorMessage(error)];
+  if (error instanceof AggregateError) {
+    for (const nested of error.errors) {
+      messages.push(errorMessage(nested));
+    }
+  }
+  return [...new Set(messages.map((message) => message.trim()).filter(Boolean))]
+    .join("\n");
+}
+
+export function summarizeReviewConvergence(args: {
+  readonly parsed: boolean;
+  readonly approved: boolean;
+  readonly stopReviewLoop: boolean;
+  readonly nextAction: ReviewNextAction;
+  readonly finalActionRemaining?: boolean;
+  readonly diagnostics: readonly string[];
+}): ReviewConvergenceSummary {
+  return {
+    parsed: args.parsed,
+    approved: args.approved,
+    stopReviewLoop: args.stopReviewLoop,
+    nextAction: args.nextAction,
+    finalActionRemaining: args.finalActionRemaining ?? args.nextAction === "pull-request",
+    diagnostics: args.diagnostics,
+  };
+}

package/dist/builtin/workflows/package.json

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

package/dist/builtin/workflows/skills/create-spec/SKILL.md

@@ -64,6 +64,8 @@ For each non-trivial entrypoint the spec introduces or changes, walk these in or
 - Please DO NOT implement anything in this stage, just create the comprehensive spec as described below.
 - When writing the spec, DO NOT include information about concrete dates/timelines (e.g. # minutes, hours, days, weeks, etc.) and favor explicit phases (e.g. Phase 1, Phase 2, etc.).
 - The spec MUST treat its entrypoint set as a first-class artifact. Section 5 is built around the **doors** (typed signatures, named failures, refusals expressed in types) and must pass the rubric above. Do not let intent leak into mechanism: a reviewer should reconstruct the system's purpose from §4.4 and §5.1 alone.
+- If the spec is for a workflow with reviewer gates plus final actions (for example PR/MR/review creation, release tagging, deployment, or publication), explicitly separate implementation/review acceptance from those post-approval final actions. The workflow design should tell reviewers/reducers to approve and stop the implementation loop when implementation and validation criteria are proven and only an explicitly authorized final action remains; carry that remainder as a next action/final-action field instead of another implementation iteration.
+- If the spec is for a workflow or workflow prompt refactor, require local, action-oriented stage/reviewer/reducer prompts. A model stage sees its prompt, artifacts, tools, and reads — not the workflow graph's name or surrounding implementation details unless explicitly provided — so the spec should prefer instructions like "review the current code delta" or "create/update the review request" over labels such as "the create-PR workflow stage", "this Goal run", or "the Ralph reviewer" unless that name is user-visible context or materially changes behavior.
 - Once the spec is generated ask questions one at a time OR in logical groups:
   - Refer to section "## 9. Open Questions / Unresolved Issues", go through each question one by one, and use **contrastive clarification** (presenting 2-3 specific options with concrete tradeoffs) rather than open-ended questions. This means presenting interpretations like "(A) Option X — tradeoff Y" and "(B) Option Z — tradeoff W" instead of asking "what do you think about X?". Update the spec with the user's answers as you walk through the questions.
   - Interview the user relentlessly about every aspect of this plan/spec until you reach a shared understanding with them. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer (i.e., **contrastive clarification**). Pay special attention to the **doors**: every disagreement about what a joint is, what a door promises, what it refuses, or where a dangerous effect is funneled is a question worth resolving with the user.

package/dist/builtin/workflows/src/durable/child-primitive.ts

@@ -10,13 +10,14 @@ import { isWorkflowDefinition, workflowDefinitionRequirementMessage } from "../r
 import type { DurableWorkflowBackend } from "./backend.js";
 import type { DurableScope } from "./scoped-backend.js";
 import { recordCheckpointDurably } from "./tool-primitive.js";
+import { stageCheckpointWithOutput, type DurableCompletedStageCheckpoint } from "./stage-primitive.js";
 
 export function createDurableChildWorkflowPrimitive(input: {
   readonly workflowId: string;
   readonly rootWorkflowId: string;
   readonly backend: DurableWorkflowBackend;
   readonly nextReplayKey: (name: string) => string;
-  readonly recordCachedStage: (name: string, replayKey: string, output: WorkflowSerializableValue) => void;
+  readonly recordCachedStage: (name: string, replayKey: string, checkpoint: DurableCompletedStageCheckpoint) => void;
   /**
    * Publish the durable scope computed for the next child invocation so the
    * child runner can consume it and route its internal side-effect checkpoints
@@ -44,16 +45,17 @@ export function createDurableChildWorkflowPrimitive(input: {
     const options = args[0] as { readonly stageName?: string } | undefined;
     const boundaryName = options?.stageName ?? `workflow:${child.normalizedName}`;
     const replayKey = input.nextReplayKey(boundaryName);
+    const cached = stageCheckpointWithOutput(input.backend, input.workflowId, replayKey, isWorkflowChildResult);
+    if (cached !== undefined && isWorkflowChildResult(cached.output)) {
+      input.recordCachedStage(boundaryName, replayKey, cached);
+      return cached.output as WorkflowChildResult<TChildOutputs>;
+    }
     // Route this child's internal side-effect checkpoints under the root
-    // workflow with a stable boundary key, so an interrupted child does not
-    // re-execute completed side effects on parent resume.
+    // workflow with the same stable boundary key used by the live boundary
+    // stage, so mixed cached/live repeated child calls do not desynchronize
+    // boundary and durable child-scope ordinals.
     // cross-ref: issue #1498.
     input.setChildDurableScope({ rootWorkflowId: input.rootWorkflowId, scopePrefix: replayKey });
-    const cached = input.backend.getStageOutput(input.workflowId, replayKey);
-    if (cached !== undefined && isWorkflowChildResult(cached)) {
-      input.recordCachedStage(boundaryName, replayKey, cached);
-      return cached as WorkflowChildResult<TChildOutputs>;
-    }
     const result = await input.workflow(child, ...args);
     await recordCheckpointDurably(input.backend, {
       kind: "stage",
@@ -63,11 +65,13 @@ export function createDurableChildWorkflowPrimitive(input: {
       replayKey,
       output: result as WorkflowSerializableValue,
       completedAt: Date.now(),
+      result: result.status,
     });
     return result as WorkflowChildResult<TChildOutputs>;
   };
 }
 
+
 function isWorkflowChildResult(value: WorkflowSerializableValue): value is WorkflowChildResult<WorkflowOutputValues> {
   return typeof value === "object"
     && value !== null

package/dist/builtin/workflows/src/durable/dbos-backend.ts

@@ -377,7 +377,7 @@ function isMetadataStep(stepName: string): boolean {
 interface DbosMetadataEnvelope {
   readonly __atomicDurableMetadata: true;
   readonly version: 1;
-  readonly entry: DurableCheckpointEntry;
+  readonly entry: WorkflowSerializableValue;
 }
 
 function encodeMetadata(entry: DurableCheckpointEntry): WorkflowSerializableValue {
@@ -404,7 +404,52 @@ function decodeMetadata(value: WorkflowSerializableValue): DurableCheckpointEntr
   if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
   const raw = value as Partial<DbosMetadataEnvelope>;
   if (raw.__atomicDurableMetadata !== true || raw.version !== METADATA_VERSION) return undefined;
-  return raw.entry;
+  const entry = raw.entry;
+  if (entry === undefined) return undefined;
+  return parseDurableCheckpointEntry(entry);
+}
+
+function parseDurableCheckpointEntry(value: WorkflowSerializableValue): DurableCheckpointEntry | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const entry = value as Partial<DurableCheckpointEntry>;
+  if (entry.type !== "workflow.durable.checkpoint"
+    || typeof entry.workflowId !== "string"
+    || typeof entry.name !== "string"
+    || typeof entry.inputs !== "object"
+    || entry.inputs === null
+    || Array.isArray(entry.inputs)
+    || typeof entry.status !== "string"
+    || !isDurableWorkflowStatus(entry.status)
+    || typeof entry.completedCheckpoints !== "number"
+    || typeof entry.pendingPrompts !== "number"
+    || typeof entry.ts !== "number"
+    || (entry.label !== undefined && typeof entry.label !== "string")
+    || (entry.rootWorkflowId !== undefined && typeof entry.rootWorkflowId !== "string")
+    || (entry.resumable !== undefined && typeof entry.resumable !== "boolean")) {
+    return undefined;
+  }
+  return {
+    type: "workflow.durable.checkpoint",
+    workflowId: entry.workflowId,
+    name: entry.name,
+    inputs: entry.inputs,
+    status: entry.status,
+    completedCheckpoints: entry.completedCheckpoints,
+    pendingPrompts: entry.pendingPrompts,
+    ts: entry.ts,
+    ...(entry.label !== undefined ? { label: entry.label } : {}),
+    ...(entry.rootWorkflowId !== undefined ? { rootWorkflowId: entry.rootWorkflowId } : {}),
+    ...(entry.resumable !== undefined ? { resumable: entry.resumable } : {}),
+  };
+}
+
+function isDurableWorkflowStatus(value: string): value is DurableWorkflowStatus {
+  return value === "running"
+    || value === "paused"
+    || value === "completed"
+    || value === "failed"
+    || value === "cancelled"
+    || value === "blocked";
 }
 
 function dbosStatusToDurable(status: string): DurableWorkflowStatus {

package/dist/builtin/workflows/src/durable/dbos-envelope.ts

@@ -51,6 +51,14 @@ export interface DbosCheckpointEnvelope extends WorkflowSerializableObject {
   readonly sessionId?: string;
   readonly sessionFile?: string;
   readonly completedAt: number;
+  readonly startedAt?: number;
+  readonly endedAt?: number;
+  readonly durationMs?: number;
+  readonly result?: string;
+  readonly model?: string;
+  readonly fastMode?: boolean;
+  readonly attemptedModels?: WorkflowSerializableValue;
+  readonly modelAttempts?: WorkflowSerializableValue;
 }
 
 /**
@@ -82,6 +90,14 @@ export function encodeCheckpoint(cp: DurableCheckpoint): DbosCheckpointEnvelope
     replayKey: s.replayKey,
     ...(s.sessionId !== undefined ? { sessionId: s.sessionId } : {}),
     ...(s.sessionFile !== undefined ? { sessionFile: s.sessionFile } : {}),
+    ...(s.startedAt !== undefined ? { startedAt: s.startedAt } : {}),
+    ...(s.endedAt !== undefined ? { endedAt: s.endedAt } : {}),
+    ...(s.durationMs !== undefined ? { durationMs: s.durationMs } : {}),
+    ...(s.result !== undefined ? { result: s.result } : {}),
+    ...(s.model !== undefined ? { model: s.model } : {}),
+    ...(s.fastMode !== undefined ? { fastMode: s.fastMode } : {}),
+    ...(s.attemptedModels !== undefined ? { attemptedModels: [...s.attemptedModels] } : {}),
+    ...(s.modelAttempts !== undefined ? { modelAttempts: s.modelAttempts as WorkflowSerializableValue } : {}),
   };
 }
 
@@ -144,9 +160,21 @@ function decodeEnvelope(workflowId: string, env: DbosCheckpointEnvelope): Durabl
     ...(env.hasOutput !== false && env.output !== undefined ? { output: env.output } : {}),
     ...(env.sessionId !== undefined ? { sessionId: env.sessionId } : {}),
     ...(env.sessionFile !== undefined ? { sessionFile: env.sessionFile } : {}),
+    ...(typeof env.startedAt === "number" ? { startedAt: env.startedAt } : {}),
+    ...(typeof env.endedAt === "number" ? { endedAt: env.endedAt } : {}),
+    ...(typeof env.durationMs === "number" ? { durationMs: env.durationMs } : {}),
+    ...(typeof env.result === "string" ? { result: env.result } : {}),
+    ...(typeof env.model === "string" ? { model: env.model } : {}),
+    ...(typeof env.fastMode === "boolean" ? { fastMode: env.fastMode } : {}),
+    ...(isStringArray(env.attemptedModels) ? { attemptedModels: env.attemptedModels } : {}),
+    ...(Array.isArray(env.modelAttempts) ? { modelAttempts: env.modelAttempts as DurableStageCheckpoint["modelAttempts"] } : {}),
   } as DurableStageCheckpoint;
 }
 
+
+function isStringArray(value: WorkflowSerializableValue | undefined): value is readonly string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
 function decodeLegacy(
   workflowId: string,
   stepName: string,