mandrel-platform 1.10.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {

package/scripts/check-coverage-threshold.mjs

@@ -10,9 +10,26 @@
  * green.
  * The `.agents/` harness ships a CRAP/MI/coverage *ratchet*, but the shared CI
  * workflow itself had no coverage floor an operator could opt into at the
- * workflow layer. This script is that floor: the `unit` job runs it with the
- * `coverage-threshold` workflow input, and a non-zero exit fails the job —
- * which is a `needs:` of `ci-required`.
+ * workflow layer. This script is that floor: the `coverage-floor` job runs it
+ * with the `coverage-threshold` workflow input, and a non-zero exit fails the
+ * job — which is a `needs:` of `ci-required`.
+ *
+ * MERGED MEASUREMENT (Story #468). The gate used to assert every discovered
+ * `coverage-summary.json` INDEPENDENTLY — a logical AND across per-workspace
+ * summaries. That made the floor an artifact of which job happened to run
+ * which tests: it false-failed every shard of a sharded tier (each shard
+ * measures its own subset), and it forced a consumer to keep its whole suite
+ * in the one tier the gate could see, because a scoped tier's summary is a
+ * partial measurement of the repo. The gate now UNIONS every summary it finds
+ * into one measurement and asserts the floor once.
+ *
+ * Two tiers can exercise the same source file, and a summary records how MANY
+ * lines each covered, never WHICH — so the true union is not recoverable from
+ * counts. Overlap therefore resolves as per-file `max(covered)`, which is a
+ * provable LOWER BOUND on the union: the merged number can only understate
+ * real coverage, so the floor may false-fail and can never false-pass. Tiers
+ * scoped to disjoint projects — the case this exists for — overlap on nothing
+ * and merge exactly.
  *
  * Design constraints:
  *   • OPT-IN. A threshold of 0 (the default) is a no-op: the gate prints a
@@ -40,7 +57,7 @@
  *
  * Exit codes:
  *   0 — gate disabled (threshold 0), or measured coverage ≥ threshold.
- *   1 — measured coverage below the threshold, OR the threshold is set but no
+ *   1 — merged coverage below the threshold, OR the threshold is set but no
  *       coverage summary could be found / parsed (a set floor must never pass
  *       silently on missing data).
  */
@@ -164,6 +181,169 @@ export function meetsThreshold(pct, threshold) {
   return typeof pct === "number" && Number.isFinite(pct) && pct >= threshold;
 }
 
+/**
+ * The per-file keys of a coverage-summary.json (everything but `total`).
+ * json-summary emits one entry per source file, keyed by the ABSOLUTE path it
+ * had in the workspace that produced it.
+ */
+export function summaryFileKeys(summary) {
+  if (!summary || typeof summary !== "object") return [];
+  return Object.keys(summary).filter(
+    (k) => k !== "total" && summary[k] && typeof summary[k] === "object"
+  );
+}
+
+/**
+ * Longest common DIRECTORY prefix of a key list (trailing slash included, or
+ * "" when there is none). Filenames are excluded from the comparison so a
+ * single-entry summary yields its own directory rather than the file itself.
+ *
+ * This is the FALLBACK normalizer only — see `toRepoRelativeKey`. It is not
+ * safe on its own across summaries: two tiers whose file sets bottom out at
+ * different depths (one scoped to `packages/api`, one spanning the repo)
+ * produce prefixes of different lengths, so the same file normalizes to two
+ * different keys and the union double-counts it.
+ */
+export function commonDirPrefix(keys) {
+  const lists = keys.map((k) => String(k).replace(/\\/g, "/").split("/").slice(0, -1));
+  if (lists.length === 0) return "";
+  let prefix = lists[0];
+  for (let i = 1; i < lists.length; i++) {
+    const other = lists[i];
+    let n = 0;
+    while (n < prefix.length && n < other.length && prefix[n] === other[n]) n++;
+    prefix = prefix.slice(0, n);
+  }
+  return prefix.length > 0 ? prefix.join("/") + "/" : "";
+}
+
+/**
+ * Normalize one absolute coverage key to a repo-relative path, ANCHORED ON
+ * THE CHECKOUT rather than on the key list's own shape: walk the key's
+ * segments left-to-right and return the first (longest) suffix that resolves
+ * to a real path under `cwd`.
+ *
+ * This is what lets two tiers' summaries merge when they were produced under
+ * different workspace roots — a self-hosted fleet where one job ran under
+ * `/actions-runner/_work/repo/repo` and another under `/srv/runner2/_work/repo/repo`
+ * still normalizes both to `src/foo.ts`. Anchoring on the checkout also avoids
+ * the mixed-depth failure `commonDirPrefix` has on its own.
+ *
+ * Returns null when nothing resolves (a generated or since-deleted file); the
+ * caller falls back to the prefix form and counts it.
+ */
+export function toRepoRelativeKey(key, { exists = existsSync, cwd = process.cwd() } = {}) {
+  if (typeof key !== "string" || key.trim() === "") return null;
+  const norm = key.replace(/\\/g, "/");
+  const absolute = norm.startsWith("/") || /^[A-Za-z]:\//.test(norm);
+  if (!absolute) return norm.replace(/^\.\//, "");
+  const segs = norm.split("/").filter((seg) => seg !== "" && !/^[A-Za-z]:$/.test(seg));
+  for (let i = 0; i < segs.length; i++) {
+    const candidate = segs.slice(i).join("/");
+    if (exists(join(cwd, candidate))) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Reduce one parsed summary to the per-file {covered, total} counts for
+ * `metric`, keyed by normalized path.
+ *
+ * A summary carrying ONLY a `total` block (no per-file entries) cannot be
+ * merged per file, so it is kept as an OPAQUE contribution keyed by nothing —
+ * its counts are added to the aggregate whole. That can double-count a file
+ * two such summaries share, which is why json-summary's per-file output is the
+ * supported shape; the opaque path exists so a reduced summary degrades to
+ * today's arithmetic rather than vanishing from the measurement.
+ */
+export function normalizeSummary(summary, metric, { exists = existsSync, cwd = process.cwd() } = {}) {
+  const files = new Map();
+  let unresolved = 0;
+  const keys = summaryFileKeys(summary);
+
+  if (keys.length === 0) {
+    const total = summary && typeof summary === "object" ? summary.total : null;
+    const entry = total && typeof total === "object" ? total[metric] : null;
+    const covered = entry && Number.isFinite(entry.covered) ? entry.covered : null;
+    const denom = entry && Number.isFinite(entry.total) ? entry.total : null;
+    return {
+      files,
+      unresolved,
+      opaque: covered !== null && denom !== null ? { covered, total: denom } : null,
+    };
+  }
+
+  const prefix = commonDirPrefix(keys);
+  for (const key of keys) {
+    const entry = summary[key][metric];
+    if (!entry || !Number.isFinite(entry.covered) || !Number.isFinite(entry.total)) continue;
+    let normalized = toRepoRelativeKey(key, { exists, cwd });
+    if (normalized === null) {
+      unresolved += 1;
+      const raw = String(key).replace(/\\/g, "/");
+      normalized = prefix && raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
+    }
+    const prev = files.get(normalized);
+    files.set(
+      normalized,
+      prev
+        ? {
+            // MAX, never sum. Two tiers exercising the same file report how
+            // MANY lines each covered, never WHICH — so the true union is
+            // unknowable from counts alone. max() is a provable lower bound on
+            // it (the union is at least the larger contribution), which keeps
+            // the floor able to false-fail but never to false-pass.
+            covered: Math.max(prev.covered, entry.covered),
+            total: Math.max(prev.total, entry.total),
+          }
+        : { covered: entry.covered, total: entry.total }
+    );
+  }
+  return { files, unresolved, opaque: null };
+}
+
+/**
+ * Union a list of normalized summaries into ONE measurement:
+ * `sum(covered) / sum(total) * 100` over the merged per-file map.
+ */
+export function mergeNormalized(parts) {
+  const files = new Map();
+  let covered = 0;
+  let total = 0;
+  let unresolved = 0;
+
+  for (const part of parts) {
+    unresolved += part.unresolved || 0;
+    for (const [key, value] of part.files) {
+      const prev = files.get(key);
+      files.set(
+        key,
+        prev
+          ? {
+              covered: Math.max(prev.covered, value.covered),
+              total: Math.max(prev.total, value.total),
+            }
+          : { covered: value.covered, total: value.total }
+      );
+    }
+    if (part.opaque) {
+      covered += part.opaque.covered;
+      total += part.opaque.total;
+    }
+  }
+  for (const value of files.values()) {
+    covered += value.covered;
+    total += value.total;
+  }
+  return {
+    covered,
+    total,
+    pct: total > 0 ? (covered / total) * 100 : null,
+    fileCount: files.size,
+    unresolved,
+  };
+}
+
 /**
  * Recursively find every `coverage-summary.json` under `root`, regardless of
  * the name of the directory that directly contains it. `node_modules` and
@@ -228,7 +408,10 @@ export function readSummary(file) {
  * drive it directly. Returns a structured verdict:
  *   { ok, skipped, reason, threshold, metric, results: [{ file, pct, ok }] }
  */
-export function evaluateGate(opts, { findSummaries = findCoverageSummaries, read = readSummary } = {}) {
+export function evaluateGate(
+  opts,
+  { findSummaries = findCoverageSummaries, read = readSummary, exists = existsSync } = {}
+) {
   const { threshold, metric, cwd, coverageDirs } = opts;
 
   if (threshold <= 0) {
@@ -239,6 +422,7 @@ export function evaluateGate(opts, { findSummaries = findCoverageSummaries, read
       threshold,
       metric,
       results: [],
+      merged: null,
     };
   }
 
@@ -254,28 +438,56 @@ export function evaluateGate(opts, { findSummaries = findCoverageSummaries, read
       threshold,
       metric,
       results: [],
+      merged: null,
     };
   }
 
+  // Per-summary rows stay in the verdict as CONTRIBUTIONS — they name which
+  // artifact carried which numbers, so a tier that quietly stopped producing
+  // coverage is visible in the log. They are no longer individually asserted:
+  // the floor is one verdict over the union (see the header note).
   const results = [];
+  const parts = [];
   for (const file of files) {
     const summary = read(file);
     const pct = extractPct(summary, metric);
-    if (pct === null) {
-      results.push({ file, pct: null, ok: false });
-    } else {
-      results.push({ file, pct, ok: meetsThreshold(pct, threshold) });
-    }
+    const part = normalizeSummary(summary, metric, { exists, cwd });
+    parts.push(part);
+    results.push({
+      file,
+      pct,
+      fileCount: part.files.size,
+      unresolved: part.unresolved,
+      contributed: part.files.size > 0 || part.opaque !== null,
+    });
   }
 
-  const failures = results.filter((r) => !r.ok);
+  const merged = mergeNormalized(parts);
+
+  if (merged.pct === null) {
+    return {
+      ok: false,
+      skipped: false,
+      reason:
+        `coverage threshold is set but no "${metric}" counts could be read from ` +
+        `any of the ${files.length} coverage summaries found (a set floor must ` +
+        "not pass on unreadable data)",
+      threshold,
+      metric,
+      results,
+      merged,
+    };
+  }
+
+  const ok = meetsThreshold(merged.pct, threshold);
   return {
-    ok: failures.length === 0,
+    ok,
     skipped: false,
-    reason: failures.length === 0 ? "all coverage summaries meet the floor" : "below floor",
+    reason: ok ? "merged coverage meets the floor" : "below floor",
     threshold,
     metric,
     results,
+    merged,
   };
 }
 
@@ -290,26 +502,43 @@ export function formatVerdict(verdict) {
     lines.push(`[coverage-threshold] ❌ ${verdict.reason}`);
     return lines;
   }
+
+  // Contribution rows first: which artifact carried what.
   for (const r of verdict.results) {
-    if (r.pct === null) {
-      lines.push(
-        `[coverage-threshold] ❌ ${r.file}: no "${verdict.metric}" total.pct in summary`
-      );
-    } else {
-      const mark = r.ok ? "✅" : "❌";
+    if (!r.contributed) {
       lines.push(
-        `[coverage-threshold] ${mark} ${r.file}: ${verdict.metric} ${r.pct}% ` +
-        `(floor ${verdict.threshold}%)`
+        `[coverage-threshold] ⚠️  ${r.file}: no "${verdict.metric}" counts — contributed nothing`
       );
+      continue;
     }
+    const shown = r.pct === null ? "n/a" : `${r.pct}%`;
+    const unresolvedNote =
+      r.unresolved > 0 ? `, ${r.unresolved} path(s) unresolved against the checkout` : "";
+    lines.push(
+      `[coverage-threshold] • ${r.file}: ${r.fileCount} file(s), ` +
+        `${verdict.metric} ${shown} on its own${unresolvedNote}`
+    );
+  }
+
+  const m = verdict.merged;
+  if (!m || m.pct === null) {
+    lines.push(`[coverage-threshold] ❌ ${verdict.reason}`);
+    return lines;
   }
+
+  const rounded = Math.round(m.pct * 100) / 100;
+  lines.push(
+    `[coverage-threshold] Σ merged across ${verdict.results.length} summary(ies): ` +
+      `${m.covered}/${m.total} ${verdict.metric} over ${m.fileCount} unique file(s) ` +
+      `= ${rounded}% (floor ${verdict.threshold}%)`
+  );
   if (verdict.ok) {
     lines.push(
-      `[coverage-threshold] ✅ ${verdict.metric} coverage meets the ${verdict.threshold}% floor.`
+      `[coverage-threshold] ✅ merged ${verdict.metric} coverage meets the ${verdict.threshold}% floor.`
     );
   } else {
     lines.push(
-      `[coverage-threshold] ❌ ${verdict.metric} coverage is below the ${verdict.threshold}% floor.`
+      `[coverage-threshold] ❌ merged ${verdict.metric} coverage is below the ${verdict.threshold}% floor.`
     );
   }
   return lines;

package/scripts/check-coverage-threshold.test.mjs

@@ -40,6 +40,11 @@ import {
   evaluateGate,
   formatVerdict,
   runCli,
+  summaryFileKeys,
+  commonDirPrefix,
+  toRepoRelativeKey,
+  normalizeSummary,
+  mergeNormalized,
 } from "./check-coverage-threshold.mjs";
 
 // Build a minimal Istanbul/c8/vitest-shaped coverage-summary object.
@@ -235,7 +240,8 @@ test("evaluateGate: SET + measured above floor → pass", () => {
   assert.equal(verdict.ok, true);
   assert.equal(verdict.skipped, false);
   assert.equal(verdict.results[0].pct, 91);
-  assert.equal(verdict.results[0].ok, true);
+  assert.equal(verdict.results[0].contributed, true);
+  assert.equal(verdict.merged.pct, 91);
 });
 
 test("evaluateGate: SET + measured below floor → fail", () => {
@@ -248,7 +254,7 @@ test("evaluateGate: SET + measured below floor → fail", () => {
   );
   assert.equal(verdict.ok, false);
   assert.equal(verdict.results[0].pct, 73);
-  assert.equal(verdict.results[0].ok, false);
+  assert.equal(verdict.merged.pct, 73);
 });
 
 test("evaluateGate: SET but no coverage summary found → fail (never silent-pass)", () => {
@@ -264,7 +270,10 @@ test("evaluateGate: SET but no coverage summary found → fail (never silent-pas
   assert.match(verdict.reason, /no coverage-summary\.json was found/);
 });
 
-test("evaluateGate: SET, one of many packages below floor → fail", () => {
+test("evaluateGate: SET, many packages — the floor is one merged number, not a per-summary AND", () => {
+  // 95/100 + 40/100 = 135/200 = 67.5%, below the 80 floor. Both summaries are
+  // still REPORTED as contributions (the log names which artifact carried
+  // what) but neither is asserted on its own.
   const verdict = evaluateGate(
     { threshold: 80, metric: "statements", cwd: ".", coverageDirs: [] },
     {
@@ -280,8 +289,13 @@ test("evaluateGate: SET, one of many packages below floor → fail", () => {
   );
   assert.equal(verdict.ok, false);
   assert.equal(verdict.results.length, 2);
-  assert.equal(verdict.results.find((r) => r.file.startsWith("a")).ok, true);
-  assert.equal(verdict.results.find((r) => r.file.startsWith("b")).ok, false);
+  assert.equal(verdict.merged.covered, 135);
+  assert.equal(verdict.merged.total, 200);
+  assert.equal(verdict.merged.pct, 67.5);
+  assert.ok(
+    verdict.results.every((r) => r.contributed),
+    "both summaries must be reported as contributions",
+  );
 });
 
 // ---------------------------------------------------------------------------
@@ -480,6 +494,279 @@ test("formatVerdict renders a skip line for the disabled gate", () => {
   assert.match(lines[0], /⏭️/);
 });
 
+// ---------------------------------------------------------------------------
+// Merged measurement (Story #468)
+//
+// The floor used to be a logical AND across per-workspace summaries, which
+// made it an artifact of which JOB ran which tests: a scoped tier's summary is
+// a partial measurement of the repo, and every shard of a sharded tier
+// false-failed on its own subset. These tests pin the union semantics and the
+// lower-bound property that makes the union safe to assert.
+// ---------------------------------------------------------------------------
+
+// A coverage-summary.json with real per-file entries: { "<abs path>": pct-ish
+// counts }, plus the `total` block json-summary always writes.
+function fileSummary(entries, metric = "lines") {
+  const out = {};
+  let covered = 0;
+  let total = 0;
+  for (const [path, counts] of Object.entries(entries)) {
+    covered += counts.covered;
+    total += counts.total;
+    out[path] = {
+      [metric]: {
+        total: counts.total,
+        covered: counts.covered,
+        skipped: 0,
+        pct: (counts.covered / counts.total) * 100,
+      },
+    };
+  }
+  out.total = {
+    [metric]: {
+      total,
+      covered,
+      skipped: 0,
+      pct: total > 0 ? (covered / total) * 100 : 0,
+    },
+  };
+  return out;
+}
+
+/** An `exists` stub that answers true only for a known set of repo-relative paths. */
+function existsIn(relPaths, cwd = "/repo") {
+  const known = new Set(relPaths.map((r) => join(cwd, r)));
+  return (candidate) => known.has(candidate);
+}
+
+test("summaryFileKeys returns per-file entries and never `total`", () => {
+  const sum = fileSummary({ "/ws/src/a.ts": { covered: 5, total: 10 } });
+  assert.deepEqual(summaryFileKeys(sum), ["/ws/src/a.ts"]);
+  assert.deepEqual(summaryFileKeys(null), []);
+});
+
+test("commonDirPrefix excludes the filename, so a single entry yields its directory", () => {
+  assert.equal(commonDirPrefix(["/ws/repo/src/a.ts"]), "/ws/repo/src/");
+  assert.equal(commonDirPrefix(["/ws/repo/src/a.ts", "/ws/repo/api/b.ts"]), "/ws/repo/");
+  assert.equal(commonDirPrefix([]), "");
+});
+
+test("toRepoRelativeKey anchors on the checkout — different workspace roots normalize alike", () => {
+  const exists = existsIn(["src/foo.ts"]);
+  // Two tiers, two runner workspace roots, one source file.
+  assert.equal(
+    toRepoRelativeKey("/actions-runner/_work/repo/repo/src/foo.ts", { exists, cwd: "/repo" }),
+    "src/foo.ts",
+  );
+  assert.equal(
+    toRepoRelativeKey("/srv/runner2/_work/repo/repo/src/foo.ts", { exists, cwd: "/repo" }),
+    "src/foo.ts",
+  );
+});
+
+test("toRepoRelativeKey returns null when nothing resolves against the checkout", () => {
+  const exists = existsIn(["src/foo.ts"]);
+  assert.equal(toRepoRelativeKey("/ws/generated/nope.ts", { exists, cwd: "/repo" }), null);
+  assert.equal(toRepoRelativeKey("", { exists, cwd: "/repo" }), null);
+});
+
+test("mergeNormalized: disjoint files sum — aggregate is sum(covered)/sum(total)", () => {
+  const exists = existsIn(["src/a.ts", "api/b.ts"]);
+  const opts = { exists, cwd: "/repo" };
+  const unit = normalizeSummary(
+    fileSummary({ "/ws/repo/src/a.ts": { covered: 90, total: 100 } }),
+    "lines",
+    opts,
+  );
+  const contract = normalizeSummary(
+    fileSummary({ "/ws/repo/api/b.ts": { covered: 30, total: 100 } }),
+    "lines",
+    opts,
+  );
+  const merged = mergeNormalized([unit, contract]);
+  assert.equal(merged.covered, 120);
+  assert.equal(merged.total, 200);
+  assert.equal(merged.pct, 60);
+  assert.equal(merged.fileCount, 2);
+});
+
+test("mergeNormalized: an overlapping file takes MAX(covered), never the sum (the lower-bound property)", () => {
+  const exists = existsIn(["src/shared.ts"]);
+  const opts = { exists, cwd: "/repo" };
+  const unit = normalizeSummary(
+    fileSummary({ "/ws/repo/src/shared.ts": { covered: 40, total: 100 } }),
+    "lines",
+    opts,
+  );
+  const contract = normalizeSummary(
+    fileSummary({ "/ws/repo/src/shared.ts": { covered: 70, total: 100 } }),
+    "lines",
+    opts,
+  );
+  const merged = mergeNormalized([unit, contract]);
+  // Summing would give 110/200 — and 110 covered lines in a 100-line file is
+  // not a measurement, it is an artifact. max() is a lower bound on the union.
+  assert.equal(merged.covered, 70);
+  assert.equal(merged.total, 100);
+  assert.equal(merged.pct, 70);
+  assert.equal(merged.fileCount, 1, "the shared file must merge into ONE entry");
+});
+
+test("normalizeSummary: mixed-depth tiers still merge the same file into one entry", () => {
+  // The unit tier spans the repo; the contract tier is scoped to packages/api.
+  // Their own longest-common-dir prefixes differ in DEPTH, so prefix-relative
+  // keys alone would disagree ("packages/api/src/db.ts" vs "src/db.ts") and
+  // double-count the shared file. Anchoring on the checkout resolves both.
+  const exists = existsIn(["packages/web/src/ui.ts", "packages/api/src/db.ts"]);
+  const opts = { exists, cwd: "/repo" };
+  const unit = normalizeSummary(
+    fileSummary({
+      "/ws/repo/packages/web/src/ui.ts": { covered: 80, total: 100 },
+      "/ws/repo/packages/api/src/db.ts": { covered: 10, total: 100 },
+    }),
+    "lines",
+    opts,
+  );
+  const contract = normalizeSummary(
+    fileSummary({ "/ws/repo/packages/api/src/db.ts": { covered: 95, total: 100 } }),
+    "lines",
+    opts,
+  );
+  assert.equal(contract.files.size, 1);
+  assert.ok(contract.files.has("packages/api/src/db.ts"));
+  const merged = mergeNormalized([unit, contract]);
+  assert.equal(merged.fileCount, 2, "the shared file must not double-count");
+  assert.equal(merged.covered, 175, "80 + max(10, 95)");
+  assert.equal(merged.total, 200);
+});
+
+test("normalizeSummary counts keys it could not resolve against the checkout", () => {
+  const exists = existsIn(["src/a.ts"]);
+  const part = normalizeSummary(
+    fileSummary({
+      "/ws/repo/src/a.ts": { covered: 5, total: 10 },
+      "/ws/repo/dist/generated.js": { covered: 1, total: 10 },
+    }),
+    "lines",
+    { exists, cwd: "/repo" },
+  );
+  assert.equal(part.unresolved, 1);
+  assert.equal(part.files.size, 2, "an unresolved key still contributes, via the prefix fallback");
+});
+
+test("evaluateGate: a weighted merge PASSES where the old per-summary AND failed", () => {
+  // 900/1000 (90%) + 70/100 (70%) = 970/1100 = 88.18%, above an 80 floor.
+  // Under the old AND the 70% summary alone red the gate — which is exactly
+  // the false-fail that forced a consumer to keep its whole suite in one tier.
+  const exists = existsIn(["src/big.ts", "api/small.ts"]);
+  const verdict = evaluateGate(
+    { threshold: 80, metric: "lines", cwd: "/repo", coverageDirs: [] },
+    {
+      exists,
+      findSummaries: () => ["unit/coverage/coverage-summary.json", "contract/coverage/coverage-summary.json"],
+      read: (f) =>
+        f.startsWith("unit")
+          ? fileSummary({ "/ws/repo/src/big.ts": { covered: 900, total: 1000 } })
+          : fileSummary({ "/ws/repo/api/small.ts": { covered: 70, total: 100 } }),
+    },
+  );
+  assert.equal(verdict.ok, true);
+  assert.equal(verdict.merged.covered, 970);
+  assert.equal(verdict.merged.total, 1100);
+  assert.equal(Math.round(verdict.merged.pct * 100) / 100, 88.18);
+});
+
+test("evaluateGate: equal-weight 85% + 70% against an 80 floor fails on the weighted number (77.5%)", () => {
+  const exists = existsIn(["src/a.ts", "api/b.ts"]);
+  const verdict = evaluateGate(
+    { threshold: 80, metric: "lines", cwd: "/repo", coverageDirs: [] },
+    {
+      exists,
+      findSummaries: () => ["a/coverage/coverage-summary.json", "b/coverage/coverage-summary.json"],
+      read: (f) =>
+        f.startsWith("a")
+          ? fileSummary({ "/ws/repo/src/a.ts": { covered: 85, total: 100 } })
+          : fileSummary({ "/ws/repo/api/b.ts": { covered: 70, total: 100 } }),
+    },
+  );
+  assert.equal(verdict.ok, false);
+  assert.equal(verdict.merged.pct, 77.5);
+});
+
+test("evaluateGate: a sharded tier's partial summaries merge instead of each false-failing", () => {
+  // Two shards of ONE tier, each measuring only the files its shard ran.
+  // Asserted individually both sit at 50%; merged they are the repo's 90%.
+  const exists = existsIn(["src/a.ts", "src/b.ts"]);
+  const verdict = evaluateGate(
+    { threshold: 80, metric: "lines", cwd: "/repo", coverageDirs: [] },
+    {
+      exists,
+      findSummaries: () => ["unit-results-1/coverage/coverage-summary.json", "unit-results-2/coverage/coverage-summary.json"],
+      read: (f) =>
+        f.includes("unit-results-1")
+          ? fileSummary({
+              "/ws/repo/src/a.ts": { covered: 90, total: 100 },
+              "/ws/repo/src/b.ts": { covered: 10, total: 100 },
+            })
+          : fileSummary({
+              "/ws/repo/src/a.ts": { covered: 10, total: 100 },
+              "/ws/repo/src/b.ts": { covered: 90, total: 100 },
+            }),
+    },
+  );
+  assert.equal(verdict.ok, true);
+  assert.equal(verdict.merged.covered, 180, "max per file across shards: 90 + 90");
+  assert.equal(verdict.merged.pct, 90);
+});
+
+test("evaluateGate: summaries carrying only a `total` block still contribute (no silent vanish)", () => {
+  const verdict = evaluateGate(
+    { threshold: 80, metric: "lines", cwd: "/repo", coverageDirs: [] },
+    {
+      exists: () => false,
+      findSummaries: () => ["a/coverage/coverage-summary.json"],
+      read: () => summary({ lines: 91 }),
+    },
+  );
+  assert.equal(verdict.ok, true);
+  assert.equal(verdict.merged.covered, 91);
+  assert.equal(verdict.merged.total, 100);
+  assert.equal(verdict.results[0].contributed, true);
+});
+
+test("evaluateGate: a set floor with summaries that carry no readable counts still FAILS", () => {
+  const verdict = evaluateGate(
+    { threshold: 80, metric: "lines", cwd: "/repo", coverageDirs: [] },
+    {
+      exists: () => false,
+      findSummaries: () => ["a/coverage/coverage-summary.json"],
+      read: () => ({ total: { branches: { total: 1, covered: 1, pct: 100 } } }),
+    },
+  );
+  assert.equal(verdict.ok, false);
+  assert.match(verdict.reason, /could be read from/);
+});
+
+test("formatVerdict names each contributing artifact and the merged total", () => {
+  const exists = existsIn(["src/a.ts", "api/b.ts"]);
+  const verdict = evaluateGate(
+    { threshold: 80, metric: "lines", cwd: "/repo", coverageDirs: [] },
+    {
+      exists,
+      findSummaries: () => ["unit-results-1/coverage/coverage-summary.json", "contract-results-1/coverage/coverage-summary.json"],
+      read: (f) =>
+        f.startsWith("unit")
+          ? fileSummary({ "/ws/repo/src/a.ts": { covered: 90, total: 100 } })
+          : fileSummary({ "/ws/repo/api/b.ts": { covered: 80, total: 100 } }),
+    },
+  );
+  const out = formatVerdict(verdict).join("\n");
+  assert.match(out, /unit-results-1\/coverage\/coverage-summary\.json/);
+  assert.match(out, /contract-results-1\/coverage\/coverage-summary\.json/);
+  assert.match(out, /merged across 2 summary\(ies\)/);
+  assert.match(out, /170\/200/);
+});
+
 // ---------------------------------------------------------------------------
 // pr-quality.yml Coverage threshold gate — workflow-step parity (#163, #230)
 //