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

package/src/patterns/council.js

@@ -0,0 +1,199 @@
+import { blocks } from "../engine.js";
+import { defaultBranch, mergeBase } from "../github.js";
+import { checkIssues, checkMark, CONFIRMATION, REVIEW_SHAPE, reproRule, severityOf } from "./findings.js";
+import { COUNCIL_SCHEMA, REVIEW_SCHEMA } from "./schemas.js";
+import { checkEvidence, fence, jsonInstruction, LETTERS, preamble, proofEvidence, proofLine, READ_ONLY, section } from "./prompts.js";
+const SEVERITY = { high: 0, medium: 1, low: 2 };
+const councilPattern = {
+  id: "council",
+  name: "Review council",
+  summary: "Several agents review the same changes on their own; a chair merges what they found.",
+  description: "Use to review a pull request or a branch before merging: different models catch different problems, code-flow runs the tests reviewers show bugs with, and the worst confirmed problems rank first. Read-only \u2014 nothing is changed.",
+  roles: [
+    { id: "reviewers", label: "Reviewers", description: "Each reviews the changes on its own, read-only", multiple: true, default: ["claude", "codex"] },
+    { id: "chair", label: "Chair", description: "Merges the reviews into one, noting where reviewers agree", default: ["claude"] }
+  ],
+  options: [],
+  async run(ctx) {
+    const reviewers = ctx.participants("reviewers");
+    if (!reviewers.length) throw new Error("Pick at least one reviewer");
+    const wt = await ctx.worktree("review");
+    const base = await ctx.remember("review-base", "base", async () => {
+      if (ctx.run.reviewBase) return ctx.run.reviewBase;
+      const main = await defaultBranch(ctx.run.repo);
+      return main ? await mergeBase(ctx.run.repo, main, ctx.run.baseRef) ?? null : null;
+    });
+    const diff = base && base !== ctx.run.baseRef ? await ctx.diff(wt, base) : "(no changes)";
+    const scope = diff === "(no changes)" ? section("What to review", "There's no diff against the default branch, so review the code the task is about.") : section("Changes under review", fence(diff, "diff"));
+    if (diff === "(no changes)") ctx.log("No diff against the default branch; reviewing the code the task points at");
+    let evidence = "";
+    let proof = null;
+    if (ctx.proves && base && diff !== "(no changes)") {
+      const check = await ctx.check(wt, "Check the changes");
+      proof = check?.ok ? await ctx.prove(wt, { from: base }) : null;
+      evidence = checkEvidence(ctx, check, 3e3) + proofEvidence(proof);
+    }
+    const reviews = await ctx.parallel(reviewers, async ({ agent, settings, identity }, i) => {
+      const label = LETTERS[i] ?? String(i + 1);
+      const outcome = await ctx.decide({
+        title: `Review ${label}`,
+        schema: REVIEW_SCHEMA,
+        what: "review",
+        role: "reviewers",
+        agent,
+        settings,
+        identity,
+        mode: "read",
+        cwd: wt,
+        prompt: preamble("reviewer", agent, `${READ_ONLY} Other reviewers are reviewing the same changes independently.`) + section("Task", ctx.task) + scope + evidence + section(
+          "Deliverable",
+          "Look for bugs, security problems, missing or weak tests, and anything that doesn't do what the task or description says. Read the surrounding code where you need to. Report real problems only \u2014 not style preferences \u2014 with the file and a concrete fix."
+        ) + reproRule(ctx) + jsonInstruction(REVIEW_SHAPE)
+      }).catch((err) => {
+        if (ctx.signal.aborted) throw err;
+        ctx.log(`Reviewer ${label} (${agent}) didn't finish: ${err.message}`, "warn");
+        return void 0;
+      });
+      return outcome ? { label, agent, review: outcome.value } : void 0;
+    });
+    const done = reviews.filter((r) => !!r);
+    if (!done.length) throw new Error("No reviewer finished");
+    const checked = [];
+    for (const r of done) checked.push(await checkIssues(ctx, wt, r.review.issues, `Reviewer ${r.label}'s test`));
+    let merged;
+    if (done.length === 1) {
+      const only = done[0];
+      merged = {
+        verdict: only.review.verdict,
+        summary: "",
+        findings: only.review.issues.map((i) => ({ ...i, severity: severityOf(i.severity), raised_by: [only.label] }))
+      };
+    } else {
+      const chair = ctx.agent("chair");
+      const letters = done.map((r) => r.label);
+      const { value } = await ctx.decide({
+        title: "Merge the reviews",
+        schema: COUNCIL_SCHEMA,
+        what: "merged review",
+        role: "chair",
+        agent: chair,
+        mode: "read",
+        cwd: wt,
+        validate: (v) => {
+          const bad = v.findings.flatMap((f) => f.raised_by).find((l) => !letters.includes(l));
+          return bad ? `raised_by must only use reviewer letters ${letters.join(", ")} (got "${bad}")` : void 0;
+        },
+        prompt: preamble("chair of a review council", chair, READ_ONLY) + section("Task", ctx.task) + section(
+          "Reviews",
+          done.map((r, n) => {
+            const issues = r.review.issues.map((issue, i) => ({ ...issue, checked_by_code_flow: checkNote(issue.severity, checked[n][i]) }));
+            return `### Reviewer ${r.label}: ${r.review.verdict}
+${fence(JSON.stringify(issues, null, 2), "json")}`;
+          }).join("\n\n")
+        ) + section(
+          "Deliverable",
+          "Merge these into one review. Combine findings that describe the same problem and list every reviewer who raised it. `checked_by_code_flow` says what code-flow found running a finding's `repro` on the code: a high-severity finding whose test passes is a false alarm, and one without a test is unconfirmed. Check doubtful findings against the code and drop the ones that are wrong. Keep each finding's `repro` as it is (the confirmed one, if several reviewers gave one); use \"\" fields when none did. Request changes if a confirmed high-severity problem or a real medium one remains. Write a short summary for the author."
+        ) + jsonInstruction(
+          '{"verdict": "approve" | "changes_requested", "summary": "...", "findings": [{"severity": "high|medium|low", "file": "path", "problem": "...", "fix": "...", "raised_by": ["A", "B"], "repro": {"path": "", "contents": "", "command": ""}}]}'
+        )
+      });
+      merged = value;
+    }
+    const agentOf = Object.fromEntries(done.map((r) => [r.label, r.agent]));
+    const checks = await checkIssues(ctx, wt, merged.findings, "Merged finding's test");
+    const { raised, added } = restoreConfirmed(done, checked, merged, checks);
+    const restored = [...raised.values(), ...added];
+    if (restored.length) {
+      ctx.log(
+        `The chair left out or rated lower ${restored.length} finding${restored.length === 1 ? "" : "s"} a test confirms; code-flow put ${restored.length === 1 ? "it" : "them"} back as raised: ` + restored.map((r) => `${r.finding.severity} "${r.finding.problem}" (Reviewer ${r.label}: ${r.why})`).join("; "),
+        "warn"
+      );
+    }
+    const note = (r) => `from Reviewer ${r.label}, whose test confirms it: ${r.why}`;
+    const findings = [
+      ...merged.findings.map((f, i) => {
+        const back = raised.get(i);
+        return {
+          severity: back?.finding.severity ?? severityOf(f.severity),
+          file: f.file,
+          problem: f.problem,
+          fix: f.fix,
+          raisedBy: [...new Set(f.raised_by.map((l) => agentOf[l]).filter(Boolean))],
+          // Rated low, the chair's copy wasn't run (a suggestion): the reviewer's test result stands.
+          check: back?.finding.check ?? checks[i],
+          ...back ? { restored: note(back) } : {}
+        };
+      }),
+      ...added.map((r) => ({ ...r.finding, raisedBy: [agentOf[r.label]], restored: note(r) }))
+    ].sort(
+      (a, b) => SEVERITY[a.severity] - SEVERITY[b.severity] || CONFIRMATION[a.check.status] - CONFIRMATION[b.check.status] || b.raisedBy.length - a.raisedBy.length
+    );
+    ctx.learn(findings.filter((f) => f.check?.status !== "refuted"));
+    const blocking = findings.filter((f) => blocks(f.severity, f.check?.status ?? "unconfirmed"));
+    const verdict = blocking.length ? "changes_requested" : "approve";
+    if (verdict !== merged.verdict) {
+      ctx.log(
+        `The chair ${merged.verdict === "approve" ? "approved" : "requested changes"}, but ` + (blocking.length ? `${blocking.length} finding${blocking.length === 1 ? "" : "s"} block${blocking.length === 1 ? "s" : ""}` : "no finding blocks") + ` once code-flow has run their tests, so the review says ${verdict === "approve" ? "Approve" : "Changes requested"}`,
+        "warn"
+      );
+    }
+    const markdown = renderReview(verdict, merged.summary, findings, done.map((r) => r.agent), proof);
+    ctx.setReview({
+      verdict,
+      summary: merged.summary,
+      findings,
+      reviewers: done.map((r) => ({ agent: r.agent, verdict: r.review.verdict, issues: r.review.issues.length })),
+      proof: proof ?? void 0,
+      markdown
+    });
+    if (proof) ctx.setFacts({ proof: proof.status });
+    ctx.log(`Council: ${verdict === "approve" ? "approve" : "changes requested"} with ${findings.length} finding(s) from ${done.length} reviewer(s)`);
+    return markdown;
+  }
+};
+function restoreConfirmed(done, checked, merged, checks) {
+  const raised = /* @__PURE__ */ new Map();
+  const added = [];
+  const standsFor = /* @__PURE__ */ new Map();
+  done.forEach(
+    (r, n) => r.review.issues.forEach((issue, i) => {
+      const check = checked[n][i];
+      if (check.status !== "confirmed") return;
+      const severity = severityOf(issue.severity);
+      const rank = (j) => SEVERITY[raised.get(j)?.finding.severity ?? severityOf(merged.findings[j].severity)];
+      const best = merged.findings.map((f, j) => ({ f, j })).filter(({ j }) => !standsFor.get(j)?.has(r.label)).filter(({ f, j }) => f.file === issue.file && (sameRepro(f.repro, issue.repro) || f.raised_by.includes(r.label) && checks[j].status === "confirmed")).sort((a, b) => rank(a.j) - rank(b.j))[0];
+      if (best) standsFor.set(best.j, (standsFor.get(best.j) ?? /* @__PURE__ */ new Set()).add(r.label));
+      if (best && rank(best.j) <= SEVERITY[severity]) return;
+      const finding = { severity, file: issue.file, problem: issue.problem, fix: issue.fix, check };
+      if (best) raised.set(best.j, { label: r.label, why: `the chair rated it ${severityOf(best.f.severity)}`, finding });
+      else added.push({ label: r.label, why: "the chair left it out", finding });
+    })
+  );
+  return { raised, added };
+}
+function sameRepro(a, b) {
+  if (!a || !b) return false;
+  const [path, command] = [(a.path ?? "").trim(), (a.command ?? "").trim()];
+  return !!(path || command) && path === (b.path ?? "").trim() && (a.contents ?? "") === (b.contents ?? "") && command === (b.command ?? "").trim();
+}
+function checkNote(severity, check) {
+  if (check.status === "confirmed") return `confirmed: \`${check.command}\` fails with its test on this code`;
+  if (check.status === "refuted") return `false alarm: \`${check.command}\` passes with its test on this code`;
+  if (severityOf(severity) === "low") return "a suggestion: not checked";
+  return check.status === "unverified" ? `couldn't run its test: ${check.detail}` : `unconfirmed: ${check.detail}`;
+}
+function renderReview(verdict, summary, findings, reviewers, proof = null) {
+  const head = `**Review council: ${verdict === "approve" ? "Approve" : "Changes requested"}** \u2014 ${reviewers.length} reviewer${reviewers.length === 1 ? "" : "s"} (${reviewers.join(", ")})`;
+  const list = findings.length ? findings.map(
+    (f, i) => `${i + 1}. **${f.severity}** \`${f.file || "general"}\` \u2014 ${f.problem}
+   *Fix:* ${f.fix}
+   *Raised by:* ${f.raisedBy.join(", ")}` + (f.check ? `
+   *Checked by code-flow:* ${checkMark(f)}` : "") + (f.restored ? `
+   *Restored by code-flow:* ${f.restored}` : "")
+  ).join("\n") : "No problems found.";
+  return [head, proofLine(proof), summary.trim() ? section("Summary", summary) : "", section("Findings", list)].join("\n");
+}
+export {
+  councilPattern,
+  renderReview
+};

