@cassiomc1/forgeloop 1.6.2 → 1.6.4

package/schemas/code-attestation.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/code-attestation.schema.json",
+  "title": "ForgeLoop code attestation predicate",
+  "type": "object",
+  "required": ["schemaVersion", "protocol", "task", "content", "evidence", "verification"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocol": {
+      "type": "object",
+      "required": ["name", "protocolVersion"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "const": "ForgeLoop" },
+        "protocolVersion": { "const": 1 }
+      }
+    },
+    "task": {
+      "type": "object",
+      "required": ["taskId", "verificationCycle"],
+      "additionalProperties": false,
+      "properties": {
+        "taskId": { "type": "string", "minLength": 1 },
+        "verificationCycle": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "content": {
+      "type": "object",
+      "required": ["manifestFingerprint", "contentDigest", "coveredPaths"],
+      "additionalProperties": false,
+      "properties": {
+        "manifestFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "contentDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "coveredPaths": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["contractFingerprint", "routeFingerprint", "stateFingerprint", "receiptFingerprint", "ledgerSeq", "ledgerHash"],
+      "additionalProperties": false,
+      "properties": {
+        "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "routeFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+        "stateFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "receiptFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "ledgerSeq": { "type": "integer", "minimum": 1 },
+        "ledgerHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "required": ["completion", "audit"],
+      "additionalProperties": false,
+      "properties": {
+        "completion": { "const": "VALID" },
+        "audit": { "const": "VALID" }
+      }
+    }
+  }
+}

package/schemas/code-manifest.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/code-manifest.schema.json",
+  "title": "ForgeLoop code content manifest",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "verificationCycle", "capture", "bindings", "entries", "contentDigest"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "verificationCycle": { "type": "integer", "minimum": 1 },
+    "capture": {
+      "type": "object",
+      "required": ["mode", "revisionProvider", "baseRevision", "observedRevision", "providerMetadata"],
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "enum": ["WORKTREE", "INDEX", "COMMIT"] },
+        "revisionProvider": { "type": "string", "minLength": 1 },
+        "baseRevision": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
+        "observedRevision": { "type": "string", "minLength": 1 },
+        "providerMetadata": { "type": "object" }
+      }
+    },
+    "bindings": {
+      "type": "object",
+      "required": ["contractFingerprint", "routeFingerprint", "stateFingerprint", "receiptFingerprint", "ledgerSeq", "ledgerHash"],
+      "additionalProperties": false,
+      "properties": {
+        "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "routeFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+        "stateFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "receiptFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "ledgerSeq": { "type": "integer", "minimum": 1 },
+        "ledgerHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "operation", "kind"],
+        "additionalProperties": false,
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "sourcePath": { "type": "string", "minLength": 1 },
+          "operation": { "enum": ["ADDED", "MODIFIED", "DELETED", "RENAMED", "COPIED", "TYPE_CHANGED"] },
+          "kind": { "enum": ["FILE", "SYMLINK", "GITLINK", "DELETED"] },
+          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "providerContentId": { "type": "string", "minLength": 1 },
+          "providerMetadata": { "type": "object" }
+        }
+      }
+    },
+    "contentDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/schemas/config.schema.json

@@ -10,7 +10,63 @@
     "complianceMode": { "enum": ["advisory", "standard", "strict"] },
     "policy": { "type": "string", "minLength": 1 },
     "requiredGates": { "type": "array", "items": { "type": "string", "minLength": 1 } },
-    "requiredEvidence": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+    "requiredEvidence": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "verification": {
+      "type": "object",
+      "required": ["checkers"],
+      "additionalProperties": false,
+      "properties": {
+        "checkers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["checkId", "scopeMode", "argvPrefix", "pathInsertion"],
+            "additionalProperties": false,
+            "properties": {
+              "checkId": { "type": "string", "minLength": 1 },
+              "scopeMode": { "const": "PATH_ARGUMENTS" },
+              "argvPrefix": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+              "pathInsertion": { "const": "APPEND" }
+            }
+          }
+        }
+      }
+    },
+    "attestation": {
+      "type": "object",
+      "required": ["mode", "revisionProvider", "requireCompleteCoverage", "coverage", "signing"],
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "enum": ["off", "optional", "required"] },
+        "revisionProvider": { "type": "string", "minLength": 1 },
+        "requireCompleteCoverage": { "type": "boolean" },
+        "coverage": {
+          "type": "object",
+          "required": ["exclude"],
+          "additionalProperties": false,
+          "properties": { "exclude": { "type": "array", "items": { "type": "string", "minLength": 1 } } }
+        },
+        "signing": {
+          "type": "object",
+          "required": ["provider", "required", "policy"],
+          "additionalProperties": false,
+          "properties": {
+            "provider": { "enum": ["none", "sigstore"] },
+            "required": { "type": "boolean" },
+            "policy": {
+              "type": "object",
+              "required": ["identities", "requireTransparencyLog"],
+              "additionalProperties": false,
+              "properties": {
+                "issuer": { "type": "string" },
+                "identities": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+                "requireTransparencyLog": { "type": "boolean" }
+              }
+            }
+          }
+        }
+      }
+    }
   },
   "additionalProperties": false
 }

