chainlesschain 0.162.160 → 0.162.162

package/src/lib/plugin-runtime/manifest.js

@@ -27,6 +27,11 @@
 import fs from "fs";
 import path from "path";
 import semver from "semver";
+import {
+  normalizeCapabilities,
+  normalizeOptionsSchema,
+  auditDeclaredCapabilities,
+} from "./capabilities.js";
 
 export const _deps = {
   existsSync: fs.existsSync,
@@ -73,6 +78,14 @@ export function parsePluginManifest(root) {
     scope: null,
     metadata: {},
     components: emptyComponents(),
+    // Declarative security contract (P1): the plugin's declared capabilities
+    // (manifest.permissions) + typed config schema (manifest.optionsSchema),
+    // normalized by capabilities.js. `capabilitiesDeclared` distinguishes a
+    // plugin that declared a permissions block (subject to the declared-vs-
+    // actual audit) from a legacy one that declared nothing (unrestricted).
+    capabilities: normalizeCapabilities(null),
+    capabilitiesDeclared: false,
+    optionsSchema: {},
     errors,
     warnings,
   };
@@ -165,6 +178,23 @@ export function parsePluginManifest(root) {
   c.bin = resolveBin(abs, manifest, safeResolve, warnings);
   c.settings = resolveSettings(abs, manifest, safeResolve);
 
+  // ── declared capabilities + options schema (P1) ──
+  const hasPermissions =
+    manifest.permissions &&
+    typeof manifest.permissions === "object" &&
+    !Array.isArray(manifest.permissions);
+  result.capabilities = normalizeCapabilities(manifest.permissions);
+  result.capabilitiesDeclared = Boolean(hasPermissions);
+  result.optionsSchema = normalizeOptionsSchema(manifest.optionsSchema);
+  // Declared-vs-actual audit runs ONLY when a permissions block is present — a
+  // legacy plugin that declares nothing is unrestricted by design, so it never
+  // gets these warnings (keeps existing manifests warning-free).
+  if (hasPermissions) {
+    for (const f of auditDeclaredCapabilities(result)) {
+      warnings.push(`capability: ${f.reason}`);
+    }
+  }
+
   result.ok = errors.length === 0;
   return result;
 }

package/src/lib/project-instructions.js

@@ -44,6 +44,83 @@ export const PROJECT_FILE_NAMES = ["cc.md", "CLAUDE.md", "AGENTS.md"];
 /** Local (gitignored) companion names, first match wins. */
 export const LOCAL_FILE_NAMES = ["cc.local.md", "CLAUDE.local.md"];
 
+/**
+ * `instructionExcludes` — a large-monorepo reduction lever (P1). Subtrees whose
+ * instruction / rule / @import files should NEVER load (legacy, vendored,
+ * generated). Opt-in: empty by default so behavior is byte-identical unless the
+ * caller (config `instructionExcludes`) sets it. Patterns are matched against a
+ * path RELATIVE to the project root, with forward slashes:
+ *   - a bare name (`node_modules`, `dist`) matches that segment ANYWHERE;
+ *   - a slashed prefix (`packages/legacy`) matches that dir and everything under;
+ *   - a glob (`**​/generated/**`, `vendor/*`) matches via `*`/`**`/`?`.
+ */
+export function normalizeInstructionExcludes(list) {
+  if (!Array.isArray(list)) return [];
+  return [
+    ...new Set(
+      list
+        .map((s) =>
+          String(s || "")
+            .trim()
+            .replace(/\\/g, "/")
+            .replace(/\/+$/, ""),
+        )
+        .filter(Boolean),
+    ),
+  ];
+}
+
+function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        re += ".*";
+        i++;
+        if (glob[i + 1] === "/") i++; // `**/` also swallows the slash
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else {
+      re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp("^" + re + "$");
+}
+
+/**
+ * True when a repo-relative path falls under an excluded subtree. A file is
+ * excluded when it, or any of its ancestor directories, matches a pattern.
+ */
+export function pathIsExcluded(relPath, excludes) {
+  if (!excludes || excludes.length === 0) return false;
+  const rel = String(relPath || "")
+    .replace(/\\/g, "/")
+    .replace(/^\.\/?/, "")
+    .replace(/\/+$/, "");
+  if (!rel) return false;
+  const segs = rel.split("/");
+  for (const pat of excludes) {
+    if (/[*?[\]]/.test(pat)) {
+      const re = globToRegExp(pat);
+      if (re.test(rel)) return true;
+      let acc = "";
+      for (const s of segs) {
+        acc = acc ? `${acc}/${s}` : s;
+        if (re.test(acc)) return true;
+      }
+    } else {
+      if (rel === pat || rel.startsWith(`${pat}/`)) return true;
+      // a bare (slash-free) name matches that path segment anywhere
+      if (!pat.includes("/") && segs.includes(pat)) return true;
+    }
+  }
+  return false;
+}
+
 // Same boundary rule as file-ref-expander: `@` at start / after whitespace or
 // an opening bracket-quote, so emails and decorative @ never match.
 const IMPORT_TOKEN_RE = /(^|[\s("'`[{])@([^\s"'`)\]}]+)/g;
@@ -100,13 +177,21 @@ export function findInstructionFiles(opts = {}) {
   const { fs, path, os } = resolveDeps(opts);
   const cwd = path.resolve(opts.cwd || process.cwd());
   const home = opts.home || os.homedir() || "";
+  const excludes = normalizeInstructionExcludes(opts.instructionExcludes);
 
   const seen = new Set();
   const out = [];
+  const root = findProjectRoot(cwd, opts) || cwd;
+  // A discovered file under an excluded subtree (relative to the project root)
+  // never loads. The user-scope file lives outside the repo, so it is exempt.
+  const excluded = (abs) =>
+    excludes.length > 0 &&
+    pathIsExcluded(path.relative(root, path.resolve(abs)), excludes);
   const push = (p, scope) => {
     if (!p) return;
     const abs = path.resolve(p);
     if (seen.has(abs) || !isFile(fs, abs)) return;
+    if (scope !== "user" && excluded(abs)) return;
     seen.add(abs);
     out.push({ path: abs, scope });
   };
@@ -121,7 +206,6 @@ export function findInstructionFiles(opts = {}) {
     );
   }
 
-  const root = findProjectRoot(cwd, opts) || cwd;
   const chain = [];
   let dir = cwd;
   for (;;) {
@@ -274,6 +358,10 @@ export function loadProjectInstructions(opts = {}) {
     : DEFAULT_MAX_TOTAL_BYTES;
 
   const roots = findInstructionFiles(opts);
+  const excludes = normalizeInstructionExcludes(opts.instructionExcludes);
+  const projectRoot =
+    findProjectRoot(path.resolve(opts.cwd || process.cwd()), opts) ||
+    path.resolve(opts.cwd || process.cwd());
   const visited = new Set(roots.map((r) => r.path));
   const out = [];
   const warnings = [];
@@ -322,6 +410,15 @@ export function loadProjectInstructions(opts = {}) {
       const resolved = path.resolve(baseDir, target);
       if (visited.has(resolved) || !isFile(fs, resolved)) continue; // silent:
       // non-files are decorative @tokens (npm scopes, emails), not imports.
+      // An @import that resolves under an excluded subtree does not load — the
+      // reduction lever must not be bypassed by an import pointing into it.
+      if (
+        excludes.length > 0 &&
+        pathIsExcluded(path.relative(projectRoot, resolved), excludes)
+      ) {
+        visited.add(resolved);
+        continue;
+      }
       // Refuse to import a credential / secret file. `cc agent` auto-loads
       // project memory, so a cloned/untrusted repo's cc.md must NOT be able to
       // pull `@~/.ssh/id_rsa` / `@../.env` into the LLM-bound system prompt

package/src/lib/remote-approval-bridge.js

@@ -23,6 +23,10 @@
 
 import { randomBytes } from "crypto";
 import { WsRpcClient } from "./ws-rpc-client.js";
+import {
+  approvalFingerprintOk,
+  operationFingerprint,
+} from "./operation-fingerprint.js";
 import {
   buildDirectPairingUri,
   pickLanAddress,
@@ -113,6 +117,15 @@ export class RemoteApprovalBridge {
     const requestId = message.event.requestId || message.event.approvalId;
     const pending = requestId ? this._pending.get(requestId) : null;
     if (!pending) return;
+    // Confused-deputy guard: a resolve that carries an operation fingerprint
+    // must match the operation this ask published. A mismatch (stale card /
+    // replayed / swapped body) is rejected — the ask stays pending and fails
+    // closed on timeout. Absent fingerprint = legacy device, accepted.
+    if (
+      !approvalFingerprintOk(pending.fingerprint, message.event.fingerprint)
+    ) {
+      return;
+    }
     this._pending.delete(requestId);
     clearTimeout(pending.timer);
     const answer = message.event.answer ?? message.event.approved;
@@ -150,6 +163,7 @@ export class RemoteApprovalBridge {
     onRequestId = null,
   } = {}) {
     const requestId = `ra-${process.pid}-${++this._counter}-${randomBytes(4).toString("hex")}`;
+    const fingerprint = operationFingerprint({ tool, action, detail });
     if (onRequestId) {
       try {
         onRequestId(requestId);
@@ -171,6 +185,7 @@ export class RemoteApprovalBridge {
       if (typeof timer.unref === "function") timer.unref();
       this._pending.set(requestId, {
         timer,
+        fingerprint,
         resolve: (decision) => {
           this._publish({
             type: "permission.resolved",
@@ -187,6 +202,7 @@ export class RemoteApprovalBridge {
         tool: tool || null,
         action,
         detail,
+        fingerprint,
         askedAt: this._now(),
       });
     });

package/src/lib/remote-path-mapping.js

@@ -0,0 +1,229 @@
+/**
+ * Remote URI ↔ filesystem path mapping for the IDE bridge.
+ *
+ * A local IDE (VS Code / JetBrains) can report a file in a representation that
+ * does not exist on the host `cc` runs on, so inlining it into the prompt makes
+ * the agent's read_file/edit_file target a path the CLI host can't see:
+ *   - a URI:  file:///c:/code/my%20proj/文件.ts
+ *             vscode-remote://wsl+Ubuntu/home/u/x
+ *             vscode-remote://ssh-remote+host/home/u/x
+ *             vscode-remote://dev-container+<hex>/workspaces/x
+ *   - a WSL UNC path from a Windows host: \\wsl.localhost\Ubuntu\home\u\x
+ *     (older Windows builds: \\wsl$\Ubuntu\home\u\x)
+ *   - a Windows drive path while cc runs INSIDE WSL: C:\code\x  ==  /mnt/c/code/x
+ *
+ * normalizeIdePathForCli() folds these foreign forms into the CLI's native fs
+ * path; anything already native (or unrecognized) passes through byte-for-byte.
+ * cliPathToIdeUri() is the reverse, for surfaces that must hand a URI back to
+ * the editor.
+ *
+ * Pure: string transforms only (no fs / process). Percent-decoding preserves
+ * spaces and non-ASCII (中文) exactly, so round-trips are lossless.
+ */
+
+/** decodeURIComponent that never throws on a malformed % sequence. */
+function decodeSafe(s) {
+  if (typeof s !== "string") return s;
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s; // leave a malformed sequence as-is rather than lose the value
+  }
+}
+
+/** Has a `scheme://` prefix (a URI, not a bare path). */
+export function looksLikeUri(value) {
+  return typeof value === "string" && /^[a-z][a-z0-9.+-]*:\/\//i.test(value);
+}
+
+/** `C:\…` or `C:/…` — a Windows drive-absolute path. */
+export function looksLikeWindowsPath(value) {
+  return typeof value === "string" && /^[a-zA-Z]:[\\/]/.test(value);
+}
+
+/** `\\host\…` or `//host/…` — a UNC path. */
+function looksLikeUnc(value) {
+  return typeof value === "string" && /^(\\\\|\/\/)[^\\/]/.test(value);
+}
+
+const WSL_UNC_RE =
+  /^(?:\\\\|\/\/)(?:wsl\.localhost|wsl\$)[\\/]([^\\/]+)[\\/]?(.*)$/i;
+
+/**
+ * `\\wsl.localhost\Ubuntu\home\u\x` (or `\\wsl$\…`, forward-slash variants) →
+ * `{ distro:"Ubuntu", posix:"/home/u/x" }`, or null when not a WSL UNC path.
+ */
+export function wslUncToPosix(value) {
+  if (typeof value !== "string") return null;
+  const m = value.match(WSL_UNC_RE);
+  if (!m) return null;
+  const distro = m[1];
+  const rest = (m[2] || "").replace(/\\/g, "/");
+  return { distro, posix: "/" + rest.replace(/^\/+/, "") };
+}
+
+/** `/home/u/x` + distro → `\\wsl.localhost\Ubuntu\home\u\x` (host overridable). */
+export function posixToWslUnc(posix, distro, { host = "wsl.localhost" } = {}) {
+  if (typeof posix !== "string" || !distro) return null;
+  const win = posix.replace(/^\/+/, "").replace(/\//g, "\\");
+  return `\\\\${host}\\${distro}\\${win}`;
+}
+
+/** `C:\code\x` → `/mnt/c/code/x`, or null when not a drive path. */
+export function winDriveToWslMount(value) {
+  if (!looksLikeWindowsPath(value)) return null;
+  const drive = value[0].toLowerCase();
+  const rest = value.slice(2).replace(/\\/g, "/").replace(/^\/+/, "");
+  return `/mnt/${drive}${rest ? "/" + rest : ""}`;
+}
+
+const WSL_MOUNT_RE = /^\/mnt\/([a-zA-Z])(?:\/(.*))?$/;
+
+/** `/mnt/c/code/x` → `C:\code\x`, or null when not a /mnt/<drive> path. */
+export function wslMountToWinDrive(value) {
+  if (typeof value !== "string") return null;
+  const m = value.match(WSL_MOUNT_RE);
+  if (!m) return null;
+  const drive = m[1].toUpperCase();
+  const rest = (m[2] || "").replace(/\//g, "\\");
+  return `${drive}:\\${rest}`;
+}
+
+/**
+ * Parse an IDE URI into its parts. Returns null for a non-URI or an unknown
+ * scheme (so the caller leaves it untouched).
+ *   { scheme, remoteKind, remoteParam, fsPath }
+ * `fsPath` is the decoded on-host path: a Windows drive path for a `file://`
+ * drive URI, else POSIX. `remoteKind`/`remoteParam` are set for vscode-remote.
+ */
+export function parseRemoteUri(uri) {
+  if (!looksLikeUri(uri)) return null;
+  const m = uri.match(/^([a-z][a-z0-9.+-]*):\/\/([^/]*)((?:\/[^?#]*)?)/i);
+  if (!m) return null;
+  const scheme = m[1].toLowerCase();
+  const authority = m[2] || "";
+  const rawPath = m[3] || "";
+
+  if (scheme === "file") {
+    if (authority) {
+      // file://server/share/… → UNC \\server\share\…
+      const unc = "\\\\" + authority + rawPath.replace(/\//g, "\\");
+      return {
+        scheme,
+        remoteKind: null,
+        remoteParam: null,
+        fsPath: decodeSafe(unc),
+      };
+    }
+    const decoded = decodeSafe(rawPath);
+    // /c:/code/x → c:\code\x  (Windows drive URI); else a POSIX path.
+    if (/^\/[a-zA-Z]:/.test(decoded)) {
+      return {
+        scheme,
+        remoteKind: null,
+        remoteParam: null,
+        fsPath: decoded.slice(1).replace(/\//g, "\\"),
+      };
+    }
+    return {
+      scheme,
+      remoteKind: null,
+      remoteParam: null,
+      fsPath: decoded || "/",
+    };
+  }
+
+  if (scheme === "vscode-remote" || scheme === "vscode-vfs") {
+    // authority = "<kind>+<param>", where `+` may be percent-encoded (%2B).
+    const auth = decodeSafe(authority);
+    const plus = auth.indexOf("+");
+    const remoteKind = plus >= 0 ? auth.slice(0, plus) : auth;
+    const remoteParam = plus >= 0 ? auth.slice(plus + 1) : null;
+    return {
+      scheme,
+      remoteKind: remoteKind || null,
+      remoteParam: remoteParam || null,
+      fsPath: decodeSafe(rawPath) || "/",
+    };
+  }
+
+  return null; // unknown scheme — don't guess
+}
+
+/**
+ * Detect the running CLI's WSL context from env (best-effort). Returns
+ * `{ isWsl, distro }`. Injected in tests; ide-context passes process.env.
+ */
+export function detectWsl(env = {}) {
+  const distro = env.WSL_DISTRO_NAME || null;
+  const isWsl = Boolean(distro || env.WSL_INTEROP);
+  return { isWsl, distro };
+}
+
+/**
+ * Fold an IDE-reported file value into the path `cc` can actually open on THIS
+ * host. Only recognized foreign forms are rewritten; a native or unrecognized
+ * value is returned unchanged (byte-for-byte).
+ *
+ * @param {string} value  URI or path as the IDE reported it
+ * @param {object} [opts]
+ * @param {string} [opts.platform=process.platform]  the CLI host platform
+ * @param {{isWsl?:boolean, distro?:string}} [opts.wsl]  WSL context (see detectWsl)
+ * @returns {string}
+ */
+export function normalizeIdePathForCli(value, opts = {}) {
+  if (typeof value !== "string" || value.length === 0) return value;
+  const platform = opts.platform || process.platform;
+  const wsl = opts.wsl || {};
+  const onWindows = platform === "win32";
+
+  // 1) Resolve a URI down to its on-host fsPath first.
+  let base = value;
+  let remoteKind = null;
+  let remoteParam = null;
+  if (looksLikeUri(value)) {
+    const parsed = parseRemoteUri(value);
+    if (!parsed) return value; // unknown scheme → leave untouched
+    base = parsed.fsPath;
+    remoteKind = parsed.remoteKind;
+    remoteParam = parsed.remoteParam;
+  }
+
+  if (onWindows) {
+    // Native form is a Windows path. A POSIX path from a wsl-remote URI is
+    // reachable from Windows as a \\wsl.localhost\<distro>\… UNC.
+    if (remoteKind === "wsl" && remoteParam && base.startsWith("/")) {
+      return posixToWslUnc(base, remoteParam) || base;
+    }
+    return base;
+  }
+
+  // Native form is POSIX (Linux remote-host or inside WSL).
+  const wslUnc = wslUncToPosix(base);
+  if (wslUnc) return wslUnc.posix;
+  if (looksLikeWindowsPath(base) && wsl.isWsl) {
+    return winDriveToWslMount(base) || base;
+  }
+  return base;
+}
+
+/**
+ * Reverse: a CLI-native fs path → a URI the editor can open. `remoteAuthority`
+ * (e.g. "wsl+Ubuntu", "ssh-remote+host") produces a vscode-remote URI; without
+ * it, a `file://` URI. Percent-encodes spaces / non-ASCII per component.
+ */
+export function cliPathToIdeUri(fsPath, { remoteAuthority } = {}) {
+  if (typeof fsPath !== "string" || fsPath.length === 0) return fsPath;
+  const isWinDrive = looksLikeWindowsPath(fsPath);
+  const posixish = fsPath.replace(/\\/g, "/");
+  const encoded = posixish
+    .split("/")
+    .map((seg) => (/^[a-zA-Z]:$/.test(seg) ? seg : encodeURIComponent(seg)))
+    .join("/");
+  if (remoteAuthority) {
+    const path = encoded.startsWith("/") ? encoded : "/" + encoded;
+    return `vscode-remote://${remoteAuthority}${path}`;
+  }
+  const path = isWinDrive ? "/" + encoded : encoded;
+  return `file://${path.startsWith("/") ? "" : "/"}${path}`;
+}

package/src/lib/review-pipeline.js

@@ -0,0 +1,227 @@
+/**
+ * Multi-agent code-review pipeline core (P2 "多 Agent Code Review").
+ *
+ * `cc review` today is a single read-only agent pass. The gap upgrades it to:
+ *   1. multiple finders (correctness / security / performance / tests),
+ *   2. a verifier that independently reproduces each finding,
+ *   3. a deduper that merges duplicates and confidence-filters,
+ *   4. structured output (path / line / category / severity / failure_scenario /
+ *      evidence).
+ *
+ * This module is the PURE aggregation core — normalize, dedup+merge, apply
+ * verifier verdicts, confidence-filter, rank, and render the structured report.
+ * The fan-out of finder/verifier AGENTS is orchestration the command layer adds;
+ * everything here is deterministic and testable without an LLM.
+ */
+
+/** The finder dimensions a full review fans out across. */
+export const REVIEW_DIMENSIONS = Object.freeze([
+  "correctness",
+  "security",
+  "performance",
+  "tests",
+]);
+
+const SEVERITY_RANK = Object.freeze({
+  critical: 5,
+  high: 4,
+  medium: 3,
+  low: 2,
+  note: 1,
+});
+const SEVERITY_LABEL = Object.freeze({
+  5: "Critical",
+  4: "High",
+  3: "Medium",
+  2: "Low",
+  1: "Note",
+});
+
+/** Canonical severity label (unknown → "Note"). */
+export function normalizeSeverity(sev) {
+  const r = SEVERITY_RANK[String(sev || "").toLowerCase()] || 1;
+  return SEVERITY_LABEL[r];
+}
+export function severityRank(sev) {
+  return SEVERITY_RANK[String(sev || "").toLowerCase()] || 0;
+}
+
+/** Clamp a confidence to [0,1]; non-numeric → `dflt`. */
+export function clampConfidence(v, dflt = 0.5) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return dflt;
+  return Math.max(0, Math.min(1, n));
+}
+
+function confOf(f) {
+  const n = Number(f?.confidence);
+  return Number.isFinite(n) ? n : 0.5;
+}
+
+function normTitle(title) {
+  return String(title || "")
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 80);
+}
+
+/** Dedup identity: same file location + same issue (title). Category-agnostic so
+ *  two finders reporting one bug under different categories merge. */
+export function findingKey(f) {
+  return `${f?.path || ""}:${f?.line ?? ""}:${normTitle(f?.title)}`;
+}
+
+function unionField(group, keys) {
+  const out = [];
+  const seen = new Set();
+  for (const f of group) {
+    for (const key of keys) {
+      const v = f?.[key];
+      const list = Array.isArray(v) ? v : v != null ? [v] : [];
+      for (const item of list) {
+        const s = String(item);
+        if (s && !seen.has(s)) {
+          seen.add(s);
+          out.push(s);
+        }
+      }
+    }
+  }
+  return out;
+}
+
+function maxSeverityLabel(group) {
+  let best = 0;
+  for (const f of group) best = Math.max(best, severityRank(f.severity));
+  return SEVERITY_LABEL[best] || "Note";
+}
+
+/**
+ * Merge findings that describe the SAME issue at the SAME location. The
+ * representative keeps the highest severity + highest confidence; categories /
+ * dimensions / evidence are unioned WHEN PRESENT (so a plain
+ * `{path,line,severity,title}` finding round-trips unchanged — the wiring into
+ * `parseFindings` relies on this). Shape-preserving for inputs without those
+ * fields.
+ */
+export function dedupeFindings(findings) {
+  const groups = new Map();
+  const order = [];
+  for (const f of findings || []) {
+    if (!f) continue;
+    const key = findingKey(f);
+    if (!groups.has(key)) {
+      groups.set(key, []);
+      order.push(key);
+    }
+    groups.get(key).push(f);
+  }
+  return order.map((key) => {
+    const group = groups.get(key);
+    const winner = [...group].sort(
+      (a, b) =>
+        severityRank(b.severity) - severityRank(a.severity) ||
+        confOf(b) - confOf(a),
+    )[0];
+    const merged = { ...winner, severity: maxSeverityLabel(group) };
+    if (Number.isFinite(Number(winner.confidence))) {
+      merged.confidence = Math.max(...group.map(confOf));
+    }
+    const cats = unionField(group, ["category", "categories"]);
+    if (cats.length) merged.categories = cats;
+    const dims = unionField(group, ["dimension", "dimensions"]);
+    if (dims.length) merged.dimensions = dims;
+    if (group.length > 1) merged.mergedCount = group.length;
+    return merged;
+  });
+}
+
+/**
+ * Apply verifier verdicts. `verdicts` maps a findingKey → { verified, confidence?,
+ * note? }. A finding the verifier could NOT reproduce (`verified === false`) is
+ * DROPPED; a reproduced one is kept, its confidence updated and a `verified`
+ * flag set. Findings with no verdict pass through as unverified.
+ */
+export function applyVerdicts(findings, verdicts = {}) {
+  const map =
+    verdicts instanceof Map
+      ? verdicts
+      : new Map(Object.entries(verdicts || {}));
+  const out = [];
+  for (const f of findings || []) {
+    if (!f) continue;
+    const v = map.get(findingKey(f));
+    if (!v) {
+      out.push(f);
+      continue;
+    }
+    if (v.verified === false) continue; // refuted → drop
+    out.push({
+      ...f,
+      verified: true,
+      confidence:
+        v.confidence != null ? clampConfidence(v.confidence) : confOf(f),
+      ...(v.note ? { verifierNote: String(v.note) } : {}),
+    });
+  }
+  return out;
+}
+
+/** Keep findings whose confidence is at least `minConfidence`. */
+export function filterByConfidence(findings, { minConfidence = 0 } = {}) {
+  return (findings || []).filter((f) => f && confOf(f) >= minConfidence);
+}
+
+/** Sort by severity (desc) then confidence (desc) then path/line for stability. */
+export function rankFindings(findings) {
+  return [...(findings || [])].sort(
+    (a, b) =>
+      severityRank(b.severity) - severityRank(a.severity) ||
+      confOf(b) - confOf(a) ||
+      String(a.path || "").localeCompare(String(b.path || "")) ||
+      (Number(a.line) || 0) - (Number(b.line) || 0),
+  );
+}
+
+function toOutputFinding(f) {
+  return {
+    path: String(f.path || ""),
+    line: Number.isFinite(Number(f.line)) ? Math.floor(Number(f.line)) : null,
+    category: f.category || (f.categories && f.categories[0]) || "correctness",
+    severity: normalizeSeverity(f.severity),
+    failure_scenario: String(f.failureScenario || f.failure_scenario || ""),
+    evidence: String(f.evidence || ""),
+    confidence: clampConfidence(f.confidence),
+  };
+}
+
+/**
+ * The full pipeline: dedup → apply verdicts → confidence-filter → rank → render
+ * the structured report (the gap's path/line/category/severity/failure_scenario/
+ * evidence output) plus severity/category rollups.
+ *
+ * @param {Array} rawFindings   findings from all finders
+ * @param {object} [opts]       { verdicts, minConfidence }
+ */
+export function buildReviewReport(
+  rawFindings,
+  { verdicts = {}, minConfidence = 0 } = {},
+) {
+  const deduped = dedupeFindings(rawFindings);
+  const verified = applyVerdicts(deduped, verdicts);
+  const filtered = filterByConfidence(verified, { minConfidence });
+  const ranked = rankFindings(filtered);
+  const findings = ranked.map(toOutputFinding);
+
+  const bySeverity = { Critical: 0, High: 0, Medium: 0, Low: 0, Note: 0 };
+  const byCategory = {};
+  for (const f of findings) {
+    bySeverity[f.severity] = (bySeverity[f.severity] || 0) + 1;
+    byCategory[f.category] = (byCategory[f.category] || 0) + 1;
+  }
+  return {
+    findings,
+    summary: { total: findings.length, bySeverity, byCategory },
+  };
+}