@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.3

package/src/patterns/loop.js

@@ -0,0 +1,158 @@
+import { getAdapter } from "../adapters/index.js";
+import { failureFingerprint } from "../checks.js";
+import { changedFiles, restorePaths } from "../git.js";
+import { describeIssues, issuesKey } from "../integrity.js";
+import { checkSection, preamble, proofLine, proofRule, section, WRITE } from "./prompts.js";
+const loopPattern = {
+  id: "loop",
+  name: "Loop until green",
+  summary: "An agent keeps fixing until your check passes; another vendor takes over if it gets stuck.",
+  description: "Use when \u201Cdone\u201D is a command you can run: tests, a type check, a build. code-flow runs it after every change, so the loop ends on evidence, not on an agent saying it's done.",
+  requiresCheck: true,
+  roles: [
+    {
+      id: "workers",
+      label: "Workers",
+      description: "Take turns in this order; the next one takes over when the current one is stuck",
+      multiple: true,
+      default: ["codex", "claude"]
+    }
+  ],
+  options: [
+    { id: "maxRounds", label: "Max rounds", type: "number", default: 6, min: 1, max: 30 },
+    { id: "stuckAfter", label: "Hand off after stuck rounds", type: "number", default: 2, min: 1, max: 10 }
+  ],
+  async run(ctx) {
+    const workers = ctx.participants("workers");
+    if (!workers.length) throw new Error("Pick at least one worker");
+    const maxRounds = ctx.option("maxRounds", 6);
+    const stuckAfter = ctx.option("stuckAfter", 2);
+    const name = (id) => getAdapter(id).displayName;
+    const wt = await ctx.worktree("loop");
+    const baseline = await ctx.check(wt, "Baseline check");
+    if (!baseline) {
+      const reason = ctx.run.checkCantRun?.reason ?? "it can't run in this environment";
+      return `**No rounds run: the check can't run here** \u2014 ${reason}. Set \`setup\` and \`check\` in .codeflow/config.json, then start the run again.`;
+    }
+    ctx.log(baseline.ok ? "Baseline: the check already passes; the task must keep it passing" : "Baseline: the check fails before any change");
+    const plural = (n) => `${n} test${n === 1 ? "" : "s"}`;
+    const distance = (r) => r.ok ? 0 : r.failed === void 0 ? void 0 : r.failed + 0.5;
+    const sessions = /* @__PURE__ */ new Map();
+    const history = [];
+    let current = 0;
+    let stuck = 0;
+    let last = baseline;
+    let handover = "";
+    let rounds = 0;
+    let toldAbout = "";
+    let unresolved = [];
+    let nudge = "";
+    let askedForProof = false;
+    let solvedBy;
+    let handoffs = 0;
+    let head = wt.base;
+    let best = {
+      head,
+      distance: distance(baseline),
+      failed: baseline.failed ?? 0,
+      where: "before any change"
+    };
+    let undone = "";
+    for (let round = 1; round <= maxRounds; round++) {
+      rounds = round;
+      const { agent, settings, identity } = workers[current];
+      const session = sessions.get(identity ?? agent);
+      const fixIt = nudge || checkSection(last) + section("Next", "Find the root cause and fix it in the code \u2014 don't weaken or skip tests. Then summarize what you changed.");
+      const prompt = session ? undone ? undone + fixIt : nudge || "The check still fails after your last change." + fixIt : preamble("worker", agent, `${WRITE} code-flow runs the check below after every turn you take; the loop ends when it passes.`) + section("Task", ctx.task) + section("Done when", `\`${ctx.run.loop.check}\` passes. Add or update tests for new behaviour, so passing the check proves the task works.`) + proofRule(ctx) + (handover ? section("Handover", handover) : "") + checkSection(last) + nudge;
+      nudge = "";
+      undone = "";
+      const turn = await ctx.ask({ title: `Round ${round}`, role: "workers", agent, settings, identity, mode: "write", cwd: wt, resume: session, prompt });
+      sessions.set(identity ?? agent, turn);
+      const sha = await ctx.commit(wt, `${agent}: round ${round}`);
+      if (sha) head = sha;
+      let result = await ctx.check(wt, `Check after round ${round}`);
+      const outcome = result.ok ? "passed" : result.failed !== void 0 ? `failed (${plural(result.failed)} failing)` : "failed";
+      history.push(`- Round ${round} (${name(agent)}): ${sha ? "changed code" : "no changes"}, check ${outcome}`);
+      const reached = distance(result);
+      const worse = !!sha && best.distance !== void 0 && (reached === void 0 || reached > best.distance);
+      if (worse) {
+        const what = result.failed !== void 0 ? `left ${plural(result.failed)} failing, more than the ${best.failed} ${best.where}` : `left no test results, where there were some ${best.where}`;
+        ctx.log(`Round ${round} ${what}; undoing it`, "warn");
+        const changed = await ctx.remember("changed", `${wt.name}|undo round ${round}`, async () => changedFiles(await ctx.gitAt(wt), best.head));
+        await ctx.remember("restore", `${wt.name}|undo round ${round}`, () => restorePaths(ctx.run.repo, wt, best.head, changed).then(() => true));
+        head = await ctx.commit(wt, `code-flow: undo round ${round}, which made the check worse`) ?? head;
+        history[history.length - 1] += ` \u2014 worse than ${best.where}, so code-flow undid it`;
+        undone = `Your last change ${what}, so code-flow undid it: the code is as it was ${best.where} (\`git log\` shows both). Take a different approach.`;
+        result = await ctx.check(wt, `Check after undoing round ${round}`);
+      }
+      const before = distance(last);
+      const after = distance(result);
+      const counted = before !== void 0 && after !== void 0 && !(after === before && result.failed === 0);
+      const progress = !worse && !!sha && (result.ok || (counted ? after < before : failureFingerprint(result) !== failureFingerprint(last)));
+      last = result;
+      if (!worse && !result.ok && after !== void 0 && (best.distance === void 0 || after <= best.distance)) {
+        best = { head, distance: after, failed: result.failed ?? 0, where: `after round ${round}`, agent };
+      }
+      if (result.ok) {
+        const uncounted = baseline.tests === void 0 || result.tests === void 0;
+        const issues = (await ctx.testChanges(wt)).filter((i) => i.severity === "high" || uncounted && i.kind === "weakened-test");
+        unresolved = issues;
+        if (!issues.length) {
+          if (!worse) best = { head, distance: 0, failed: 0, where: `after round ${round}`, agent };
+          const proof = await ctx.prove(wt, { known: baseline });
+          if (proof?.status === "unproven" && !askedForProof && round < maxRounds) {
+            askedForProof = true;
+            history[history.length - 1] += " \u2014 but no test fails without the change";
+            nudge = section(
+              "The check passes, but nothing proves the change",
+              "code-flow ran this change's tests on the original code, without the change, and they pass there too: nothing shows the change does what the task asks.\n\nAdd or update a test that fails without your change and passes with it. If the task can't be tested that way (docs, a pure refactor), change nothing and say why."
+            );
+            continue;
+          }
+          if (proof?.status === "unproven") ctx.log(`The check passes, but no test fails without the change; review it before merging`, "warn");
+          solvedBy = worse ? best.agent : agent;
+          break;
+        }
+        if (issuesKey(issues) === toldAbout) {
+          ctx.log(`${name(agent)} kept its test changes after being asked to undo them; the pass doesn't count until you've reviewed them`, "warn");
+          break;
+        }
+        toldAbout = issuesKey(issues);
+        ctx.log(`The check passes, but only after changes to the tests that could hide the failure:
+${describeIssues(issues)}`, "warn");
+        history[history.length - 1] += " \u2014 but tests were weakened";
+        nudge = section(
+          "The check passes, but not on evidence",
+          "code-flow found these changes to the tests in this branch. They can make the check pass without fixing anything:\n" + describeIssues(issues) + "\n\nUndo them and fix the code instead. Only if the task itself requires these test changes, keep them and say why in your summary."
+        );
+        continue;
+      }
+      stuck = progress ? 0 : stuck + 1;
+      if (stuck >= stuckAfter && workers.length > 1) {
+        const next = (current + 1) % workers.length;
+        ctx.log(`${name(agent)} made no progress for ${stuck} rounds; handing over to ${name(workers[next].agent)}`, "warn");
+        handover = `${name(agent)} worked on this before you without getting the check to pass. Its commits are on this branch (\`git log\` shows them); keep what's useful, and take a fresh look rather than repeating its approach.
+${history.join("\n")}`;
+        sessions.delete(workers[next].identity ?? workers[next].agent);
+        current = next;
+        stuck = 0;
+        handoffs++;
+      }
+    }
+    await ctx.artifact("Result", wt);
+    const passed = last.ok && !unresolved.length;
+    if (passed || !last.ok) ctx.setVerdict(passed ? "passed" : "failing");
+    ctx.setFacts({ solvedBy: passed ? solvedBy ?? workers[current]?.agent : void 0, handoffs, proof: ctx.proofOf(wt)?.status });
+    const s = rounds === 1 ? "" : "s";
+    return [
+      passed ? `**Check passes** after ${rounds} round${s} \u2014 branch \`${wt.branch}\`` : last.ok ? `**The check passes only with changes to the tests** after ${rounds} round${s} \u2014 branch \`${wt.branch}\`; review them before merging` : `**Check still failing** after ${rounds} rounds \u2014 branch \`${wt.branch}\` has ${last.failed !== void 0 ? `the best attempt (${plural(last.failed)} failing)` : "the latest attempt"}`,
+      passed ? proofLine(ctx.proofOf(wt)) : "",
+      last.ok && !passed ? section("Changes to the tests that could hide the failure", describeIssues(unresolved)) : "",
+      section("Rounds", history.join("\n")),
+      last.ok ? "" : section("Last failure", "```\n" + last.output.slice(-1500).trim() + "\n```")
+    ].join("\n");
+  }
+};
+export {
+  loopPattern
+};