package/schemas/handoff-envelope.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/handoff-envelope.schema.json",
+  "title": "ForgeLoop canonical handoff envelope",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "handoffId", "taskId", "createdAt", "intent", "state", "evidence", "continuity", "artifactDigest"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "handoffId": { "type": "string", "pattern": "^handoff-[A-Za-z0-9_-]+$" },
+    "taskId": { "type": "string", "minLength": 1 },
+    "createdAt": { "type": "string", "minLength": 1 },
+    "intent": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "recipientHint": { "type": "string", "minLength": 1 },
+        "note": { "type": "string", "minLength": 1 }
+      }
+    },
+    "state": {
+      "type": "object",
+      "required": ["phase", "revision", "verificationCycle", "contractFingerprint", "routeFingerprint", "repositoryFingerprint", "writeClaims", "changedPaths"],
+      "additionalProperties": false,
+      "properties": {
+        "phase": { "type": "string", "minLength": 1 },
+        "revision": { "type": "integer", "minimum": 0 },
+        "verificationCycle": { "type": "integer", "minimum": 1 },
+        "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "routeFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+        "repositoryFingerprint": { "type": "object" },
+        "writeClaims": { "type": "array", "items": { "type": "string" } },
+        "changedPaths": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["executionRefs", "checkIds"],
+      "additionalProperties": false,
+      "properties": {
+        "executionRefs": { "type": "array", "items": { "type": "string" } },
+        "checkIds": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "continuity": {
+      "type": "object",
+      "required": ["ref", "fingerprint"],
+      "additionalProperties": false,
+      "properties": {
+        "ref": { "type": "string", "minLength": 1 },
+        "fingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] }
+      }
+    },
+    "artifactDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/schemas/in-toto-statement.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/in-toto-statement.schema.json",
+  "title": "ForgeLoop in-toto Statement v1",
+  "type": "object",
+  "required": ["schemaVersion", "_type", "subject", "predicateType", "predicate"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "_type": { "const": "https://in-toto.io/Statement/v1" },
+    "subject": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name", "digest"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "digest": {
+            "type": "object",
+            "required": ["sha256"],
+            "additionalProperties": false,
+            "properties": { "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }
+          }
+        }
+      }
+    },
+    "predicateType": { "const": "https://forgeloop.dev/attestation/v1" },
+    "predicate": { "type": "object" }
+  }
+}

package/schemas/responsibility.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/responsibility.schema.json",
+  "title": "ForgeLoop responsibility constraints",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "label", "createdAt", "allowedPaths", "readOnlyPaths", "requiredCheckIds", "frozenInputs", "baseline"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "label": { "type": "string", "minLength": 1 },
+    "createdAt": { "type": "string", "minLength": 1 },
+    "allowedPaths": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "readOnlyPaths": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "requiredCheckIds": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "frozenInputs": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "contract": { "type": "boolean" },
+        "route": { "type": "boolean" },
+        "claims": { "type": "boolean" }
+      }
+    },
+    "baseline": {
+      "type": "object",
+      "required": ["contractFingerprint", "routeFingerprint", "claimsFingerprint"],
+      "additionalProperties": false,
+      "properties": {
+        "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "routeFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+        "claimsFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    }
+  }
+}

