@karajan-family/code 4.68.1 → 4.69.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karajan-family/code",
-  "version": "4.68.1",
+  "version": "4.69.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/cli/register-pipeline.js

@@ -267,10 +267,12 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--lens <lens>", "With --third-party: what the reviewer looks at; qa = test coverage, weak assertions, flakiness, test data")
     .option("--verifier <provider>", "With --third-party: an AI of another family confirms, downgrades or rejects each finding (#2369)")
     .option("--verifier-model <model>", "With --verifier: the verifier's model")
+    .option("--reviewers <a,b>", "With --third-party: two reviewers of different families review on their own and verify each other (#2623)")
+    .option("--reviewer-models <a=model,b=model>", "With --reviewers: each reviewer's model")
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "review", flags, async ({ config, logger }) => {
-        if ((flags.verifier || flags.verifierModel) && !flags.thirdParty) {
-          logger.error("--verifier and --verifier-model work with --third-party only");
+        if ((flags.verifier || flags.verifierModel || flags.reviewers || flags.reviewerModels) && !flags.thirdParty) {
+          logger.error("--verifier, --verifier-model, --reviewers and --reviewer-models work with --third-party only");
           process.exitCode = 1;
           return;
         }

package/src/review/dual-review.js

@@ -0,0 +1,73 @@
+/**
+ * KJC-TSK-1247 (#2623): the dual third-party review. Two reviewers of different families review
+ * the same range on their own, and each one's findings are verified by the other family (the
+ * --verifier of #2369). This module reconciles both into one result: every finding says who
+ * found it and how it was verified, the ones both found rank first, the rejected are listed
+ * apart (never dropped), and there is one verdict.
+ */
+
+const RANK = { low: 0, medium: 1, high: 2, critical: 3 };
+const rank = (f) => RANK[f.severity] ?? -1;
+// Within a few lines of each other in the same file, two reviewers are talking about the same thing.
+const NEAR_LINES = 3;
+const sameSpot = (a, b) => a.file === b.file
+  && (a.line == null || b.line == null ? a.line == null && b.line == null : Math.abs(a.line - b.line) <= NEAR_LINES);
+const isBlocker = (f) => f.category === "security" || rank(f) >= RANK.high;
+// Security is never overridable; otherwise the other family confirmed it, or both reviewers found it.
+const isConfirmed = (f) => f.category === "security" || f.found_by.length === 2
+  || Object.values(f.verification).some((o) => o === "confirmed" || o === "kept_by_rule");
+const where = (f) => `${f.file ?? "?"}:${f.line ?? "?"}`;
+
+/** Each side's kept findings, tagged with who found them and how the other family judged them. */
+function tagged(side) {
+  const verifier = side.verification?.verifier;
+  return side.findings.map((finding, i) => ({
+    ...finding,
+    found_by: [side.reviewer],
+    verification: verifier ? { [verifier]: side.outcomes?.[i] ?? "unverified" } : {},
+  }));
+}
+
+/** One list: a finding both reviewers made is merged (the higher severity wins) and ranks first. */
+function mergeFindings(a, b) {
+  const rest = tagged(b);
+  const merged = tagged(a).map((fa) => {
+    const at = rest.findIndex((fb) => sameSpot(fa, fb));
+    if (at < 0) return fa;
+    const [fb] = rest.splice(at, 1);
+    const top = rank(fb) > rank(fa) ? fb : fa;
+    return { ...top, found_by: [...fa.found_by, ...fb.found_by], verification: { ...fa.verification, ...fb.verification } };
+  });
+  return [...merged, ...rest].toSorted((x, y) => y.found_by.length - x.found_by.length || rank(y) - rank(x));
+}
+
+function verdictOf(sides, findings, coverage) {
+  const blockers = findings.filter((f) => isBlocker(f) && isConfirmed(f));
+  const summary = sides.map((s) => s.verdict?.summary).filter(Boolean).join("\n");
+  if (blockers.length) return { status: "rejected", approved: false, reason: `confirmed blocker(s): ${blockers.map(where).join(", ")}`, summary };
+  const rejecting = sides.filter((s) => !s.verdict?.approved).map((s) => s.reviewer);
+  if (rejecting.length === 0 && !coverage.truncated) return { status: "approved", approved: true, summary };
+  const reason = rejecting.length
+    ? `${rejecting.join(" and ")} rejected, but no blocking finding was confirmed by the other family`
+    : "not every file was reviewed";
+  return { status: "partial", approved: false, reason, summary };
+}
+
+/** The two sides (reviewer, model, verdict, coverage, findings, outcomes, verification) as one result. */
+export function reconcileReviews([a, b]) {
+  const findings = mergeFindings(a, b);
+  const coverage = { ...a.coverage, truncated: Boolean(a.coverage?.truncated || b.coverage?.truncated) };
+  const counts = ({ reviewer, verification: v = {} }) => ({
+    reviewer, verifier: v.verifier ?? null, confirmed: v.confirmed ?? 0, downgraded: v.downgraded ?? 0,
+    unverified: v.unverified ?? 0, kept_by_rule: v.kept_by_rule ?? 0, ...(v.error && { error: v.error }),
+  });
+  const rejected = [a, b].flatMap((s) => (s.verification?.rejected ?? [])
+    .map((r) => ({ ...r, found_by: s.reviewer, rejected_by: s.verification.verifier })));
+  return {
+    reviewers: [a, b].map((s) => ({ reviewer: s.reviewer, model: s.model ?? null, verdict: s.verdict })),
+    verdict: verdictOf([a, b], findings, coverage),
+    coverage,
+    findings,
+    verification: { by: [a, b].map(counts), rejected },
+  };
+}

package/src/review/finding-verifier.js

@@ -65,6 +65,9 @@ export function applyVerification(findings, verdicts, { verifier, model = null }
     if (Number.isInteger(v?.index) && VERDICTS.has(v.verdict) && !byIndex.has(v.index)) byIndex.set(v.index, v);
   }
   const kept = [];
+  // KJC-TSK-1247: how each kept finding came out, parallel to `kept`, for the dual review.
+  const outcomes = [];
+  const keep = (finding, outcome) => { kept.push(finding); outcomes.push(outcome); };
   const rejected = [];
   let confirmed = 0;
   let downgraded = 0;
@@ -74,19 +77,19 @@ export function applyVerification(findings, verdicts, { verifier, model = null }
     const v = byIndex.get(i);
     if (v && v.verdict !== "confirmed" && isProtected(finding)) {
       keptByRule += 1;
-      kept.push(finding);
+      keep(finding, "kept_by_rule");
     } else if (v?.verdict === "rejected") {
       rejected.push({ finding, reason: oneLine(v.reason) });
     } else if (v?.verdict === "confirmed") {
       confirmed += 1;
-      kept.push(finding);
+      keep(finding, "confirmed");
     } else if (v?.verdict === "downgraded" && isLower(v.severity, finding.severity)) {
       downgraded += 1;
-      kept.push({ ...finding, severity: v.severity });
+      keep({ ...finding, severity: v.severity }, "downgraded");
     } else {
       unverified += 1;
-      kept.push(finding);
+      keep(finding, "unverified");
     }
   });
-  return { findings: kept, verification: { verifier, model, confirmed, downgraded, rejected, unverified, kept_by_rule: keptByRule } };
+  return { findings: kept, outcomes, verification: { verifier, model, confirmed, downgraded, rejected, unverified, kept_by_rule: keptByRule } };
 }

