mandrel 2.32.0 → 2.34.0

package/.agents/scripts/lib/audit-to-stories/build-story-body.js

@@ -22,6 +22,7 @@
  * structured contract.
  */
 
+import path from 'node:path';
 import { AGENT_LABELS, RISK_LABELS, TYPE_LABELS } from '../label-constants.js';
 import { serialize } from '../story-body/story-body.js';
 import { definesAuditLabel } from './audit-label-taxonomy.js';
@@ -116,10 +117,7 @@ function acceptanceCriteriaFromGroup(group) {
 
 /**
  * Resolve the `edges[]` sequencing anchored on this group. Each edge whose
- * `fromGroupKey` matches this group's key contributes its `toGroupKey`. Group
- * keys are the only stable identifier available at emit time — issues are not
- * numbered yet — so the relationship is preserved as machine-readable keys the
- * operator can resolve.
+ * `fromGroupKey` matches this group's key contributes its `toGroupKey`.
  *
  * @param {object} group
  * @param {Array<{ fromGroupKey: string, toGroupKey: string }>} edges
@@ -135,22 +133,38 @@ function sequencingDepsForGroup(group, edges) {
 }
 
 /**
- * Render the carried-through `edges[]` sequencing as a dedicated extended
- * markdown block. The canonical `depends_on[]` footer only round-trips `#N`
- * issue refs (`blocked by #123`), which do not exist before the issues are
- * opened; rendering the group-key sequencing as its own informational section
- * keeps the signal in the body (not discarded — Story #4270) and survives
- * `parse()` / `serialize()` round-tripping (it is preamble/extended content,
- * not a structured section). Returns the empty string when there is no
- * sequencing to surface.
+ * Resolve this group's sequencing to canonical `#N` issue refs, or `[]` when
+ * the caller has no issue numbers yet (Story #5044).
  *
- * @param {string[]} deps
- * @returns {string}
+ * Group keys are the only identifier that exists at *emit* time — the issues
+ * are not numbered — which is why this used to render as a prose
+ * `## Sequencing` block that nothing could act on. Standalone audit Stories
+ * therefore hardcoded `depends_on: []`, and their only actual serializer was
+ * an accident: their shared provenance footers collided under the delivery
+ * footprint guard. Narrowing that scrape removes the accident, so the ordering
+ * has to become real in the same change.
+ *
+ * The resolution is the two-pass shape `plan-persist` already uses: create every
+ * issue first, then re-render each body with the now-known numbers and mirror
+ * the same edges as native `blocked_by` relations. An edge whose target was not
+ * created (deduped against an existing Issue, suppressed by the ledger) simply
+ * drops — a `blocked by #undefined` would be worse than an absent edge.
+ *
+ * A **plain object**, deliberately, not a `Map`: the same map is handed to
+ * `applyBlockedByDependencies`, which indexes it with property access, so a
+ * `Map` there would silently resolve every lookup to `undefined`, skip every
+ * edge, and report success having written nothing. One shape, both halves.
+ *
+ * @param {string[]} deps                     Group keys this group depends on.
+ * @param {Record<string, number>|null} issueByGroupKey
+ * @returns {string[]} `#N` refs, in `deps` order.
  */
-function sequencingSection(deps) {
-  if (deps.length === 0) return '';
-  const lines = deps.map((k) => `- depends on group \`${k}\``);
-  return ['## Sequencing', '', lines.join('\n'), ''].join('\n');
+function dependencyRefs(deps, issueByGroupKey) {
+  if (!issueByGroupKey) return [];
+  return deps
+    .map((key) => issueByGroupKey[key])
+    .filter((n) => Number.isInteger(n) && n > 0)
+    .map((n) => `#${n}`);
 }
 
 function agentPromptsSection(group) {
@@ -162,6 +176,21 @@ function agentPromptsSection(group) {
   return blocks.join('\n\n') || '_(no copy-pasteable prompts captured)_';
 }
 
+/**
+ * Link each source audit report **once**.
+ *
+ * This used to render `- [\`path\`](path)` — the same
+ * `temp/audits/audit-<lens>-results.md` in the link text and again in the URL,
+ * byte-identical across every Story of a same-lens sweep. That doubled a token
+ * the delivery footprint guard scraped as edit intent, so a lens's whole cohort
+ * serialized on a report none of them would ever write to (Story #5044). The
+ * guard now ignores markdown-link URLs and temp-root paths, but rendering the
+ * path twice was never useful to a reader either: the file name is the label,
+ * the path is the target.
+ *
+ * @param {object} group
+ * @returns {string}
+ */
 function contextLinksFromGroup(group) {
   const reports = uniq(
     (group.findings ?? [])
@@ -169,7 +198,11 @@ function contextLinksFromGroup(group) {
       .filter((s) => typeof s === 'string'),
   );
   if (reports.length === 0) return '_(no source audit reports captured)_';
-  return reports.map((r) => `- [\`${r}\`](${r})`).join('\n');
+  // `path.basename` rather than `split('/')`: on win32 it splits on both
+  // separators, so an absolute Windows path yields the file name instead of
+  // the whole path — which would render the path twice in one link and
+  // re-create the very duplication this function exists to remove.
+  return reports.map((r) => `- [${path.basename(r)}](${r})`).join('\n');
 }
 
 function labelsForGroup(group) {
@@ -226,20 +259,27 @@ function assertLabelsInTaxonomy(labels) {
  *   — the dependency `edges[]` emitted by `groupFindings`. Edges anchored on
  *   this group are carried through to `depends_on[]`; omit when no sequencing
  *   is known.
- * @returns {{ title: string, body: string, labels: string[] }}
+ * @param {Record<string, number>|null} [params.issueByGroupKey]
+ *   — group key → opened issue number. Supplied on the **second** pass, once
+ *   the issues exist, so this group's edges render as canonical
+ *   `blocked by #N` footers (Story #5044). Omit on the first pass.
+ * @returns {{ title: string, body: string, labels: string[], groupKey: string, dependsOn: string[] }}
+ *   `groupKey` and `dependsOn` are the caller's handle on the second pass:
+ *   they name this Story and the groups it must follow, so the caller can map
+ *   both onto issue numbers without re-deriving the grouping.
  */
-export function buildStoryBody({ group, edges = [] }) {
+export function buildStoryBody({ group, edges = [], issueByGroupKey = null }) {
   if (!group || !Array.isArray(group.findings)) {
     throw new Error('buildStoryBody: group with findings[] is required');
   }
   const title = group.title;
+  const dependsOn = sequencingDepsForGroup(group, edges);
 
   // Build the canonical StoryBody object from the audit group data. The
   // acceptance + verify arrays are populated so the body clears the
-  // inline-contract bar; changes[] carries the file footprint. The edges[]
-  // sequencing is carried through as an extended `## Sequencing` block (see
-  // sequencingSection) — group keys are not `#N` refs, so they cannot ride the
-  // canonical depends_on footer.
+  // inline-contract bar; changes[] carries the file footprint. `depends_on`
+  // is empty on the first pass (the blockers have no issue numbers yet) and
+  // carries real `#N` refs on the second — see dependencyRefs.
   const storyBody = {
     goal: goalFromGroup(group),
     changes: changesFromGroup(group),
@@ -248,20 +288,21 @@ export function buildStoryBody({ group, edges = [] }) {
     references: [],
     wide: null,
     reason_to_exist: null,
-    depends_on: [],
+    depends_on: dependencyRefs(dependsOn, issueByGroupKey),
   };
 
-  // Serialize via the canonical serializer (no footer — depends_on is empty).
-  const canonicalSections = serialize(storyBody);
-  const sequencing = sequencingSection(sequencingDepsForGroup(group, edges));
+  // The `---` / `blocked by #N` footer is the canonical serializer's own, so
+  // the body round-trips through `parse()` and `/deliver`'s resolver reads the
+  // ordering from the same place it reads every other Story's.
+  const canonicalSections = serialize(storyBody, {
+    includeFooter: storyBody.depends_on.length > 0,
+  });
 
-  // Append audit-specific extended sections (sequencing, agent prompts,
-  // context links, fingerprint footer) that are not part of the canonical
-  // shape.
+  // Append audit-specific extended sections (agent prompts, context links,
+  // provenance footers) that are not part of the canonical shape.
   const body = [
     canonicalSections,
     '',
-    ...(sequencing ? [sequencing] : []),
     '## Agent Prompts',
     '',
     agentPromptsSection(group),
@@ -276,5 +317,11 @@ export function buildStoryBody({ group, edges = [] }) {
     renderSemanticKeyFooter(group.findings),
   ].join('\n');
 
-  return { title, body, labels: labelsForGroup(group) };
+  return {
+    title,
+    body,
+    labels: labelsForGroup(group),
+    groupKey: group.groupKey,
+    dependsOn,
+  };
 }

package/.agents/scripts/lib/audit-to-stories/wire-dependencies.js

@@ -0,0 +1,185 @@
+/**
+ * lib/audit-to-stories/wire-dependencies.js — turn a standalone audit cohort's
+ * detected group edges into declared ordering, once the issues exist.
+ *
+ * `groupFindings` detects `edges[]` between finding groups, but at emit time
+ * the groups have no issue numbers, so the ordering could only be rendered as
+ * prose. Every standalone audit Story therefore shipped with `depends_on: []`,
+ * and what actually kept a cohort from being co-dispatched onto colliding
+ * branches was an **accident**: siblings shared the sweep-wide audit provenance
+ * footers `plan-persist` stamps, and the delivery footprint guard scraped
+ * path-shaped tokens out of them. Story #5044 narrows that scrape, which is why
+ * this module lands with it — removing the accidental serializer without giving
+ * the cohort a real one would leave it less ordered than before.
+ *
+ * The shape is `plan-persist`'s two-pass crossing (`plan-persist/story-ops.js`),
+ * because it is the same problem: **create every issue first, then mirror the
+ * edges**. Both halves are written:
+ *
+ *   1. The **body footer** (`---` / `blocked by #N`) — canonical, parsed by
+ *      `/deliver`'s resolver, and the fallback when the dependencies API is
+ *      unavailable.
+ *   2. The **native `blocked_by` relation** — visible in the GitHub UI,
+ *      readable without parsing markdown, and settable by an operator later.
+ *
+ * Native mirroring is **non-fatal by design**, matching `plan-persist`: the
+ * footer has already been written by the time it runs, so a dependencies API
+ * that says no costs visibility, not ordering.
+ *
+ * @module lib/audit-to-stories/wire-dependencies
+ */
+
+import { applyBlockedByDependencies } from '../../providers/github/blocked-by-add.js';
+import { Logger } from '../Logger.js';
+import { buildStoryBody } from './build-story-body.js';
+
+/**
+ * Re-render each created Story's body with its blockers resolved to `#N`, and
+ * mirror the same edges as native `blocked_by` relations.
+ *
+ * Groups whose issue was not created — deduped against an existing Issue,
+ * suppressed by the ledger, or simply not in `issueByGroupKey` — are skipped
+ * rather than guessed at, and an edge pointing at one drops with them
+ * (`dependencyRefs` filters it). A `blocked by #undefined` would gate a Story
+ * on nothing forever, which is strictly worse than the un-ordered cohort this
+ * replaces.
+ *
+ * @param {object} args
+ * @param {Array<object>} args.groups          The `create`-eligible groups, in
+ *   the order their issues were opened.
+ * @param {Array<{ fromGroupKey: string, toGroupKey: string }>} [args.edges]
+ * @param {Record<string, number>} args.issueByGroupKey  Group key → issue number.
+ * @param {(issueNumber: number, body: string) => Promise<unknown>} args.updateBody
+ *   Persist a re-rendered body. Injected so the caller owns the provider call.
+ * @param {object|null} [args.provider] Provider for native edge mirroring.
+ *   Omit (or pass one without the dependency ports) to write footers only.
+ * @returns {Promise<{
+ *   storiesWired: number,
+ *   bodiesUpdated: number,
+ *   edgesDeclared: number,
+ *   native: { edgesAdded: number, edgesSkipped: number, edgesFailed: number }|null
+ * }>}
+ */
+export async function wireAuditStoryEdges({
+  groups,
+  edges = [],
+  issueByGroupKey,
+  updateBody,
+  provider = null,
+}) {
+  const wired = collectWiredStories({ groups, edges, issueByGroupKey });
+  if (wired.length === 0) {
+    return {
+      storiesWired: 0,
+      bodiesUpdated: 0,
+      edgesDeclared: 0,
+      native: null,
+    };
+  }
+
+  let bodiesUpdated = 0;
+  for (const story of wired) {
+    await updateBody(story.issueNumber, story.body);
+    bodiesUpdated++;
+  }
+
+  return {
+    storiesWired: wired.length,
+    bodiesUpdated,
+    edgesDeclared: wired.reduce((n, s) => n + s.blockerKeys.length, 0),
+    native: await mirrorNativeEdges({ provider, wired, issueByGroupKey }),
+  };
+}
+
+/**
+ * Re-render every group that both has an issue **and** has at least one blocker
+ * whose issue also exists.
+ *
+ * A group with no resolvable blocker is deliberately left alone rather than
+ * rewritten to an identical body: an issue-body update is a mutation and a
+ * notification, and doing it for a no-op edit is noise on every Story of every
+ * sweep.
+ *
+ * @param {object} args
+ * @returns {Array<{ groupKey: string, issueNumber: number, body: string, blockerKeys: string[] }>}
+ */
+function collectWiredStories({ groups, edges, issueByGroupKey }) {
+  const wired = [];
+  for (const group of groups ?? []) {
+    const issueNumber = issueByGroupKey?.[group?.groupKey];
+    if (!Number.isInteger(issueNumber)) continue;
+    const rendered = buildStoryBody({ group, edges, issueByGroupKey });
+    const blockerKeys = rendered.dependsOn.filter((key) =>
+      Number.isInteger(issueByGroupKey[key]),
+    );
+    if (blockerKeys.length === 0) continue;
+    wired.push({
+      groupKey: rendered.groupKey,
+      issueNumber,
+      body: rendered.body,
+      blockerKeys,
+    });
+  }
+  return wired;
+}
+
+/**
+ * Mirror the declared edges as native GitHub `blocked_by` relations.
+ *
+ * Two shape hazards this crossing inherits from `plan-persist`, both silent if
+ * missed: `applyBlockedByDependencies` indexes `slugToIssueNumber` with plain
+ * property access (so it must be a plain object, never a `Map` — a `Map` yields
+ * `undefined` for every lookup, skips every edge, and reports success having
+ * written nothing), and it reads `dependsOn`, not `depends_on`.
+ *
+ * @param {object} args
+ * @returns {Promise<{ edgesAdded: number, edgesSkipped: number, edgesFailed: number }|null>}
+ *   `null` when there is no interface to mirror through.
+ */
+async function mirrorNativeEdges({ provider, wired, issueByGroupKey }) {
+  if (
+    typeof provider?.getDependencyWriteContext !== 'function' ||
+    typeof provider?.getTicket !== 'function'
+  ) {
+    Logger.warn(
+      '[audit-to-stories] provider exposes no getDependencyWriteContext/getTicket — ' +
+        'skipping native blocked_by edges. Ordering survives in the ' +
+        '`blocked by #N` body footers just written.',
+    );
+    return null;
+  }
+  try {
+    const { gh, owner, repo } = provider.getDependencyWriteContext();
+    const summary = await applyBlockedByDependencies({
+      // The group key IS the slug here — it is the stable identifier both
+      // sides of an edge are keyed by — so `issueByGroupKey` is already the
+      // slug→number map the helper wants.
+      stories: wired.map((s) => ({
+        slug: s.groupKey,
+        dependsOn: s.blockerKeys,
+      })),
+      slugToIssueNumber: issueByGroupKey,
+      getTicket: (issueNumber) => provider.getTicket(issueNumber),
+      owner,
+      repo,
+      gh,
+    });
+    if (summary.edgesFailed > 0) {
+      Logger.warn(
+        `[audit-to-stories] ${summary.edgesFailed} native blocked_by edge(s) could ` +
+          'not be written. Ordering survives in the `blocked by #N` body footers.',
+      );
+    }
+    return {
+      edgesAdded: summary.edgesAdded,
+      edgesSkipped: summary.edgesSkipped,
+      edgesFailed: summary.edgesFailed,
+    };
+  } catch (err) {
+    Logger.warn(
+      `[audit-to-stories] native blocked_by mirroring failed (${err.message}) — ` +
+        'ordering survives in the `blocked by #N` body footers.',
+    );
+    return null;
+  }
+}

package/.agents/scripts/lib/baselines/kernel.js

@@ -107,6 +107,7 @@ import {
 } from './kinds/maintainability.js';
 import {
   applyEpsilon as mutationApplyEpsilon,
+  assertBaselineCompatible as mutationAssertBaselineCompatible,
   compare as mutationCompare,
   kernelVersion as mutationKernelVersion,
   keyField as mutationKeyField,
@@ -211,6 +212,7 @@ const KIND_MODULES = Object.freeze({
     compare: mutationCompare,
     applyEpsilon: mutationApplyEpsilon,
     mergeRows: mutationMergeRows,
+    assertBaselineCompatible: mutationAssertBaselineCompatible,
   }),
   lighthouse: bindKindModule({
     name: lighthouseName,
@@ -280,6 +282,22 @@ export function currentKernelVersion(kind) {
   return getKindModule(kind).kernelVersion();
 }
 
+/**
+ * Resolve a kind module, or null when the kind is not registered. Lets the
+ * optional-hook callers below stay expression-shaped instead of threading a
+ * mutable binding through a try/catch.
+ *
+ * @param {string} kind
+ * @returns {object|null}
+ */
+function tryGetKindModule(kind) {
+  try {
+    return getKindModule(kind);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Ask a kind whether a loaded baseline is compatible with the running
  * scorer's SEMANTICS — a dimension `kernelVersion` cannot express, because a
@@ -291,13 +309,8 @@ export function currentKernelVersion(kind) {
  * @returns {string|null} Operator-facing message, or null when compatible.
  */
 export function checkBaselineSemantics(kind, baseline) {
-  let mod;
-  try {
-    mod = getKindModule(kind);
-  } catch {
-    return null;
-  }
-  if (typeof mod.assertBaselineCompatible !== 'function') return null;
+  const mod = tryGetKindModule(kind);
+  if (typeof mod?.assertBaselineCompatible !== 'function') return null;
   return mod.assertBaselineCompatible(baseline);
 }
 

package/.agents/scripts/lib/baselines/kinds/mutation.js

@@ -2,13 +2,43 @@
  * kinds/mutation.js — per-kind module for the mutation-testing baseline
  * (Story #1891). Row shape: `{ path, score, killed, survived }`. Rollup
  * carries score/killed/survived/noCoverage. Stryker is the upstream
- * kernel; we pin a static `1.0.0` until a Mandrel-side retrofit story
+ * kernel; we pin a static version until a Mandrel-side retrofit story
  * wires the running Stryker version through (#1908).
  *
  * Higher score = better. New paths land in the `additions` bucket
  * (Story #2012 — any real-world score under 100 must never flip to a
  * regression); removed paths count as improvements when their score was
  * non-perfect. Scaffold is generated by `makeBaselineKind` (Story #3983).
+ *
+ * ## Rollup weighting (Story #5058)
+ *
+ * The rollup score is a **mutant-weighted** mean —
+ * `sum(score_i * mutants_i) / sum(mutants_i)`, where
+ * `mutants_i = killed_i + survived_i`. It used to be `scoreSum / rows.length`,
+ * an unweighted mean over files, under which a 3-mutant file carried the same
+ * weight as a 300-mutant one: adding a handful of thinly-mutated new files
+ * dragged the whole-repo number down far enough to breach the floor arm while
+ * the compare arm reported no regression at all (a newly-scanned file has no
+ * baseline row, so it can only move the aggregate `applyFloors` scores).
+ *
+ * Both weights are already summed in the same loop and are already required
+ * by the row schema, which is `additionalProperties: false` — so the weighted
+ * score is computable from the existing row shape with no producer change and
+ * no schema change.
+ *
+ * **Limit of the approximation.** Rows carry no timeout or no-coverage counts
+ * (`noCoverage` in the rollup is hardcoded `0`), so `killed + survived` is not
+ * Stryker's full mutant population wherever timed-out or uncovered mutants
+ * exist. The weighted score therefore *approximates* Stryker's published
+ * overall score — it does not reproduce it. Closing that gap needs a producer
+ * change and its own Story.
+ *
+ * Because this changes what the stored number MEANS, it is a semantics
+ * migration: a baseline measured at 88.51 unweighted is 85.18 weighted over
+ * the same rows, so every floor calibrated on the old mean breaches on
+ * upgrade. `assertBaselineCompatible` below fails such a baseline closed —
+ * a bare `kernelVersion` bump would not, because `kernelMatch` feeds only the
+ * reporting-side drift count and reaches no exit code.
  */
 
 import { canonicalise } from '../path-canon.js';
@@ -17,6 +47,24 @@ import { makeBaselineKind } from './kind-factory.js';
 export const name = 'mutation';
 export const keyField = 'path';
 
+/**
+ * Kernel version of the mutation scorer. Bumped off the original `1.0.0` by
+ * Story #5058: the rollup score changed from an unweighted file mean to a
+ * mutant-weighted mean, so rows stamped below this version were aggregated
+ * under superseded semantics.
+ */
+const KERNEL_VERSION = '2.0.0';
+
+/** Major of {@link KERNEL_VERSION} — the weighted-rollup boundary. */
+const WEIGHTED_ROLLUP_MAJOR = 2;
+
+const RESEED_REMEDY =
+  'Re-seed the baseline: re-run this project mutation run (Mandrel ships no ' +
+  "runner — Stryker is the upstream producer, e.g. 'npx stryker run') so " +
+  "'baselines/mutation.json' is rewritten under the weighted rollup, then " +
+  "commit it with a 'baseline-refresh:' subject and recalibrate the gate's " +
+  'floors against the new number.';
+
 export function projectRow(row) {
   return {
     path: canonicalise(row.path),
@@ -26,20 +74,102 @@ export function projectRow(row) {
   };
 }
 
+/**
+ * Parse the major component of a semver-ish stamp.
+ *
+ * @param {unknown} version
+ * @returns {number|null} The major, or null when unparseable/absent.
+ */
+function majorOf(version) {
+  const match = /^(\d+)\./.exec(String(version ?? ''));
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Kind-module hook (Story #4775) — refuse a loaded baseline whose rollup was
+ * aggregated by the superseded unweighted mean. `checkBaselineSemantics`
+ * dispatches here and `check-baselines`' evaluate phase turns a non-null
+ * return into a fail-closed `semantics` schema error, so a pre-weighting
+ * baseline can never be silently scored against floors calibrated on a
+ * different definition of the number. Follows the `kinds/crap.js` precedent.
+ *
+ * An absent or unparseable stamp is rejected too: `kernelVersion` is required
+ * by the shared envelope schema, so its absence is not evidence of a newer
+ * writer.
+ *
+ * @param {object|null} baseline A loaded v2 baseline envelope.
+ * @returns {string|null} Operator-facing message, or null when compatible.
+ */
+export function assertBaselineCompatible(baseline) {
+  if (!baseline) return null;
+  const stamped = baseline.kernelVersion ?? null;
+  const major = majorOf(stamped);
+  if (major !== null && major >= WEIGHTED_ROLLUP_MAJOR) return null;
+  return (
+    `[mutation] rollup scoring semantics changed: baseline=${stamped ?? '<unstamped>'} ` +
+    `running=${KERNEL_VERSION}. The rollup score is now a mutant-weighted mean ` +
+    '(sum(score * mutants) / sum(mutants)) rather than an unweighted mean over ' +
+    'files, so the stored aggregate is a different number for the same rows and ' +
+    `the floors calibrated against it no longer mean what they did. ${RESEED_REMEDY}`
+  );
+}
+
+/**
+ * A row's mutant count — the weight it carries in the rollup score.
+ *
+ * @param {object} row
+ * @returns {number}
+ */
+function mutantsOf(row) {
+  return (row.killed ?? 0) + (row.survived ?? 0);
+}
+
+/**
+ * Sum one numeric row field across a row set.
+ *
+ * @param {object[]} rows
+ * @param {string} field
+ * @returns {number}
+ */
+function sumOf(rows, field) {
+  let total = 0;
+  for (const r of rows) total += r[field] ?? 0;
+  return total;
+}
+
+/**
+ * The mutant-weighted mean score: `sum(score * mutants) / sum(mutants)`.
+ *
+ * Zero-mutant guard: an empty row set, or one whose rows carry only zeroes,
+ * has no weight to divide by. Returning 0 rather than dividing keeps `NaN` and
+ * `Infinity` out of the envelope, where they would fail the schema's numeric
+ * bounds downstream.
+ *
+ * @param {object[]} rows
+ * @param {number} mutants Total mutant count across `rows`.
+ * @returns {number}
+ */
+function weightedScore(rows, mutants) {
+  if (mutants <= 0) return 0;
+  let weighted = 0;
+  for (const r of rows) weighted += (r.score ?? 0) * mutantsOf(r);
+  return Number((weighted / mutants).toFixed(2));
+}
+
+/**
+ * Aggregate rows into the rollup shape. `killed` and `survived` stay plain
+ * sums and `noCoverage` stays hardcoded 0 — the weighting changes `score`
+ * alone.
+ *
+ * @param {object[]} rows
+ * @returns {{score: number, killed: number, survived: number, noCoverage: number}}
+ */
 function aggregate(rows) {
-  if (!rows || rows.length === 0) {
-    return { score: 0, killed: 0, survived: 0, noCoverage: 0 };
-  }
-  let scoreSum = 0;
-  let killed = 0;
-  let survived = 0;
-  for (const r of rows) {
-    scoreSum += r.score ?? 0;
-    killed += r.killed ?? 0;
-    survived += r.survived ?? 0;
-  }
+  const scored = rows ?? [];
+  const killed = sumOf(scored, 'killed');
+  const survived = sumOf(scored, 'survived');
   return {
-    score: Number((scoreSum / rows.length).toFixed(2)),
+    score: weightedScore(scored, killed + survived),
     killed,
     survived,
     noCoverage: 0,
@@ -55,7 +185,7 @@ export const {
   mergeRows,
 } = makeBaselineKind({
   keyField,
-  kernelVersion: '1.0.0',
+  kernelVersion: KERNEL_VERSION,
   axes: ['score'],
   betterWhen: 'higher',
   aggregate,

package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js

@@ -10,20 +10,23 @@
  * spread into.
  *
  * Default (key absent) preserves today's full-repo behaviour byte-for-byte.
- * When `enabled: true`, `coverage-capture.js` scopes `npm run test:coverage`
- * to the files changed against `baseRef` (default: the gate's own `--ref` /
- * `main`), and the CRAP join treats a method in a file the diff did not
- * touch as resolved by its committed baseline row instead of requiring
- * fresh coverage for it.
+ * When `enabled: true`, the changed-file set against `baseRef` (default: the
+ * gate's own `--ref` / `main`) decides **whether** to capture — no changed
+ * file under `crap.targetDirs` means no capture at all — and the CRAP join
+ * treats a method in a file the diff did not touch as resolved by its
+ * committed baseline row instead of requiring fresh coverage for it. It does
+ * not narrow the capture run itself: a capture that does happen is the
+ * ordinary full `npm run test:coverage` (Story #5065).
  */
 export const INCREMENTAL_COVERAGE_SCHEMA = {
   type: 'object',
   description:
-    'Story #4981 — opt-in incremental coverage-capture + CRAP-join scoping. Default (key absent) preserves today’s full-repo behaviour byte-for-byte. When `enabled: true`, `coverage-capture.js` scopes `npm run test:coverage` to the files changed against `baseRef` (default: the gate’s own `--ref` / `main`), and the CRAP join treats a method in a file the diff did not touch as resolved by its committed baseline row instead of requiring fresh coverage for it.',
+    'Story #4981 — opt-in incremental coverage-capture + CRAP-join scoping. Default (key absent) preserves today’s full-repo behaviour byte-for-byte. When `enabled: true`, the changed-file set against `baseRef` (default: the gate’s own `--ref` / `main`) decides WHETHER to capture — no changed file under `crap.targetDirs` means no capture at all — and the CRAP join treats a method in a file the diff did not touch as resolved by its committed baseline row instead of requiring fresh coverage for it. It does NOT narrow the capture run itself: a capture that does happen is the ordinary full `npm run test:coverage` (Story #5065).',
   properties: {
     enabled: {
       type: 'boolean',
-      description: 'Master switch for incremental capture + join scoping.',
+      description:
+        'Master switch for the capture skip and the baseline-resolved CRAP join.',
     },
     baseRef: {
       type: 'string',

package/.agents/scripts/lib/config/quality.js

@@ -78,6 +78,13 @@ const DEFAULT_MI_FLOORS = Object.freeze({
  * `enabled: true`. `baseRef: null` means "use the caller's own ref
  * resolution" (the gate's `--ref` flag / `main`) rather than a second,
  * possibly-conflicting default.
+ *
+ * Story #5065 — what `enabled: true` actually buys, measured: the capture is
+ * **skipped entirely** when no changed file lives under `crap.targetDirs`,
+ * and the CRAP join resolves methods in untouched files from the committed
+ * baseline row instead of requiring fresh coverage. It does **not** shorten
+ * the capture run — when a capture does happen it is the ordinary full
+ * `npm run test:coverage`.
  */
 const DEFAULT_INCREMENTAL_COVERAGE = Object.freeze({
   enabled: false,