package/src/patterns/debate.js

@@ -0,0 +1,188 @@
+import { getAdapter } from "../adapters/index.js";
+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, LETTERS, planCheckpoint, preamble, proofEvidence, proofLine, proofRule, proveOrAsk, READ_ONLY, section, WRITE } from "./prompts.js";
+const debatePattern = {
+  id: "debate",
+  name: "Debate \u2192 Synthesize \u2192 Build",
+  summary: "Agents propose designs independently, critique each other, then one plan is synthesized and built.",
+  description: "Use for design-heavy or ambiguous work (architecture, APIs, refactors) where independent perspectives beat a single plan.",
+  roles: [
+    {
+      id: "debaters",
+      label: "Debaters",
+      description: "Each proposes and defends a design",
+      multiple: true,
+      default: ["claude", "codex"]
+    },
+    { id: "synthesizer", label: "Synthesizer", description: "Merges the debate into one plan, ideally a vendor that isn't debating", default: ["claude"] },
+    {
+      id: "builder",
+      label: "Builder",
+      description: "Implements the final plan (leave empty for design only)",
+      optional: true,
+      default: ["codex"]
+    },
+    {
+      id: "reviewer",
+      label: "Reviewer",
+      description: "Reviews the build against the agreed plan (optional)",
+      optional: true,
+      default: ["claude"]
+    }
+  ],
+  options: [
+    { id: "rounds", label: "Critique rounds", type: "number", default: 1, min: 0, max: 3 },
+    { id: "reviewRounds", label: "Max review rounds", type: "number", default: 2, min: 1, max: 5 }
+  ],
+  async run(ctx) {
+    const debaters = ctx.participants("debaters");
+    if (debaters.length < 2) throw new Error("A debate needs at least two debaters");
+    const rounds = ctx.option("rounds", 1);
+    const synthesizer = ctx.agent("synthesizer");
+    if (debaters.some((d) => d.agent === synthesizer)) ctx.log(`${synthesizer} both debates and synthesizes; a synthesizer from another vendor is fairer`, "warn");
+    const designWt = await ctx.worktree("design");
+    const label = (i) => `Proposal ${LETTERS[i] ?? String(i + 1)}`;
+    let positions = await ctx.parallel(
+      debaters,
+      ({ agent, settings, identity }, i) => ctx.ask({
+        title: `Proposal \u2014 ${getAdapter(agent).displayName}`,
+        role: "debaters",
+        agent,
+        settings,
+        identity,
+        mode: "read",
+        cwd: designWt,
+        prompt: preamble("debater", agent, `${READ_ONLY} Other agents are proposing designs independently. Yours will be ${label(i)}.`) + section("Task", ctx.task) + section(
+          "Deliverable",
+          "Study the codebase and propose a design: approach, key changes, trade-offs, and the risks you see. Under 500 words."
+        )
+      })
+    );
+    for (let round = 1; round <= rounds; round++) {
+      const snapshot = positions;
+      positions = await ctx.parallel(snapshot, (own, i) => {
+        const others = snapshot.map((p, j) => j === i ? "" : section(label(j), p.finalText)).join("");
+        return ctx.ask({
+          title: `Critique round ${round} \u2014 ${getAdapter(own.agent).displayName}`,
+          role: "debaters",
+          agent: own.agent,
+          settings: debaters[i].settings,
+          identity: debaters[i].identity,
+          mode: "read",
+          cwd: designWt,
+          resume: own,
+          prompt: `Here are the other agents' current proposals (yours is ${label(i)}).` + others + section(
+            "Deliverable",
+            "Critique them honestly: what is better than yours, what is wrong or risky. Then give your revised proposal. Concede points where they are right; hold your ground where you have evidence."
+          ),
+          // Its own conversation gone, a new one needs its earlier proposal too.
+          fresh: preamble("debater", own.agent, `${READ_ONLY} Other agents are proposing designs too.`) + section("Task", ctx.task) + section(`Your proposal so far (${label(i)})`, own.finalText) + section("The other agents' current proposals", others) + section(
+            "Deliverable",
+            "Critique them honestly: what is better than yours, what is wrong or risky. Then give your revised proposal. Concede points where they are right; hold your ground where you have evidence."
+          )
+        });
+      });
+    }
+    let plan = await ctx.ask({
+      title: "Synthesize plan",
+      role: "synthesizer",
+      agent: synthesizer,
+      mode: "read",
+      cwd: designWt,
+      prompt: preamble("synthesizer", synthesizer, `${READ_ONLY} The debaters are anonymous: weigh each proposal on its merits.`) + section("Task", ctx.task) + positions.map((p, i) => section(`Final position: ${label(i)}`, p.finalText)).join("") + section(
+        "Deliverable",
+        "Merge these into a single implementation plan. List each point of disagreement and which side you chose and why. End with concrete steps and verification commands."
+      )
+    });
+    const [builder] = ctx.agents("builder");
+    if (!builder) {
+      return section("Synthesized plan", plan.finalText);
+    }
+    plan = await planCheckpoint(ctx, { agent: synthesizer, role: "synthesizer", wt: designWt, plan, what: "plan" });
+    const buildWt = await ctx.worktree("build");
+    const build = await ctx.ask({
+      title: "Implement synthesized plan",
+      role: "builder",
+      agent: builder,
+      mode: "write",
+      cwd: buildWt,
+      prompt: preamble("builder", builder, WRITE) + section("Task", ctx.task) + section("Agreed plan", plan.finalText) + proofRule(ctx) + section("Deliverable", "Implement the plan, run the relevant tests, then summarize the changes.")
+    });
+    await ctx.commit(buildWt, `${builder}: implement synthesized plan`);
+    let fixed = await fixUntilGreen(ctx, { agent: builder, role: "builder", wt: buildWt, session: build, attempts: 2 });
+    const proved = await proveOrAsk(ctx, { agent: builder, role: "builder", wt: buildWt, check: fixed.check, session: fixed.session ?? build, attempts: 2, ask: true });
+    fixed = { check: proved.check, session: proved.session ?? fixed.session };
+    let check = fixed.check;
+    const [reviewer] = ctx.agents("reviewer");
+    const reviewRounds = ctx.option("reviewRounds", 2);
+    let verdict;
+    let findings = [];
+    let review;
+    let proof = proved.proof;
+    let session = fixed.session ?? build;
+    let reply;
+    let reviewed = 0;
+    let unreviewed = false;
+    for (let round = 1; reviewer && (!check || check.ok) && round <= reviewRounds; round++) {
+      const testChanges = await ctx.testChanges(buildWt);
+      const decided = await ctx.decide({
+        title: round === 1 ? "Review the build" : `Review the build (round ${round})`,
+        schema: REVIEW_SCHEMA,
+        what: "review verdict",
+        role: "reviewer",
+        agent: reviewer,
+        mode: "read",
+        cwd: buildWt,
+        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("Agreed plan", plan.finalText) : "") + section("Diff against base", fence(await ctx.diff(buildWt), "diff")) + checkEvidence(ctx, check) + proofEvidence(proof) + (testChanges.length ? section("Changes to tests (found by code-flow)", `Raise each as a medium issue unless the task requires it:
+${describeIssues(testChanges)}`) : "") + section("Deliverable", "Check that the build does what the plan and task say, and look for bugs, missed edge cases and missing tests. Only raise real problems.") + reproRule(ctx) + jsonInstruction(REVIEW_SHAPE)
+      });
+      review = decided.outcome;
+      verdict = decided.value;
+      reviewed = round;
+      unreviewed = false;
+      findings = await checkReview(ctx, buildWt, { label: `Review round ${round}`, reviewer, round, review: verdict });
+      if (approves(findings) || round === reviewRounds) break;
+      session = await ctx.ask({
+        title: round === 1 ? "Address review" : `Address review (round ${round})`,
+        role: "builder",
+        agent: builder,
+        mode: "write",
+        cwd: buildWt,
+        resume: session,
+        prompt: findingsForBuilder(reviewer, findings)
+      });
+      reply = session.finalText;
+      await ctx.commit(buildWt, round === 1 ? `${builder}: address review` : `${builder}: address review round ${round}`);
+      unreviewed = true;
+      fixed = await fixUntilGreen(ctx, { agent: builder, role: "builder", wt: buildWt, session, attempts: 2 });
+      session = fixed.session ?? session;
+      check = fixed.check;
+      if (check && !check.ok) {
+        ctx.log("The check still fails after 2 fix attempts; stopping before the next review", "warn");
+        break;
+      }
+      proof = check?.ok ? await ctx.prove(buildWt) : null;
+    }
+    const approved = !!verdict && approves(findings);
+    await ctx.artifact("Result", buildWt);
+    if (check) ctx.setVerdict(check.ok ? "passed" : "failing");
+    if (verdict) ctx.setFacts({ approved, reviewRounds: reviewed });
+    ctx.setFacts({ proof: ctx.proofOf(buildWt)?.status });
+    return [
+      `**Built**${check ? check.ok ? `, and \`${check.command}\` passes` : `, but \`${check.command}\` still fails` : ""} on branch \`${buildWt.branch}\``,
+      proofLine(ctx.proofOf(buildWt)),
+      verdict ? `Review by ${reviewer}: ${approved ? `approved${reviewed > 1 ? ` in round ${reviewed}` : ""}` : unreviewed ? `${findings.filter((f) => f.blocking).length} blocking finding(s) sent back to the builder, whose fixes weren't re-reviewed: the check fails since` : `not approved after ${reviewed} round${reviewed === 1 ? "" : "s"}`}.` : "",
+      verdict ? findingsLine(findings) : "",
+      verdict && !approved && !unreviewed ? findingsSection("Open review findings", findings) : "",
+      section("Synthesized plan", plan.finalText),
+      section("Builder summary", build.finalText)
+    ].join("\n");
+  }
+};
+export {
+  debatePattern
+};

