redlinegate 0.0.1

package/scripts/lib/__tests__/exemptions.test.mjs

@@ -0,0 +1,85 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readExemption, standingExemptions } from '../exemptions.mjs';
+
+const block = (until, scope = 'checklist') =>
+  `## Summary\n\nx\n\n## Redline exemption\n\n- reason: a reason long enough to be useful to a later reader\n- until: ${until}\n- scope: ${scope}\n`;
+
+test('reads a structured exemption out of a pull request body', () => {
+  const exemption = readExemption(block('2026-10-01'));
+
+  assert.equal(exemption?.until, '2026-10-01');
+  assert.deepEqual(exemption?.scope, ['checklist']);
+});
+
+test('a body with no block reads as no exemption, not as an empty one', () => {
+  assert.equal(readExemption('## Summary\n\nnothing\n'), null);
+  assert.equal(readExemption(''), null);
+  assert.equal(readExemption(null), null);
+});
+
+test('a block missing a required field is not an exemption', () => {
+  assert.equal(readExemption('## Redline exemption\n- reason: something long enough to count\n'), null);
+  assert.equal(readExemption('## Redline exemption\n- until: 2026-10-01\n'), null);
+});
+
+test('an omitted scope reads as everything, matching the CLI', () => {
+  const exemption = readExemption(
+    '## Redline exemption\n- reason: a reason long enough to be useful\n- until: 2026-10-01\n'
+  );
+
+  assert.deepEqual(exemption?.scope, ['*']);
+});
+
+test('the reason stops at the next heading', () => {
+  const exemption = readExemption(
+    '## Redline exemption\n- reason: a reason long enough to be useful\n- until: 2026-10-01\n\n## Rollback\n- until: 2099-01-01\n'
+  );
+
+  assert.equal(exemption?.until, '2026-10-01');
+});
+
+const record = (repo, until, scope = ['checklist']) => ({
+  repo,
+  exemption: { reason: 'r', until, scope },
+});
+
+test('standing exemptions group by scope and count the repositories using each', () => {
+  const standing = standingExemptions(
+    [
+      record('acme/web', '2026-10-01'),
+      record('acme/api', '2026-10-05'),
+      record('acme/web', '2026-10-09'),
+      record('acme/infra', '2026-10-02', ['adr']),
+    ],
+    new Date('2026-09-04T00:00:00.000Z')
+  );
+
+  assert.deepEqual(standing[0], { scope: 'checklist', count: 3, repos: 2, soonest: '2026-10-01' });
+  assert.deepEqual(standing[1], { scope: 'adr', count: 1, repos: 1, soonest: '2026-10-02' });
+});
+
+test('an expired exemption is history, not a standing one', () => {
+  // Counting it would make a resolved problem look permanent.
+  const standing = standingExemptions(
+    [record('acme/web', '2026-01-01'), record('acme/api', '2026-10-01')],
+    new Date('2026-09-04T00:00:00.000Z')
+  );
+
+  assert.equal(standing.length, 1);
+  assert.equal(standing[0]?.count, 1);
+});
+
+test('a pull request with no exemption contributes nothing', () => {
+  const standing = standingExemptions([{ repo: 'acme/web' }], new Date('2026-09-04T00:00:00.000Z'));
+
+  assert.deepEqual(standing, []);
+});
+
+test('a wildcard scope is reported as itself, not expanded', () => {
+  // Expanding it would invent checks the author never named and make the trend
+  // unreadable.
+  const standing = standingExemptions([record('acme/web', '2026-10-01', ['*'])], new Date('2026-09-04'));
+
+  assert.equal(standing[0]?.scope, '*');
+});

package/scripts/lib/__tests__/metrics-scanner.test.mjs

