@getarbiter/cli 0.5.0

package/dist/templates/scripts/test-gate-layering.mjs.ejs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// <%= projectName %> — gate-layering contract test (#2041, AC-2041.3).
+// Asserts the structural containment L1 ⊂ L2 ⊂ L3 from the DECLARATIVE gate
+// registry embedded in scripts/check-all.mjs (the #2041 registry, not a
+// re-derivation): every L1 gate must be a subset of the L2 slice, which must
+// be a subset of the L3 slice, and each gate must belong to exactly one level.
+// Exits 0 when the contract holds; 1 when it is violated.
+// Exit codes (INV-53): 0 = PASS, 1 = FAIL, 2 = ERROR.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CWD = process.cwd();
+const GATE_PATH = join(CWD, 'scripts', 'check-all.mjs');
+
+if (!existsSync(GATE_PATH)) {
+  process.stderr.write(`test-gate-layering: FAIL — ${GATE_PATH} not found\n`);
+  process.exit(2);
+}
+
+const gateSrc = readFileSync(GATE_PATH, 'utf-8');
+const match = gateSrc.match(/const GATE_REGISTRY = (\[.*?\]);\n/s);
+if (!match) {
+  process.stderr.write('test-gate-layering: FAIL — no GATE_REGISTRY embedded in check-all.mjs\n');
+  process.exit(2);
+}
+let registry;
+try {
+  registry = JSON.parse(match[1]);
+} catch (err) {
+  process.stderr.write(`test-gate-layering: FAIL — GATE_REGISTRY is not valid JSON: ${err.message}\n`);
+  process.exit(2);
+}
+if (!Array.isArray(registry)) {
+  process.stderr.write('test-gate-layering: FAIL — GATE_REGISTRY is not an array\n');
+  process.exit(2);
+}
+
+const byLevel = { L1: [], L2: [], L3: [] };
+for (const gate of registry) {
+  if (!gate || typeof gate.id !== 'string' || !byLevel[gate.level]) {
+    process.stderr.write(
+      `test-gate-layering: FAIL — malformed registry entry: ${JSON.stringify(gate)}\n`,
+    );
+    process.exit(2);
+  }
+  byLevel[gate.level].push(gate.id);
+}
+
+const violations = [];
+const l1 = new Set(byLevel.L1);
+const l2 = new Set(byLevel.L2);
+const l3 = new Set(byLevel.L3);
+
+// Each gate belongs to exactly one level.
+for (const id of byLevel.L1) {
+  if (l2.has(id) || l3.has(id)) violations.push(`gate ${id} appears in more than one level`);
+}
+for (const id of byLevel.L2) {
+  if (l3.has(id)) violations.push(`gate ${id} appears in more than one level`);
+}
+
+// Containment: the slice run at each level is cumulative — slice(L1) = L1,
+// slice(L2) = L1 ∪ L2, slice(L3) = L1 ∪ L2 ∪ L3 — so the structural contract
+// `L1 ⊂ L2 ⊂ L3` holds iff slice(L1) ⊆ slice(L2) ⊆ slice(L3) AND each level
+// contributes at least one gate (a level with zero gates would be a phantom
+// lane). The emitted check-all runs L1 gates always, L2 at L2+, L3 at L3+.
+const sliceL2 = new Set([...l1, ...l2]);
+const sliceL3 = new Set([...l1, ...l2, ...l3]);
+for (const id of l1) {
+  if (!sliceL2.has(id) || !sliceL3.has(id)) {
+    violations.push(`L1 gate ${id} missing from the cumulative L2/L3 slice (L1 ⊄ L2 ⊂ L3)`);
+  }
+}
+for (const id of l2) {
+  if (!sliceL3.has(id)) {
+    violations.push(`L2 gate ${id} missing from the cumulative L3 slice (L2 ⊄ L3)`);
+  }
+}
+if (l1.size === 0) violations.push('L1 lane declares zero gates');
+if (l2.size === 0) violations.push('L2 lane declares zero gates');
+if (l3.size === 0) violations.push('L3 lane declares zero gates');
+
+if (violations.length > 0) {
+  process.stderr.write(`test-gate-layering: FAIL — ${violations.length} layering violation(s):\n`);
+  for (const v of violations) process.stderr.write(`  - ${v}\n`);
+  process.exit(1);
+}
+
+process.stdout.write(
+  `test-gate-layering: PASS — ${byLevel.L1.length} L1 + ${byLevel.L2.length} L2 + ${byLevel.L3.length} L3 gates, containment L1 ⊂ L2 ⊂ L3 holds\n`,
+);
+process.exit(0);