package/src/patterns/findings.js

@@ -0,0 +1,141 @@
+import { getAdapter } from "../adapters/index.js";
+import { blocks } from "../engine.js";
+import { fence, section } from "./prompts.js";
+const REVIEW_SHAPE = '{"verdict": "approve" | "changes_requested", "issues": [{"severity": "high|medium|low", "file": "path", "problem": "...", "fix": "...", "repro": {"path": "test file to add, or \\"\\"", "contents": "the whole test file, or \\"\\"", "command": "plain test command that runs it, or \\"\\""}}]}';
+const MAX_REPROS = 6;
+const SEVERITIES = ["high", "medium", "low"];
+function reproRule(ctx) {
+  const check = ctx.hasCheck ? ctx.run.loop.check : void 0;
+  return section(
+    "Show it (code-flow runs your tests)",
+    "Severity decides what blocks approval: high and medium issues block, low ones are suggestions. A high-severity issue says the code has a bug, so show it with a `repro`: a test that fails on this code because of the bug. Give the test file's path, named like the project's tests, and its whole contents" + (check ? `. code-flow adds it to a copy of this code and runs \`${check}\` there, or the plain test command you give instead (one that runs just your test, say).` : ", and the plain test command that runs it (e.g. `pytest tests/test_bug.py`): this run has no check of its own.") + " A command alone can run tests that are already there. A high-severity issue blocks only if its test fails. If the test passes, the issue is a false alarm and doesn't block; without a repro it's marked unconfirmed and doesn't block either, so rate a problem no test can show medium. A repro on a medium issue is welcome too: if it passes, that issue doesn't block. Use \"\" for every `repro` field when there's none."
+  );
+}
+async function checkReview(ctx, wt, opts) {
+  const issues = opts.review.issues ?? [];
+  const checks = await checkIssues(ctx, wt, issues, "Reviewer's test");
+  const findings = issues.map((issue, i) => {
+    const severity = severityOf(issue.severity);
+    const check = checks[i];
+    return { severity, file: issue.file ?? "", problem: issue.problem, fix: issue.fix ?? "", check, blocking: blocks(severity, check.status) };
+  });
+  ctx.setFindings(wt, { reviewer: opts.reviewer, round: opts.round, verdict: opts.review.verdict, findings, head: await ctx.head(wt), at: Date.now() });
+  const blocking = findings.filter((f) => f.blocking);
+  ctx.log(`${opts.label}: ${opts.review.verdict} (${findings.length} issues${findings.length ? `; ${tally(findings)}` : ""})`);
+  if (blocking.length) ctx.learn(findings.filter((f) => f.check.status !== "refuted"));
+  return findings;
+}
+async function checkIssues(ctx, wt, issues, title) {
+  const checks = [];
+  let ran = 0;
+  for (const issue of issues) {
+    if (severityOf(issue.severity) === "low") checks.push({ status: "unconfirmed", detail: "a suggestion: not checked" });
+    else if (!hasRepro(issue.repro)) checks.push({ status: "unconfirmed", detail: "no test came with it" });
+    else if (ran >= MAX_REPROS) checks.push({ status: "unverified", detail: `not run: code-flow runs at most ${MAX_REPROS} tests per review` });
+    else {
+      ran++;
+      checks.push(await ctx.reproduce(wt, issue.repro, `${title}: ${short(issue.problem)}`));
+    }
+  }
+  return checks;
+}
+function severityOf(severity) {
+  return SEVERITIES.find((s) => s === severity) ?? "medium";
+}
+function approves(findings) {
+  return !findings.some((f) => f.blocking);
+}
+function findingsForBuilder(reviewer, findings) {
+  const confirmed = findings.filter((f) => f.check.status === "confirmed" && f.severity !== "low");
+  const open = findings.filter((f) => f.check.status !== "confirmed" && f.check.status !== "refuted" && f.severity !== "low");
+  const falseAlarms = findings.filter((f) => f.check.status === "refuted" && f.severity !== "low");
+  const suggestions = findings.filter((f) => f.severity === "low");
+  const item = (f, i) => `${i + 1}. **${f.severity}** \`${f.file || "general"}\` \u2014 ${f.problem}
+   Suggested fix: ${f.fix || "(none given)"}`;
+  return `The ${getAdapter(reviewer).displayName} reviewer's findings, checked by code-flow. Fix what blocks, re-run the tests, then summarize what you fixed and anything you dispute.` + (confirmed.length ? section(
+    "Confirmed: the reviewer's test fails on your code (these block)",
+    confirmed.map(
+      (f, i) => item(f, i) + (f.check.path && f.check.contents ? `
+   The test, \`${f.check.path}\`:
+${fence(f.check.contents)}` : "") + `
+   \`${f.check.command}\` fails:
+${fence(f.check.detail)}`
+    ).join("\n") + "\n\nMake each of these tests pass by fixing the code, and add the reviewer's test (or one like it) to your change. If a test itself is wrong, say why instead."
+  ) : "") + (open.length ? section(
+    "Not shown by a test",
+    open.map((f, i) => `${item(f, i)}
+   ${openNote(f)}`).join("\n") + "\n\nFix these if you agree. If you don't, change nothing for it and say why, with evidence (a test you ran, the code that already handles it): the reviewer sees your answer."
+  ) : "") + (falseAlarms.length ? section("False alarms: the reviewer's own test passes (no change needed)", falseAlarms.map((f, i) => item(f, i)).join("\n")) : "") + (suggestions.length ? section("Suggestions (low severity, optional)", suggestions.map((f, i) => item(f, i)).join("\n")) : "");
+}
+function builderReply(text) {
+  if (!text?.trim()) return "";
+  return section(
+    "The builder's answer to your review",
+    `${text.trim()}
+
+It may dispute findings no test shows. Drop the ones it shows are wrong; keep a disputed bug only with a repro that fails.`
+  );
+}
+function findingsSection(title, findings) {
+  if (!findings.length) return "";
+  return section(
+    title,
+    findings.map((f) => `- **${f.severity}** \`${f.file || "general"}\` \u2014 ${f.problem} \u2014 ${checkMark(f)}${f.blocking ? " \xB7 blocks" : ""}`).join("\n")
+  );
+}
+function findingsLine(findings) {
+  const unconfirmed = findings.filter((f) => f.severity === "high" && f.check.status === "unconfirmed").length;
+  const falseAlarms = findings.filter((f) => f.check.status === "refuted" && f.severity !== "low").length;
+  const parts = [
+    unconfirmed ? `\u26A0 ${unconfirmed} unconfirmed high-severity claim${unconfirmed === 1 ? "" : "s"} (no test shows it; not blocking)` : "",
+    falseAlarms ? `${falseAlarms} false alarm${falseAlarms === 1 ? "" : "s"} (the reviewer's own test passes)` : ""
+  ].filter(Boolean);
+  return parts.length ? `Review findings: ${parts.join("; ")}.` : "";
+}
+function checkMark(f) {
+  const check = f.check;
+  if (!check) return "not checked";
+  if (check.status === "confirmed") return "\u2713 confirmed: its test fails";
+  if (check.status === "refuted") return "\u2717 not confirmed: its test passes (a false alarm)";
+  if (f.severity === "low") return "suggestion";
+  if (check.status === "unverified") return `couldn't run its test (${check.detail})`;
+  return f.severity === "high" ? "\u26A0 unconfirmed: no test shows it" : "no test";
+}
+const CONFIRMATION = { confirmed: 0, unverified: 1, unconfirmed: 2, refuted: 3 };
+function hasRepro(repro) {
+  return !!repro && (!!repro.path?.trim() || !!repro.command?.trim());
+}
+function openNote(f) {
+  if (f.check.status === "unverified") return `code-flow couldn't run the reviewer's test: ${f.check.detail}. It blocks on the reviewer's word.`;
+  if (f.severity === "high") return `Unconfirmed: ${f.check.detail}. A bug claim nobody has shown; it doesn't block.`;
+  return "No test with it; it blocks on the reviewer's word.";
+}
+function tally(findings) {
+  const count = (pred) => findings.filter(pred).length;
+  const parts = [
+    [count((f) => f.blocking), "blocking"],
+    [count((f) => f.check.status === "confirmed"), "confirmed by a failing test"],
+    [count((f) => f.check.status === "refuted"), "false alarm (its test passes)"],
+    [count((f) => f.severity === "high" && f.check.status === "unconfirmed"), "unconfirmed high-severity claim"]
+  ];
+  return parts.map(([n, what]) => `${n} ${what}`).filter((p) => !p.startsWith("0 ")).join(", ") || "none blocking";
+}
+function short(text) {
+  const line = text.split("\n")[0].trim();
+  return line.length > 60 ? `${line.slice(0, 59)}\u2026` : line;
+}
+export {
+  CONFIRMATION,
+  REVIEW_SHAPE,
+  approves,
+  builderReply,
+  checkIssues,
+  checkMark,
+  checkReview,
+  findingsForBuilder,
+  findingsLine,
+  findingsSection,
+  hasRepro,
+  reproRule,
+  severityOf
+};

package/src/patterns/index.js

@@ -0,0 +1,19 @@
+import { pipelinePattern } from "./pipeline.js";
+import { racePattern } from "./race.js";
+import { debatePattern } from "./debate.js";
+import { supervisorPattern } from "./supervisor.js";
+import { tddPattern } from "./tdd.js";
+import { loopPattern } from "./loop.js";
+import { councilPattern } from "./council.js";
+import { soloPattern } from "./solo.js";
+import { autoTeamPattern } from "./auto-team.js";
+import { taskDraftPattern } from "./task-draft.js";
+const patterns = [autoTeamPattern, pipelinePattern, loopPattern, racePattern, debatePattern, supervisorPattern, tddPattern, councilPattern, soloPattern];
+function findPattern(id) {
+  if (id === taskDraftPattern.id) return taskDraftPattern;
+  return patterns.find((p) => p.id === id);
+}
+export {
+  findPattern,
+  patterns
+};