@@ -0,0 +1,65 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { aggregate } from '../metrics.mjs';
+
+const record = (over = {}) => ({
+  repo: 'acme/web',
+  merged_at: '2026-08-01T00:00:00Z',
+  findings: { total: 4, blocker: 1, high: 2, suggestion: 1 },
+  outcomes: { resolved: 3, stale_by_severity: {} },
+  rules: { 'react/effect-derived-state': { severity: 'BLOCKER', fired: 1, resolved: 1, stale: 0 } },
+  reviewers: ['copilot'],
+  ...over,
+});
+
+test('scanner findings are aggregated alongside Redline’s, never into them', () => {
+  // Folding another tool's rule ids into byRule would tune Redline's rules on
+  // that tool's noise — the one way ingestion makes things worse.
+  const agg = aggregate([
+    record({ scanner: { findings: 3, by_tool: { CodeQL: 3 }, by_severity: { blocker: 2, high: 1 } } }),
+  ]);
+
+  assert.equal(agg.findings, 4, "Redline's own total is untouched");
+  assert.deepEqual(Object.keys(Object.fromEntries(agg.byRule.map((r) => [r.id, r]))), [
+    'react/effect-derived-state',
+  ]);
+  assert.equal(agg.scanner.findings, 3);
+  assert.deepEqual(agg.scanner.bySeverity, { blocker: 2, high: 1, suggestion: 0 });
+});
+
+test('per-tool totals identify one noisy scanner across the estate', () => {
+  const agg = aggregate([
+    record({ scanner: { findings: 3, by_tool: { CodeQL: 3 }, by_severity: {} } }),
+    record({ repo: 'acme/api', scanner: { findings: 5, by_tool: { Semgrep: 5 }, by_severity: {} } }),
+  ]);
+
+  assert.deepEqual(agg.scanner.byTool, [
+    { tool: 'Semgrep', findings: 5 },
+    { tool: 'CodeQL', findings: 3 },
+  ]);
+});
+
+test('the count of repositories emitting anything answers the roadmap’s open question 1', () => {
+  const agg = aggregate([
+    record({ scanner: { findings: 3, by_tool: {}, by_severity: {} } }),
+    record({ repo: 'acme/api', scanner: { findings: 0, by_tool: {}, by_severity: {} } }),
+    record({ repo: 'acme/infra' }),
+  ]);
+
+  assert.equal(agg.scanner.repos, 1);
+});
+
+test('records from before ingestion existed aggregate to zero, not to NaN', () => {
+  const agg = aggregate([record()]);
+
+  assert.equal(agg.scanner.findings, 0);
+  assert.equal(agg.scanner.repos, 0);
+});
+
+test('an unknown severity from a scanner is ignored rather than inventing a bucket', () => {
+  const agg = aggregate([
+    record({ scanner: { findings: 1, by_tool: {}, by_severity: { catastrophic: 1 } } }),
+  ]);
+
+  assert.deepEqual(agg.scanner.bySeverity, { blocker: 0, high: 0, suggestion: 0 });
+});

package/scripts/lib/__tests__/sarif.test.mjs

