@bastani/atomic 0.5.11 → 0.5.12-1

package/src/sdk/workflows/builtin/ralph/copilot/index.ts

@@ -5,27 +5,42 @@
  * so users can see each iteration's progress in real time. The loop
  * terminates when:
  *   - {@link MAX_LOOPS} iterations have completed, OR
- *   - Two consecutive reviewer passes return zero findings.
+ *   - Two parallel reviewer passes both return zero findings.
+ *
+ * The reviewer stages use a `submit_review` custom tool (defined via
+ * `defineTool` with Zod schema validation) to guarantee the review result
+ * matches the {@link ReviewResultSchema}. The Copilot SDK validates tool
+ * call arguments against the Zod schema before the handler fires.
  *
  * Run: atomic workflow -n ralph -a copilot "<your spec>"
  */
 
 import { defineWorkflow } from "../../../index.ts";
+import { defineTool } from "@github/copilot-sdk";
 import type { SessionEvent } from "@github/copilot-sdk";
 
 import {
   buildPlannerPrompt,
   buildOrchestratorPrompt,
+  buildInfraDiscoveryPrompts,
   buildReviewPrompt,
   buildDebuggerReportPrompt,
-  parseReviewResult,
   extractMarkdownBlock,
+  filterActionable,
+  mergeReviewResults,
+  ReviewResultSchema,
+  type ReviewResult,
+  type StructuredReviewResult,
 } from "../helpers/prompts.ts";
 import { hasActionableFindings } from "../helpers/review.ts";
-import { safeGitStatusS } from "../helpers/git.ts";
+import { captureBranchChangeset } from "../helpers/git.ts";
 
 const MAX_LOOPS = 10;