package/src/patterns/pipeline.js

@@ -0,0 +1,125 @@
+import { describeIssues } from "../integrity.js";
+import { approves, builderReply, checkReview, findingsForBuilder, findingsLine, findingsSection, REVIEW_SHAPE, reproRule } from "./findings.js";
+import { REVIEW_SCHEMA } from "./schemas.js";
+import { checkEvidence, fence, fixUntilGreen, jsonInstruction, planCheckpoint, preamble, proofEvidence, proofLine, proofRule, proveOrAsk, READ_ONLY, section, WRITE } from "./prompts.js";
+const pipelinePattern = {
+  id: "pipeline",
+  name: "Plan \u2192 Build \u2192 Review",
+  summary: "Planner writes a plan, builder implements it, an independent reviewer loops until it approves.",
+  description: "The default for well-defined features and bug fixes. Cross-vendor review catches mistakes a model misses in its own work.",
+  roles: [
+    { id: "planner", label: "Planner", description: "Reads the code, writes the implementation plan", default: ["claude"] },
+    { id: "builder", label: "Builder", description: "Implements the plan and applies review fixes", default: ["codex"] },
+    { id: "reviewer", label: "Reviewer", description: "Reviews the diff against the task, ideally a vendor other than the planner", default: ["codex"] }
+  ],
+  options: [
+    { id: "maxRounds", label: "Max review rounds", type: "number", default: 2, min: 1, max: 5 },
+    { id: "checkFixes", label: "Check fix attempts per round", type: "number", default: 2, min: 0, max: 5 }
+  ],
+  async run(ctx) {
+    const planner = ctx.agent("planner");
+    const builder = ctx.agent("builder");
+    const reviewer = ctx.agent("reviewer");
+    const maxRounds = ctx.option("maxRounds", 2);
+    if (reviewer === planner) ctx.log(`${planner} both plans and reviews; a reviewer from another vendor is likelier to catch a wrong plan`, "warn");
+    const wt = await ctx.worktree("build");
+    let plan = await ctx.ask({
+      title: "Plan",
+      role: "planner",
+      agent: planner,
+      mode: "read",
+      cwd: wt,
+      prompt: preamble("planner", planner, `${READ_ONLY} Another agent will implement your plan, so be concrete.`) + section("Task", ctx.task) + section(
+        "Deliverable",
+        "Explore the relevant code, then write an implementation plan: files to change, the approach, edge cases, and how to verify it (tests or commands). Keep it under 400 words. Identify focused verification commands; leave their execution to the implementation and verification stages. Do not run full build or test suites while planning unless the task explicitly requires a baseline before planning."
+      )
+    });
+    plan = await planCheckpoint(ctx, { agent: planner, role: "planner", wt, plan, what: "plan" });
+    const build = await ctx.ask({
+      title: "Implement plan",
+      role: "builder",
+      agent: builder,
+      mode: "write",
+      cwd: wt,
+      prompt: preamble("builder", builder, WRITE) + section("Task", ctx.task) + section("Plan from the planner", plan.finalText) + proofRule(ctx) + section("Deliverable", "Implement the plan, run the relevant tests, then summarize what you changed.")
+    });
+    await ctx.commit(wt, `${builder}: implement plan`);
+    const checkFixes = ctx.option("checkFixes", 2);
+    let verdict;
+    let findings = [];
+    let review;
+    let reply;
+    let fixer = build;
+    let check = null;
+    let proof = null;
+    let askedForProof = false;
+    let reviewRounds = 0;
+    for (let round = 1; round <= maxRounds; round++) {
+      const fixed = await fixUntilGreen(ctx, { agent: builder, role: "builder", wt, session: fixer, attempts: checkFixes });
+      fixer = fixed.session ?? fixer;
+      const proved = await proveOrAsk(ctx, { agent: builder, role: "builder", wt, check: fixed.check, session: fixer, attempts: checkFixes, ask: !askedForProof });
+      askedForProof ||= proved.asked;
+      check = proved.check;
+      proof = proved.proof;
+      fixer = proved.session ?? fixer;
+      if (check && !check.ok) {
+        ctx.log(`The check still fails after ${checkFixes} fix attempts; stopping before review`, "warn");
+        break;
+      }
+      const diff = await ctx.diff(wt);
+      const testChanges = await ctx.testChanges(wt);
+      const decided = await ctx.decide({
+        title: `Review (round ${round})`,
+        schema: REVIEW_SCHEMA,
+        what: "review verdict",
+        role: "reviewer",
+        agent: reviewer,
+        mode: "read",
+        cwd: wt,
+        resume: review,
+        prompt: (review ? "The builder addressed your previous review. Here is the updated diff.\n" : "") + builderReply(reply) + preamble("reviewer", reviewer, `${READ_ONLY} You did not write this code; review it critically.`) + section("Task", ctx.task) + // A reviewer without its earlier session hasn't seen the plan.
+        (round === 1 || !review?.sessionId ? section("The planner's plan (context, not the spec)", plan.finalText) : "") + section("Diff against base", fence(diff, "diff")) + checkEvidence(ctx, check) + proofEvidence(proof) + (testChanges.length ? section(
+          "Changes to tests (found by code-flow)",
+          `These can make the check pass without fixing anything. Raise each as a medium issue unless the task clearly requires it:
+${describeIssues(testChanges)}`
+        ) : "") + section(
+          "Deliverable",
+          "Judge the change against the task, not against the plan: the plan is one way to do it, and it can be wrong. If following it missed or broke something the task asks for, raise that and say what the task needs instead. Check correctness, missed requirements, edge cases, tests and security. Only raise real problems, not style preferences."
+        ) + reproRule(ctx) + jsonInstruction(REVIEW_SHAPE)
+      });
+      review = decided.outcome;
+      verdict = decided.value;
+      reviewRounds = round;
+      findings = await checkReview(ctx, wt, { label: `Review round ${round}`, reviewer, round, review: verdict });
+      if (approves(findings) || round === maxRounds) break;
+      fixer = await ctx.ask({
+        title: `Address review (round ${round})`,
+        role: "builder",
+        agent: builder,
+        mode: "write",
+        cwd: wt,
+        resume: fixer,
+        prompt: findingsForBuilder(reviewer, findings)
+      });
+      reply = fixer.finalText;
+      await ctx.commit(wt, `${builder}: address review round ${round}`);
+    }
+    await ctx.artifact("Result", wt);
+    const green = !check || check.ok;
+    const approved = green && !!review && approves(findings);
+    if (ctx.hasCheck) ctx.setVerdict(green ? "passed" : "failing");
+    ctx.setFacts({ reviewRounds, approved, proof: ctx.proofOf(wt)?.status });
+    const headline = !green ? `Check \`${check.command}\` still fails after ${checkFixes} fix attempts` : approved ? ctx.hasCheck ? `Approved, and \`${check.command}\` passes` : "Approved" : "Not approved: findings still block after the last review round";
+    return [
+      `**${headline}** \u2014 branch \`${wt.branch}\``,
+      proofLine(ctx.proofOf(wt)),
+      review ? findingsLine(findings) : "",
+      section("Builder summary", fixer.finalText),
+      review && !approved ? findingsSection("Open review findings", findings) : "",
+      !green ? section("Last failure", "```\n" + check.output.slice(-1500).trim() + "\n```") : ""
+    ].join("\n");
+  }
+};
+export {
+  pipelinePattern
+};

