mandrel 1.57.0

package/.agents/scripts/lib/mutation/survivor-report.js

@@ -0,0 +1,160 @@
+/**
+ * lib/mutation/survivor-report.js — enumerate actionable surviving mutants
+ * from a Stryker JSON report (Story #3428).
+ *
+ * The mutation gate (`stryker-runner.js` → `summariseReport`) collapses the
+ * report into a single score. That score tells you *whether* the suite is
+ * leaky, not *where*. This helper does the complementary job: it walks the
+ * same `files[].mutants[].status` surface and enumerates the mutants that
+ * the suite failed to kill — `Survived` (a mutation that the tests ran over
+ * but never caught) and `NoCoverage` (a mutation in a line no test exercises
+ * at all) — grouped per file so the survivor-kill loop has concrete targets.
+ *
+ * It is **pure**: no network, no child process, no filesystem reads. The
+ * caller hands in an already-parsed report object (the same JSON that
+ * `stryker-runner.js` reads from `reports/mutation/mutation.json`). This
+ * keeps the helper trivially unit-testable with inline fixtures and lets
+ * remediation tooling reuse a report it already loaded for scoring.
+ *
+ * Output contract:
+ *
+ *   {
+ *     ok: true,
+ *     totals: { survived, noCoverage, actionable, files },
+ *     files: [
+ *       {
+ *         file: "src/a.js",
+ *         survived: [{ id, line, mutatorName, status, ... }],
+ *         noCoverage: [{ ... }],
+ *         count: <survived.length + noCoverage.length>,
+ *       },
+ *       ...
+ *     ],
+ *   }
+ *   { ok: false, error: <string> }
+ *
+ * Files with no actionable survivors are omitted from `files`. The `files`
+ * array is sorted by descending actionable count (worst offenders first),
+ * ties broken by file path for stable output.
+ */
+
+/** Mutant statuses this helper treats as actionable survivors. */
+export const ACTIONABLE_STATUSES = Object.freeze(['Survived', 'NoCoverage']);
+
+/**
+ * Fields copied verbatim from each Stryker mutant onto the enumerated
+ * survivor record. We deliberately keep a fixed allowlist (rather than
+ * spreading the raw mutant) so the output shape is stable and never leaks
+ * unexpected report internals.
+ */
+const MUTANT_FIELDS = Object.freeze([
+  'id',
+  'mutatorName',
+  'status',
+  'location',
+  'replacement',
+]);
+
+/**
+ * Pure: enumerate `Survived` and `NoCoverage` mutants per file from a
+ * parsed Stryker mutation report.
+ *
+ * @param {unknown} report Parsed Stryker JSON report (an object with a
+ *   top-level `files` map). Passing the raw JSON string is **not**
+ *   supported — parse it first (mirrors `summariseReport`).
+ * @returns {(
+ *   { ok: true, totals: { survived: number, noCoverage: number, actionable: number, files: number }, files: Array<{ file: string, survived: object[], noCoverage: object[], count: number }> }
+ *   | { ok: false, error: string }
+ * )}
+ */
+export function enumerateSurvivors(report) {
+  if (!report || typeof report !== 'object' || Array.isArray(report)) {
+    return { ok: false, error: 'Stryker report must be a JSON object' };
+  }
+
+  const files = /** @type {Record<string, unknown> | undefined} */ (
+    /** @type {Record<string, unknown>} */ (report).files
+  );
+  if (!files || typeof files !== 'object' || Array.isArray(files)) {
+    return { ok: false, error: "Stryker report missing 'files' map" };
+  }
+
+  const perFile = [];
+  let survivedTotal = 0;
+  let noCoverageTotal = 0;
+
+  for (const [filePath, entry] of Object.entries(files)) {
+    if (!entry || typeof entry !== 'object') continue;
+    const mutants = /** @type {{ mutants?: unknown }} */ (entry).mutants;
+    if (!Array.isArray(mutants)) continue;
+
+    const survived = [];
+    const noCoverage = [];
+    for (const mutant of mutants) {
+      if (!mutant || typeof mutant !== 'object') continue;
+      const status = /** @type {{ status?: unknown }} */ (mutant).status;
+      if (status === 'Survived') {
+        survived.push(pickMutant(mutant));
+      } else if (status === 'NoCoverage') {
+        noCoverage.push(pickMutant(mutant));
+      }
+    }
+
+    if (survived.length === 0 && noCoverage.length === 0) continue;
+
+    survivedTotal += survived.length;
+    noCoverageTotal += noCoverage.length;
+    perFile.push({
+      file: filePath,
+      survived,
+      noCoverage,
+      count: survived.length + noCoverage.length,
+    });
+  }
+
+  perFile.sort((a, b) => b.count - a.count || a.file.localeCompare(b.file));
+
+  return {
+    ok: true,
+    totals: {
+      survived: survivedTotal,
+      noCoverage: noCoverageTotal,
+      actionable: survivedTotal + noCoverageTotal,
+      files: perFile.length,
+    },
+    files: perFile,
+  };
+}
+
+/**
+ * Copy the stable allowlist of fields off a raw Stryker mutant. The `line`
+ * convenience field is derived from `location.start.line` when present so
+ * callers can sort/print without re-walking the nested location shape.
+ *
+ * @param {Record<string, unknown>} mutant
+ * @returns {Record<string, unknown>}
+ */
+function pickMutant(mutant) {
+  const out = {};
+  for (const field of MUTANT_FIELDS) {
+    if (mutant[field] !== undefined) out[field] = mutant[field];
+  }
+  const line = extractLine(mutant.location);
+  if (line !== null) out.line = line;
+  return out;
+}
+
+/**
+ * Pull the 1-based start line out of a Stryker `location` object, or null
+ * when the shape is missing or malformed.
+ *
+ * @param {unknown} location
+ * @returns {number | null}
+ */
+function extractLine(location) {
+  if (!location || typeof location !== 'object') return null;
+  const start = /** @type {{ start?: unknown }} */ (location).start;
+  if (!start || typeof start !== 'object') return null;
+  const line = /** @type {{ line?: unknown }} */ (start).line;
+  return typeof line === 'number' && Number.isFinite(line) ? line : null;
+}

