@agentsdance/codejury 0.1.0

package/lib/store.js

@@ -0,0 +1,316 @@
+// Where a run lives on disk.
+//
+// runs/<slug>/events.ndjson  append-only; two writers are safe (the CLI appends
+//                            agent events, the main agent appends verdicts)
+// runs/<slug>/run.json       the folded view the console reads
+import { mkdir, readFile, writeFile, appendFile, readdir, open } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Where a run lives.
+ *
+ * `attempt` separates one invocation from another. Without it every
+ * `jury agent <same-pr>` appended to the same directory, so three separate
+ * reviews merged into rounds 1-5 of a single run — and a killed run's open
+ * rounds interleaved with the next one's. Rounds within ONE invocation still
+ * belong together; two invocations do not.
+ */
+export function slugFor(target) {
+  const repo = (target.repo ?? "repo").replace(/[^\w.-]+/g, "-");
+  const id = String(target.id ?? "0").replace(/[^\w.-]+/g, "");
+  const base = `${repo}-${id}`;
+  const attempt = target.attempt ? String(target.attempt).replace(/[^\w.-]+/g, "") : "";
+  return attempt ? `${base}-${attempt}` : base;
+}
+
+/**
+ * A short, sortable stamp identifying one invocation: YYYYMMDD-HHMM.
+ * Sortable so the directory listing reads chronologically, and minute
+ * granularity because two runs of the same PR in the same minute are the same
+ * mistake as running it twice by accident.
+ */
+export function attemptStamp(now = new Date()) {
+  const p = (n) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}`
+    + `-${p(now.getHours())}${p(now.getMinutes())}`;
+}
+
+export function runsDir(cwd = process.cwd()) {
+  return path.join(cwd, "runs");
+}
+
+export async function appendEvent(dir, event) {
+  await mkdir(dir, { recursive: true });
+  const line = JSON.stringify({ ts: new Date().toISOString(), ...event });
+  await appendFile(path.join(dir, "events.ndjson"), line + "\n", "utf8");
+}
+
+export async function readEvents(dir) {
+  try {
+    const raw = await readFile(path.join(dir, "events.ndjson"), "utf8");
+    return raw
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => {
+        try {
+          return JSON.parse(l);
+        } catch {
+          return null; // a torn line must not blank the run
+        }
+      })
+      .filter(Boolean);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+/**
+ * Verbatim text kept beside the event log — the prompt a reviewer was given and
+ * the raw stream it produced. These are the evidence that the review happened
+ * and are often far too large for the event log, so they live in their own files.
+ */
+export async function writeArtifact(dir, name, text) {
+  await mkdir(dir, { recursive: true });
+  const safe = name.replace(/[^\w.-]+/g, "_");
+  await writeFile(path.join(dir, safe), text ?? "", "utf8");
+  return safe;
+}
+
+/**
+ * An artifact opened for incremental writing, so a reviewer's stream reaches
+ * disk while it is still talking rather than only when it exits. Writes are
+ * chained through one promise: fs handles do not queue concurrent writes, and
+ * chunks arriving faster than the disk can take them would otherwise interleave.
+ */
+export async function openArtifact(dir, name) {
+  await mkdir(dir, { recursive: true });
+  const safe = path.basename(name);
+  const fh = await open(path.join(dir, safe), "w");
+  let chain = Promise.resolve();
+  let closed = false;
+  return {
+    name: safe,
+    write(text) {
+      if (closed) return chain;
+      // Swallowed on purpose: a failed tail-write must not kill a review that
+      // is otherwise fine, and r.raw still holds the authoritative copy.
+      chain = chain.then(() => fh.write(text)).catch(() => {});
+      return chain;
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      await chain;
+      await fh.close().catch(() => {});
+    },
+  };
+}
+
+export async function readArtifact(dir, name) {
+  // Never let a caller-supplied name walk out of the run directory.
+  const safe = path.basename(name);
+  return readFile(path.join(dir, safe), "utf8");
+}
+
+export async function writeRun(dir, run) {
+  await mkdir(dir, { recursive: true });
+  await writeFile(path.join(dir, "run.json"), JSON.stringify(run, null, 2) + "\n", "utf8");
+}
+
+export async function readRun(dir) {
+  const raw = await readFile(path.join(dir, "run.json"), "utf8");
+  return JSON.parse(raw);
+}
+
+/**
+ * Every run under runs/. A malformed one is skipped and reported, never fatal —
+ * one bad file must not blank the whole console.
+ */
+export async function listRuns(base) {
+  let entries;
+  try {
+    entries = await readdir(base, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return { runs: [], skipped: [] };
+    throw err;
+  }
+  const runs = [];
+  const skipped = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    try {
+      // The directory name is how the console asks for this run's artifacts.
+      runs.push({ slug: e.name, ...(await readRun(path.join(base, e.name))) });
+    } catch (err) {
+      skipped.push({ dir: e.name, reason: err.code === "ENOENT" ? "no run.json" : err.message });
+    }
+  }
+  const rank = { human: 0, review: 1, queued: 2, converged: 3, merged: 4 };
+  // Newest first within a state. The id used to be the only tiebreak, which
+  // ordered runs alphabetically: an old review of #3 outranked a fresh one of
+  // #5, and the console's bare fallback (runs[0]) opened the stale one.
+  // `attempt` is the run's own stamp; runs made before it existed have none and
+  // sort last among their peers rather than jumping the queue. The id stays on
+  // as the final tiebreak so equal-attempt runs keep a stable order instead of
+  // falling back to whatever readdir returned.
+  const when = (r) => String(r.target?.attempt ?? "");
+  runs.sort((a, b) => {
+    const ra = rank[a.target?.state] ?? 9;
+    const rb = rank[b.target?.state] ?? 9;
+    return ra - rb
+      || when(b).localeCompare(when(a))
+      || String(a.target?.id).localeCompare(String(b.target?.id));
+  });
+  return { runs, skipped };
+}
+
+/** Fold the event log into the shape the console renders. */
+export function foldEvents(events, seed = {}) {
+  const run = {
+    target: seed.target ?? {},
+    rounds: [],
+    exchanges: [],
+    replies: [],
+    lanes: [],
+    marks: [],
+    ship: [],
+    tlfoot: "",
+    foot: "",
+    ...seed,
+  };
+  const findings = new Map();
+  const lanes = new Map(); // agent -> lane, kept in launch order
+  let t0 = null;
+  let lastMin = 0;
+
+  const laneFor = (agent) => {
+    let lane = lanes.get(agent);
+    if (!lane) lanes.set(agent, (lane = { who: agent, label: agent, segs: [] }));
+    return lane;
+  };
+
+  for (const e of events) {
+    const at = e.ts ? Date.parse(e.ts) : null;
+    if (at && t0 === null) t0 = at;
+    const min = at && t0 !== null ? +((at - t0) / 60000).toFixed(1) : 0;
+    if (min > lastMin) lastMin = min;
+
+    switch (e.t) {
+      case "round.start":
+        run.rounds.push({
+          n: e.n, sha: e.sha ?? "", verdicts: [], startMin: min,
+          // Wall-clock, not just the offset: the console sorts runs by recency
+          // and a round that has not reported yet still happened at a time.
+          startedAt: e.ts ?? "",
+          // The exact text the reviewers were given, so a verdict can be read
+          // against the question that produced it.
+          prompt: e.prompt ?? "", promptFile: e.promptFile ?? "",
+        });
+        run.marks.push({ at: min, l: `round ${e.n}` });
+        break;
+      case "agent.launch":
+        laneFor(e.agent).segs.push({ r: e.round, s: min });
+        break;
+      case "agent.report": {
+        const r = run.rounds.find((x) => x.n === e.round);
+        r?.verdicts.push({
+          a: e.agent, s: e.verdict, t: e.summary ?? e.verdict, seconds: e.seconds,
+          // Full text, not just the first line: a clean verdict still carries
+          // what the reviewer checked and what it could not check.
+          report: e.report ?? "", rawFile: e.rawFile ?? "", rawBytes: e.rawBytes ?? 0,
+          at: e.ts ?? "", atMin: min,
+        });
+        // Closes the span its own launch opened, so two rounds stay two spans.
+        const seg = lanes.get(e.agent)?.segs.find((s) => s.r === e.round && s.e === undefined);
+        if (seg) seg.e = min;
+        break;
+      }
+      case "finding.raised":
+        findings.set(e.id, {
+          id: e.id, round: e.round, with: e.agent, claim: e.claim,
+          loc: e.loc ?? "", res: "open", turns: [],
+        });
+        break;
+      case "finding.reproduced": {
+        const f = findings.get(e.id);
+        if (f) f.reproduced = e.evidence ?? true;
+        break;
+      }
+      case "finding.resolved": {
+        const f = findings.get(e.id);
+        if (f) { f.res = e.verdict; f.outcome = e.reason ?? ""; }
+        break;
+      }
+      // A reply is a turn in one reviewer's conversation, not a round of its
+      // own: it concerns only that reviewer's findings, so it hangs off them
+      // rather than appearing as a fourth round nobody ran.
+      case "reply.sent":
+        for (const f of findings.values()) {
+          if (f.with === e.agent && f.res !== "open") {
+            f.turns.push({ who: "claude", kind: "reply", resumed: e.resumed, at: min });
+          }
+        }
+        break;
+      case "reply.answered": {
+        const lane = laneFor(e.agent);
+        lane.segs.push({ r: "reply", s: min, e: min, t: `reply · ${e.seconds}s` });
+        for (const f of findings.values()) {
+          if (f.with === e.agent && f.res !== "open") {
+            f.turns.push({ who: e.agent, kind: "answer", seconds: e.seconds, at: min });
+          }
+        }
+        run.replies = [
+          ...(run.replies ?? []),
+          { agent: e.agent, verdict: e.verdict, seconds: e.seconds, report: e.report ?? "" },
+        ];
+        break;
+      }
+      case "target":
+        run.target = { ...run.target, ...e.target };
+        break;
+    }
+  }
+
+  // A launch with no report — the agent was killed, or the round is still
+  // running. Only the LAST round can still be running: once a later round has
+  // started, an unfinished launch from an earlier one is abandoned, not live.
+  // Running those to the newest event drew a span across every round that
+  // followed — a killed reviewer showed as "963.7 min · unfinished" stretched
+  // over the whole timeline, burying the rounds that actually happened.
+  const lastRound = Math.max(0, ...run.rounds.map((r) => r.n));
+  // Where each round ended, so an abandoned span stops at its own round rather
+  // than at the present moment.
+  const endOf = new Map();
+  for (const r of run.rounds) {
+    const done = r.verdicts.map((v) => v.atMin).filter((m) => typeof m === "number");
+    if (done.length) endOf.set(r.n, Math.max(...done));
+  }
+  for (const lane of lanes.values()) {
+    for (const s of lane.segs) {
+      if (s.e !== undefined) continue;
+      const live = s.r === lastRound || s.r === "reply";
+      if (live) {
+        s.e = Math.max(s.s, lastMin);
+        s.open = true;
+        s.t = `round ${s.r} · ${+(s.e - s.s).toFixed(1)} min · still running`;
+      } else {
+        // Abandoned: end it where its own round ended, or at its start if
+        // nothing in that round ever reported.
+        s.e = Math.max(s.s, endOf.get(s.r) ?? s.s);
+        s.abandoned = true;
+        s.t = `round ${s.r} · never finished`;
+      }
+    }
+  }
+
+  run.lanes = [...lanes.values()];
+  run.exchanges = [...findings.values()];
+  // Spans count too: one ending past the last mark would overflow the timeline.
+  run.totalMin = Math.max(
+    1,
+    ...run.marks.map((m) => m.at),
+    ...run.lanes.flatMap((l) => l.segs.map((s) => s.e)),
+  );
+  return run;
+}

package/lib/style.js

@@ -0,0 +1,90 @@
+// Colour and shape for the CLI's own output.
+//
+// A round prints for pages, and every line used to arrive at the same weight:
+// a round boundary, a reviewer's raw report and a triage verdict were
+// indistinguishable while scrolling. Colour is used only where it carries
+// meaning — whose turn it is, and how a finding was settled — and never as
+// decoration.
+
+/**
+ * Colour is off unless stdout is a terminal that wants it.
+ *
+ * `NO_COLOR` is honoured for any value at all, per no-color.org: the variable
+ * existing is the signal. A pipe or a file gets plain text, so `jury … > log`
+ * and `| grep` stay readable.
+ */
+const ON = process.env.NO_COLOR === undefined
+  && process.env.TERM !== "dumb"
+  && process.stdout.isTTY === true;
+
+const ESC = "\x1b[";
+const wrap = (open, close) => (s) => (ON ? `${ESC}${open}m${s}${ESC}${close}m` : String(s));
+
+export const bold = wrap(1, 22);
+export const dim = wrap(2, 22);
+export const under = wrap(4, 24);
+
+// 256-colour, so the palette matches the console's hues rather than whatever
+// the terminal theme maps the 8 basic colours to.
+const fg = (n) => wrap(`38;5;${n}`, 39);
+
+export const ok = fg(71);      // green — accepted, converged
+export const bad = fg(167);    // red — rejected, failed to run
+export const warn = fg(179);   // amber — deferred, still open
+export const info = fg(74);    // blue — headings, structural
+export const muted = fg(245);  // grey — timings, paths, detail
+
+/** The console assigns each agent a hue; the CLI uses the same ones. */
+const AGENT_HUE = {
+  claude: 176, codex: 250, grok: 66, agy: 74, droid: 209,
+};
+
+/** Stable per name, so an unconfigured agent still reads as itself. */
+export function agent(name) {
+  if (!ON) return String(name);
+  let n = AGENT_HUE[name];
+  if (n === undefined) {
+    let h = 0;
+    for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) | 0;
+    // 22..219 avoids the near-black and near-white ends of the cube, both of
+    // which vanish into one terminal background or the other.
+    n = 22 + (Math.abs(h) % 198);
+  }
+  return fg(n)(name);
+}
+
+const VERDICT_COLOUR = { accepted: ok, rejected: bad, deferred: warn, superseded: muted };
+
+/** accepted / rejected / deferred in the three colours the web view uses. */
+export function verdict(v) {
+  return (VERDICT_COLOUR[v] ?? muted)(String(v).toUpperCase());
+}
+
+/**
+ * "1 finding" / "2 findings", rather than the "(s)" placeholder that leaked
+ * into the output and stayed there.
+ */
+export function count(n, one, many = `${one}s`) {
+  return `${n} ${n === 1 ? one : many}`;
+}
+
+/** A labelled line in the run header: dim key, plain value. */
+export function field(key, value) {
+  return `${dim(key.padEnd(8))} ${value}`;
+}
+
+/**
+ * A rule that says what follows it. Reviewer reports are dumped whole, and
+ * without a marked boundary one runs straight into the triage below it.
+ */
+export function rule(label, width = 64) {
+  const text = label ? ` ${label} ` : "";
+  const dashes = Math.max(0, width - text.length);
+  const left = Math.min(3, dashes);
+  return dim("─".repeat(left)) + bold(text) + dim("─".repeat(dashes - left));
+}
+
+/** Indent every line of a block, so a pasted report is visibly not our voice. */
+export function indent(text, prefix = "  ") {
+  return String(text).replace(/^/gm, prefix);
+}

package/lib/triage.js

@@ -0,0 +1,144 @@
+// Triage: the judgement half of the loop.
+//
+// DESIGN.md left this to the operator on purpose — "deciding a finding
+// reproduces is the calling agent's job, and roughly a third of suggestions do
+// not survive that step". With nobody in that seat the loop reviewed the same
+// commit ten times and called it convergence.
+//
+// The main agent fills the seat now. It is spawned exactly like a reviewer, but
+// it is the only one allowed to touch the tree: it reproduces a claim before
+// accepting it, writes the regression test, and answers the ones it rejects
+// with the evidence that settled them.
+import { runAgent } from "./agents.js";
+
+/** What the main agent must answer for one finding. */
+export const VERDICT_SCHEMA = `{
+  "reproduced": "<what you observed, or null if it does not reproduce>",
+  "verdict": "accepted | rejected | deferred",
+  "reason": "<why, in one or two sentences>",
+  "test": "<the regression test you added and watched fail without the fix, or null>"
+}`;
+
+/**
+ * The prompt for one finding.
+ *
+ * Deliberately adversarial about acceptance: a reviewer's claim is a hypothesis,
+ * and the whole value of the gate is that a third of them do not survive being
+ * checked. Being asked to demonstrate it first is what makes "accepted" mean
+ * something.
+ */
+export function triagePrompt({ finding, trunk, stopToken }) {
+  return `A code reviewer raised this finding against the current worktree.
+
+FINDING: ${finding.claim}
+${finding.loc ? `WHERE: ${finding.loc}` : ""}
+
+${finding.body || "(no further detail given)"}
+
+Your job is to decide whether it is real, and to act on it.
+
+1. Read the code at that location. Run \`git diff $(git merge-base HEAD origin/${trunk}) HEAD\`
+   if you need to see what changed.
+2. Try to REPRODUCE it — a failing test, an observed wrong value, a traced path.
+   A claim you cannot demonstrate is not accepted, however plausible it sounds.
+   Roughly a third of review findings do not survive this step; rejecting one
+   with evidence is as valuable as fixing one.
+3. If it reproduces: fix it, and add a regression test. Run the test with the
+   fix reverted and confirm it FAILS — a test that passes either way is
+   decoration. Then run the full suite.
+4. If it does not: say what you checked and why the claim is wrong.
+5. Deferring means you did NOT fix it. Use it only when the problem is
+   pre-existing and not made materially more likely by this change, and leave
+   the code alone. If you fixed it, the verdict is "accepted" — a fix plus a
+   proven test recorded as "deferred" tells the reviewer its finding was
+   waved through, and leaves the loop believing there is still work to do.
+
+Do not fix anything the finding did not raise. Do not commit — the loop commits.
+
+Answer with ONLY a JSON object on the last line of your output, no fence:
+
+${VERDICT_SCHEMA}
+
+Choosing the verdict:
+
+  accepted   you demonstrated it AND fixed it AND have a test that failed
+             without the fix. Requires non-null "reproduced" and "test" — the
+             CLI refuses an acceptance carrying neither.
+  rejected   you checked and the claim is wrong. Say what you checked.
+  deferred   real, pre-existing, out of scope, and you changed nothing.
+
+If you edited a file, the verdict is "accepted" or you should revert the edit.`;
+}
+
+/**
+ * Parse the verdict out of the main agent's output.
+ *
+ * Last JSON object wins: agents narrate before answering, and an example echoed
+ * from the prompt earlier in the transcript must not beat the real answer at
+ * the end.
+ */
+export function parseVerdict(text) {
+  const s = String(text ?? "");
+  let found = null;
+  // Scan for balanced top-level objects rather than regex-matching braces,
+  // which breaks on any nested object in the reasoning above it.
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] !== "{") continue;
+    let depth = 0, inStr = false, esc = false;
+    for (let j = i; j < s.length; j++) {
+      const c = s[j];
+      if (esc) { esc = false; continue; }
+      if (c === "\\") { esc = true; continue; }
+      if (c === '"') { inStr = !inStr; continue; }
+      if (inStr) continue;
+      if (c === "{") depth++;
+      else if (c === "}" && --depth === 0) {
+        try {
+          const o = JSON.parse(s.slice(i, j + 1));
+          if (o && typeof o === "object" && "verdict" in o) found = o;
+        } catch { /* not the object we want */ }
+        i = j;
+        break;
+      }
+    }
+  }
+  if (!found) return null;
+  const verdict = String(found.verdict ?? "").toLowerCase().trim();
+  const clean = (v) => {
+    const t = typeof v === "string" ? v.trim() : v;
+    // Agents write "null" and "none" as strings when they mean nothing.
+    return !t || /^(null|none|n\/a)$/i.test(String(t)) ? null : String(t);
+  };
+  return {
+    verdict: ["accepted", "rejected", "deferred", "superseded"].includes(verdict) ? verdict : null,
+    reproduced: clean(found.reproduced),
+    reason: clean(found.reason) ?? "",
+    test: clean(found.test),
+  };
+}
+
+/**
+ * Put one finding to the main agent and return its verdict.
+ *
+ * Never throws: a main agent that dies on one finding must not lose the round's
+ * other verdicts, so a failure is a null verdict and the finding stays open for
+ * the next round to raise again.
+ */
+export async function triageOne(main, finding, { worktree, trunk, stopToken, dryRun, onLog, onChunk }) {
+  const prompt = triagePrompt({ finding, trunk, stopToken });
+  if (dryRun) {
+    return { verdict: "rejected", reproduced: null, reason: "dry run — not triaged", test: null, seconds: 0 };
+  }
+  const r = await runAgent(main, {
+    worktree, prompt, stopToken, onLog, onChunk,
+    // Triage is slower than review: it reads, reproduces, edits and runs tests.
+    // Floor as well as multiple: a misconfigured 0 must not mean 'kill it now'.
+    timeoutSeconds: Math.max(900, (main.expectSeconds || 900) * 3),
+  });
+  if (!r.ok) return { verdict: null, failed: true, report: r.report, seconds: r.seconds };
+  const v = parseVerdict(r.report) ?? parseVerdict(r.raw);
+  if (!v?.verdict) {
+    return { verdict: null, unparsed: true, report: r.report, seconds: r.seconds };
+  }
+  return { ...v, report: r.report, seconds: r.seconds };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@agentsdance/codejury",
+  "version": "0.1.0",
+  "description": "Independent AI reviewers that iterate until your pull request is clean.",
+  "keywords": [
+    "code-review",
+    "ai",
+    "agents",
+    "pull-request",
+    "claude",
+    "codex"
+  ],
+  "homepage": "https://github.com/agentsdance/codejury#readme",
+  "bugs": "https://github.com/agentsdance/codejury/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentsdance/codejury.git"
+  },
+  "type": "module",
+  "bin": {
+    "jury": "bin/jury.js",
+    "codejury": "bin/jury.js",
+    "cr": "bin/jury.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "web/index.html",
+    "prompts",
+    "jury.config.example.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "npm test",
+    "start": "node bin/jury.js web --open",
+    "test": "node --test \"test/*.test.js\""
+  },
+  "license": "MIT"
+}

