@olives/devos 2.1.0

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

@@ -0,0 +1,166 @@
+#!/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 { gates, DEFAULT_MAX_CODE_CANDIDATES, GATE_VERSION } from '../lib/gates/index.mjs';
+import { applyAuthDisqualifier } from '../lib/auth-route.mjs';
+import { dedupeCandidates } from '../lib/route-normalize.mjs';
+import { validateCandidates } from '../lib/gates/contract.mjs';
+import { applyHardGates } from '../lib/gates/hard-gates.mjs';
+import { selectLaunchCandidates } from '../lib/gates/select-candidates.mjs';
+import { routePathMatchScore } from '../lib/investigation-brief.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/.agents/skills/vercel-optimize/scripts/merge-signals.mjs

@@ -0,0 +1,192 @@
+#!/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 { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+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/.agents/skills/vercel-optimize/scripts/prepare-investigation-brief.mjs

@@ -0,0 +1,231 @@
+#!/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 {
+  buildBrief,
+  inferPlaybook,
+  inferFrameworkPlaybook,
+  resolveFiles,
+  citationSubset,
+} from '../lib/investigation-brief.mjs';
+import { supportTopicSubset } from '../lib/support-topics.mjs';
+import { candidateRefFor } from '../lib/reconcile-candidates.mjs';
+import { formatCandidateLabel } from '../lib/display-labels.mjs';
+import { fileURLToPath } from 'node:url';
+
+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/.agents/skills/vercel-optimize/scripts/reconcile-candidates.mjs

@@ -0,0 +1,62 @@
+#!/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);
+});