package/src/patterns/prompts.js

@@ -0,0 +1,181 @@
+import { getAdapter } from "../adapters/index.js";
+import { failureExcerpt } from "../checks.js";
+import { RejectedError } from "../engine.js";
+import { changedFiles, resolveCommit, restorePaths } from "../git.js";
+function preamble(role, agent, duty) {
+  return [
+    `You are the ${role} on a team of AI coding agents (Claude Code, Codex, Antigravity) coordinated by code-flow.`,
+    `You are running as ${getAdapter(agent).displayName}, non-interactively: nobody can answer questions, so make reasonable assumptions and state them.`,
+    duty,
+    "Do not run `git commit`, `git push` or change branches \u2014 code-flow commits your work after you finish."
+  ].join("\n");
+}
+function section(title, body) {
+  return `
+## ${title}
+${body.trim()}
+`;
+}
+function fence(body, lang = "") {
+  return `\`\`\`${lang}
+${body}
+\`\`\``;
+}
+const READ_ONLY = "You have read-only access: inspect code and run read-only commands, but do not modify any files.";
+const WRITE = "You may edit files and run build/test commands in the current directory, which is an isolated git worktree.";
+function jsonInstruction(shape) {
+  return `
+End your answer with a fenced \`\`\`json block exactly matching this shape:
+${fence(shape, "json")}`;
+}
+const LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+async function planCheckpoint(ctx, opts) {
+  let plan = opts.plan;
+  for (let round = 1; ; round++) {
+    const title = round === 1 ? `Approve the ${opts.what}` : `Approve the revised ${opts.what} (${round})`;
+    const answer = await ctx.approve("plan", title, opts.render ? opts.render(plan.finalText) : plan.finalText);
+    if (answer.decision === "approve") return plan;
+    if (answer.decision === "reject") throw new RejectedError(`You rejected the ${opts.what}.${answer.note ? ` (${answer.note})` : ""}`);
+    plan = await ctx.ask({
+      title: `Revise the ${opts.what} (${round})`,
+      role: opts.role,
+      agent: opts.agent,
+      mode: "read",
+      cwd: opts.wt,
+      resume: plan.sessionId ? plan : void 0,
+      prompt: (plan.sessionId ? "" : `Your earlier ${opts.what}:
+${plan.finalText}
+
+`) + `The user asked for changes to your ${opts.what}:
+${answer.note}
+
+Revise it and reply with the complete updated ${opts.what}.`
+    });
+  }
+}
+function checkSection(result, maxOutput = 6e3) {
+  const status = result.ok ? "passed" : result.timedOut ? "timed out" : `failed (exit code ${result.exitCode})`;
+  const body = result.ok ? "All checks pass." : fence(failureExcerpt(result.output, maxOutput) || "(no output)");
+  return section(`Check \`${result.command}\` ${status} (run by code-flow)`, body);
+}
+function checkEvidence(ctx, check, maxOutput) {
+  if (check) return checkSection(check, maxOutput);
+  const cantRun = ctx.run.checkCantRun;
+  if (!cantRun) return "";
+  return section(
+    `Check \`${cantRun.command}\` couldn't run (run by code-flow)`,
+    `It can't run in this environment (${cantRun.reason}) \u2014 on the base commit either, so not because of this change. Nobody has run the tests on this change; review it with that in mind.`
+  );
+}
+function proofRule(ctx) {
+  if (!ctx.proves) return "";
+  return section(
+    "Prove it",
+    "code-flow will run your tests on the original code, without your change: at least one should fail there and pass with your change. Add or update a test that shows the change works, unless the task can't be tested that way (docs, a pure refactor); then say why in your summary."
+  );
+}
+function proofEvidence(proof) {
+  if (!proof) return "";
+  const tests = proof.tests.length ? `this change's tests (${proof.tests.join(", ")})` : "the existing tests";
+  if (proof.status === "proven") {
+    return section(
+      "Fail-to-pass: proven (run by code-flow)",
+      `code-flow put ${tests} onto the original code and ran \`${proof.command}\`: it fails there and passes with the change, so the tests need the change.
+${fence(proof.detail)}`
+    );
+  }
+  if (proof.status === "weak") {
+    return section(
+      "Fail-to-pass: weak (run by code-flow)",
+      `code-flow put ${tests} onto the original code and ran \`${proof.command}\`: it fails there, but only because the tests can't load (an import or build error), so they show the change adds what they import, not that it works. Look for a test that fails on the behaviour itself.
+` + fence(proof.detail)
+    );
+  }
+  if (proof.status === "unproven") {
+    return section(
+      "Fail-to-pass: not proven (run by code-flow)",
+      `code-flow put ${tests} onto the original code and ran \`${proof.command}\`: it passes there too, so no test shows the change works. Ask for a test that fails without the change, unless the task can't be tested that way (docs, a pure refactor).`
+    );
+  }
+  return section("Fail-to-pass: couldn't tell (run by code-flow)", `code-flow couldn't run the tests on the original code: ${proof.detail}.`);
+}
+function proofLine(proof) {
+  if (!proof) return "";
+  if (proof.status === "proven") return `Proven: \`${proof.command}\` fails without the change${proof.tests.length ? ` (with ${proof.tests.join(", ")})` : ""}, so its tests need it.`;
+  if (proof.status === "weak") return `\u26A0 Weak proof: \`${proof.command}\` fails without the change only because its tests can't load there (an import or build error), not on what they check.`;
+  if (proof.status === "unproven") return "\u26A0 Not proven: no test fails without the change.";
+  return `Couldn't prove it fails without the change: ${proof.detail}.`;
+}
+async function proveOrAsk(ctx, opts) {
+  let { check, session } = opts;
+  if (!check?.ok) return { check, proof: null, session, asked: false };
+  let proof = await ctx.prove(opts.wt);
+  if (proof?.status !== "unproven" || !opts.ask) return { check, proof, session, asked: false };
+  session = session?.agent === opts.agent ? session : void 0;
+  const before = await ctx.remember("head", `before proof test in ${opts.wt.name}`, async () => resolveCommit(await ctx.gitAt(opts.wt)));
+  session = await ctx.ask({
+    title: "Add a test that fails without the change",
+    role: opts.role,
+    agent: opts.agent,
+    mode: "write",
+    cwd: opts.wt,
+    resume: session,
+    prompt: (session ? "" : preamble(opts.role, opts.agent, WRITE) + section("Task", ctx.task) + (opts.context ?? "")) + "The check passes, but code-flow ran this change's tests on the original code, without the change, and they pass there too: nothing shows the change does what the task asks." + section(
+      "Next",
+      "Add or update a test that fails without your change and passes with it. Don't change the implementation unless the test finds a real bug. If the task can't be tested that way (docs, a pure refactor), change nothing and say why."
+    )
+  });
+  const sha = await ctx.commit(opts.wt, `${opts.agent}: add a test that fails without the change`);
+  if (!sha) {
+    ctx.log(`${getAdapter(opts.agent).displayName} added no test; the result stays unproven`, "warn");
+    return { check, proof, session, asked: true };
+  }
+  const fixed = await fixUntilGreen(ctx, { agent: opts.agent, role: opts.role, wt: opts.wt, session, attempts: opts.attempts, context: opts.context });
+  check = fixed.check;
+  session = fixed.session ?? session;
+  if (check && !check.ok) {
+    ctx.log(`The check fails since ${getAdapter(opts.agent).displayName} added its test, and fixing didn't help; undoing that`, "warn");
+    const changed = await ctx.remember("changed", `since proof test in ${opts.wt.name}`, async () => changedFiles(await ctx.gitAt(opts.wt), before));
+    await ctx.remember("restore-before-proof", opts.wt.name, () => restorePaths(ctx.run.repo, opts.wt, before, changed).then(() => true));
+    await ctx.commit(opts.wt, `code-flow: undo ${opts.agent}'s test that never passed`);
+    check = await ctx.check(opts.wt);
+    return { check, proof: check?.ok ? await ctx.prove(opts.wt) : null, session, asked: true };
+  }
+  proof = check?.ok ? await ctx.prove(opts.wt) : null;
+  return { check, proof, session, asked: true };
+}
+async function fixUntilGreen(ctx, opts) {
+  let check = opts.initial !== void 0 ? opts.initial : await ctx.check(opts.wt);
+  let session = opts.session?.agent === opts.agent ? opts.session : void 0;
+  for (let attempt = 1; check && !check.ok && attempt <= opts.attempts; attempt++) {
+    session = await ctx.ask({
+      title: `Fix failing check (${attempt}/${opts.attempts})`,
+      role: opts.role,
+      agent: opts.agent,
+      mode: "write",
+      cwd: opts.wt,
+      resume: session,
+      prompt: (session ? "" : preamble(opts.role, opts.agent, WRITE) + section("Task", ctx.task) + (opts.context ?? "")) + "code-flow ran the project's check on the current code and it fails. Fix the cause in the code \u2014 don't weaken or skip tests \u2014 then summarize." + checkSection(check)
+    });
+    await ctx.commit(opts.wt, `${opts.agent}: fix failing check`);
+    check = await ctx.check(opts.wt);
+  }
+  return { check, session };
+}
+export {
+  LETTERS,
+  READ_ONLY,
+  WRITE,
+  checkEvidence,
+  checkSection,
+  fence,
+  fixUntilGreen,
+  jsonInstruction,
+  planCheckpoint,
+  preamble,
+  proofEvidence,
+  proofLine,
+  proofRule,
+  proveOrAsk,
+  section
+};