-const CONSECUTIVE_CLEAN_THRESHOLD = 2;
+
+const SUBMIT_REVIEW_DESCRIPTION =
+  "Submit the structured code review result. You MUST call this tool " +
+  "exactly once with your complete review. Do not output the review as " +
+  "plain text — use this tool.";
 
 /**
  * Concatenate the text content of every top-level assistant message in the
@@ -65,20 +80,13 @@ export default defineWorkflow<"copilot">({
     "Plan → orchestrate → review → debug loop with bounded iteration",
 })
   .run(async (ctx) => {
-    // Free-form workflows receive their positional prompt under
-    // `inputs.prompt`; destructure once so every stage below can close
-    // over a bare `userPromptText` without re-reaching into ctx.inputs.
-    // (Named `userPromptText` rather than `prompt` to avoid confusion
-    // with the `prompt:` object key used in the Copilot send call.)
     const userPromptText = ctx.inputs.prompt ?? "";
-    let consecutiveClean = 0;
     let debuggerReport = "";
 
     for (let iteration = 1; iteration <= MAX_LOOPS; iteration++) {
       // ── Plan ──────────────────────────────────────────────────────────
-      const plannerName = `planner-${iteration}`;
       const planner = await ctx.stage(
-        { name: plannerName },
+        { name: `planner-${iteration}` },
         {},
         { agent: "planner" },
         async (s) => {
@@ -94,11 +102,9 @@ export default defineWorkflow<"copilot">({
         },
       );
 
-
       // ── Orchestrate ───────────────────────────────────────────────────
-      const orchName = `orchestrator-${iteration}`;
       await ctx.stage(
-        { name: orchName },
+        { name: `orchestrator-${iteration}` },
         {},
         { agent: "orchestrator" },
         async (s) => {
@@ -111,82 +117,134 @@ export default defineWorkflow<"copilot">({
         },
       );
 
+      // ── Infrastructure Discovery (three parallel sub-agent stages) ──
+      const changeset = await captureBranchChangeset();
+      const discoveryPrompts = buildInfraDiscoveryPrompts();
 
-      // ── Review (first pass) ───────────────────────────────────────────
-      let gitStatus = await safeGitStatusS();
-      const reviewerName = `reviewer-${iteration}`;
-      const review = await ctx.stage(
-        { name: reviewerName },
-        {},
-        { agent: "reviewer" },
-        async (s) => {
-          await s.session.send({
-            prompt: buildReviewPrompt(userPromptText, {
-              gitStatus,
-              iteration,
-            }),
-          });
-          const messages = await s.session.getMessages();
-          s.save(messages);
-          return getAssistantText(messages);
-        },
-      );
+      const [locatorResult, analyzerResult, patternResult] = await Promise.all([
+        ctx.stage(
+          { name: `infra-locate-${iteration}`, headless: true },
+          {},
+          { agent: "codebase-locator" },
+          async (s) => {
+            await s.session.send({ prompt: discoveryPrompts.locator });
+            const messages = await s.session.getMessages();
+            s.save(messages);
+            return getAssistantText(messages);
+          },
+        ),
+        ctx.stage(
+          { name: `infra-analyze-${iteration}`, headless: true },
+          {},
+          { agent: "codebase-analyzer" },
+          async (s) => {
+            await s.session.send({ prompt: discoveryPrompts.analyzer });
+            const messages = await s.session.getMessages();
+            s.save(messages);
+            return getAssistantText(messages);
+          },
+        ),
+        ctx.stage(
+          { name: `infra-patterns-${iteration}`, headless: true },
+          {},
+          { agent: "codebase-pattern-finder" },
+          async (s) => {
+            await s.session.send({ prompt: discoveryPrompts.patternFinder });
+            const messages = await s.session.getMessages();
+            s.save(messages);
+            return getAssistantText(messages);
+          },
+        ),
+      ]);
+
+      const discoveryContext = [
+        "### Infrastructure Files (codebase-locator)\n\n" + locatorResult.result,
+        "### Infrastructure Analysis (codebase-analyzer)\n\n" + analyzerResult.result,
+        "### Build & Test Patterns (codebase-pattern-finder)\n\n" + patternResult.result,
+      ].join("\n\n---\n\n");
+
+      // ── Review (two parallel passes) ──────────────────────────────────
+      const reviewPrompt = buildReviewPrompt(userPromptText, {
+        changeset,
+        iteration,
+        useSubmitTool: true,
+        discoveryContext,
+      });
 
+      // Each parallel reviewer gets its own tool + capture ref so they
+      // don't race on a shared mutable.
+      let captureA: ReviewResult | null = null;
+      let captureB: ReviewResult | null = null;
 
-      let reviewRaw = review.result;
-      let parsed = parseReviewResult(reviewRaw);
+      const toolA = defineTool("submit_review", {
+        description: SUBMIT_REVIEW_DESCRIPTION,
+        parameters: ReviewResultSchema,
+        skipPermission: true,
+        handler: async (data: ReviewResult) => {
+          captureA = filterActionable(data);
+          return "Review submitted successfully.";
+        },
+      });
 
-      if (!hasActionableFindings(parsed, reviewRaw)) {
-        consecutiveClean += 1;
-        if (consecutiveClean >= CONSECUTIVE_CLEAN_THRESHOLD) break;
+      const toolB = defineTool("submit_review", {
+        description: SUBMIT_REVIEW_DESCRIPTION,
+        parameters: ReviewResultSchema,
+        skipPermission: true,
+        handler: async (data: ReviewResult) => {
+          captureB = filterActionable(data);
+          return "Review submitted successfully.";
+        },
+      });
 
-        // Confirmation pass — re-run reviewer only
-        gitStatus = await safeGitStatusS();
-        const confirmName = `reviewer-${iteration}-confirm`;
-        const confirm = await ctx.stage(
-          { name: confirmName },
+      const [reviewA, reviewB] = await Promise.all([
+        ctx.stage(
+          { name: `reviewer-${iteration}-a` },
           {},
-          { agent: "reviewer" },
+          { agent: "reviewer", tools: [toolA] },
           async (s) => {
-            await s.session.send({
-              prompt: buildReviewPrompt(userPromptText, {
-                gitStatus,
-                iteration,
-                isConfirmationPass: true,
-              }),
-            });
+            await s.session.sendAndWait({ prompt: reviewPrompt });
             const messages = await s.session.getMessages();
             s.save(messages);
-            return getAssistantText(messages);
+            return {
+              structured: captureA,
+              raw: getAssistantText(messages),
+            } as StructuredReviewResult;
           },
-        );
-
+        ),
+        ctx.stage(
+          { name: `reviewer-${iteration}-b` },
+          {},
+          { agent: "reviewer", tools: [toolB] },
+          async (s) => {
+            await s.session.sendAndWait({ prompt: reviewPrompt });
+            const messages = await s.session.getMessages();
+            s.save(messages);
+            return {
+              structured: captureB,
+              raw: getAssistantText(messages),
+            } as StructuredReviewResult;
+          },
+        ),
+      ]);
 
-        reviewRaw = confirm.result;
-        parsed = parseReviewResult(reviewRaw);
+      const merged = mergeReviewResults(reviewA.result, reviewB.result);
+      const parsed = merged.structured;
+      const reviewRaw = merged.raw;
 
-        if (!hasActionableFindings(parsed, reviewRaw)) {
-          consecutiveClean += 1;
-          if (consecutiveClean >= CONSECUTIVE_CLEAN_THRESHOLD) break;
-        } else {
-          consecutiveClean = 0;
-        }
-      } else {
-        consecutiveClean = 0;
-      }
+      // Both reviewers agree the code is clean → done
+      if (!hasActionableFindings(parsed, reviewRaw)) break;
 
-      // ── Debug (only if findings remain AND another iteration is allowed) ─
-      if (hasActionableFindings(parsed, reviewRaw) && iteration < MAX_LOOPS) {
-        const debuggerName = `debugger-${iteration}`;
+      // ── Debug (only if another iteration is allowed) ──────────────────
+      if (iteration < MAX_LOOPS) {
         const debugger_ = await ctx.stage(
-          { name: debuggerName },
+          { name: `debugger-${iteration}` },
           {},
           { agent: "debugger" },
           async (s) => {
             await s.session.send({
               prompt: buildDebuggerReportPrompt(parsed, reviewRaw, {
                 iteration,
-                gitStatus,
+                changeset,
               }),
             });
             const messages = await s.session.getMessages();

package/src/sdk/workflows/builtin/ralph/helpers/git.ts

@@ -1,34 +1,201 @@
 /**
- * Deterministic working-tree probes used by the Ralph loop.
+ * Deterministic changeset probes used by the Ralph loop.
  *
  * The reviewer and debugger sub-agents both benefit from knowing exactly which
- * files were touched in the current iteration. Asking an LLM to figure that
- * out via tool calls is expensive and lossy, so we capture `git status -s`
- * directly from the workflow runner and inject it into prompts.
+ * files were touched by the current work. We compute a diff relative to the
+ * parent branch (auto-discovered, defaulting to main) so the changeset
+ * includes BOTH committed and uncommitted changes — not just the working tree.
  *
- * Failures (no git binary, not a repo, command non-zero) collapse to "" so
- * the prompts can fall back to the "working tree clean" branch.
+ * Git command failures are captured — not swallowed — so downstream agents
+ * can distinguish "nothing changed" from "git broke" and course-correct.
  */
 