@@ -0,0 +1,125 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { aggregateBySource, ingestAlerts, mapSeverity } from '../sarif.mjs';
+
+const alert = (over = {}) => ({
+  rule: { id: 'js/sql-injection', security_severity_level: 'critical' },
+  tool: { name: 'CodeQL' },
+  state: 'open',
+  most_recent_instance: { location: { path: 'src/db.ts', start_line: 42 } },
+  ...over,
+});
+
+test('an alert becomes a finding carrying its tool and its own rule id', () => {
+  const { findings, problems } = ingestAlerts([alert()]);
+
+  assert.deepEqual(problems, []);
+  assert.deepEqual(findings[0], {
+    source: 'sarif',
+    tool: 'CodeQL',
+    ruleId: 'js/sql-injection',
+    severity: 'BLOCKER',
+    nativeSeverity: 'critical',
+    state: 'open',
+    file: 'src/db.ts',
+    line: 42,
+  });
+});
+
+test('security severity wins over the SARIF level when both are present', () => {
+  const { findings } = ingestAlerts([
+    alert({ rule: { id: 'r', security_severity_level: 'low', severity: 'error' } }),
+  ]);
+
+  assert.equal(findings[0]?.severity, 'SUGGESTION');
+});
+
+test('the SARIF level is used when there is no security severity', () => {
+  const { findings } = ingestAlerts([alert({ rule: { id: 'r', severity: 'warning' } })]);
+
+  assert.equal(findings[0]?.severity, 'HIGH');
+});
+
+test('an alert with no rule id is reported and skipped', () => {
+  const { findings, problems } = ingestAlerts([alert({ rule: {} })]);
+
+  assert.deepEqual(findings, []);
+  assert.match(problems[0] ?? '', /no rule id/);
+});
+
+test('an unknown severity falls back to SUGGESTION and says so', () => {
+  const { findings, problems } = ingestAlerts([
+    alert({ rule: { id: 'r', security_severity_level: 'apocalyptic' } }),
+  ]);
+
+  assert.equal(findings[0]?.severity, 'SUGGESTION');
+  assert.match(problems[0] ?? '', /not in the severity map/);
+});
+
+test('a repository override changes the mapping', () => {
+  assert.equal(mapSeverity('warning', { warning: 'BLOCKER' }).severity, 'BLOCKER');
+});
+
+test('an alert with no location is still a finding', () => {
+  const { findings } = ingestAlerts([alert({ most_recent_instance: undefined })]);
+
+  assert.equal(findings[0]?.file, null);
+  assert.equal(findings[0]?.line, null);
+});
+
+const finding = (over = {}) => ({
+  source: 'sarif',
+  tool: 'CodeQL',
+  ruleId: 'js/x',
+  severity: 'BLOCKER',
+  acted: false,
+  ...over,
+});
+
+test('the two sources are aggregated apart and never merged', () => {
+  // The single way this piece can make things worse: tuning Redline's rules on
+  // another tool's noise.
+  const agg = aggregateBySource([
+    finding(),
+    finding({ acted: true }),
+    finding({ source: 'redline', tool: 'redline', ruleId: 'core/hardcoded-secrets', acted: true }),
+  ]);
+
+  assert.equal(agg.sarif.total, 2);
+  assert.equal(agg.redline.total, 1);
+  assert.deepEqual(Object.keys(agg.redline.byRule), ['core/hardcoded-secrets']);
+  assert.deepEqual(Object.keys(agg.sarif.byRule), ['js/x']);
+});
+
+test('acted-on rate is computed within each source, never across them', () => {
+  // Redline's "acted on" is a resolved review thread; a scanner's is a closed
+  // alert. Averaging two different definitions describes neither.
+  const agg = aggregateBySource([
+    finding({ acted: true }),
+    finding({ acted: false }),
+    finding({ source: 'redline', acted: true }),
+  ]);
+
+  assert.equal(agg.sarif.actedRate, 0.5);
+  assert.equal(agg.redline.actedRate, 1);
+});
+
+test('a source with nothing in it has a null rate, not a zero one', () => {
+  const agg = aggregateBySource([finding()]);
+
+  assert.equal(agg.redline.total, 0);
+  assert.equal(agg.redline.actedRate, null);
+});
+
+test('a finding with an unknown source is ignored rather than miscounted', () => {
+  const agg = aggregateBySource([finding({ source: 'somewhere-else' })]);
+
+  assert.equal(agg.sarif.total, 0);
+  assert.equal(agg.redline.total, 0);
+});
+
+test('per-tool counts survive aggregation, so one noisy scanner is identifiable', () => {
+  const agg = aggregateBySource([finding(), finding({ tool: 'Semgrep' }), finding({ tool: 'Semgrep' })]);
+
+  assert.deepEqual(agg.sarif.byTool, { CodeQL: 1, Semgrep: 2 });
+});

package/scripts/lib/__tests__/spend.test.mjs

@@ -0,0 +1,64 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { costPerBlocker, readSpend } from '../spend.mjs';
+
+test('a supplied figure carries its grain and its source', () => {
+  const spend = readSpend({ total: 1200, currency: 'GBP', grain: 'org', source: 'vendor console' });
+
+  assert.equal(spend.available, true);
+  assert.equal(spend.grain, 'org');
+  assert.equal(spend.currency, 'GBP');
+  assert.equal(spend.source, 'vendor console');
+});
+
+test('an unrecognised grain becomes "unknown" rather than being trusted', () => {
+  assert.equal(readSpend({ total: 10, grain: 'per-seat' }).grain, 'unknown');
+});
+
+test('no figure is unavailable with a reason, never zero', () => {
+  const spend = readSpend(null);
+
+  assert.equal(spend.available, false);
+  assert.match(spend.reason, /usage reporting/);
+});
+
+test('a negative figure is refused', () => {
+  assert.equal(readSpend({ total: -5 }).available, false);
+});
+
+test('cost per BLOCKER divides spend by what was actually caught', () => {
+  const result = costPerBlocker(readSpend({ total: 400, grain: 'org' }), 20);
+
+  assert.equal(result.value, 20);
+  assert.equal(result.blockersCaught, 20);
+});
+
+test('no BLOCKERs is a refusal, not an infinity', () => {
+  const result = costPerBlocker(readSpend({ total: 400, grain: 'org' }), 0);
+
+  assert.equal(result.value, null);
+  assert.match(result.reason, /nothing to divide by/);
+});
+
+test('an org-level figure cannot answer a per-repository question', () => {
+  // The failure this prevents: org spend divided by repo count, presented as
+  // per-repository cost. It looks precise, is invented, and is the number a
+  // stakeholder will act on.
+  const result = costPerBlocker(readSpend({ total: 400, grain: 'org' }), 20, { scope: 'repo' });
+
+  assert.equal(result.value, null);
+  assert.match(result.reason, /cannot be attributed per repository/);
+  assert.match(result.reason, /org-level figure against org-level value/);
+});
+
+test('a per-repo figure answers a per-repo question', () => {
+  const result = costPerBlocker(readSpend({ total: 40, grain: 'repo' }), 4, { scope: 'repo' });
+
+  assert.equal(result.value, 10);
+});
+
+test('missing spend propagates its own reason rather than a generic one', () => {
+  const result = costPerBlocker(readSpend(null), 20);
+
+  assert.match(result.reason, /usage reporting/);
+});