package/prompts/feedback.md

@@ -0,0 +1,54 @@
+# Feedback prompt template
+
+Sent back to an agent after acting on its review. Purpose: close the loop on disagreements explicitly,
+rather than silently ignoring findings you chose not to act on.
+
+Delivery differs per agent:
+
+- **codex** — `codex exec resume --last "$(cat feedback.md)"`, prior context retained.
+- **droid** — no session id in `exec` text output; re-run fresh and quote its prior findings into the
+  prompt so it knows what it said.
+
+---
+
+Thanks — I acted on your review. Here is what I did with each finding, including where I disagree. The
+final state is at {{worktree path}} (detached at {{sha}}). Please verify my claims and tell me where you
+still disagree.
+
+**{{N}}. {{finding title}} — ACCEPTED, fixed.**
+
+{{What changed, with the code if short. If the regression test needed a non-obvious shape, say why —
+e.g. "a single run only catches this 50% of the time because the select is random, so the test repeats
+20 runs".}}
+
+**{{N}}. {{finding title}} — AGREE it is real, NOT fixing here.**
+
+{{Why it is out of scope: untouched by this change, pre-existing, needs its own tests.}}
+
+Question: do you agree it is (a) pre-existing and (b) not made materially more likely by this change?
+If you think otherwise, say so and I will reconsider.
+
+**{{N}}. {{finding title}} — REJECTED.**
+
+{{The evidence. Prefer something reproducible: a command, an error message, a counter-example.}}
+
+**{{N}}. {{finding title}} — PARTIAL pushback.**
+
+{{Which half you accept and which you dispute, and what you changed as a result.}}
+
+Question: do you accept that framing, or is a different definition actually better?
+
+Please review the final state and answer: any remaining correctness problem, and do you accept my
+positions on {{list}}? Do not edit files.
+
+---
+
+## Notes
+
+- Ending each disputed item with a **direct question** is what makes this a conversation. In the
+  reference run it converted two "you should fix this" items into explicit agreement to defer.
+- State rejections with evidence, not authority. One rejection was settled by writing a three-line
+  throwaway test and pasting the panic message.
+- Expect to be wrong sometimes. The most valuable single finding of the reference run — a real
+  cancellation bug — came back in a reply to feedback, not in the first review.
+- Tell an agent when its finding was caused by *your* prompt (e.g. a wrong diff base). It is your bug.