package/.agents/scripts/lib/notifications/notifier.js

@@ -0,0 +1,75 @@
+/**
+ * Notification helpers — shared severity vocabulary and webhook URL resolver.
+ *
+ * The unified `notify()` API in `notify.js` is the single dispatch entry
+ * point for two event-allowlist-gated channels: GitHub comments
+ * (`notifications.commentEvents`) and the Slack webhook
+ * (`notifications.webhookEvents`). Both channels filter independently by
+ * event-name membership — there is no fallback chain and severity is no
+ * longer a routing factor for either channel.
+ *
+ * Severity vocabulary: low | medium | high. Severity is carried as
+ * envelope metadata so Slack consumers can color-code by it and so
+ * high-severity comments still `@mention` the operator, but it does not
+ * gate channel delivery.
+ *   - low    — routine pipeline progress: task transitions, story-run
+ *              progress upserts. `transitionTicketState` skips the
+ *              `notify()` dispatch entirely for these so the comment
+ *              channel never sees them.
+ *   - medium — operator-visible milestones: story / epic → done
+ *              transitions, story-merged, epic milestones.
+ *   - high   — operator must act: epic blockers, HITL gates,
+ *              autonomous-chain failures. Webhook envelope prefix is
+ *              `[Action Required]`; high-severity comments always
+ *              `@mention` the operator.
+ *
+ * Webhook URL resolution: `process.env.NOTIFICATION_WEBHOOK_URL` only —
+ * loaded from `.env` locally, the Claude Code web environment-variables UI,
+ * or `ENV_FILE` on GitHub Actions. The webhook URL is never read from
+ * `.agentrc.json` and (as of Epic #702) is no longer sourced from
+ * `.mcp.json`.
+ */
+
+import { AGENT_LABELS } from '../label-constants.js';
+
+export const SEVERITY_RANK = Object.freeze({ low: 0, medium: 1, high: 2 });
+
+/**
+ * Compute the severity of a ticket-state-transition event.
+ *
+ * Today only Story or Epic tickets reaching `agent::done` rate `medium`;
+ * every other transition (intermediate or task-level) is `low`. State-
+ * transition events never reach `high` — that level is reserved for
+ * explicit `notify()` calls signalling operator action is required.
+ *
+ * @param {{ kind?: string, ticket?: { type?: string }, toState?: string|null }} event
+ */
+export function eventSeverity(event) {
+  if (event?.kind === 'state-transition') {
+    const type = event.ticket?.type;
+    const isStoryOrEpic = type === 'story' || type === 'epic';
+    if (isStoryOrEpic && event.toState === AGENT_LABELS.DONE) return 'medium';
+  }
+  return 'low';
+}
+
+/**
+ * Render a state-transition event into a human-readable summary line used
+ * as both the GitHub comment body and the webhook message text.
+ */
+export function renderTransitionMessage(event) {
+  const type = event.ticket?.type ?? 'ticket';
+  const id = event.ticket?.id;
+  const title = event.ticket?.title ?? '';
+  const toState = event.toState ?? '';
+  const fromState = event.fromState ?? '';
+  let summary = fromState
+    ? `${type} #${id} · \`${fromState}\` → \`${toState}\``
+    : `${type} #${id} · → \`${toState}\``;
+  if (title) summary += ` — ${title.slice(0, 80)}`;
+  return summary;
+}
+
+export function resolveWebhookUrl() {
+  return process.env.NOTIFICATION_WEBHOOK_URL?.trim() || null;
+}