package/scripts/lib/baseline.mjs

@@ -0,0 +1,156 @@
+// Computes the Phase 0 baseline the roadmap's acceptance criteria name.
+//
+// The rule this module exists to enforce: an unavailable figure is `null` with a
+// stated reason, never `0`. A baseline is the number every later phase is judged
+// against, and a zero that actually means "nobody measured this" is worse than a
+// gap — it reads as a finding, and it makes every later comparison look like
+// progress that did not happen.
+
+/** A measured figure, or an honest absence. */
+export const measured = (value) => ({ value, available: true });
+export const unavailable = (reason) => ({ value: null, available: false, reason });
+
+const rate = (numerator, denominator) =>
+  denominator > 0 ? measured(numerator / denominator) : unavailable('nothing to divide — no findings in the window');
+
+/**
+ * The baseline, from data already collected plus whatever the caller could read.
+ *
+ * @param {object} input
+ * @param {object} input.aggregate      output of metrics.aggregate over the window
+ * @param {number} input.windowDays     how many days the window covers
+ * @param {object|null} input.registry  the derived register, or null if unreadable
+ * @param {object[]|null} input.ownPullRequests  Redline's own PRs on the estate, or null
+ * @param {object|null} input.sarifProducers     {repo: [tool]} or null if not surveyed
+ * @param {object|null} input.spend              {total, currency, grain} or null
+ */
+export function buildBaseline(input) {
+  const {
+    aggregate: agg,
+    windowDays,
+    registry = null,
+    ownPullRequests = null,
+    sarifProducers = null,
+    spend = null,
+  } = input;
+
+  const findings = agg.findings ?? 0;
+  const resolved = agg.resolved ?? 0;
+  const blocker = agg.blocker ?? 0;
+
+  // The primary metric. Acted-on is resolved over fired — the same definition the
+  // dashboard and the digest use, deliberately: three numbers called "acted-on
+  // rate" that disagree is how a programme loses an argument it was winning.
+  const actedOnRate = rate(resolved, findings);
+
+  const coverage = registry
+    ? measured(registry.entries?.length ?? 0)
+    : unavailable('registry.json could not be read — run the Redline Registry workflow');
+
+  const instrumented = agg.repos ?? 0;
+  const onboarded = coverage.available ? coverage.value : null;
+
+  const ownMergeRate =
+    ownPullRequests === null
+      ? unavailable('Redline\'s own pull requests were not surveyed — needs org read access')
+      : ownPullRequests.length === 0
+        ? unavailable('Redline has opened no pull requests on the estate yet')
+        : measured(ownPullRequests.filter((pr) => pr.merged).length / ownPullRequests.length);
+
+  const sarif =
+    sarifProducers === null
+      ? unavailable('no SARIF survey was run — open question 1 in the roadmap is unanswered')
+      : measured(
+          Object.entries(sarifProducers).reduce((acc, [, tools]) => {
+            for (const tool of tools) acc[tool] = (acc[tool] ?? 0) + 1;
+            return acc;
+          }, {})
+        );
+
+  const tokenSpend =
+    spend === null
+      ? unavailable('AI vendor usage reporting was not read — open question 2 is unanswered')
+      : measured(spend);
+
+  return {
+    generatedAt: new Date().toISOString(),
+    windowDays,
+
+    // --- the primary metric and its guardrails, per roadmap §3 ---------------
+    primary: { actedOnRate },
+    guardrails: {
+      coverage: {
+        onboarded: coverage,
+        instrumented: measured(instrumented),
+        // Instrumented-against-onboarded, so partial coverage cannot read as
+        // health. Absent rather than 1.0 when the register is unreadable.
+        ratio:
+          onboarded === null
+            ? unavailable('onboarded count unavailable, so the ratio has no denominator')
+            : onboarded === 0
+              ? unavailable('no repositories are onboarded — the ratio has no meaning yet')
+              : measured(instrumented / onboarded),
+      },
+      ownPullRequestMergeRate: ownMergeRate,
+      falsePositivesOnCleanCorpus: unavailable(
+        'read from data/seed-scores.jsonl by the canary — not derivable from merged-PR telemetry'
+      ),
+      standingExemptions: measured(agg.exempted ?? 0),
+    },
+
+    // --- the rest of Phase 0's acceptance list -------------------------------
+    findings: {
+      total: measured(findings),
+      blocker: measured(blocker),
+      perWeek: measured(windowDays > 0 ? (findings / windowDays) * 7 : 0),
+      untagged: measured(agg.untagged ?? 0),
+    },
+    sarifProducers: sarif,
+    tokenSpend,
+
+    // The number D exists to produce. It needs both halves, and says which one
+    // is missing rather than dividing by an assumption.
+    costPerBlockerCaught:
+      !tokenSpend.available
+        ? unavailable(`spend unavailable: ${tokenSpend.reason}`)
+        : blocker === 0
+          ? unavailable('no BLOCKER findings in the window — nothing to divide by')
+          : measured(tokenSpend.value.total / blocker),
+  };
+}
+
+/** A readable summary. Every absent figure prints its reason, not a dash. */
+export function formatBaseline(baseline) {
+  const lines = [`Redline baseline — ${baseline.generatedAt} (${baseline.windowDays}-day window)`, ''];
+  const show = (label, figure, format = (v) => String(v)) => {
+    lines.push(
+      figure.available
+        ? `  ${label.padEnd(34)} ${format(figure.value)}`
+        : `  ${label.padEnd(34)} not available — ${figure.reason}`
+    );
+  };
+  const pct = (v) => `${(v * 100).toFixed(1)}%`;
+
+  lines.push('PRIMARY');
+  show('BLOCKER acted-on rate', baseline.primary.actedOnRate, pct);
+  lines.push('', 'GUARDRAILS');
+  show('repositories onboarded', baseline.guardrails.coverage.onboarded);
+  show('repositories instrumented', baseline.guardrails.coverage.instrumented);
+  show('coverage', baseline.guardrails.coverage.ratio, pct);
+  show('merge rate on Redline\'s own PRs', baseline.guardrails.ownPullRequestMergeRate, pct);
+  show('false positives (clean corpus)', baseline.guardrails.falsePositivesOnCleanCorpus);
+  show('standing exemptions', baseline.guardrails.standingExemptions);
+  lines.push('', 'VOLUME');
+  show('findings in window', baseline.findings.total);
+  show('BLOCKER findings', baseline.findings.blocker);
+  show('findings per week', baseline.findings.perWeek, (v) => v.toFixed(1));
+  show('untagged findings', baseline.findings.untagged);
+  lines.push('', 'COST');
+  show('SARIF producers in use', baseline.sarifProducers, (v) =>
+    Object.entries(v).map(([tool, n]) => `${tool} (${n})`).join(', ') || 'none found'
+  );
+  show('AI spend', baseline.tokenSpend, (v) => `${v.total} ${v.currency} (${v.grain})`);
+  show('cost per BLOCKER caught', baseline.costPerBlockerCaught, (v) => v.toFixed(2));
+
+  return lines.join('\n');
+}