package/dist/templates/scripts/validate-api-snapshots.mjs.ejs

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// validate-api-snapshots.mjs — API contract snapshot changeset validator
+//
+// Generated by arbiter (#896) — F9: API contract baselines template
+// Emitted when contractType=rest-owned for Java projects.
+//
+// Purpose:
+//   Verifies that the api-snapshots/ JSON baseline files are structurally sound
+//   and reports any missing or malformed snapshot files. Run this before committing
+//   snapshot updates to catch accidental contract breakage.
+//
+// Usage:
+//   node scripts/validate-api-snapshots.mjs [--dir src/test/resources/api-snapshots]
+//
+// Exit codes:
+//   0 — all snapshots valid
+//   1 — one or more snapshots invalid or missing
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const args = process.argv.slice(2)
+const dirIdx = args.indexOf('--dir')
+const SNAPSHOTS_DIR = resolve(
+  dirIdx >= 0 ? args[dirIdx + 1] : 'src/test/resources/api-snapshots',
+)
+
+// Expected snapshot filenames — update this list when new baselines are added.
+const EXPECTED_SNAPSHOTS = [
+  'openapi-baseline.json',
+  'openapi-paths-baseline.json',
+  'openapi-response-status-baseline.json',
+  'openapi-content-types-baseline.json',
+  'openapi-required-fields-baseline.json',
+  'config-response-baseline.json',
+  'config-keys-baseline.json',
+  'enum-values-baseline.json',
+  'error-shape-baseline.json',
+  'test-snapshot.json',
+]
+
+let exitCode = 0
+const errors = []
+
+if (!existsSync(SNAPSHOTS_DIR)) {
+  console.error(`[validate-api-snapshots] ERROR: directory not found: ${SNAPSHOTS_DIR}`)
+  console.error('  Run the contract test suite once with SNAPSHOT_UPDATE=true to generate baselines.')
+  process.exit(1)
+}
+
+// Check each expected snapshot exists and is valid JSON
+for (const name of EXPECTED_SNAPSHOTS) {
+  const filePath = join(SNAPSHOTS_DIR, name)
+  if (!existsSync(filePath)) {
+    errors.push(`MISSING: ${name}`)
+    exitCode = 1
+    continue
+  }
+  try {
+    const raw = readFileSync(filePath, 'utf-8')
+    JSON.parse(raw)
+    console.log(`[validate-api-snapshots] OK: ${name}`)
+  } catch {
+    errors.push(`INVALID JSON: ${name}`)
+    exitCode = 1
+  }
+}
+
+// Report any unexpected files (informational, not an error)
+const actual = readdirSync(SNAPSHOTS_DIR).filter((f) => f.endsWith('.json'))
+const unexpected = actual.filter((f) => !EXPECTED_SNAPSHOTS.includes(f))
+if (unexpected.length > 0) {
+  console.warn(`[validate-api-snapshots] WARN: unexpected snapshot files (not in expected list):`)
+  for (const f of unexpected) {
+    console.warn(`  ${f}`)
+  }
+}
+
+if (errors.length > 0) {
+  console.error('\n[validate-api-snapshots] FAILURES:')
+  for (const e of errors) {
+    console.error(`  ${e}`)
+  }
+}
+
+process.exit(exitCode)