+// ─── Internals ──────────────────────────────────────────────────────────────
+
+/** Result of running a single git command. */
+interface GitResult {
+  /** Trimmed stdout on success, "" on failure. */
+  stdout: string;
+  /** True when the command exited with code 0. */
+  ok: boolean;
+  /** Human-readable error context when ok is false. */
+  error?: string;
+}
+
 /**
- * Run `git status -s` from the given cwd. Returns trimmed stdout, or "" on
- * any error. Never throws.
+ * Run a git command and return both the output and error context.
+ *
+ * Never throws — call-site code can check `.ok` and propagate `.error`
+ * to downstream agents instead of silently producing empty strings.
  */
-export async function safeGitStatusS(
+async function git(
+  args: string[],
   cwd: string = process.cwd(),
-): Promise<string> {
+): Promise<GitResult> {
   try {
     const proc = Bun.spawn({
-      cmd: ["git", "status", "-s"],
+      cmd: ["git", ...args],
       cwd,
       stdout: "pipe",
-      stderr: "ignore",
+      stderr: "pipe",
     });
-    const stdout = await new Response(proc.stdout).text();
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
     const code = await proc.exited;
-    if (code !== 0) return "";
-    return stdout;
-  } catch {
-    return "";
+    if (code !== 0) {
+      return {
+        stdout: "",
+        ok: false,
+        error: `\`git ${args.join(" ")}\` exited with code ${code}${stderr.trim() ? ": " + stderr.trim() : ""}`,
+      };
+    }
+    return { stdout: stdout.trim(), ok: true };
+  } catch (err) {
+    return {
+      stdout: "",
+      ok: false,
+      error: `\`git ${args.join(" ")}\` failed to spawn: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+// ─── Branch discovery ───────────────────────────────────────────────────────
+
+/** Well-known default branch names, tried in order. */
+const DEFAULT_BRANCH_CANDIDATES = ["main", "master", "develop"] as const;
+
+/**
+ * Discover the parent (base) branch for the current HEAD.
+ *
+ * Strategy:
+ * 1. Find the merge-base between HEAD and each default-branch candidate.
+ *    The candidate whose merge-base is closest to HEAD (fewest commits away)
+ *    is the winner.
+ * 2. If no candidate exists locally, fall back to "main".
+ *
+ * This handles the common case of feature branches off main/master without
+ * requiring configuration.
+ */
+export async function discoverBaseBranch(
+  cwd: string = process.cwd(),
+): Promise<string> {
+  const branchResult = await git(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+  const currentBranch = branchResult.stdout;
+
+  let bestCandidate = "main";
+  let bestDistance = Infinity;
+
+  for (const candidate of DEFAULT_BRANCH_CANDIDATES) {
+    // Skip if we ARE the candidate (reviewing main against itself is useless)
+    if (currentBranch === candidate) continue;
+
+    // Check the ref exists
+    const refExists = await git(["rev-parse", "--verify", `refs/heads/${candidate}`], cwd);
+    if (!refExists.ok) continue;
+
+    const mergeBase = await git(["merge-base", "HEAD", candidate], cwd);
+    if (!mergeBase.ok) continue;
+
+    // Count commits from merge-base to HEAD — fewer = closer = better match
+    const countResult = await git(["rev-list", "--count", `${mergeBase.stdout}..HEAD`], cwd);
+    const distance = parseInt(countResult.stdout, 10);
+    if (!Number.isNaN(distance) && distance < bestDistance) {
+      bestDistance = distance;
+      bestCandidate = candidate;
+    }
   }
+
+  return bestCandidate;
+}
+
+// ─── Changeset capture ──────────────────────────────────────────────────────
+
+/** The result of capturing the full changeset for a review. */
+export interface BranchChangeset {
+  /** The base branch the diff is relative to (e.g. "main") */
+  baseBranch: string;
+  /**
+   * `git diff --stat` output showing files changed, insertions, deletions
+   * relative to the merge-base with the parent branch. Includes both
+   * committed AND uncommitted changes.
+   */
+  diffStat: string;
+  /**
+   * Short list of uncommitted working-tree changes (`git status -s`).
+   * Useful for the reviewer to distinguish "already committed" from
+   * "still in-flight".
+   */
+  uncommitted: string;
+  /**
+   * `git diff --name-status` output listing each changed file with its
+   * status (A=added, M=modified, D=deleted, R=renamed).
+   */
+  nameStatus: string;
+  /**
+   * Human-readable error messages for any git commands that failed during
+   * changeset capture. Empty when everything succeeded. Downstream prompts
+   * surface these so the reviewing agent can course-correct (e.g. run the
+   * git commands itself, or flag the gap as a finding).
+   */
+  errors: string[];
 }
+
+/**
+ * Capture the full changeset for the current branch relative to its parent.
+ *
+ * Combines:
+ * - `git diff <merge-base>..HEAD --stat` (committed changes)
+ * - `git diff --stat` (uncommitted staged+unstaged changes)
+ * - `git status -s` (working tree snapshot)
+ *
+ * Into a single {@link BranchChangeset} that gives the reviewer complete
+ * visibility into everything this branch has done.
+ *
+ * Git failures are collected in {@link BranchChangeset.errors} rather than
+ * swallowed, so downstream agents see exactly what broke and can compensate.
+ */
+export async function captureBranchChangeset(
+  cwd: string = process.cwd(),
+): Promise<BranchChangeset> {
+  const errors: string[] = [];
+
+  const baseBranch = await discoverBaseBranch(cwd);
+  const mergeBaseResult = await git(["merge-base", "HEAD", baseBranch], cwd);
+
+  if (!mergeBaseResult.ok && mergeBaseResult.error) {
+    errors.push(mergeBaseResult.error);
+  }
+
+  // Compute the merge-base ref, falling back to baseBranch if merge-base fails
+  const baseRef = mergeBaseResult.stdout || baseBranch;
+
+  // Full diff stat: committed changes from branch point through HEAD,
+  // plus any uncommitted working-tree changes (the combined diff captures
+  // the complete picture)
+  const diffStatResult = await git(["diff", `${baseRef}...HEAD`, "--stat"], cwd);
+  const uncommittedStatResult = await git(["diff", "--stat"], cwd);
+  const uncommittedResult = await git(["status", "-s"], cwd);
+  const nameStatusResult = await git(["diff", `${baseRef}...HEAD`, "--name-status"], cwd);
+
+  // Collect errors from each command
+  if (!diffStatResult.ok && diffStatResult.error) errors.push(diffStatResult.error);
+  if (!uncommittedStatResult.ok && uncommittedStatResult.error) errors.push(uncommittedStatResult.error);
+  if (!uncommittedResult.ok && uncommittedResult.error) errors.push(uncommittedResult.error);
+  if (!nameStatusResult.ok && nameStatusResult.error) errors.push(nameStatusResult.error);
+
+  // Merge committed + uncommitted stats for a complete picture
+  const combinedStat = [diffStatResult.stdout, uncommittedStatResult.stdout]
+    .filter(Boolean)
+    .join("\n");
+
+  return {
+    baseBranch,
+    diffStat: combinedStat,
+    uncommitted: uncommittedResult.stdout,
+    nameStatus: nameStatusResult.stdout,
+    errors,
+  };
+}
+