package/src/patterns/race.js

@@ -0,0 +1,147 @@
+import { describeIssues } from "../integrity.js";
+import { JUDGE_SCHEMA } from "./schemas.js";
+import { checkSection, fence, jsonInstruction, LETTERS, preamble, proofEvidence, proofLine, proofRule, READ_ONLY, section, WRITE } from "./prompts.js";
+const racePattern = {
+  id: "race",
+  name: "Best-of-N race",
+  summary: "All contestants solve the task in parallel; a judge picks the best anonymized diff.",
+  description: "Use when the solution space is wide or a task is risky: you get several independent attempts and keep the best one.",
+  roles: [
+    {
+      id: "contestants",
+      label: "Contestants",
+      description: "Each solves the whole task in its own worktree",
+      multiple: true,
+      default: ["claude", "codex"]
+    },
+    {
+      id: "judge",
+      label: "Judge",
+      description: "Compares the results blind; pick several for a majority vote, ideally vendors that aren't competing",
+      multiple: true,
+      default: ["claude"]
+    }
+  ],
+  options: [],
+  async run(ctx) {
+    const contestants = ctx.participants("contestants");
+    if (contestants.length < 2) throw new Error("A race needs at least two contestants");
+    const judges = ctx.participants("judge");
+    if (!judges.length) throw new Error("Pick at least one judge");
+    const entries = await ctx.parallel(contestants, async ({ agent, settings, identity }, i) => {
+      const label = LETTERS[i] ?? String(i + 1);
+      const wt = await ctx.worktree(`candidate-${label.toLowerCase()}`);
+      const result = await ctx.ask({
+        title: `Candidate ${label}`,
+        role: "contestants",
+        agent,
+        settings,
+        identity,
+        mode: "write",
+        cwd: wt,
+        allowFailure: true,
+        prompt: preamble("contestant", agent, `${WRITE} Other agents are solving the same task independently; the best solution is kept.`) + section("Task", ctx.task) + proofRule(ctx) + section("Deliverable", "Implement the task completely, run the relevant tests, then summarize your approach and test results.")
+      });
+      await ctx.commit(wt, `candidate ${label}`);
+      const check = result.ok ? await ctx.check(wt, `Check candidate ${label}`) : null;
+      const tests = result.ok ? (await ctx.testChanges(wt)).filter((i2) => i2.severity === "high") : [];
+      return { label, agent, wt, result, check, tests, diff: result.ok ? await ctx.diff(wt) : "(attempt failed)" };
+    });
+    const changed = entries.filter((e) => e.result.ok && e.diff !== "(no changes)");
+    if (changed.length === 0) throw new Error("No contestant produced a usable change");
+    for (const e of entries) await ctx.artifact(`Candidate ${e.label} (${e.agent})`, e.wt);
+    const proofs = new Map(entries.map((e) => [e.label, ctx.proofOf(e.wt)]));
+    const passing = changed.filter((e) => e.check?.ok);
+    const honest = passing.filter((e) => !e.tests.length);
+    const viable = ctx.hasCheck && passing.length ? honest.length ? honest : passing : changed;
+    for (const e of changed.filter((e2) => e2.tests.length)) {
+      ctx.log(`Candidate ${e.label} changed tests in ways that could hide failures${honest.length && e.check?.ok ? ", so it can't win" : ""}:
+${describeIssues(e.tests)}`, "warn");
+    }
+    if (ctx.hasCheck) {
+      ctx.log(passing.length ? `Passing the check: ${passing.map((e) => e.label).join(", ")}${passing.length < changed.length ? " (only these can win)" : ""}` : "No candidate passes the check; the judge picks the closest one", passing.length ? "info" : "warn");
+    }
+    let winner = viable[0];
+    let reasons = [];
+    if (viable.length > 1) {
+      const competing = judges.filter((j) => contestants.some((c) => c.agent === j.agent)).map((j) => j.agent);
+      if (competing.length) ctx.log(`${competing.join(", ")} both competes and judges; a judge from another vendor is fairer`, "warn");
+      const judgeWt = await ctx.worktree("judge");
+      const order = seededShuffle(viable, ctx.run.id);
+      const labels = viable.map((e) => e.label);
+      const votes = await ctx.parallel(
+        judges,
+        ({ agent: judge, settings, identity }, i) => ctx.decide({
+          title: judges.length > 1 ? `Judge ${i + 1}` : "Judge candidates",
+          role: "judge",
+          agent: judge,
+          settings,
+          identity,
+          mode: "read",
+          cwd: judgeWt,
+          schema: JUDGE_SCHEMA,
+          what: "pick",
+          validate: (v) => changed.some((e) => e.label === v.winner.trim().toUpperCase()) ? void 0 : `winner must be one of ${changed.map((e) => e.label).join(", ")}`,
+          prompt: preamble("judge", judge, `${READ_ONLY} You are looking at the original, unmodified code; each candidate's changes are shown as a diff.`) + section("Task", ctx.task) + order.map(
+            (e) => section(
+              `Candidate ${e.label}`,
+              fence(e.diff, "diff") + (e.check ? checkSection(e.check, 2e3) : "") + proofEvidence(proofs.get(e.label) ?? null) + (e.tests.length ? `
+**Changes to tests found by code-flow:**
+${describeIssues(e.tests)}
+` : "")
+            )
+          ).join("") + section(
+            "Deliverable",
+            "Compare the candidates on correctness, completeness, test coverage, simplicity and risk" + (ctx.proves ? ", and on whether their tests prove the change (a test that fails without it)" : "") + `. Pick one winner from: ${labels.join(", ")}.`
+          ) + jsonInstruction('{"winner": "A", "ranking": ["A", "B"], "reasons": "..."}')
+        })
+      );
+      const tally = /* @__PURE__ */ new Map();
+      for (const { value } of votes) {
+        const choice = value.winner.trim().toUpperCase();
+        if (viable.some((e) => e.label === choice)) tally.set(choice, (tally.get(choice) ?? 0) + 1);
+        else ctx.log(`Judge picked candidate ${choice}, but it fails the check${tally.size || votes.length > 1 ? "" : `; using passing candidate ${winner.label}`}`, "warn");
+        reasons.push(value.reasons);
+      }
+      const best = [...tally.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0];
+      if (best) winner = viable.find((e) => e.label === best[0]);
+      if (judges.length > 1) ctx.log(`Votes: ${[...tally.entries()].map(([label, n]) => `${label}=${n}`).join(", ") || "none valid"}`);
+    }
+    ctx.log(`Winner: candidate ${winner.label} (${winner.agent})`);
+    if (ctx.hasCheck) ctx.setVerdict(winner.check?.ok ? "passed" : "failing");
+    ctx.setFacts({ winner: winner.agent, entrants: entries.map((e) => e.agent), proof: proofs.get(winner.label)?.status });
+    return [
+      `**Winner: Candidate ${winner.label} \u2014 ${winner.agent}** on branch \`${winner.wt.branch}\``,
+      proofLine(proofs.get(winner.label) ?? null),
+      reasons.length ? section(reasons.length > 1 ? "Judges' reasoning" : "Judge's reasoning", reasons.join("\n\n")) : "",
+      section(
+        "All candidates",
+        entries.map((e) => {
+          const status = e.result.ok ? "completed" : `failed (${e.result.error})`;
+          const check = e.check ? e.check.ok ? ", check passes" : ", check fails" : "";
+          const proof = proofs.get(e.label)?.status;
+          const proven = proof === "proven" ? ", proven" : proof === "weak" ? ", weakly proven" : proof === "unproven" ? ", not proven" : "";
+          return `- ${e.label}: ${e.agent} \u2014 ${status}${check}${proven} \u2014 \`${e.wt.branch}\``;
+        }).join("\n")
+      )
+    ].join("\n");
+  }
+};
+function seededShuffle(items, seed) {
+  let h = 2166136261;
+  for (const ch of seed) h = Math.imul(h ^ ch.charCodeAt(0), 16777619);
+  const random = () => {
+    h = Math.imul(h ^ h >>> 15, 2246822507);
+    h = Math.imul(h ^ h >>> 13, 3266489909);
+    return ((h ^= h >>> 16) >>> 0) / 4294967296;
+  };
+  const out = [...items];
+  for (let i = out.length - 1; i > 0; i--) {
+    const j = Math.floor(random() * (i + 1));
+    [out[i], out[j]] = [out[j], out[i]];
+  }
+  return out;
+}
+export {
+  racePattern
+};