package/.agents/scripts/lib/observability/active-story-env.js

@@ -0,0 +1,182 @@
+/**
+ * Active-Story env-var propagation (Epic #1030 Story #1043 / Task #1061).
+ *
+ * The PreToolUse / PostToolUse trace hook in
+ * `lib/observability/tool-trace-hook.js` resolves the active Epic +
+ * Story from `process.env.CC_EPIC_ID` and `process.env.CC_STORY_ID`.
+ * This module is the single writer/clearer of those vars:
+ *
+ *   - `setActiveStoryEnv({ epicId, storyId, workCwd })` is called from
+ *     `story-init.js` after the worktree is materialised. It sets the
+ *     vars on the current `process.env` (so any child commands the
+ *     orchestrator spawns inherit them) and exports them to a sibling
+ *     `.env.local` inside the worktree. The harness re-spawns the
+ *     agent with that file's contents loaded, so the trace hook fires
+ *     with the right ids on the *next* tool call after init returns.
+ *
+ *   - `clearActiveStoryEnv({ workCwd })` is called from
+ *     `story-close/post-merge-close.js` after the merge lands. It
+ *     deletes the env vars from `process.env` and removes the
+ *     `.env.local` file. Tooling invoked outside an active Story —
+ *     planning, dispatch, ad-hoc CLI — must NOT pollute random
+ *     `traces.ndjson` files; the hook's no-op contract relies on the
+ *     vars being absent at that point.
+ *
+ * Both functions are best-effort and never throw on fs failures. The
+ * trace hook is itself best-effort, so a stale `.env.local` would at
+ * worst cause one extra trace line to land in a stale `temp/.../`
+ * directory — annoying but not a correctness bug. We log warnings via
+ * the caller's logger when provided.
+ */
+
+import nodeFs from 'node:fs';
+import nodePath from 'node:path';
+
+const ENV_LOCAL_BASENAME = '.env.local';
+
+/**
+ * Names of the env vars we own. Keeping the list central makes the
+ * round-trip (set on init, clear on close) trivially auditable —
+ * grep `CC_EPIC_ID` / `CC_STORY_ID` to find every read site.
+ */
+export const ACTIVE_STORY_ENV_KEYS = ['CC_EPIC_ID', 'CC_STORY_ID'];
+
+/**
+ * Render the `.env.local` body. One `KEY=value` line per var, LF
+ * line endings (the harness's dotenv parser tolerates CRLF too but LF
+ * keeps the file deterministic across Windows / macOS / Linux).
+ *
+ * Story #2874 — when `epicId === null` (standalone Story, no parent
+ * Epic), the `CC_EPIC_ID=` line is omitted entirely. The trace
+ * hook's no-op contract reads "var absent from env" as the signal,
+ * so emitting an empty `CC_EPIC_ID=` line would set the var to the
+ * empty string and change the contract.
+ *
+ * Exported for testing.
+ *
+ * @param {{ epicId: number|null, storyId: number }} input
+ * @returns {string}
+ */
+export function renderActiveStoryEnvFile({ epicId, storyId }) {
+  const lines = [
+    '# Auto-managed by .agents/scripts/lib/observability/active-story-env.js',
+    '# Re-generated on every story-init; deleted on story-close.',
+  ];
+  if (epicId !== null) lines.push(`CC_EPIC_ID=${epicId}`);
+  lines.push(`CC_STORY_ID=${storyId}`, '');
+  return lines.join('\n');
+}
+
+/**
+ * Set `CC_EPIC_ID` / `CC_STORY_ID` on the current process and (when
+ * `workCwd` is provided) export them to `<workCwd>/.env.local`.
+ *
+ * Idempotent: re-running with the same ids is a no-op on disk; with
+ * different ids the `.env.local` is overwritten.
+ *
+ * Story #2874 — `epicId: null` is the standalone-Story sentinel.
+ * When passed:
+ *   - `CC_EPIC_ID` is removed from `env` (the var MUST NOT be set
+ *     to an empty string — the trace hook's `resolveActiveStory`
+ *     no-op contract is keyed on the var's absence).
+ *   - The rendered `.env.local` omits the `CC_EPIC_ID=` line.
+ *   - `CC_STORY_ID` behaviour is unchanged.
+ * All other invalid `epicId` values (`0`, negative, NaN, non-integer)
+ * still throw — `null` is the only standalone signal.
+ *
+ * @param {{ epicId: number|null, storyId: number, workCwd?: string,
+ *           env?: NodeJS.ProcessEnv, fs?: typeof nodeFs,
+ *           logger?: { warn?: (m: string) => void } }} args
+ * @returns {{ envSet: boolean, fileWritten: boolean, filePath: string|null }}
+ */
+export function setActiveStoryEnv({
+  epicId,
+  storyId,
+  workCwd,
+  env = process.env,
+  fs = nodeFs,
+  logger,
+} = {}) {
+  if (epicId !== null && (!Number.isInteger(epicId) || epicId <= 0)) {
+    throw new Error(
+      `[active-story-env] epicId must be a positive integer or null; got ${epicId}`,
+    );
+  }
+  if (!Number.isInteger(storyId) || storyId <= 0) {
+    throw new Error(
+      `[active-story-env] storyId must be a positive integer; got ${storyId}`,
+    );
+  }
+
+  if (epicId === null) {
+    // Standalone Story — ensure CC_EPIC_ID is absent so the trace
+    // hook's no-op contract sees "no epic" rather than "epic=''".
+    if ('CC_EPIC_ID' in env) delete env.CC_EPIC_ID;
+  } else {
+    env.CC_EPIC_ID = String(epicId);
+  }
+  env.CC_STORY_ID = String(storyId);
+
+  let fileWritten = false;
+  let filePath = null;
+  if (typeof workCwd === 'string' && workCwd.length > 0) {
+    filePath = nodePath.join(workCwd, ENV_LOCAL_BASENAME);
+    try {
+      fs.writeFileSync(
+        filePath,
+        renderActiveStoryEnvFile({ epicId, storyId }),
+        {
+          encoding: 'utf8',
+        },
+      );
+      fileWritten = true;
+    } catch (err) {
+      logger?.warn?.(
+        `[active-story-env] Failed to write ${filePath}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  }
+  return { envSet: true, fileWritten, filePath };
+}
+
+/**
+ * Delete `CC_EPIC_ID` / `CC_STORY_ID` from the current process env and
+ * remove `<workCwd>/.env.local` when present. Best-effort; a missing
+ * file is not an error.
+ *
+ * @param {{ workCwd?: string, env?: NodeJS.ProcessEnv,
+ *           fs?: typeof nodeFs,
+ *           logger?: { warn?: (m: string) => void } }} args
+ * @returns {{ envCleared: boolean, fileRemoved: boolean, filePath: string|null }}
+ */
+export function clearActiveStoryEnv({
+  workCwd,
+  env = process.env,
+  fs = nodeFs,
+  logger,
+} = {}) {
+  for (const k of ACTIVE_STORY_ENV_KEYS) {
+    if (k in env) delete env[k];
+  }
+
+  let fileRemoved = false;
+  let filePath = null;
+  if (typeof workCwd === 'string' && workCwd.length > 0) {
+    filePath = nodePath.join(workCwd, ENV_LOCAL_BASENAME);
+    try {
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+        fileRemoved = true;
+      }
+    } catch (err) {
+      logger?.warn?.(
+        `[active-story-env] Failed to remove ${filePath}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  }
+  return { envCleared: true, fileRemoved, filePath };
+}

package/.agents/scripts/lib/observability/baseline-refresh-rate.js

@@ -0,0 +1,221 @@
+/**
+ * baseline-refresh-rate.js — pure reporter for the per-Epic baseline-refresh
+ * commit rate (Epic #1386, Story #1400).
+ *
+ * The "baseline-refresh discipline" (Story #1124, Tech Spec #902) requires
+ * that every Story whose merge introduces baseline drift land an explicit
+ * `baseline-refresh:` commit in the same close PR (or, post Story #1398,
+ * fold the refresh into the close commit itself). The 90% target — that
+ * at least 90% of merged Stories per Epic land without leaving baseline
+ * drift behind — needs a measurable signal so retros can spot regressions
+ * before they leak into `main`.
+ *
+ * This module exports a single pure function that takes a fixture of
+ * commit records (one per Story-attributable commit on `epic/<id>` over
+ * the trailing window) and returns:
+ *
+ *   - per-Epic counts of `baseline-refresh:` commits
+ *   - per-Epic counts of merged Stories
+ *   - per-Epic percentage of merged Stories that did NOT land a
+ *     baseline-refresh commit (the "clean-merge" rate)
+ *
+ * The caller (analyze-execution.js) is responsible for shelling out to
+ * `git log` and resolving each commit to its parent Epic ID — this
+ * module touches no I/O so the test fixture can pin behavior without a
+ * temp git repo or stubbed spawn.
+ *
+ * Default window is 4 weeks (28 days). Pass `windowDays` to override
+ * (e.g., `windowDays: 14` for a fortnightly retro).
+ *
+ * Aligned with `perf-aggregator.js`: empty input yields a well-formed
+ * empty payload, malformed records are silently skipped, the function
+ * never throws on bad data.
+ */
+
+import { isObject } from '../json-utils.js';
+import { RESOLVES_TRAILER_RE } from '../orchestration/resolves-token.js';
+
+const BASELINE_REFRESH_PREFIX = 'baseline-refresh:';
+const DEFAULT_WINDOW_DAYS = 28;
+
+/**
+ * Coerce an ISO-8601 date string to epoch ms. Returns NaN for malformed
+ * input so the caller's window filter drops the record.
+ */
+function toEpochMs(iso) {
+  if (typeof iso !== 'string' || iso.length === 0) return Number.NaN;
+  const ms = Date.parse(iso);
+  return Number.isFinite(ms) ? ms : Number.NaN;
+}
+
+/**
+ * Classify a commit by its subject line.
+ *
+ *   - `baseline-refresh:` prefix → refresh commit
+ *   - subject containing `(resolves #N)` → Story-merge commit
+ *   - everything else → ignored (chore commits, baseline-only fixes, etc.)
+ *
+ * The classification is deliberately disjoint: a `baseline-refresh:`
+ * commit is never counted as a Story merge, and a Story merge is never
+ * counted as a baseline-refresh — even if the subject happens to mention
+ * both keywords. This matches the on-the-ground convention: refreshes
+ * land as their own commit (or amended into the close), Stories land as
+ * `feat: ... (resolves #N)`.
+ */
+function classifySubject(subject) {
+  if (typeof subject !== 'string' || subject.length === 0) return 'other';
+  if (subject.startsWith(BASELINE_REFRESH_PREFIX)) return 'refresh';
+  if (RESOLVES_TRAILER_RE.test(subject)) return 'story';
+  return 'other';
+}
+
+/**
+ * Compute the trailing-window cutoff in epoch ms. Exported on the
+ * exported function via the `now` option so tests can pin the clock.
+ */
+function computeCutoffMs(nowMs, windowDays) {
+  const days =
+    Number.isFinite(windowDays) && windowDays > 0
+      ? windowDays
+      : DEFAULT_WINDOW_DAYS;
+  return nowMs - days * 24 * 60 * 60 * 1000;
+}
+
+/**
+ * Pure reporter for the per-Epic baseline-refresh commit rate.
+ *
+ * @param {Iterable<{
+ *   sha?: string,
+ *   isoDate: string,
+ *   subject: string,
+ *   epicId: number | string | null,
+ * }>} commits
+ *   Commit records from the caller. Records missing `epicId` (the commit
+ *   isn't on any Epic branch) are dropped. Records older than the window
+ *   are also dropped. Order does not matter — the function aggregates by
+ *   Epic regardless of input ordering.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.windowDays] — trailing window in days (default 28).
+ * @param {() => Date | number} [opts.now] — clock injector for tests.
+ *   Accepts either a Date or epoch-ms; defaults to `() => Date.now()`.
+ *
+ * @returns {{
+ *   kind: 'baseline-refresh-rate',
+ *   windowDays: number,
+ *   generatedAt: string,
+ *   cutoffAt: string,
+ *   perEpic: Array<{
+ *     epicId: number | string,
+ *     storyMerges: number,
+ *     baselineRefreshes: number,
+ *     cleanMergeRate: number,
+ *   }>,
+ *   totals: {
+ *     storyMerges: number,
+ *     baselineRefreshes: number,
+ *     cleanMergeRate: number,
+ *   },
+ * }}
+ *
+ * `cleanMergeRate` is the fraction of merged Stories that did NOT need a
+ * baseline-refresh commit follow-up (or amend), in `[0, 1]` rounded to
+ * 4 decimal places. The 90% target is `cleanMergeRate >= 0.9`. When
+ * `storyMerges === 0`, the rate is `1` (vacuously clean — no Stories,
+ * no drift) so a quiet Epic doesn't show up as red.
+ */
+export function computeBaselineRefreshRate(commits, opts = {}) {
+  const nowFn = opts.now ?? (() => Date.now());
+  const nowVal = nowFn();
+  const nowMs = nowVal instanceof Date ? nowVal.getTime() : Number(nowVal);
+  const windowDays =
+    Number.isFinite(opts.windowDays) && opts.windowDays > 0
+      ? Math.floor(opts.windowDays)
+      : DEFAULT_WINDOW_DAYS;
+  const cutoffMs = computeCutoffMs(nowMs, windowDays);
+
+  // Map<epicId, { storyMerges, baselineRefreshes }>. Insertion order is
+  // preserved so the output array is stable for snapshot-style assertions.
+  const perEpic = new Map();
+  const ensureBucket = (epicId) => {
+    if (!perEpic.has(epicId)) {
+      perEpic.set(epicId, { storyMerges: 0, baselineRefreshes: 0 });
+    }
+    return perEpic.get(epicId);
+  };
+
+  for (const raw of commits ?? []) {
+    if (!isObject(raw)) continue;
+    const epicId = raw.epicId;
+    if (epicId == null || epicId === '') continue;
+    const ts = toEpochMs(raw.isoDate);
+    if (!Number.isFinite(ts)) continue;
+    if (ts < cutoffMs) continue;
+
+    const klass = classifySubject(raw.subject);
+    if (klass === 'other') continue;
+
+    const bucket = ensureBucket(epicId);
+    if (klass === 'refresh') bucket.baselineRefreshes += 1;
+    else if (klass === 'story') bucket.storyMerges += 1;
+  }
+
+  const perEpicRows = [];
+  let totalStories = 0;
+  let totalRefreshes = 0;
+  for (const [epicId, counts] of perEpic) {
+    const cleanMergeRate =
+      counts.storyMerges === 0
+        ? 1
+        : Math.max(
+            0,
+            Math.min(
+              1,
+              (counts.storyMerges - counts.baselineRefreshes) /
+                counts.storyMerges,
+            ),
+          );
+    perEpicRows.push({
+      epicId,
+      storyMerges: counts.storyMerges,
+      baselineRefreshes: counts.baselineRefreshes,
+      cleanMergeRate: roundRate(cleanMergeRate),
+    });
+    totalStories += counts.storyMerges;
+    totalRefreshes += counts.baselineRefreshes;
+  }
+
+  const totalsClean =
+    totalStories === 0
+      ? 1
+      : Math.max(
+          0,
+          Math.min(1, (totalStories - totalRefreshes) / totalStories),
+        );
+
+  return {
+    kind: 'baseline-refresh-rate',
+    windowDays,
+    generatedAt: new Date(nowMs).toISOString(),
+    cutoffAt: new Date(cutoffMs).toISOString(),
+    perEpic: perEpicRows,
+    totals: {
+      storyMerges: totalStories,
+      baselineRefreshes: totalRefreshes,
+      cleanMergeRate: roundRate(totalsClean),
+    },
+  };
+}
+
+function roundRate(rate) {
+  if (!Number.isFinite(rate)) return 0;
+  return Math.round(rate * 10000) / 10000;
+}
+
+// Exported for unit tests that want to assert the classifier directly
+// without round-tripping through the aggregator.
+export const __test__ = {
+  classifySubject,
+  computeCutoffMs,
+  DEFAULT_WINDOW_DAYS,
+};