package/scripts/lib/correlate.mjs

@@ -0,0 +1,125 @@
+// Does ignoring a finding cost anything?
+//
+// Redline can already say a rule was ignored. It cannot say ignoring it mattered.
+// Where a finding was left unresolved and the same file later attracted a revert
+// or a hotfix, that is *evidence* the rule earns its place — computable from
+// merged-pull-request history alone, with no incident feed, which is what keeps
+// it inside the non-goals.
+//
+// THIS IS RESEARCH, and the roadmap says to cut it without regret if the signal
+// is too weak. So the design decision that matters here is not the correlation —
+// it is the refusal. This module reports a rate only when the sample supports one,
+// and returns `reportable: false` with the reason otherwise. A correlation quoted
+// without its sample size is how a plausible story becomes a policy nobody can
+// unwind, and the honest output of a weak experiment is "we cannot say".
+
+const DAY = 86400000;
+
+// Below this many ignored findings for a rule, no rate is reported for it. Ten is
+// not a statistical threshold — it is the point below which a single coincidence
+// moves the number by ten percentage points, which is enough to mislead.
+export const MIN_SAMPLE = 10;
+
+const REVERT = /^revert[\s:"']|^revert\b/i;
+const HOTFIX = /\b(hotfix|hot-fix)\b/i;
+
+const isRemediation = (record) => REVERT.test(record.title ?? '') || HOTFIX.test(record.title ?? '');
+
+/**
+ * Files a pull request's ignored findings touched, per rule.
+ *
+ * A record carries per-rule counts, not per-file findings, so file attribution is
+ * only available where the collector recorded it. Where it is not, the pull
+ * request contributes to the totals and not to the correlation — counted as
+ * unattributable rather than quietly dropped, because a correlation computed over
+ * whichever records happened to have the field is not a correlation.
+ */
+export function correlate(records, { windowDays = 30, minSample = MIN_SAMPLE } = {}) {
+  const byRepo = new Map();
+  for (const record of records ?? []) {
+    if (!record.merged_at) continue;
+    if (!byRepo.has(record.repo)) byRepo.set(record.repo, []);
+    byRepo.get(record.repo).push(record);
+  }
+  for (const list of byRepo.values()) {
+    list.sort((a, b) => Date.parse(a.merged_at) - Date.parse(b.merged_at));
+  }
+
+  const perRule = new Map();
+  let unattributable = 0;
+
+  for (const [, list] of byRepo) {
+    for (let i = 0; i < list.length; i += 1) {
+      const record = list[i];
+      const at = Date.parse(record.merged_at);
+      const followedByRemediation = list
+        .slice(i + 1)
+        .some((later) => {
+          const gap = Date.parse(later.merged_at) - at;
+          return gap >= 0 && gap <= windowDays * DAY && isRemediation(later);
+        });
+
+      for (const [ruleId, stats] of Object.entries(record.rules ?? {})) {
+        const ignored = stats.stale ?? 0;
+        if (ignored === 0) continue;
+        // A remediation's own findings are not evidence about the change it
+        // remedied. Counting them would let one incident inflate every rule that
+        // happened to fire on the fix.
+        if (isRemediation(record)) {
+          unattributable += ignored;
+          continue;
+        }
+        const entry = perRule.get(ruleId) ?? { ruleId, ignored: 0, followedByRemediation: 0, severity: stats.severity };
+        entry.ignored += ignored;
+        if (followedByRemediation) entry.followedByRemediation += ignored;
+        perRule.set(ruleId, entry);
+      }
+    }
+  }
+
+  const rules = [...perRule.values()]
+    .map((entry) => ({
+      ...entry,
+      // Reported ONLY where the sample supports it. Below the threshold the rate
+      // exists arithmetically and means nothing, and publishing it anyway is how
+      // a coincidence becomes a rule nobody can argue with.
+      rate: entry.ignored >= minSample ? entry.followedByRemediation / entry.ignored : null,
+      reportable: entry.ignored >= minSample,
+      reason:
+        entry.ignored >= minSample
+          ? null
+          : `${entry.ignored} ignored finding(s); at least ${minSample} are needed before a rate means anything`,
+    }))
+    .sort((a, b) => (b.rate ?? -1) - (a.rate ?? -1) || b.ignored - a.ignored);
+
+  const reportable = rules.filter((r) => r.reportable);
+  const totalIgnored = rules.reduce((n, r) => n + r.ignored, 0);
+
+  return {
+    windowDays,
+    minSample,
+    rules,
+    unattributable,
+    // The verdict on the experiment itself, not on any one rule. The roadmap
+    // asks for the correlation "with its confidence, or the work abandoned and
+    // said so" — this is that sentence, computed rather than written.
+    verdict:
+      reportable.length === 0
+        ? {
+            reportable: false,
+            reason:
+              totalIgnored === 0
+                ? 'no findings were ignored in this window, so there is nothing to correlate — which is a good result, not a failed experiment'
+                : `no rule reached ${minSample} ignored findings. The signal is too weak to report, and reporting it anyway would turn a coincidence into a policy nobody can unwind.`,
+          }
+        : {
+            reportable: true,
+            rulesReported: reportable.length,
+            rulesWithheld: rules.length - reportable.length,
+            caveat:
+              'Correlation, not causation, and a weak one: a revert near an ignored finding is ' +
+              'evidence the rule earns its place, never proof the finding caused the revert. ' +
+              'Use it to prioritise which rules to examine, never to justify a rule on its own.',
+          },
+  };
+}