mandrel-platform 0.16.0 → 0.17.1

package/README.md

@@ -87,6 +87,13 @@ every consumer.
 A Biome base config with the recommended linter rule set, import organizer,
 and standard formatter defaults (2-space indent, 100-char line width).
 
+**Minimum Biome version: 2.0.** The base targets the **Biome v2 schema**
+(`$schema: https://biomejs.dev/schemas/2.5.0/schema.json`, `assist.actions.
+source.organizeImports`, `linter.rules.preset`). Biome v1 consumers cannot
+`extends` this base — the v2 config shape is a hard configuration error on
+Biome 1.x. There is no dual v1/v2 export; consumers on Biome 1.x must
+upgrade to 2.x before adopting this base (refs #153).
+
 **Consumer usage (`biome.json`):**
 
 ```jsonc
@@ -175,13 +182,28 @@ export default [
 ];
 ```
 
-#### `lighthouse.base.json`
-
-Lighthouse's `lighthouserc.json` has no whole-file `extends`, so the
-base ships the shared `ci` block — collect settings plus the four
-category assertions on the `lighthouse:recommended` preset. Deep-merge
-it and add your repo-specific `ci.collect.url` /
-`ci.collect.staticDistDir`:
+#### `lighthouse.base.json` / `lighthouse-thresholds.base.json`
+
+Lighthouse has **two runner mechanisms** in the fleet — `@lhci/cli`
+(`lighthouserc`) and a bespoke puppeteer + baseline-drift script (collect a
+Lighthouse result programmatically, diff category scores against a checked-in
+baseline JSON). Neither can consume the other's config shape natively, so the
+package ships **two bases**:
+
+- **`lighthouse-thresholds.base.json`** — the **mechanism-neutral** score
+  floors (`categories.performance` / `.accessibility` / `.best-practices` /
+  `.seo`, each a bare `0.0`–`1.0` number). This is the shared source of
+  truth both mechanisms read. Runner-agnostic on purpose: it has no LHCI
+  `ci.assert` wrapper and no puppeteer-script wiring, just the floors.
+- **`lighthouse.base.json`** — the **LHCI wrapper**. Ships the shared `ci`
+  block (collect settings + the four category assertions on the
+  `lighthouse:recommended` preset) for `@lhci/cli` consumers. Its
+  `categories:*` `minScore` values are sourced from
+  `lighthouse-thresholds.base.json` — keep the two in sync when a floor
+  changes.
+
+**LHCI consumers** (`@lhci/cli`) deep-merge `lighthouse.base.json` and add
+repo-specific `ci.collect.url` / `ci.collect.staticDistDir`:
 
 ```jsonc
 // lighthouserc.js — deep-merge the base, add repo-specific collect targets
@@ -198,6 +220,23 @@ export default {
 };
 ```
 
+**Puppeteer / baseline-drift consumers** (no `@lhci/cli`, no `lighthouserc`)
+extend `lighthouse-thresholds.base.json` directly — read the bare category
+floors and gate the collected result against them, independent of any LHCI
+config shape:
+
+```jsonc
+// scripts/lighthouse-baseline.mjs — read the shared floors, gate the collected result
+import thresholds from "mandrel-platform/lighthouse-thresholds.base.json" with { type: "json" };
+
+for (const [category, minScore] of Object.entries(thresholds.categories)) {
+  const score = lighthouseResult.categories[category].score;
+  if (score < minScore) {
+    throw new Error(`${category} score ${score} below floor ${minScore}`);
+  }
+}
+```
+
 > **Budgets stay consumer-tunable.** These bases standardize *which*
 > tools run and their shared defaults — not *what each tool gates on*
 > per consumer. Override any threshold, score floor, or budget locally;
@@ -465,6 +504,7 @@ pnpm run bootstrap
 | `mandrel-platform/dependency-cruiser.base.json` | `config/dependency-cruiser.base.json` |
 | `mandrel-platform/size-limit.base.json`         | `config/size-limit.base.json`         |
 | `mandrel-platform/lighthouse.base.json`         | `config/lighthouse.base.json`         |
+| `mandrel-platform/lighthouse-thresholds.base.json` | `config/lighthouse-thresholds.base.json` |
 | `mandrel-platform/pnpm-workspace.supply-chain.yaml` | `config/pnpm-workspace.supply-chain.yaml` |
 | `mandrel-platform/edge-security`                | `config/edge-security/index.mjs`      |
 | `mandrel-platform/edge-security/*`              | `config/edge-security/*`              |

package/config/biome.base.json

@@ -1,12 +1,11 @@
 {
-  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
-  "organizeImports": {
-    "enabled": true
-  },
+  "root": false,
+  "$schema": "https://biomejs.dev/schemas/2.5.0/schema.json",
+  "assist": { "actions": { "source": { "organizeImports": "on" } } },
   "linter": {
     "enabled": true,
     "rules": {
-      "recommended": true
+      "preset": "recommended"
     }
   },
   "formatter": {

package/config/lighthouse-thresholds.base.json

@@ -0,0 +1,9 @@
+{
+  "_comment": "Mechanism-neutral Lighthouse score-floor thresholds for mandrel-platform consumers (refs #157). Runner-agnostic: both an LHCI `lighthouserc` (via lighthouse.base.json, which spreads this file's `categories` into its `ci.assert.assertions`) and a bespoke puppeteer + baseline-drift script (reading `categories` directly against each category's `lighthouse-result.categories.<key>.score`) can consume the same floors. Consumer-tunable: override any entry locally in either mechanism.",
+  "categories": {
+    "performance": 0.9,
+    "accessibility": 0.9,
+    "best-practices": 0.9,
+    "seo": 0.9
+  }
+}

package/config/lighthouse.base.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Shared Lighthouse CI base for mandrel-platform consumers. Lighthouse's `lighthouserc.json` has no whole-file `extends`, so this ships the shared `ci` block (collect settings + category assertions on the recommended preset). Consumers deep-merge it and add repo-specific `ci.collect.url` / `ci.collect.staticDistDir` and any per-repo assertion overrides (see README). Category score floors stay consumer-tunable.",
+  "_comment": "Shared Lighthouse CI base for mandrel-platform LHCI (@lhci/cli) consumers. Lighthouse's `lighthouserc.json` has no whole-file `extends`, so this ships the shared `ci` block (collect settings + category assertions on the recommended preset). Consumers deep-merge it and add repo-specific `ci.collect.url` / `ci.collect.staticDistDir` and any per-repo assertion overrides (see README). The `categories:*` minScore floors below are sourced from the mechanism-neutral `mandrel-platform/lighthouse-thresholds.base.json` (refs #157) — keep the two files' scores in sync when a floor changes. Consumers who run Lighthouse via a bespoke puppeteer + baseline-drift script instead of @lhci/cli should extend `lighthouse-thresholds.base.json` directly rather than this file (see README). Category score floors stay consumer-tunable.",
   "ci": {
     "collect": {
       "numberOfRuns": 3,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {
@@ -24,6 +24,7 @@
     "./dependency-cruiser.base.json": "./config/dependency-cruiser.base.json",
     "./size-limit.base.json": "./config/size-limit.base.json",
     "./lighthouse.base.json": "./config/lighthouse.base.json",
+    "./lighthouse-thresholds.base.json": "./config/lighthouse-thresholds.base.json",
     "./pnpm-workspace.supply-chain.yaml": "./config/pnpm-workspace.supply-chain.yaml",
     "./edge-security": "./config/edge-security/index.mjs",
     "./edge-security/*": "./config/edge-security/*",
@@ -40,7 +41,7 @@
     "provenance": true
   },
   "dependencies": {
-    "mandrel": "^1.78.0"
+    "mandrel": "^1.81.0"
   },
   "scripts": {
     "typecheck": "node --input-type=module --eval 'process.exit(0)'",

package/scripts/check-coverage-threshold.mjs

@@ -127,10 +127,19 @@ export function meetsThreshold(pct, threshold) {
 }
 
 /**
- * Recursively find every `coverage-summary.json` under `coverage/` directories
- * below `root`. `node_modules` and dotted dirs (e.g. `.git`, `.agents`) are
- * pruned so the scan stays fast and never reads a vendored framework tree.
- * `roots` (from `--coverage-dir`) overrides the auto-scan when provided.
+ * Recursively find every `coverage-summary.json` under `root`, regardless of
+ * the name of the directory that directly contains it. `node_modules` and
+ * dotted dirs (e.g. `.git`, `.agents`) are pruned so the scan stays fast and
+ * never reads a vendored framework tree. `roots` (from `--coverage-dir`)
+ * overrides the auto-scan when provided.
+ *
+ * A directory literally named `coverage` (the common single-workspace shape)
+ * is still discovered, but so is a per-workspace fan-out layout where the
+ * top-level `coverage/` dir nests differently-named subdirectories per
+ * package (e.g. `coverage/web/coverage-summary.json`,
+ * `coverage/shared/coverage-summary.json`) — the match condition is "this
+ * directory contains a coverage-summary.json file", not "this directory is
+ * named coverage".
  */
 export function findCoverageSummaries(root, roots = []) {
   if (roots.length > 0) {
@@ -151,17 +160,13 @@ export function findCoverageSummaries(root, roots = []) {
     } catch {
       return;
     }
+    const file = join(dir, "coverage-summary.json");
+    if (existsSync(file)) found.push(file);
     for (const entry of entries) {
       const name = entry.name;
       if (!entry.isDirectory()) continue;
       if (name === "node_modules" || name.startsWith(".")) continue;
-      const full = join(dir, name);
-      if (name === "coverage") {
-        const file = join(full, "coverage-summary.json");
-        if (existsSync(file)) found.push(file);
-        // A coverage dir may still nest sub-package coverage; keep walking.
-      }
-      walk(full);
+      walk(join(dir, name));
     }
   };
   walk(resolve(root));

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

@@ -14,11 +14,21 @@
  */
 
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import {
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { test } from "node:test";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
 import {
   VALID_METRICS,
   parseArgs,
@@ -33,11 +43,21 @@ import {
 } from "./check-coverage-threshold.mjs";
 
 // Build a minimal Istanbul/c8/vitest-shaped coverage-summary object.
-function summary({ lines = 0, statements = 0, functions = 0, branches = 0 } = {}) {
+function summary({
+  lines = 0,
+  statements = 0,
+  functions = 0,
+  branches = 0,
+} = {}) {
   return {
     total: {
       lines: { total: 100, covered: lines, skipped: 0, pct: lines },
-      statements: { total: 100, covered: statements, skipped: 0, pct: statements },
+      statements: {
+        total: 100,
+        covered: statements,
+        skipped: 0,
+        pct: statements,
+      },
       functions: { total: 100, covered: functions, skipped: 0, pct: functions },
       branches: { total: 100, covered: branches, skipped: 0, pct: branches },
     },
@@ -80,10 +100,14 @@ test("parseArgs defaults: threshold 0, metric lines", () => {
 
 test("parseArgs reads --threshold/--metric/--coverage-dir", () => {
   const opts = parseArgs([
-    "--threshold", "85",
-    "--metric", "Statements",
-    "--coverage-dir", "packages/api/coverage",
-    "--coverage-dir", "packages/web/coverage",
+    "--threshold",
+    "85",
+    "--metric",
+    "Statements",
+    "--coverage-dir",
+    "packages/api/coverage",
+    "--coverage-dir",
+    "packages/web/coverage",
   ]);
   assert.equal(opts.threshold, 85);
   assert.equal(opts.metric, "statements"); // normalized lowercase
@@ -98,7 +122,12 @@ test("parseArgs rejects an unknown --metric", () => {
 });
 
 test("VALID_METRICS covers the four Istanbul totals", () => {
-  assert.deepEqual(VALID_METRICS, ["lines", "statements", "functions", "branches"]);
+  assert.deepEqual(VALID_METRICS, [
+    "lines",
+    "statements",
+    "functions",
+    "branches",
+  ]);
 });
 
 // ---------------------------------------------------------------------------
@@ -141,7 +170,7 @@ test("evaluateGate: threshold 0 is a no-op pass (skipped)", () => {
       read: () => {
         throw new Error("read should not run when gate is disabled");
       },
-    }
+    },
   );
   assert.equal(verdict.ok, true);
   assert.equal(verdict.skipped, true);
@@ -158,7 +187,7 @@ test("evaluateGate: SET + measured above floor → pass", () => {
     {
       findSummaries: () => ["/x/coverage/coverage-summary.json"],
       read: () => summary({ lines: 91 }),
-    }
+    },
   );
   assert.equal(verdict.ok, true);
   assert.equal(verdict.skipped, false);
@@ -172,7 +201,7 @@ test("evaluateGate: SET + measured below floor → fail", () => {
     {
       findSummaries: () => ["/x/coverage/coverage-summary.json"],
       read: () => summary({ lines: 73 }),
-    }
+    },
   );
   assert.equal(verdict.ok, false);
   assert.equal(verdict.results[0].pct, 73);
@@ -185,7 +214,7 @@ test("evaluateGate: SET but no coverage summary found → fail (never silent-pas
     {
       findSummaries: () => [],
       read: () => null,
-    }
+    },
   );
   assert.equal(verdict.ok, false);
   assert.equal(verdict.skipped, false);
@@ -196,9 +225,15 @@ test("evaluateGate: SET, one of many packages below floor → fail", () => {
   const verdict = evaluateGate(
     { threshold: 80, metric: "statements", cwd: ".", coverageDirs: [] },
     {
-      findSummaries: () => ["a/coverage/coverage-summary.json", "b/coverage/coverage-summary.json"],
-      read: (f) => (f.startsWith("a") ? summary({ statements: 95 }) : summary({ statements: 40 })),
-    }
+      findSummaries: () => [
+        "a/coverage/coverage-summary.json",
+        "b/coverage/coverage-summary.json",
+      ],
+      read: (f) =>
+        f.startsWith("a")
+          ? summary({ statements: 95 })
+          : summary({ statements: 40 }),
+    },
   );
   assert.equal(verdict.ok, false);
   assert.equal(verdict.results.length, 2);
@@ -217,24 +252,29 @@ test("findCoverageSummaries auto-scans **/coverage/, pruning node_modules + dott
     mkdirSync(join(root, "packages", "api", "coverage"), { recursive: true });
     writeFileSync(
       join(root, "packages", "api", "coverage", "coverage-summary.json"),
-      JSON.stringify(summary({ lines: 88 }))
+      JSON.stringify(summary({ lines: 88 })),
     );
     // A decoy under node_modules that MUST be pruned.
-    mkdirSync(join(root, "node_modules", "dep", "coverage"), { recursive: true });
+    mkdirSync(join(root, "node_modules", "dep", "coverage"), {
+      recursive: true,
+    });
     writeFileSync(
       join(root, "node_modules", "dep", "coverage", "coverage-summary.json"),
-      JSON.stringify(summary({ lines: 1 }))
+      JSON.stringify(summary({ lines: 1 })),
     );
     // A decoy under a dotted dir that MUST be pruned.
     mkdirSync(join(root, ".agents", "coverage"), { recursive: true });
     writeFileSync(
       join(root, ".agents", "coverage", "coverage-summary.json"),
-      JSON.stringify(summary({ lines: 2 }))
+      JSON.stringify(summary({ lines: 2 })),
     );
 
     const files = findCoverageSummaries(root);
     assert.equal(files.length, 1);
-    assert.match(files[0], /packages[/\\]api[/\\]coverage[/\\]coverage-summary\.json$/);
+    assert.match(
+      files[0],
+      /packages[/\\]api[/\\]coverage[/\\]coverage-summary\.json$/,
+    );
 
     const parsed = readSummary(files[0]);
     assert.equal(extractPct(parsed, "lines"), 88);
@@ -243,13 +283,57 @@ test("findCoverageSummaries auto-scans **/coverage/, pruning node_modules + dott
   }
 });
 
+test("findCoverageSummaries discovers a per-workspace fan-out layout (coverage/<workspace>/coverage-summary.json)", () => {
+  const root = mkdtempSync(join(tmpdir(), "cov-gate-"));
+  try {
+    // domio's shape: top-level coverage/ dir nests per-workspace subdirs that
+    // are NOT themselves named "coverage".
+    mkdirSync(join(root, "coverage", "web"), { recursive: true });
+    writeFileSync(
+      join(root, "coverage", "web", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 77 })),
+    );
+    mkdirSync(join(root, "coverage", "shared"), { recursive: true });
+    writeFileSync(
+      join(root, "coverage", "shared", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 93 })),
+    );
+    // Decoys that must still be pruned.
+    mkdirSync(join(root, "node_modules", "dep", "coverage"), {
+      recursive: true,
+    });
+    writeFileSync(
+      join(root, "node_modules", "dep", "coverage", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 1 })),
+    );
+    mkdirSync(join(root, ".agents", "coverage"), { recursive: true });
+    writeFileSync(
+      join(root, ".agents", "coverage", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 2 })),
+    );
+
+    const files = findCoverageSummaries(root).sort();
+    assert.equal(files.length, 2);
+    assert.ok(
+      files.some((f) =>
+        /coverage[/\\]shared[/\\]coverage-summary\.json$/.test(f),
+      ),
+    );
+    assert.ok(
+      files.some((f) => /coverage[/\\]web[/\\]coverage-summary\.json$/.test(f)),
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("findCoverageSummaries honours explicit --coverage-dir roots", () => {
   const root = mkdtempSync(join(tmpdir(), "cov-gate-"));
   try {
     mkdirSync(join(root, "custom", "cov"), { recursive: true });
     writeFileSync(
       join(root, "custom", "cov", "coverage-summary.json"),
-      JSON.stringify(summary({ lines: 90 }))
+      JSON.stringify(summary({ lines: 90 })),
     );
     const files = findCoverageSummaries(root, ["custom/cov"]);
     assert.equal(files.length, 1);
@@ -291,7 +375,7 @@ test("runCli: threshold set, real passing coverage tree → exit 0", () => {
     mkdirSync(join(root, "coverage"), { recursive: true });
     writeFileSync(
       join(root, "coverage", "coverage-summary.json"),
-      JSON.stringify(summary({ lines: 95 }))
+      JSON.stringify(summary({ lines: 95 })),
     );
     const out = [];
     const code = runCli(["--threshold", "80", "--cwd", root], {
@@ -311,7 +395,7 @@ test("runCli: threshold set, real failing coverage tree → exit 1", () => {
     mkdirSync(join(root, "coverage"), { recursive: true });
     writeFileSync(
       join(root, "coverage", "coverage-summary.json"),
-      JSON.stringify(summary({ lines: 50 }))
+      JSON.stringify(summary({ lines: 50 })),
     );
     const out = [];
     const code = runCli(["--threshold", "80", "--cwd", root], {
@@ -342,9 +426,179 @@ test("runCli: threshold set but no coverage data → exit 1", () => {
 
 test("formatVerdict renders a skip line for the disabled gate", () => {
   const lines = formatVerdict({
-    ok: true, skipped: true, reason: "threshold 0 — coverage gate disabled (no-op)",
-    threshold: 0, metric: "lines", results: [],
+    ok: true,
+    skipped: true,
+    reason: "threshold 0 — coverage gate disabled (no-op)",
+    threshold: 0,
+    metric: "lines",
+    results: [],
   });
   assert.equal(lines.length, 1);
   assert.match(lines[0], /⏭️/);
 });
+
+// ---------------------------------------------------------------------------
+// pr-quality.yml Coverage threshold gate — inline step regression (#163)
+//
+// The workflow step embeds its OWN copy of the discovery logic (it must stay
+// dependency-free for consumer checkouts that have not adopted
+// check-coverage-threshold.mjs). #158 fixed only the standalone script; this
+// suite's `findCoverageSummaries` tests above cannot catch a regression in the
+// workflow file's embedded JS. These tests extract that embedded node script
+// straight out of pr-quality.yml and run it against real fixture trees, so the
+// exact #163 bug (matching a directory literally named `coverage`, missing
+// `coverage/<workspace>/coverage-summary.json`) cannot survive a refactor.
+// ---------------------------------------------------------------------------
+
+// Pull the embedded `node --input-type=module - <<'NODE' … NODE` script body
+// out of the "Coverage threshold gate" step, de-indenting the YAML block
+// scalar so it runs as a standalone ES module.
+function extractGateScript() {
+  const yaml = readFileSync(
+    join(__dirname, "..", ".github", "workflows", "pr-quality.yml"),
+    "utf8",
+  );
+  const lines = yaml.split(/\r?\n/);
+  const startIdx = lines.findIndex((l) =>
+    /node --input-type=module - <<'NODE'\s*$/.test(l),
+  );
+  assert.ok(
+    startIdx !== -1,
+    "expected an embedded `<<'NODE'` heredoc in pr-quality.yml",
+  );
+  // The heredoc opener carries the block-scalar indent; every body line shares
+  // at least that indent, and the closing `NODE` sentinel sits at the same
+  // indent. Strip it uniformly.
+  const indent = lines[startIdx].match(/^(\s*)/)[1];
+  const body = [];
+  for (let i = startIdx + 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === "NODE") return body.join("\n");
+    body.push(
+      lines[i].startsWith(indent) ? lines[i].slice(indent.length) : lines[i],
+    );
+  }
+  throw new Error("unterminated `NODE` heredoc in pr-quality.yml gate step");
+}
+
+// Run the extracted gate script with COVERAGE_THRESHOLD / COVERAGE_METRIC set
+// and cwd pointed at `treeRoot`. Returns { status, stdout, stderr }.
+function runGateStep(treeRoot, { threshold = "0", metric = "lines" } = {}) {
+  const scriptPath = join(treeRoot, "__gate-step.mjs");
+  writeFileSync(scriptPath, extractGateScript());
+  try {
+    const stdout = execFileSync("node", [scriptPath], {
+      cwd: treeRoot,
+      env: {
+        ...process.env,
+        COVERAGE_THRESHOLD: threshold,
+        COVERAGE_METRIC: metric,
+      },
+      encoding: "utf8",
+    });
+    return { status: 0, stdout, stderr: "" };
+  } catch (err) {
+    return {
+      status: err.status ?? 1,
+      stdout: err.stdout?.toString() ?? "",
+      stderr: err.stderr?.toString() ?? "",
+    };
+  }
+}
+
+test("pr-quality gate step discovers a per-workspace coverage/<ws>/ layout (#163 regression)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gate-step-fanout-"));
+  try {
+    // Per-workspace fan-out: NO top-level coverage/coverage-summary.json,
+    // only coverage/web/ and coverage/shared/ — the exact shape that the
+    // pre-#158 literal-`coverage`-name match missed.
+    mkdirSync(join(dir, "coverage", "web"), { recursive: true });
+    mkdirSync(join(dir, "coverage", "shared"), { recursive: true });
+    writeFileSync(
+      join(dir, "coverage", "web", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 95 })),
+    );
+    writeFileSync(
+      join(dir, "coverage", "shared", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 90 })),
+    );
+
+    const res = runGateStep(dir, { threshold: "80", metric: "lines" });
+    assert.equal(
+      res.status,
+      0,
+      `gate step should PASS on the fan-out layout, got exit ${res.status}\n${res.stderr}`,
+    );
+    // Both per-workspace summaries were discovered and gated — not the
+    // "no coverage-summary.json was found" false failure.
+    assert.doesNotMatch(res.stderr, /no coverage-summary\.json/);
+    assert.match(res.stdout, /coverage[/\\]web[/\\]coverage-summary\.json/);
+    assert.match(res.stdout, /coverage[/\\]shared[/\\]coverage-summary\.json/);
+    assert.match(res.stdout, /coverage meets the 80% floor/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("pr-quality gate step: per-workspace summary below floor fails (#163 regression)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gate-step-fanout-fail-"));
+  try {
+    mkdirSync(join(dir, "coverage", "web"), { recursive: true });
+    writeFileSync(
+      join(dir, "coverage", "web", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 40 })),
+    );
+    const res = runGateStep(dir, { threshold: "80", metric: "lines" });
+    assert.equal(
+      res.status,
+      1,
+      "below-floor per-workspace coverage must fail the gate",
+    );
+    assert.match(res.stderr, /coverage[/\\]web[/\\]coverage-summary\.json/);
+    assert.match(res.stderr, /below the 80% floor/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("pr-quality gate step stays byte-for-byte compatible with the single coverage/ dir shape (#163)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gate-step-single-"));
+  try {
+    // Legacy single-workspace shape: coverage/coverage-summary.json directly.
+    mkdirSync(join(dir, "coverage"), { recursive: true });
+    writeFileSync(
+      join(dir, "coverage", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 88 })),
+    );
+    // node_modules + dotted dirs must still be pruned (never read a vendored
+    // coverage tree).
+    mkdirSync(join(dir, "node_modules", "pkg", "coverage"), {
+      recursive: true,
+    });
+    writeFileSync(
+      join(dir, "node_modules", "pkg", "coverage", "coverage-summary.json"),
+      JSON.stringify(summary({ lines: 1 })),
+    );
+    const res = runGateStep(dir, { threshold: "80", metric: "lines" });
+    assert.equal(
+      res.status,
+      0,
+      `single-dir shape should PASS, got exit ${res.status}\n${res.stderr}`,
+    );
+    assert.match(res.stdout, /coverage[/\\]coverage-summary\.json/);
+    assert.doesNotMatch(res.stdout, /node_modules/);
+    assert.doesNotMatch(res.stderr, /node_modules/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("pr-quality gate step still hard-fails when threshold set but no summary exists (#163)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gate-step-empty-"));
+  try {
+    const res = runGateStep(dir, { threshold: "80", metric: "lines" });
+    assert.equal(res.status, 1, "a set floor must not pass on missing data");
+    assert.match(res.stderr, /no coverage-summary\.json/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});