package/schemas/verification-scope.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/verification-scope.schema.json",
+  "title": "ForgeLoop verification scope",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "requestedMode", "resolvedMode", "verificationCycle", "changedPaths", "claimedPaths", "selectedPaths", "reasons", "fallback", "contractFingerprint", "repositoryFingerprint", "claimsFingerprint", "createdAt"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "requestedMode": { "enum": ["AUTO", "CHANGED", "CLAIMED", "FULL"] },
+    "resolvedMode": { "enum": ["CHANGED", "CLAIMED", "FULL", "UNRESOLVED"] },
+    "verificationCycle": { "type": "integer", "minimum": 1 },
+    "changedPaths": { "type": "array", "items": { "type": "string" } },
+    "claimedPaths": { "type": "array", "items": { "type": "string" } },
+    "selectedPaths": { "type": "array", "items": { "type": "string" } },
+    "reasons": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "fallback": { "oneOf": [{ "type": "null" }, { "type": "object" }] },
+    "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "repositoryFingerprint": { "type": "object" },
+    "claimsFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "checkerCapabilityFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "createdAt": { "type": "string", "minLength": 1 }
+  }
+}

package/schemas/workspace-binding.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/workspace-binding.schema.json",
+  "title": "ForgeLoop task workspace binding",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "mode", "repositoryIdentity", "workspaceIdentity", "branchAtBind", "headAtBind", "boundAt"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "mode": { "const": "GIT_WORKTREE" },
+    "repositoryIdentity": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "workspaceIdentity": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "branchAtBind": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
+    "headAtBind": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
+    "boundAt": { "type": "string", "minLength": 1 },
+    "metadata": { "type": "object" }
+  }
+}

package/scripts/CI_VALIDATORS.md

@@ -16,6 +16,9 @@ change the historical scanner and validator contracts without a dedicated
 parity project. They are not runtime dependencies, are not shipped as the CLI
 runtime, and are not required by `npm install`.
 
