@oriro/orirocli 0.1.0

package/skills/craft/vercel-optimize/scripts/gate-investigations.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// Pure-JS deterministic gate. Reads merged signals.json, emits
+// {toLaunch, platform, gated}. Same input → byte-identical output (modulo
+// appliedAt). Sort keys are stable and explicit — never change without
+// a co-located golden-output test update.
+
+import { readFile } from "node:fs/promises";
+import { applyAuthDisqualifier } from "../lib/auth-route.mjs";
+import { validateCandidates } from "../lib/gates/contract.mjs";
+import { applyHardGates } from "../lib/gates/hard-gates.mjs";
+import { gates, DEFAULT_MAX_CODE_CANDIDATES, GATE_VERSION } from "../lib/gates/index.mjs";
+import { selectLaunchCandidates } from "../lib/gates/select-candidates.mjs";
+import { routePathMatchScore } from "../lib/investigation-brief.mjs";
+import { dedupeCandidates } from "../lib/route-normalize.mjs";
+
+const SCHEMA_VERSION = "1.1";
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.signalsPath) {
+    console.error(
+      "usage: node scripts/gate-investigations.mjs <signals.json> [--max-candidates N|all]",
+    );
+    console.error("       VERCEL_OPTIMIZE_MAX_CANDIDATES env var supported (same values)");
+    process.exit(1);
+  }
+  const budget = resolveBudget(args);
+  const signals = JSON.parse(await readFile(args.signalsPath, "utf-8"));
+
+  const allSeeds = gates.flatMap((g) => {
+    try {
+      return g.gate(signals) ?? [];
+    } catch (err) {
+      console.error(`[gate-investigations] gate ${g.metadata?.id} threw: ${err.message}`);
+      return [];
+    }
+  });
+
+  const validSeeds = validateCandidates(allSeeds, { source: "gate-output" });
+  const annotated = validSeeds.map(applyAuthDisqualifier);
+  const sorted = annotated.slice().sort(stableCompare);
+
+  // Next.js 16 segment-tree metric paths surface the same source file under
+  // many encoded labels (city variants, _tree/_index siblings, base64 flag
+  // prefixes). Without dedup the budget gets shredded ~4-10x per page.
+  const { deduped, dropped } = dedupeCandidates(sorted);
+  const displayAnnotated = deduped.map((candidate) => attachDisplayRoute(candidate, signals));
+  const hardGateResult = applyHardGates(displayAnnotated, signals);
+  const gateable = hardGateResult.allowed;
+
+  // Account-scope candidates don't compete with code-scope for the budget.
+  const codeScoped = gateable.filter((c) => !c.disqualified && c.scope !== "account");
+  const platformScoped = gateable.filter((c) => !c.disqualified && c.scope === "account");
+
+  const selection = selectLaunchCandidates(codeScoped, budget, {
+    diversify: args.budgetSource === "default",
+  });
+  const toLaunch = selection.selected;
+  const skippedByBudget = selection.skipped;
+  const budgetLabel = budget === Infinity ? "unlimited (all)" : String(budget);
+  const gated = [
+    ...gateable
+      .filter((c) => c.disqualified)
+      .map((c) => ({ ...c, gatedReason: c.disqualifyReason ?? "disqualified" })),
+    ...hardGateResult.gated,
+    ...skippedByBudget.map((c) => ({
+      ...c,
+      gatedReason: `skippedByBudget (max-candidates=${budgetLabel}; raise with --max-candidates N or =all)`,
+    })),
+    ...dropped.map((d) => ({
+      ...d.candidate,
+      gatedReason: `coveredBy (${d.mergedInto}) — ${d.reason}`,
+    })),
+  ];
+
+  process.stdout.write(
+    JSON.stringify(
+      {
+        schemaVersion: SCHEMA_VERSION,
+        gateVersion: GATE_VERSION,
+        appliedAt: new Date().toISOString(),
+        budget: {
+          maxCandidates: budget === Infinity ? "all" : budget,
+          source: args.budgetSource,
+          selection: selection.selectionMode,
+        },
+        toLaunch,
+        platform: platformScoped,
+        gated,
+        gateMetadata: gates.map((g) => ({
+          id: g.metadata?.id,
+          threshold: g.metadata?.threshold,
+          billingDimension: g.metadata?.billingDimension,
+          sourceCitation: g.metadata?.sourceCitation,
+        })),
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+}
+
+function parseArgs(argv) {
+  const out = { positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--max-candidates") out.maxCandidatesArg = argv[++i];
+    else if (a.startsWith("--max-candidates="))
+      out.maxCandidatesArg = a.slice("--max-candidates=".length);
+    else out.positional.push(a);
+  }
+  out.signalsPath = out.positional[0];
+  return out;
+}
+
+function resolveBudget(args) {
+  const raw = args.maxCandidatesArg ?? process.env.VERCEL_OPTIMIZE_MAX_CANDIDATES;
+  if (raw == null || raw === "") {
+    args.budgetSource = "default";
+    return DEFAULT_MAX_CODE_CANDIDATES;
+  }
+  const trimmed = String(raw).trim().toLowerCase();
+  if (trimmed === "all" || trimmed === "unlimited" || trimmed === "-1") {
+    args.budgetSource = args.maxCandidatesArg != null ? "flag" : "env";
+    return Infinity;
+  }
+  const n = Number(trimmed);
+  if (!Number.isFinite(n) || n < 1 || !Number.isInteger(n)) {
+    console.error(
+      `[gate-investigations] bad budget value '${raw}'; expected positive integer or 'all'`,
+    );
+    process.exit(2);
+  }
+  args.budgetSource = args.maxCandidatesArg != null ? "flag" : "env";
+  return n;
+}
+
+// Total ordering: priority desc, kind asc, route asc. Underpins byte-identical output.
+function stableCompare(a, b) {
+  const pa = a.priority ?? 0;
+  const pb = b.priority ?? 0;
+  if (pa !== pb) return pb - pa;
+  const ka = String(a.kind ?? "");
+  const kb = String(b.kind ?? "");
+  if (ka !== kb) return ka.localeCompare(kb);
+  const ra = String(a.route ?? a.hostname ?? "");
+  const rb = String(b.route ?? b.hostname ?? "");
+  return ra.localeCompare(rb);
+}
+
+function attachDisplayRoute(candidate, signals) {
+  if (!candidate || candidate.scope !== "route" || typeof candidate.route !== "string")
+    return candidate;
+  if (!candidate.route.includes("[*]")) return candidate;
+
+  const routes = (signals.codebase?.routes ?? [])
+    .map((route) => route?.routePath)
+    .filter((routePath) => typeof routePath === "string" && routePath.length > 0);
+  if (routes.length === 0) return candidate;
+
+  let bestRoute = null;
+  let bestScore = 0;
+  for (const routePath of routes) {
+    const score = routePathMatchScore(routePath, candidate.route);
+    if (score > bestScore) {
+      bestRoute = routePath;
+      bestScore = score;
+    }
+  }
+
+  if (!bestRoute || bestScore <= 0 || bestRoute === candidate.route) return candidate;
+  return { ...candidate, displayRoute: bestRoute };
+}
+
+main().catch((err) => {
+  console.error("[gate-investigations] FAILED:", err.message);
+  process.exit(1);
+});

package/skills/craft/vercel-optimize/scripts/merge-signals.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+// Deterministically combines Vercel metric collection with the local codebase
+// scan. Keeps the merged artifact shape stable: collect-signals output at the
+// top level, scan-codebase output under `codebase`.
+
+import { realpathSync } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { routePathMatchScore } from "../lib/investigation-brief.mjs";
+import { canonicalizeRoute } from "../lib/route-normalize.mjs";
+
+const log = (...args) => console.error("[merge-signals]", ...args);
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.signalsPath || !args.codebasePath) {
+    console.error(
+      "usage: node scripts/merge-signals.mjs <signals.json> <codebase.json> [--out merged.json] [--force]",
+    );
+    process.exit(1);
+  }
+
+  const [signals, codebase] = await Promise.all([
+    readJson(args.signalsPath, "signals"),
+    readJson(args.codebasePath, "codebase scan"),
+  ]);
+
+  const merged = mergeSignals(signals, codebase);
+  const body = JSON.stringify(merged, null, 2) + "\n";
+  if (args.outPath) {
+    await writeOutput(args.outPath, body, { force: args.force });
+    log(`wrote ${args.outPath}`);
+  } else {
+    process.stdout.write(body);
+  }
+}
+
+export function mergeSignals(signals, codebase) {
+  assertObject(signals, "signals");
+  assertObject(codebase, "codebase scan");
+
+  if (!signals.schemaVersion) {
+    throw new Error(
+      "signals.json is missing schemaVersion; pass collect-signals output as the first file.",
+    );
+  }
+  if (!Array.isArray(codebase.routes) || !Array.isArray(codebase.findings) || !codebase.stack) {
+    throw new Error(
+      "codebase.json must be scan-codebase output with stack, routes[], and findings[].",
+    );
+  }
+
+  return {
+    ...signals,
+    codebase: annotateCodebaseScan(signals, codebase),
+  };
+}
+
+export function annotateCodebaseScan(signals, codebase) {
+  const index = buildRouteMetricIndex(signals);
+  return {
+    ...codebase,
+    findings: (codebase.findings ?? []).map((finding) => annotateFinding(finding, index)),
+  };
+}
+
+function annotateFinding(finding, index) {
+  if (!finding || typeof finding !== "object") return finding;
+  if (finding.trafficIndependent) return finding;
+  if (!finding.route) return { ...finding, o11ySignal: "NO-ROUTE-MAPPING" };
+
+  const summary = bestRouteSummary(finding.route, index);
+  if (!summary || !hasTraffic(summary)) return { ...finding, o11ySignal: "COLD-PATH" };
+  return { ...finding, o11ySignal: formatRouteSignal(summary) };
+}
+
+function buildRouteMetricIndex(signals) {
+  const out = new Map();
+  const ensure = (route) => {
+    const canonical = canonicalizeRoute(route);
+    const existing = out.get(canonical) ?? { route: canonical };
+    out.set(canonical, existing);
+    return existing;
+  };
+
+  for (const row of rows(signals, "fnStatusByRoute")) {
+    if (!row.route) continue;
+    const summary = ensure(row.route);
+    summary.functionRuns = (summary.functionRuns ?? 0) + numeric(row.value);
+  }
+  for (const row of rows(signals, "fnDurationP95ByRoute")) {
+    if (!row.route) continue;
+    ensure(row.route).p95Ms = numeric(row.value);
+  }
+  for (const row of rows(signals, "requestsByRouteCache")) {
+    if (!row.route) continue;
+    const summary = ensure(row.route);
+    const count = numeric(row.value);
+    summary.requests = (summary.requests ?? 0) + count;
+    if (String(row.cache_result).toUpperCase() === "HIT") {
+      summary.cacheHits = (summary.cacheHits ?? 0) + count;
+    }
+  }
+  return out;
+}
+
+function rows(signals, metricId) {
+  const rows = signals?.metrics?.[metricId]?.rows;
+  return Array.isArray(rows) ? rows : [];
+}
+
+function numeric(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function bestRouteSummary(route, index) {
+  const canonical = canonicalizeRoute(route);
+  const exact = index.get(canonical);
+  if (exact) return exact;
+
+  let best = null;
+  for (const summary of index.values()) {
+    const score = routePathMatchScore(canonical, summary.route);
+    if (score <= 0) continue;
+    if (!best || score > best.score) best = { score, summary };
+  }
+  return best?.summary ?? null;
+}
+
+function hasTraffic(summary) {
+  return (summary.functionRuns ?? 0) > 0 || (summary.requests ?? 0) > 0;
+}
+
+function formatRouteSignal(summary) {
+  const parts = [];
+  if ((summary.functionRuns ?? 0) > 0) parts.push(`inv=${Math.round(summary.functionRuns)}`);
+  else if ((summary.requests ?? 0) > 0) parts.push(`requests=${Math.round(summary.requests)}`);
+  if ((summary.p95Ms ?? 0) > 0) parts.push(`p95=${Math.round(summary.p95Ms)}ms`);
+  if ((summary.requests ?? 0) > 0 && summary.cacheHits != null) {
+    const hitRate = Math.round((summary.cacheHits / summary.requests) * 100);
+    parts.push(`cache=${hitRate}%`);
+  }
+  return parts.join(",") || "COLD-PATH";
+}
+
+function parseArgs(argv) {
+  const out = { positional: [], force: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--out") out.outPath = argv[++i];
+    else if (a.startsWith("--out=")) out.outPath = a.slice("--out=".length);
+    else if (a === "--force") out.force = true;
+    else out.positional.push(a);
+  }
+  out.signalsPath = out.positional[0];
+  out.codebasePath = out.positional[1];
+  return out;
+}
+
+async function readJson(path, label) {
+  try {
+    return JSON.parse(await readFile(path, "utf-8"));
+  } catch (err) {
+    throw new Error(`Could not read ${label} JSON at ${path}: ${err.message}`);
+  }
+}
+
+function assertObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be a JSON object.`);
+  }
+}
+
+async function writeOutput(path, body, { force }) {
+  if (!force && (await exists(path))) {
+    throw new Error(
+      `output file already exists: ${path}. Use a fresh run directory or pass --force to overwrite.`,
+    );
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, body);
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+if (
+  process.argv[1] &&
+  realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+) {
+  main().catch((err) => {
+    console.error("[merge-signals] FAILED:", err.message);
+    process.exit(1);
+  });
+}

package/skills/craft/vercel-optimize/scripts/prepare-investigation-brief.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+// Emits the ENTIRE prompt a sub-agent sees for one candidate (candidate +
+// deep-dive evidence + filtered citations + playbook + protocol + output
+// schema). --list emits a manifest the orchestrator uses to decide fan-out
+// vs serial. Brief → stdout, status → stderr.
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { formatCandidateLabel } from "../lib/display-labels.mjs";
+import {
+  buildBrief,
+  inferPlaybook,
+  inferFrameworkPlaybook,
+  resolveFiles,
+  citationSubset,
+} from "../lib/investigation-brief.mjs";
+import { candidateRefFor } from "../lib/reconcile-candidates.mjs";
+import { supportTopicSubset } from "../lib/support-topics.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PLAYBOOKS_DIR = join(HERE, "..", "references", "playbooks");
+
+const log = (...a) => console.error("[prepare-brief]", ...a);
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.mergedPath || !args.investigationPath) {
+    console.error(
+      "usage: node scripts/prepare-investigation-brief.mjs <merged.json> <investigation.json> [--index N] [--group toLaunch|platform] [--out FILE]",
+    );
+    console.error(
+      "   or: node scripts/prepare-investigation-brief.mjs <merged.json> <investigation.json> --list",
+    );
+    process.exit(1);
+  }
+
+  const [merged, investigation] = await Promise.all([
+    readFile(args.mergedPath, "utf-8").then(JSON.parse),
+    readFile(args.investigationPath, "utf-8").then(JSON.parse),
+  ]);
+
+  if (args.list) {
+    const manifest = buildManifest(merged, investigation);
+    process.stdout.write(JSON.stringify(manifest, null, 2) + "\n");
+    return;
+  }
+
+  const group = args.group ?? "toLaunch";
+  const index = args.index ?? 0;
+  const pool = Array.isArray(investigation[group]) ? investigation[group] : [];
+  if (index < 0 || index >= pool.length) {
+    console.error(
+      `[prepare-brief] FATAL: ${group}[${index}] out of range (${group} has ${pool.length} entries)`,
+    );
+    process.exit(2);
+  }
+  let candidate = pool[index];
+
+  // Scan output may live at merged.codebase (older shape) or merged.signals.codebase
+  // (current shape, after the jq merge nests it under signals). Resolve either.
+  const codebase = pickCodebase(merged);
+  const signals = {
+    ...merged,
+    codebase,
+  };
+  const files = resolveFiles(candidate, signals);
+  candidate = {
+    ...candidate,
+    candidateRef: candidate.candidateRef ?? candidateRefFor(candidate, files),
+  };
+  const playbookId = inferPlaybook(signals);
+  const playbookBody = playbookId ? await tryReadPlaybook(playbookId) : null;
+  const frameworkPlaybookId = inferFrameworkPlaybook(signals);
+  const frameworkPlaybookBody = frameworkPlaybookId
+    ? await tryReadPlaybook(frameworkPlaybookId)
+    : null;
+
+  const stack = signals.stack ?? signals.codebase?.stack ?? {};
+  const framework = stack.framework ?? "unknown";
+  const version = stack.frameworkVersion ?? "unknown";
+  const citations = await citationSubset(candidate.kind, framework, version);
+  const supportTopics = await supportTopicSubset({
+    candidate,
+    signals,
+    framework,
+    version,
+    profile: playbookId,
+    frameworkPlaybookId,
+  });
+
+  const brief = buildBrief({
+    candidate,
+    candidateIndex: index,
+    candidateGroup: group,
+    files,
+    signals,
+    citations,
+    playbookId,
+    playbookBody,
+    frameworkPlaybookId,
+    frameworkPlaybookBody,
+    supportTopics,
+    generatedAt: args.deterministic ? null : new Date().toISOString(),
+  });
+
+  if (args.outPath) {
+    await mkdir(dirname(args.outPath), { recursive: true });
+    await writeBriefFile(args.outPath, brief, { force: args.force });
+    log(`wrote ${brief.length}B → ${args.outPath}`);
+  } else {
+    process.stdout.write(brief + "\n");
+  }
+}
+
+function buildManifest(merged, investigation) {
+  const out = [];
+  const groups = ["toLaunch", "platform"];
+  for (const group of groups) {
+    const pool = Array.isArray(investigation[group]) ? investigation[group] : [];
+    pool.forEach((c, i) => {
+      const files = resolveFiles(c, { ...merged, codebase: pickCodebase(merged) });
+      const candidateRef = c.candidateRef ?? candidateRefFor(c, files);
+      out.push({
+        group,
+        index: i,
+        kind: c.kind,
+        route: c.route ?? c.hostname ?? null,
+        scope: c.scope ?? null,
+        priority: c.priority ?? null,
+        confidence: c.confidence ?? null,
+        o11ySignal: c.o11ySignal ?? null,
+        files,
+        candidateRef,
+        label: formatCandidateLabel({ ...c, files }),
+      });
+    });
+  }
+  return {
+    schemaVersion: "1.0",
+    totalBriefs: out.length,
+    toLaunchCount: out.filter((b) => b.group === "toLaunch").length,
+    platformCount: out.filter((b) => b.group === "platform").length,
+    preResolvedRecords: Array.isArray(investigation.preResolvedRecords)
+      ? investigation.preResolvedRecords
+      : [],
+    fanoutPlan: buildFanoutPlan(out),
+    briefs: out,
+  };
+}
+
+function buildFanoutPlan(briefs) {
+  const groups = new Map();
+  for (const brief of briefs) {
+    const key = candidateFamilyKey(brief);
+    const existing = groups.get(key) ?? {
+      familyKey: key,
+      label: brief.label,
+      kind: brief.kind,
+      primaryBrief: { group: brief.group, index: brief.index, candidateRef: brief.candidateRef },
+      relatedBriefs: [],
+    };
+    if (existing.primaryBrief.candidateRef !== brief.candidateRef) {
+      existing.relatedBriefs.push({
+        group: brief.group,
+        index: brief.index,
+        candidateRef: brief.candidateRef,
+      });
+    }
+    groups.set(key, existing);
+  }
+  return {
+    totalFamilies: groups.size,
+    families: [...groups.values()].map((g) => ({
+      ...g,
+      totalBriefs: 1 + g.relatedBriefs.length,
+    })),
+  };
+}
+
+function candidateFamilyKey(brief) {
+  const file = Array.isArray(brief.files) && brief.files.length > 0 ? brief.files[0] : null;
+  const target = file ?? brief.route ?? brief.scope ?? "<account>";
+  return `${brief.kind ?? "unknown"}:${target}`;
+}
+
+// Prefer merged.codebase, fall back to merged.signals.codebase, then empty.
+// Also accepts a fully-shaped scan doc directly (used in tests).
+function pickCodebase(merged) {
+  if (!merged || typeof merged !== "object") return {};
+  if (
+    merged.codebase &&
+    typeof merged.codebase === "object" &&
+    (merged.codebase.routes || merged.codebase.findings)
+  ) {
+    return merged.codebase;
+  }
+  if (merged.signals?.codebase && typeof merged.signals.codebase === "object") {
+    return merged.signals.codebase;
+  }
+  return {};
+}
+
+async function tryReadPlaybook(id) {
+  try {
+    return await readFile(join(PLAYBOOKS_DIR, `${id}.md`), "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function parseArgs(argv) {
+  const out = { positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--index") out.index = Number(argv[++i]);
+    else if (a.startsWith("--index=")) out.index = Number(a.slice("--index=".length));
+    else if (a === "--group") out.group = argv[++i];
+    else if (a.startsWith("--group=")) out.group = a.slice("--group=".length);
+    else if (a === "--out") out.outPath = resolve(argv[++i]);
+    else if (a.startsWith("--out=")) out.outPath = resolve(a.slice("--out=".length));
+    else if (a === "--list") out.list = true;
+    else if (a === "--deterministic") out.deterministic = true;
+    else if (a === "--force") out.force = true;
+    else out.positional.push(a);
+  }
+  out.mergedPath = out.positional[0];
+  out.investigationPath = out.positional[1];
+  return out;
+}
+
+async function writeBriefFile(outPath, brief, { force = false } = {}) {
+  try {
+    await writeFile(outPath, brief + "\n", { encoding: "utf-8", flag: force ? "w" : "wx" });
+  } catch (err) {
+    if (err?.code === "EEXIST") {
+      throw new Error(
+        `output file already exists: ${outPath}. Use a fresh run directory or pass --force to overwrite.`,
+      );
+    }
+    throw err;
+  }
+}
+
+main().catch((err) => {
+  console.error("[prepare-brief] FAILED:", err.message);
+  console.error(err.stack);
+  process.exit(1);
+});

package/skills/craft/vercel-optimize/scripts/reconcile-candidates.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// Deterministic reconciliation between deep-dive and investigator fan-out.
+// Reads investigation-evidence.json, removes candidates whose follow-up metric
+// evidence already disproves/reframes the gate hypothesis, and emits the same
+// shape with preResolvedRecords for the final report.
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { reconcileInvestigation } from "../lib/reconcile-candidates.mjs";
+
+const log = (...a) => console.error("[reconcile-candidates]", ...a);
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.investigationPath) {
+    console.error(
+      "usage: node scripts/reconcile-candidates.mjs <investigation-evidence.json> [--gate gate.json] [--out reconciled-investigation.json]",
+    );
+    process.exit(1);
+  }
+
+  const [investigation, gate] = await Promise.all([
+    readFile(args.investigationPath, "utf-8").then(JSON.parse),
+    args.gatePath ? readFile(args.gatePath, "utf-8").then(JSON.parse) : null,
+  ]);
+
+  const reconciled = reconcileInvestigation(investigation, { gate });
+  const serialized =
+    JSON.stringify(
+      {
+        ...reconciled,
+        reconciledAt: args.noTimestamp ? null : new Date().toISOString(),
+      },
+      null,
+      2,
+    ) + "\n";
+
+  if (args.outPath) {
+    await mkdir(dirname(args.outPath), { recursive: true });
+    await writeFile(args.outPath, serialized, "utf-8");
+    log(`wrote ${serialized.length}B -> ${args.outPath}`);
+  } else {
+    process.stdout.write(serialized);
+  }
+
+  const dropped = reconciled.reconciliation?.droppedBeforeInvestigation ?? 0;
+  if (dropped > 0) log(`dropped ${dropped} candidate(s) before investigation`);
+}
+
+function parseArgs(argv) {
+  const out = { positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--gate") out.gatePath = resolve(argv[++i]);
+    else if (a.startsWith("--gate=")) out.gatePath = resolve(a.slice("--gate=".length));
+    else if (a === "--out") out.outPath = resolve(argv[++i]);
+    else if (a.startsWith("--out=")) out.outPath = resolve(a.slice("--out=".length));
+    else if (a === "--no-timestamp") out.noTimestamp = true;
+    else out.positional.push(a);
+  }
+  out.investigationPath = out.positional[0] ? resolve(out.positional[0]) : null;
+  return out;
+}
+
+main().catch((err) => {
+  console.error("[reconcile-candidates] FAILED:", err.message);
+  console.error(err.stack);
+  process.exit(1);
+});