package/src/review/run-verifier.js

@@ -27,13 +27,13 @@ export function parseVerdicts(text) {
 }
 
 /** Throws when the verifier is the reviewer's family; warns when either family cannot be told. */
-export function assertCrossFamily({ reviewer, reviewerModel = null, verifier, verifierModel = null, logger }) {
+export function assertCrossFamily({ reviewer, reviewerModel = null, verifier, verifierModel = null, logger, flag = "--verifier" }) {
   const theirs = familyOf(reviewer, reviewerModel);
   const mine = familyOf(verifier, verifierModel);
   if (theirs && theirs === mine) {
-    throw new Error(`--verifier ${verifier} is the same family (${mine}) as the reviewer ${reviewer}: it would repeat its blind spots; pick another family`);
+    throw new Error(`${flag} ${verifier} is the same family (${mine}) as the reviewer ${reviewer}: it would repeat its blind spots; pick another family`);
   }
-  if (!theirs || !mine) logger?.warn?.(`--verifier: the family of ${mine ? reviewer : verifier} cannot be told; make sure it differs from the reviewer's`);
+  if (!theirs || !mine) logger?.warn?.(`${flag}: the family of ${mine ? reviewer : verifier} cannot be told; make sure it differs from the reviewer's`);
 }
 
 /** The findings after the verifier, and the verification block. */

package/src/review/third-party-review.js

@@ -19,6 +19,7 @@ import { thirdPartyTask } from "./untrusted-context.js";
 import { readTaskFile } from "../utils/task-file.js";
 import { DIFF_CLIP_CHARS } from "../prompts/diff-clip.js";
 import { assertCrossFamily, verifyFindings } from "./run-verifier.js";
+import { reconcileReviews } from "./dual-review.js";
 
 // KJC-BUG-0378: a reviewer call per batch; past this many, files are left out and named.
 const MAX_REVIEW_BATCHES = 10;
@@ -36,10 +37,12 @@ const finding = (i) => ({
 });
 
 /** The review as data: verdict, findings, suggestions, security checks and, apart, the house requirements. */
-export async function thirdPartyReview({ range, config, projectDir, logger, task = null, gitDiff = gitDiffOf, run = runOneShotReview, requirements = prRequirementChecks, security = prSecurityChecks, sonar = sonarCheck, limit = DIFF_CLIP_CHARS, maxBatches = MAX_REVIEW_BATCHES, sizeLimit = null, verifier = null, verifierModel = null, verify = verifyFindings }) {
+export async function thirdPartyReview({ range, config, projectDir, logger, task = null, gitDiff = gitDiffOf, run = runOneShotReview, requirements = prRequirementChecks, security = prSecurityChecks, sonar = sonarCheck, limit = DIFF_CLIP_CHARS, maxBatches = MAX_REVIEW_BATCHES, sizeLimit = null, verifier = null, verifierModel = null, verify = verifyFindings, reviewers = null }) {
   // KJC-TSK-1195: a verifier of the reviewer's own family is refused before any token is spent.
   const reviewerRole = resolveRole(config, "reviewer");
   if (verifier) assertCrossFamily({ reviewer: reviewerRole.provider, reviewerModel: reviewerRole.model, verifier, verifierModel, logger });
+  // KJC-TSK-1248 (#2623): two reviewers of the same family would share their blind spots.
+  if (reviewers) assertCrossFamily({ reviewer: reviewers[0].provider, reviewerModel: reviewers[0].model, verifier: reviewers[1].provider, verifierModel: reviewers[1].model, logger, flag: "--reviewers" });
   const diff = await gitDiff(projectDir, range);
   // KJC-TSK-1076/1077: the PR's requirements and its security, with no tokens; they never stop the review.
   // KJC-BUG-0379 (#2263): the house requirements (size, commits, attribution, tests) travel apart:
@@ -51,10 +54,16 @@ export async function thirdPartyReview({ range, config, projectDir, logger, task
   const provider = reviewerRole.provider || null;
   const { batches, coverage } = batchDiff(diff, { limit, maxBatches });
   if (coverage.files.total === 0) throw new Error(`nothing to review — ${range} has no file changes`);
-  const records = [];
-  for (const batch of batches) {
-    records.push(await run({ diff: batch.text, task, config, logger, projectDir, reviewerOverride: provider, persist: false }));
+  const reviewWith = async (who, cfg) => {
+    const recs = [];
+    for (const batch of batches) recs.push(await run({ diff: batch.text, task, config: cfg, logger, projectDir, reviewerOverride: who, persist: false }));
+    return recs;
+  };
+  if (reviewers) {
+    const dual = await dualReview({ reviewers, reviewWith, verify, diff, coverage, config, logger });
+    return { mode: "third-party", range, ...dual, checks, policyChecks, advice: adviceFor(diff, sizeLimit ?? prSizeLimit({ projectDir, config }).limit) };
   }
+  const records = await reviewWith(provider, config);
   const findings = records.flatMap((r) => (r.issues ?? []).map(finding));
   // KJC-TSK-1195 (#2369): with a verifier, the findings are the verified ones and the block says what changed.
   const verified = verifier ? await verify({ findings, diff, verifier, model: verifierModel, config, logger }) : null;
@@ -73,6 +82,23 @@ export async function thirdPartyReview({ range, config, projectDir, logger, task
   };
 }
 
+/**
+ * KJC-TSK-1248 (#2623): both reviewers review the whole range on their own, in parallel, each
+ * with its model; each one's findings are verified by the other family; one reconciled result.
+ */
+async function dualReview({ reviewers, reviewWith, verify, diff, coverage, config, logger }) {
+  const withModel = ({ provider, model }) => ({ ...config, roles: { ...config?.roles, reviewer: { ...config?.roles?.reviewer, provider, model } } });
+  const records = await Promise.all(reviewers.map((r) => reviewWith(r.provider, withModel(r))));
+  const sides = await Promise.all(reviewers.map(async (me, i) => {
+    const other = reviewers[1 - i];
+    const found = records[i].flatMap((r) => (r.issues ?? []).map(finding));
+    const verified = await verify({ findings: found, diff, verifier: other.provider, model: other.model, config, logger });
+    return { reviewer: me.provider, model: me.model, coverage, verdict: verdictOf(records[i], coverage), ...verified };
+  }));
+  const reconciled = reconcileReviews(sides);
+  return { reviewer: reviewers.map((r) => r.provider).join("+"), ...reconciled, suggestions: records.flat().flatMap((r) => r.suggestions ?? []) };
+}
+
 /** KJC-TSK-1101: over the size budget, how to split the PR; advice only, never a finding. */
 function adviceFor(diff, budget) {
   const files = splitByFile(diff).filter((f) => !isGenerated(f.file));
@@ -92,6 +118,19 @@ function verdictOf(records, coverage) {
 // KJC-TSK-1153: flags of the own-work review that this mode would otherwise ignore in silence.
 const OWN_WORK_FLAGS = { staged: "--staged", check: "--check", installGate: "--install-gate", prune: "--prune", dryRun: "--dry-run", publishPr: "--publish-pr", verifyPr: "--verify-pr", baseRef: "--base-ref", walkedWith: "--walked-with" };
 
+/** KJC-TSK-1248: --reviewers a,b [--reviewer-models a=model,b=model] as two reviewers, or null. */
+function reviewersOf(flags) {
+  if (!flags.reviewers) {
+    if (flags.reviewerModels) throw new Error("--reviewer-models needs --reviewers <a,b>");
+    return null;
+  }
+  if (flags.verifier) throw new Error("--reviewers already verifies each reviewer with the other: drop --verifier");
+  const providers = String(flags.reviewers).split(",").map((p) => p.trim()).filter(Boolean);
+  if (providers.length !== 2) throw new Error("--reviewers takes exactly two providers of different families, e.g. claude,codex");
+  const models = Object.fromEntries(String(flags.reviewerModels ?? "").split(",").filter(Boolean).map((pair) => pair.split("=").map((s) => s.trim())));
+  return providers.map((provider) => ({ provider, model: models[provider] || null }));
+}
+
 function assertThirdPartyFlags(flags) {
   const used = Object.keys(OWN_WORK_FLAGS).filter((k) => flags[k]).map((k) => OWN_WORK_FLAGS[k]);
   if (flags.walked?.length) used.push("--walked");
@@ -120,7 +159,8 @@ export async function thirdPartyReviewCommand({ flags, config, out = process.std
     const context = flags.taskFile ? await readTask(flags.taskFile, { projectDir }) : flags.task;
     const task = await lensTask(flags.lens ?? null, thirdPartyTask(context ?? null));
     if (flags.verifierModel && !flags.verifier) throw new Error("--verifier-model needs --verifier <provider>");
-    print(await review({ range: flags.range, config, projectDir, logger, task, verifier: flags.verifier ?? null, verifierModel: flags.verifierModel ?? null }));
+    const reviewers = reviewersOf(flags);
+    print(await review({ range: flags.range, config, projectDir, logger, task, verifier: flags.verifier ?? null, verifierModel: flags.verifierModel ?? null, ...(reviewers && { reviewers }) }));
     return 0;
   } catch (e) {
     print({ error: e.message });