package/src/patterns/schemas.js

@@ -0,0 +1,40 @@
+const obj = (properties) => ({
+  type: "object",
+  properties,
+  required: Object.keys(properties),
+  additionalProperties: false
+});
+const str = { type: "string" };
+const strings = { type: "array", items: str };
+const repro = obj({ path: str, contents: str, command: str });
+const REVIEW_SCHEMA = obj({
+  verdict: { type: "string", enum: ["approve", "changes_requested"] },
+  issues: {
+    type: "array",
+    items: obj({ severity: { type: "string", enum: ["high", "medium", "low"] }, file: str, problem: str, fix: str, repro })
+  }
+});
+const JUDGE_SCHEMA = obj({ winner: str, ranking: strings, reasons: str });
+const SUBTASKS_SCHEMA = obj({
+  /** What every part must agree on (interfaces, names, data shapes); each worker gets it. */
+  contracts: str,
+  subtasks: { type: "array", items: obj({ id: str, title: str, instructions: str, agent: str }) }
+});
+const TEST_SPEC_SCHEMA = obj({ test_command: str, test_files: strings });
+const TEST_VERDICT_SCHEMA = obj({ verdict: { type: "string", enum: ["pass", "fail"] }, failures: strings });
+const COUNCIL_SCHEMA = obj({
+  verdict: { type: "string", enum: ["approve", "changes_requested"] },
+  summary: str,
+  findings: {
+    type: "array",
+    items: obj({ severity: { type: "string", enum: ["high", "medium", "low"] }, file: str, problem: str, fix: str, raised_by: strings, repro })
+  }
+});
+export {
+  COUNCIL_SCHEMA,
+  JUDGE_SCHEMA,
+  REVIEW_SCHEMA,
+  SUBTASKS_SCHEMA,
+  TEST_SPEC_SCHEMA,
+  TEST_VERDICT_SCHEMA
+};