package/dist/templates/scripts/validate-k6-scenarios.mjs.ejs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// k6 scenario completeness validator (#895)
+// Checks that all scenario files are structurally sound before running CI.
+// Exit code 0 = all scenarios valid; exit code 1 = one or more issues found.
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const SCENARIOS_DIR = resolve(__dirname, '..', 'perf', 'k6', 'scenarios')
+const REQUIRED_ENTRY_POINT = 'export default function'
+const REQUIRED_IMPORT = "from 'k6"
+
+const REQUIRED_SCENARIOS = [
+  'load',
+  'stress',
+  'spike',
+  'soak',
+  'smoke',
+  'ramp-up',
+  'ramp-down',
+  'steady-state',
+  'burst',
+  'endurance',
+]
+
+let errors = 0
+
+function fail(msg) {
+  console.error(`  [FAIL] ${msg}`)
+  errors++
+}
+
+function pass(msg) {
+  console.log(`  [PASS] ${msg}`)
+}
+
+// ── 1. Scenarios directory must exist ────────────────────────────────────────
+console.log('\nValidating k6 scenarios...\n')
+
+if (!existsSync(SCENARIOS_DIR)) {
+  console.error(`[ERROR] Scenarios directory not found: ${SCENARIOS_DIR}`)
+  process.exit(1)
+}
+
+const scenarioFiles = readdirSync(SCENARIOS_DIR).filter((f) => f.endsWith('.js'))
+
+// ── 2. Required scenarios must be present ────────────────────────────────────
+console.log('Required scenarios:')
+for (const name of REQUIRED_SCENARIOS) {
+  const file = `${name}.js`
+  if (scenarioFiles.includes(file)) {
+    pass(file)
+  } else {
+    fail(`Missing required scenario: ${file}`)
+  }
+}
+
+// ── 3. Each scenario must have the k6 entry point and import ─────────────────
+console.log('\nScenario structure:')
+for (const file of scenarioFiles) {
+  const filePath = join(SCENARIOS_DIR, file)
+  const content = readFileSync(filePath, 'utf-8')
+
+  let fileOk = true
+
+  if (!content.includes(REQUIRED_ENTRY_POINT)) {
+    fail(`${file}: missing "${REQUIRED_ENTRY_POINT}"`)
+    fileOk = false
+  }
+
+  if (!content.includes(REQUIRED_IMPORT)) {
+    fail(`${file}: missing k6 import (expected "${REQUIRED_IMPORT}...")`)
+    fileOk = false
+  }
+
+  if (!content.includes('options')) {
+    fail(`${file}: missing exported options object`)
+    fileOk = false
+  }
+
+  if (fileOk) {
+    pass(`${file}: entry point + import + options present`)
+  }
+}
+
+// ── Result ────────────────────────────────────────────────────────────────────
+console.log()
+if (errors === 0) {
+  console.log(`All ${scenarioFiles.length} scenario(s) validated successfully.`)
+  process.exit(0)
+} else {
+  console.error(`Validation failed with ${errors} error(s).`)
+  process.exit(1)
+}