+The minimum supported Python version for these validators is Python 3.9. CI
+must select or verify Python 3.9 or newer before invoking the frozen commands.
+
 ## CI invocation
 
 ```bash

package/scripts/benchmark-cli-startup.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const DEFAULT_ITERATIONS = 7;
+const DEFAULT_BUDGET_MS = 1000;
+
+function numericArgument(name, fallback) {
+  const index = process.argv.indexOf(name);
+  if (index === -1) return fallback;
+  const value = Number(process.argv[index + 1]);
+  if (!Number.isFinite(value) || value <= 0) throw new Error(`${name} requires a positive number`);
+  return value;
+}
+
+export function benchmarkCliStartup({
+  iterations = DEFAULT_ITERATIONS,
+  budgetMs = DEFAULT_BUDGET_MS,
+  spawnProcess = spawnSync,
+  cwd = repositoryRoot,
+} = {}) {
+  const samples = [];
+  for (let index = 0; index < iterations; index += 1) {
+    const started = performance.now();
+    const result = spawnProcess(process.execPath, ["src/cli.js", "protocol-info", "--json"], {
+      cwd,
+      stdio: "ignore",
+      shell: false,
+    });
+    const elapsed = performance.now() - started;
+    if (result.status !== 0) {
+      throw new Error(`protocol-info startup command failed with exit code ${result.status ?? "unknown"}`);
+    }
+    samples.push(elapsed);
+  }
+  const sorted = [...samples].sort((left, right) => left - right);
+  const median = sorted[Math.floor(sorted.length / 2)];
+  return { iterations, budgetMs, medianMs: median, samplesMs: samples };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const result = benchmarkCliStartup({
+      iterations: numericArgument("--iterations", DEFAULT_ITERATIONS),
+      budgetMs: numericArgument("--budget-ms", DEFAULT_BUDGET_MS),
+    });
+    console.log(`CLI startup median: ${result.medianMs.toFixed(1)} ms (budget: ${result.budgetMs} ms, samples: ${result.iterations})`);
+    if (result.medianMs > result.budgetMs) {
+      console.error("CLI startup budget exceeded.");
+      process.exitCode = 1;
+    }
+  } catch (error) {
+    console.error(`CLI startup benchmark failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/check-changelog-freshness.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function git(args, cwd = repositoryRoot) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+export function latestReleaseTag(tags) {
+  return tags
+    .map((tag) => tag.trim())
+    .filter((tag) => /^v?\d+\.\d+\.\d+$/u.test(tag))
+    .sort((left, right) => left.localeCompare(right, undefined, { numeric: true })).at(-1) ?? null;
+}
+
+export function unreleasedSection(changelog) {
+  const heading = /^## Unreleased\s*$/imu.exec(changelog);
+  if (!heading) return "";
+  const rest = changelog.slice(heading.index + heading[0].length);
+  const nextHeading = /^##\s/imu.exec(rest);
+  return nextHeading ? rest.slice(0, nextHeading.index) : rest;
+}
+
+export function stripHtmlComments(value) {
+  const chunks = [];
+  let cursor = 0;
+
+  while (cursor < value.length) {
+    const commentStart = value.indexOf("<!--", cursor);
+    if (commentStart === -1) {
+      chunks.push(value.slice(cursor));
+      break;
+    }
+
+    chunks.push(value.slice(cursor, commentStart));
+    const commentEnd = value.indexOf("-->", commentStart + 4);
+    if (commentEnd === -1) break;
+    cursor = commentEnd + 3;
+  }
+
+  return chunks.join("");
+}
+
+export function hasMeaningfulUnreleasedContent(section) {
+  return stripHtmlComments(section)
+    .split("\n")
+    .map((line) => line.trim())
+    .some((line) => line && !/^No changes\.?$/iu.test(line));
+}
+
+export function checkChangelogFreshness({ changelog, tags = [], commitsSinceLatestTag = 0, allowEmpty = false } = {}) {
+  const latestTag = latestReleaseTag(tags);
+  const section = unreleasedSection(changelog);
+  const hasChanges = commitsSinceLatestTag > 0;
+  const populated = hasMeaningfulUnreleasedContent(section);
+  const ok = allowEmpty || !hasChanges || populated;
+  return { ok, latestTag, hasChanges, populated, section };
+}
+
+async function run() {
+  const changelog = await readFile(path.join(repositoryRoot, "CHANGELOG.md"), "utf8");
+  const tags = git(["tag", "--list"]).split("\n").filter(Boolean);
+  const latestTag = latestReleaseTag(tags);
+  const commitsSinceLatestTag = latestTag
+    ? Number(git(["rev-list", "--count", `${latestTag}..HEAD`]))
+    : Number(git(["rev-list", "--count", "HEAD"]));
+  const result = checkChangelogFreshness({ changelog, tags, commitsSinceLatestTag, allowEmpty: process.argv.includes("--allow-empty") });
+  if (!result.ok) {
+    console.error(`CHANGELOG.md has changes since ${result.latestTag ?? "the initial commit"} but the Unreleased section is empty.`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Changelog freshness valid: ${result.latestTag ?? "no release tag"}`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    await run();
+  } catch (error) {
+    console.error(`Changelog freshness check failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/check-critical-coverage.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const summaryPath = path.join(repositoryRoot, "coverage", "coverage-summary.json");
+
+export const CRITICAL_COVERAGE_THRESHOLDS = Object.freeze({
+  "src/core/repository.js": { lines: 80, branches: 60 },
+  "src/core/policy-discovery.js": { lines: 75, branches: 45 },
+  "src/core/policy-adapters.js": { lines: 70, branches: 45 },
+  "src/core/task-identity.js": { lines: 75, branches: 50 },
+  "src/core/task-migration-validation.js": { lines: 75, branches: 50 },
+});
+
+function findSummaryEntry(summary, relativePath) {
+  const absolutePath = path.join(repositoryRoot, relativePath);
+  return summary[absolutePath] ?? summary[relativePath] ?? summary[path.resolve(relativePath)];
+}
+
+export async function checkCriticalCoverage({ summary = null, readSummary = readFile } = {}) {
+  const value = summary ?? JSON.parse(await readSummary(summaryPath, "utf8"));
+  const failures = [];
+  const missing = [];
+  for (const [file, thresholds] of Object.entries(CRITICAL_COVERAGE_THRESHOLDS)) {
+    const entry = findSummaryEntry(value, file);
+    if (!entry) {
+      missing.push(file);
+      continue;
+    }
+    for (const metric of ["lines", "branches"]) {
+      const actual = entry[metric]?.pct;
+      if (typeof actual !== "number" || actual < thresholds[metric]) {
+        failures.push({ file, metric, actual, required: thresholds[metric] });
+      }
+    }
+  }
+  return { ok: failures.length === 0 && missing.length === 0, failures, missing };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const result = await checkCriticalCoverage();
+    if (result.missing.length > 0) {
+      console.error(`Critical coverage report is missing: ${result.missing.join(", ")}`);
+    }
+    for (const failure of result.failures) {
+      console.error(`${failure.file} ${failure.metric}: ${failure.actual ?? "unknown"}% (required ${failure.required}%)`);
+    }
+    if (!result.ok) process.exitCode = 1;
+    else console.log("Critical-module coverage meets the configured thresholds.");
+  } catch (error) {
+    console.error(`Critical coverage check failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+}