package/dist/templates/scripts/validate-openapi-field-types.mjs.ejs

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// validate-openapi-field-types.mjs — OpenAPI schema field-type validator
+//
+// Generated by arbiter (#896) — F9: API contract baselines template
+// Emitted when contractType=rest-owned for Java projects.
+//
+// Purpose:
+//   Validates that the OpenAPI specification contains no untyped or
+//   ambiguously-typed fields. Checks that all schema properties have
+//   explicit `type` declarations and that enum fields list their values.
+//   Compares against the openapi-baseline.json snapshot to detect drift.
+//
+// Usage:
+//   node scripts/validate-openapi-field-types.mjs [--spec <path>] [--baseline <path>]
+//
+// Environment:
+//   OPENAPI_SPEC_URL — URL to fetch the live OpenAPI spec (default: http://localhost:8080/v3/api-docs)
+//   OPENAPI_SPEC_FILE — path to a local spec file (takes precedence over URL)
+//
+// Exit codes:
+//   0 — all field types valid
+//   1 — untyped fields or drift detected
+
+import { readFileSync, existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const args = process.argv.slice(2)
+
+function argValue(flag) {
+  const idx = args.indexOf(flag)
+  return idx >= 0 ? args[idx + 1] : null
+}
+
+const BASELINE_PATH = resolve(
+  argValue('--baseline') ?? 'src/test/resources/api-snapshots/openapi-baseline.json',
+)
+const SPEC_FILE = process.env.OPENAPI_SPEC_FILE ?? argValue('--spec')
+const SPEC_URL = process.env.OPENAPI_SPEC_URL ?? 'http://localhost:8080/v3/api-docs'
+
+let exitCode = 0
+const errors = []
+
+/**
+ * Recursively find all schema properties that lack an explicit `type`.
+ */
+function findUntypedProperties(schemas, prefix = '') {
+  const untyped = []
+  for (const [schemaName, schema] of Object.entries(schemas ?? {})) {
+    const props = schema.properties ?? {}
+    for (const [propName, propDef] of Object.entries(props)) {
+      const path = `${prefix}${schemaName}.${propName}`
+      if (!propDef.type && !propDef.$ref && !propDef.allOf && !propDef.oneOf && !propDef.anyOf) {
+        untyped.push(path)
+      }
+    }
+  }
+  return untyped
+}
+
+async function loadSpec() {
+  if (SPEC_FILE && existsSync(SPEC_FILE)) {
+    console.log(`[validate-openapi-field-types] Loading spec from file: ${SPEC_FILE}`)
+    return JSON.parse(readFileSync(SPEC_FILE, 'utf-8'))
+  }
+
+  console.log(`[validate-openapi-field-types] Fetching openapi spec from: ${SPEC_URL}`)
+  try {
+    const res = await fetch(SPEC_URL)
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}`)
+    }
+    return await res.json()
+  } catch (err) {
+    console.error(`[validate-openapi-field-types] ERROR: could not load openapi spec: ${err.message}`)
+    console.error('  Set OPENAPI_SPEC_FILE to a local spec path, or ensure the service is running.')
+    process.exit(2)
+  }
+}
+
+const spec = await loadSpec()
+const schemas = spec?.components?.schemas ?? {}
+
+if (Object.keys(schemas).length === 0) {
+  console.warn('[validate-openapi-field-types] WARN: no schemas found in openapi spec — skipping field-type check.')
+  process.exit(0)
+}
+
+// Check for untyped properties
+const untypedFields = findUntypedProperties(schemas)
+if (untypedFields.length > 0) {
+  console.error('[validate-openapi-field-types] ERROR: untyped schema properties found:')
+  for (const f of untypedFields) {
+    console.error(`  ${f}`)
+  }
+  errors.push(`${untypedFields.length} untyped field(s)`)
+  exitCode = 1
+} else {
+  console.log(`[validate-openapi-field-types] OK: all ${Object.keys(schemas).length} schema(s) have typed properties`)
+}
+
+// Compare paths against baseline if available
+if (existsSync(BASELINE_PATH)) {
+  const baseline = JSON.parse(readFileSync(BASELINE_PATH, 'utf-8'))
+  const baselineSchemas = Object.keys(baseline?.components?.schemas ?? {}).sort()
+  const currentSchemas = Object.keys(schemas).sort()
+
+  const removed = baselineSchemas.filter((s) => !currentSchemas.includes(s))
+  if (removed.length > 0) {
+    console.error('[validate-openapi-field-types] BREAKING: schemas removed vs baseline:')
+    for (const s of removed) {
+      console.error(`  ${s}`)
+    }
+    errors.push(`${removed.length} schema(s) removed`)
+    exitCode = 1
+  }
+} else {
+  console.warn(`[validate-openapi-field-types] WARN: baseline not found at ${BASELINE_PATH} — skipping drift check.`)
+}
+
+if (errors.length > 0) {
+  console.error(`\n[validate-openapi-field-types] FAILURES: ${errors.join(', ')}`)
+}
+
+process.exit(exitCode)

package/dist/templates/scripts/validate-postman-collection.mjs.ejs

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: Apache-2.0
+// validate-postman-collection.mjs — Postman collection structural validator
+//
+// Generated by arbiter (#896) — F9: API contract baselines template
+// Emitted when contractType=rest-owned for Java projects.
+//
+// Purpose:
+//   Validates that the project's Postman collection file is structurally complete:
+//   - Collection v2.1 schema compliance (required keys present)
+//   - All requests have at least one test assertion
+//   - No requests reference undefined variables
+//   - Newman-compatible (no unsupported auth types)
+//
+// Usage:
+//   node scripts/validate-postman-collection.mjs [--collection <path>]
+//
+// Exit codes:
+//   0 — collection valid
+//   1 — structural errors found
+//   2 — collection file not found
+
+import { readFileSync, existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const args = process.argv.slice(2)
+const colIdx = args.indexOf('--collection')
+const DEFAULT_COLLECTION = 'postman/<%= projectName ? projectName.replace(/[^a-z0-9_-]/gi, "-").toLowerCase() : "api" %>.postman_collection.json'
+const COLLECTION_PATH = resolve(
+  colIdx >= 0 ? args[colIdx + 1] : (process.env.POSTMAN_COLLECTION ?? DEFAULT_COLLECTION),
+)
+
+if (!existsSync(COLLECTION_PATH)) {
+  console.error(`[validate-postman-collection] ERROR: collection not found: ${COLLECTION_PATH}`)
+  console.error('  Set POSTMAN_COLLECTION env var or pass --collection <path>')
+  process.exit(2)
+}
+
+let collection
+try {
+  collection = JSON.parse(readFileSync(COLLECTION_PATH, 'utf-8'))
+} catch (err) {
+  console.error(`[validate-postman-collection] ERROR: invalid JSON in collection: ${err.message}`)
+  process.exit(1)
+}
+
+let exitCode = 0
+const errors = []
+const warnings = []
+
+// ─── Schema compliance ────────────────────────────────────────────────────────
+
+const info = collection.info ?? {}
+if (!info.name) {
+  errors.push('collection.info.name is missing')
+  exitCode = 1
+}
+if (!info.schema) {
+  warnings.push('collection.info.schema is missing — cannot confirm Postman v2.1 compliance')
+} else if (!info.schema.includes('v2.1')) {
+  warnings.push(`collection schema is not v2.1: ${info.schema}`)
+}
+
+if (!Array.isArray(collection.item)) {
+  errors.push('collection.item is missing or not an array — no requests defined')
+  exitCode = 1
+}
+
+// ─── Request validation ───────────────────────────────────────────────────────
+
+function validateItems(items, path = '') {
+  let requestCount = 0
+  let assertionCount = 0
+  const undefinedVars = new Set()
+
+  for (const item of items ?? []) {
+    const itemPath = path ? `${path} > ${item.name}` : item.name
+    if (Array.isArray(item.item)) {
+      // Folder — recurse
+      const sub = validateItems(item.item, itemPath)
+      requestCount += sub.requestCount
+      assertionCount += sub.assertionCount
+      sub.undefinedVars.forEach((v) => undefinedVars.add(v))
+      continue
+    }
+    if (!item.request) continue
+
+    requestCount++
+
+    // Check for test assertions
+    const events = item.event ?? []
+    const testEvent = events.find((e) => e.listen === 'test')
+    if (!testEvent || !testEvent.script?.exec?.join('').includes('pm.test')) {
+      warnings.push(`no pm.test assertion in: ${itemPath}`)
+    } else {
+      assertionCount++
+    }
+
+    // Check for undefined variables ({{VAR}} pattern)
+    const urlStr = JSON.stringify(item.request.url ?? '')
+    const headerStr = JSON.stringify(item.request.header ?? [])
+    const bodyStr = JSON.stringify(item.request.body ?? {})
+    const combined = urlStr + headerStr + bodyStr
+    const varMatches = combined.match(/\{\{([^}]+)\}\}/g) ?? []
+    for (const match of varMatches) {
+      const varName = match.slice(2, -2)
+      // Common environment variables are expected — only flag truly unknown ones
+      const knownVars = ['baseUrl', 'BASE_URL', 'host', 'port', 'token', 'authToken', 'apiKey']
+      if (!knownVars.includes(varName)) {
+        undefinedVars.add(`{{${varName}}} in ${itemPath}`)
+      }
+    }
+  }
+
+  return { requestCount, assertionCount, undefinedVars }
+}
+
+const { requestCount, assertionCount, undefinedVars } = validateItems(collection.item)
+
+if (requestCount === 0) {
+  errors.push('collection contains no requests')
+  exitCode = 1
+} else {
+  console.log(
+    `[validate-postman-collection] ${requestCount} request(s) found, ${assertionCount} with pm.test assertions`,
+  )
+}
+
+if (undefinedVars.size > 0) {
+  console.warn('[validate-postman-collection] WARN: potentially undefined variables:')
+  for (const v of undefinedVars) {
+    console.warn(`  ${v}`)
+  }
+}
+
+// ─── Newman compatibility ─────────────────────────────────────────────────────
+
+const authType = collection.auth?.type
+const UNSUPPORTED_NEWMAN_AUTH = ['ntlm', 'hawk']
+if (authType && UNSUPPORTED_NEWMAN_AUTH.includes(authType)) {
+  errors.push(`auth type "${authType}" is not supported by newman`)
+  exitCode = 1
+}
+
+// ─── Summary ─────────────────────────────────────────────────────────────────
+
+for (const w of warnings) {
+  console.warn(`[validate-postman-collection] WARN: ${w}`)
+}
+
+if (errors.length > 0) {
+  console.error('\n[validate-postman-collection] FAILURES:')
+  for (const e of errors) {
+    console.error(`  ${e}`)
+  }
+} else {
+  console.log(`[validate-postman-collection] OK: collection "${info.name}" is newman-compatible`)
+}
+
+process.exit(exitCode)

package/dist/templates/scripts/verify-fe-coverage.mjs.ejs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: FE per-layer coverage ratchet (#1127 Slice 4).
+// Reads Vitest coverage-summary.json and enforces per-layer coverage
+// thresholds against fe-coverage-baseline.json. Upward-only ratchet:
+// coverage may increase but never decrease below the baseline.
+// Exit 1 if any layer falls below baseline − SLACK.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ROOT = process.cwd()
+const COVERAGE_FILE = join(ROOT, 'coverage', 'coverage-summary.json')
+const BASELINE_FILE = join(ROOT, 'fe-coverage-baseline.json')
+const SLACK = 0.5 // tolerated regression in percentage points
+const UPDATE_BASELINE = process.argv.includes('--update-baseline')
+
+if (!existsSync(COVERAGE_FILE)) {
+  if (existsSync(BASELINE_FILE)) {
+    // Baseline exists but coverage was not generated — this is a CI misconfiguration,
+    // not a first-run scenario. Exiting 0 here would produce a false-negative.
+    process.stderr.write(
+      '[verify-fe-coverage] FAIL: coverage-summary.json not found but fe-coverage-baseline.json exists.\n' +
+        '  Run vitest --coverage before this gate, or delete the baseline for a fresh project.\n',
+    )
+    process.exit(1)
+  }
+  // True first-run: no baseline and no coverage — seed baseline first.
+  process.stdout.write(
+    '[verify-fe-coverage] no baseline found — run with --update-baseline to seed, then re-run\n',
+  )
+  process.exit(0)
+}
+
+let coverageSummary
+try {
+  coverageSummary = JSON.parse(readFileSync(COVERAGE_FILE, 'utf-8'))
+} catch (err) {
+  process.stderr.write(`[verify-fe-coverage] failed to parse coverage-summary.json: ${err.message}\n`)
+  process.exit(1)
+}
+
+// Aggregate coverage by layer (FSD: app, pages, widgets, features, entities, shared)
+const FSD_LAYERS = ['app', 'pages', 'widgets', 'features', 'entities', 'shared']
+
+function classifyFile(filePath) {
+  for (const layer of FSD_LAYERS) {
+    if (filePath.includes(`/src/${layer}/`) || filePath.includes(`\\src\\${layer}\\`)) {
+      return layer
+    }
+  }
+  return 'other'
+}
+
+const layerStats = {}
+for (const [filePath, stats] of Object.entries(coverageSummary)) {
+  if (filePath === 'total') continue
+  const layer = classifyFile(filePath)
+  if (!layerStats[layer]) {
+    layerStats[layer] = { lines: { covered: 0, total: 0 }, branches: { covered: 0, total: 0 } }
+  }
+  layerStats[layer].lines.covered += stats.lines?.covered ?? 0
+  layerStats[layer].lines.total += stats.lines?.total ?? 0
+  layerStats[layer].branches.covered += stats.branches?.covered ?? 0
+  layerStats[layer].branches.total += stats.branches?.total ?? 0
+}
+
+// Compute percentages
+const layerPct = {}
+for (const [layer, s] of Object.entries(layerStats)) {
+  layerPct[layer] = {
+    lines: s.lines.total > 0 ? (s.lines.covered / s.lines.total) * 100 : 100,
+    branches: s.branches.total > 0 ? (s.branches.covered / s.branches.total) * 100 : 100,
+  }
+}
+
+if (UPDATE_BASELINE) {
+  const baseline = {}
+  for (const [layer, pct] of Object.entries(layerPct)) {
+    baseline[layer] = {
+      lines: Math.round(pct.lines * 100) / 100,
+      branches: Math.round(pct.branches * 100) / 100,
+    }
+  }
+  writeFileSync(BASELINE_FILE, JSON.stringify(baseline, null, 2) + '\n')
+  process.stdout.write(`[verify-fe-coverage] baseline updated (${Object.keys(baseline).length} layers)\n`)
+  process.exit(0)
+}
+
+if (!existsSync(BASELINE_FILE)) {
+  // No baseline yet — generate it on first run
+  process.stdout.write(
+    '[verify-fe-coverage] no baseline found — run with --update-baseline to seed\n',
+  )
+  process.exit(0)
+}
+
+let baseline
+try {
+  baseline = JSON.parse(readFileSync(BASELINE_FILE, 'utf-8'))
+} catch (err) {
+  process.stderr.write(`[verify-fe-coverage] failed to parse fe-coverage-baseline.json: ${err.message}\n`)
+  process.exit(1)
+}
+
+let violations = 0
+for (const [layer, base] of Object.entries(baseline)) {
+  const current = layerPct[layer]
+  if (!current) {
+    process.stderr.write(`[verify-fe-coverage] layer "${layer}" in baseline but not in coverage — possible rename\n`)
+    violations++
+    continue
+  }
+  if (base.lines !== undefined && current.lines < base.lines - SLACK) {
+    process.stderr.write(
+      `[verify-fe-coverage] ${layer}: lines coverage dropped: ${current.lines.toFixed(1)}% < ${base.lines}% (slack: ${SLACK}pp)\n`,
+    )
+    violations++
+  }
+  if (base.branches !== undefined && current.branches < base.branches - SLACK) {
+    process.stderr.write(
+      `[verify-fe-coverage] ${layer}: branches coverage dropped: ${current.branches.toFixed(1)}% < ${base.branches}% (slack: ${SLACK}pp)\n`,
+    )
+    violations++
+  }
+}
+
+if (violations > 0) {
+  process.stderr.write(
+    `\n[verify-fe-coverage] ${violations} coverage regression(s) found.\n` +
+      `  Ratchet is upward-only — coverage must not decrease below fe-coverage-baseline.json.\n` +
+      `  To advance baseline: node scripts/verify-fe-coverage.mjs --update-baseline\n`,
+  )
+  process.exit(1)
+}
+
+const layerCount = Object.keys(baseline).length
+process.stdout.write(`[verify-fe-coverage] FE coverage OK — ${layerCount} layers within baseline (slack: ${SLACK}pp)\n`)