connections-architect 0.2.0

package/README.md

@@ -0,0 +1,61 @@
+# connections-architect
+
+The **Architect** — a portable checks-and-balances framework. A generic CORE of checks ships from
+Connections; you add your OWN under `your-checks/` (the core never touches them); together they form a
+**cast** on your codebase that catches breakage and drift and gets tighter as you add rules.
+
+> Built from scratch, distilling the best of Connections' internal `arkitect` (the self-registering check
+> contract, two-root auto-discovery, the `requires` portability gate, the conformance-oracle tier) and
+> `daggar` (the multi-axis "justify existence" judge for live infra/DB). Zero runtime dependencies.
+
+## Use it
+
+```sh
+npx -y connections-architect                  # run every applicable check
+npx -y connections-architect --check no-secrets-committed
+npx -y connections-architect list             # what's discovered (core + your-checks)
+npx -y connections-architect --fail-on-drift  # exit 1 if a gating check fails (CI)
+```
+
+Output: `tmp/architect/FIX_QUEUE.md` (ranked) + `tmp/architect/manifest.json` whose `pass.nextAction`
+(`fix-errors` → `review-warnings` → `done`) is the one field an agent reads to know if it's finished.
+
+## Two halves, one shape
+
+- **code** — checks that run statically in your repo (shipped now).
+- **hosted** — checks that run through the **Connections MCP** against _your own_ cloud credentials
+  (AWS / Supabase / your DB), generalizing the daggar DB governor's "justify existence" judgment.
+  Strictly read-only; emits a `remediation.sql` / kill-orders a human executes. _(Phase 3.)_
+
+## Make it yours
+
+Add `.mjs` files under `your-checks/` — each exports an `audit` and **auto-registers, no wiring**. A user
+check whose `id` matches a core check **shadows** it (patch the core without editing it). Pin or fork via
+`architect.config.json` (`update.pinnedVersion` / `update.autoUpdate: false`) to stop pulling the core and
+own it outright.
+
+```js
+export const audit = {
+  id: "my-rule",
+  title: "My rule",
+  category: "custom",
+  domain: "code", // or "hosted"
+  requires: {}, // {} = any repo
+  gating: false, // true ⇒ blocks --fail-on-drift
+  async run(ctx) {
+    return { failed: false, findings: [], report: "" };
+  },
+};
+```
+
+Node ≥ 18. `node test/smoke.mjs` proves the engine end to end.
+
+## Roadmap
+
+| Phase | What |
+| ----- | ---- |
+| **1 (done)** | portable core engine (runner + two-root discovery + `requires` gating + FIX_QUEUE/manifest) + 3 generic checks + the `your-checks/` extension layer |
+| **2 (done)** | conformance-oracle reference mode (`runFamilyConformance` — reference + consensus), SARIF 2.1.0 (`findings.sarif`), DECISION_BRIEF flat finding list, `tsconfig-conformance` check, `dependency-freshness` check |
+| **3 (done)** | the hosted/DB half — generic 5-verdict justify-existence judge + spine (claims/overrides) + read-only vault seam + the `db-justify-existence` governor (runs through the MCP vault against your own DB; review-only remediation) |
+| **4 (done, unreleased)** | self-update machinery — version-gated manifest pull + SHA-pinned apply with `.prev` rollback (mirrors the MCP loader) + `publish-core.mjs` release publisher. Built + verified; **not published** (release-time) |
+| **5 (wired; awaiting release)** | the MCP `architect_run` tool (code half + hosted-via-vault) is built. The public releases — npm publish + S3 core publish + the MCP deploy — are **owner-gated**, not done yet |

package/architect.config.example.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "extensionDir": "your-checks",
+  "update": {
+    "channel": "stable",
+    "pinnedVersion": null,
+    "autoUpdate": true
+  },
+  "checks": {
+    "oversized-files": { "warnLines": 800, "errorLines": 2500 },
+    "sibling-consensus": { "family": "package.json", "field": "license" }
+  },
+  "hosted": {
+    "spine": "spine/justify-existence.json",
+    "targets": []
+  }
+}

package/bin/architect.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// The Architect CLI. `architect` / `architect --all` runs every applicable check; `architect --check <id>`
+// runs one; `architect list` shows what's discovered. It discovers the shipped CORE (this package's
+// src/checks/) AND the target repo's your-checks/ — the user's checks shadow core checks of the same id.
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { discoverAudits } from "../src/core/discovery.mjs";
+import { detectProject } from "../src/core/project-detect.mjs";
+import { runAudits } from "../src/core/runner.mjs";
+import { selfUpdate } from "../src/update/self-update.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG = resolve(HERE, "..");
+const argv = process.argv.slice(2);
+const flag = (f) => argv.includes(f);
+const opt = (f, d) => {
+  const i = argv.indexOf(f);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : d;
+};
+
+const root = resolve(opt("--root", process.cwd()));
+const failOnDrift = flag("--fail-on-drift");
+const only = opt("--check", null);
+const wantList = argv.includes("list") || flag("--list");
+
+// Config (optional) lives in the TARGET repo — never in the core.
+let config = {};
+const cfgPath = join(root, "architect.config.json");
+if (existsSync(cfgPath)) {
+  try {
+    config = JSON.parse(readFileSync(cfgPath, "utf8"));
+  } catch (e) {
+    console.error(`[architect] bad architect.config.json: ${e.message}`);
+  }
+}
+const extensionDir = config.extensionDir || "your-checks";
+const coreRoot = join(PKG, "src", "checks"); // shipped CORE — what self-update refreshes
+const userRoot = join(root, extensionDir); // the user's own checks — never touched by self-update
+
+// Pull the freshest CORE from Connections before discovery — opt-in via config.update.autoUpdate (the
+// shipped default config sets it true). Fail-soft: an update attempt NEVER breaks the run. No config
+// opt-in ⇒ no network (so dev + CI stay offline). Inert until the core bucket exists at release.
+if (config.update?.autoUpdate === true && !config.update?.pinnedVersion) {
+  try {
+    const installedVersion = JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version;
+    const r = await selfUpdate({ installedVersion, srcDir: join(PKG, "src"), config });
+    if (r?.applied) console.error(`[architect] self-updated core → v${r.version} (${r.applied} files)`);
+  } catch {
+    /* an update attempt must never break a run */
+  }
+}
+
+const { audits, loadErrors, shadowed } = await discoverAudits([coreRoot, userRoot]);
+for (const le of loadErrors) console.error(`[architect] FAILED TO LOAD check ${le.file}: ${le.error}`);
+for (const s of shadowed) console.error(`[architect] your-checks override: '${s.id}' shadows the core check`);
+
+if (wantList) {
+  for (const a of audits.sort((x, y) => x.id.localeCompare(y.id))) {
+    const where = a.__root === coreRoot ? "core" : "your-checks";
+    console.log(`${a.id.padEnd(28)} [${a.__group}/${where}]  ${a.title}`);
+  }
+  process.exit(0);
+}
+
+const selected = only ? audits.filter((a) => a.id === only) : audits;
+if (only && selected.length === 0) {
+  console.error(`[architect] no check with id '${only}'. Try: architect list`);
+  process.exit(2);
+}
+
+const project = detectProject(root);
+const ctxBase = { root, config, project, options: { failOnDrift }, vault: null };
+const { manifest } = await runAudits(selected, ctxBase, { outDir: join(root, "tmp", "architect") });
+
+const line = `Architect · ${manifest.checks.length} checks · ${manifest.gatingErrors} gating error(s) · ${manifest.warnings} warning(s) · ${manifest.crashed} crash(es) · nextAction=${manifest.pass.nextAction}`;
+console.log(manifest.pass.clean ? `✅ ${line}` : `⚠️  ${line}`);
+console.log("   → tmp/architect/FIX_QUEUE.md  ·  tmp/architect/manifest.json");
+
+process.exit(failOnDrift && manifest.gatingErrors > 0 ? 1 : 0);

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "connections-architect",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "The Connections Architect — a portable, self-updating checks-and-balances framework. Ships a generic core of checks; you add your own in your-checks/ (the core never touches them); it keeps your codebase (and, via the Connections MCP, your hosted cloud) from drifting. Zero runtime dependencies.",
+  "bin": {
+    "architect": "./bin/architect.mjs"
+  },
+  "exports": {
+    ".": "./src/core/index.mjs",
+    "./finding": "./src/core/finding.mjs",
+    "./oracle": "./src/core/oracle/family-conformance.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "your-checks",
+    "spine",
+    "architect.config.example.json",
+    "README.md"
+  ],
+  "keywords": ["lint", "audit", "checks", "governance", "drift", "connections", "self-updating"],
+  "homepage": "https://studio.connections.icu/mcp",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}

package/spine/justify-existence.example.json

@@ -0,0 +1,11 @@
+{
+  "appCodeRoots": ["src", "services", "lib"],
+  "features": [
+    { "name": "billing", "claims": ["invoices", "payments", "payment_*"] },
+    { "name": "identity", "claims": ["users", "sessions", "profile_*"] }
+  ],
+  "verdicts": {
+    "legacy_temp_import": "REMOVE",
+    "mystery_table": "INVESTIGATE"
+  }
+}

package/src/checks/code/dependency-freshness.mjs

@@ -0,0 +1,87 @@
+// CORE check — advisory. Flags package.json files that depend on unpinned version ranges (`*`, `latest`,
+// `>=x`) or that have dependencies declared but no lockfile in the same directory. Unpinned ranges mean
+// your build is not reproducible; missing lockfiles mean you can't prove it either. Advisory by default
+// so it never blocks a fork whose own dep conventions differ.
+import { existsSync, readFileSync } from "node:fs";
+import { relative, basename, dirname, join } from "node:path";
+import { createFinding } from "../../core/finding.mjs";
+import { walkFiles } from "../../core/fs-walk.mjs";
+
+/** Unpinned range patterns — `*`, `latest`, `>=x`, `>x`. Does NOT flag `^` / `~` (those are pinned ranges). */
+const UNPINNED_RE = /^(\*|latest|>=?)/;
+
+/** Lockfile names we recognize. */
+const LOCKFILES = ["package-lock.json", "bun.lockb", "yarn.lock", "pnpm-lock.yaml"];
+
+export const audit = {
+  id: "dependency-freshness",
+  title: "Dependencies use pinned version ranges",
+  category: "dependencies",
+  domain: "code",
+  requires: { ecosystems: ["npm"] },
+  gating: false,
+  defaultConfig: {},
+  async run(ctx) {
+    const { root } = ctx;
+    const findings = [];
+
+    for (const file of walkFiles(root)) {
+      if (basename(file) !== "package.json") continue;
+
+      let pkg;
+      try {
+        pkg = JSON.parse(readFileSync(file, "utf8"));
+      } catch {
+        continue;
+      }
+
+      const relFile = relative(root, file);
+      const dir = dirname(file);
+
+      // 1. Check for unpinned ranges in dependencies + devDependencies.
+      const allDeps = {
+        ...(pkg.dependencies || {}),
+        ...(pkg.devDependencies || {}),
+      };
+      for (const [name, version] of Object.entries(allDeps)) {
+        if (typeof version === "string" && UNPINNED_RE.test(version.trim())) {
+          findings.push(
+            createFinding({
+              id: "unpinned-dependency",
+              title: `Unpinned dependency: ${name}`,
+              severity: "warning",
+              file: relFile,
+              message: `'${name}': "${version}" is unpinned (use an exact version or a caret/tilde range for reproducibility)`,
+              fix: `Replace "${version}" with a pinned version such as "1.2.3" or "^1.2.3".`,
+            }),
+          );
+        }
+      }
+
+      // 2. Check for missing lockfile when any deps are declared.
+      const hasDeps =
+        Object.keys(pkg.dependencies || {}).length > 0 ||
+        Object.keys(pkg.devDependencies || {}).length > 0;
+      if (hasDeps) {
+        const hasLockfile = LOCKFILES.some((lf) => existsSync(join(dir, lf)));
+        if (!hasLockfile) {
+          findings.push(
+            createFinding({
+              id: "missing-lockfile",
+              title: "No lockfile found alongside package.json",
+              severity: "warning",
+              file: relFile,
+              message: `${relFile} declares dependencies but has no lockfile (${LOCKFILES.join(" / ")}) — installs are not reproducible`,
+              fix: "Run your package manager (npm install / bun install / yarn / pnpm install) to generate a lockfile and commit it.",
+            }),
+          );
+        }
+      }
+    }
+
+    const report = findings.length
+      ? `# Dependency freshness\n\n${findings.map((f) => `- WARN ${f.file} — ${f.message}`).join("\n")}\n\nErrors: 0\nWarnings: ${findings.length}\n`
+      : "";
+    return { failed: false, findings, report };
+  },
+};

package/src/checks/code/no-secrets-committed.mjs

@@ -0,0 +1,65 @@
+// CORE check — generic, runs on any repo. High-confidence committed-secret patterns only (low false
+// positives by design; broader entropy scanning is a Phase-2 refinement).
+import { readFileSync } from "node:fs";
+import { relative, extname } from "node:path";
+import { createFinding } from "../../core/finding.mjs";
+import { walkFiles } from "../../core/fs-walk.mjs";
+
+const SCAN_EXT = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".rs", ".go", ".rb", ".java", ".php",
+  ".vue", ".json", ".yaml", ".yml", ".env", ".sh", ".toml", ".ini", ".cfg", ".tf",
+]);
+const PATTERNS = [
+  { id: "aws-access-key-id", re: /\bAKIA[0-9A-Z]{16}\b/, title: "AWS access key id committed" },
+  { id: "private-key-block", re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/, title: "Private key block committed" },
+  { id: "aws-secret-key", re: /aws_secret_access_key["'\s:=]+["'][A-Za-z0-9/+=]{40}["']/i, title: "AWS secret access key committed" },
+  { id: "slack-token", re: /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/, title: "Slack token committed" },
+  { id: "google-api-key", re: /\bAIza[0-9A-Za-z_\-]{35}\b/, title: "Google API key committed" },
+];
+
+export const audit = {
+  id: "no-secrets-committed",
+  title: "No committed secrets",
+  category: "security",
+  domain: "code",
+  requires: {}, // any repo
+  gating: true,
+  defaultConfig: { maxFileBytes: 2_000_000 },
+  async run(ctx) {
+    const { root, checkConfig } = ctx;
+    const findings = [];
+    for (const file of walkFiles(root)) {
+      if (!SCAN_EXT.has(extname(file))) continue;
+      let text;
+      try {
+        const buf = readFileSync(file);
+        if (buf.length > checkConfig.maxFileBytes) continue;
+        text = buf.toString("utf8");
+      } catch {
+        continue;
+      }
+      const lines = text.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        for (const p of PATTERNS) {
+          if (p.re.test(lines[i])) {
+            findings.push(
+              createFinding({
+                id: p.id,
+                title: p.title,
+                severity: "error",
+                file: relative(root, file),
+                line: i + 1,
+                message: `${p.title} at ${relative(root, file)}:${i + 1}`,
+                fix: "Remove it, rotate the credential, and load it from an env var / secret manager.",
+              }),
+            );
+          }
+        }
+      }
+    }
+    const report = findings.length
+      ? `# No committed secrets\n\n${findings.map((f) => `- ERROR ${f.file}:${f.line} — ${f.title}`).join("\n")}\n\nErrors: ${findings.length}\nWarnings: 0\n`
+      : "";
+    return { failed: findings.length > 0, findings, report };
+  },
+};

package/src/checks/code/oversized-files.mjs

@@ -0,0 +1,40 @@
+// CORE check — generic. Advisory by default (surfaces debt without blocking a fork whose files are
+// already large). A user can flip it to gating in architect.config.json.
+import { readFileSync } from "node:fs";
+import { relative, extname } from "node:path";
+import { createFinding } from "../../core/finding.mjs";
+import { walkFiles } from "../../core/fs-walk.mjs";
+
+const CODE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".rs", ".go", ".rb", ".java", ".php", ".vue", ".css", ".scss"]);
+
+export const audit = {
+  id: "oversized-files",
+  title: "Oversized source files",
+  category: "maintainability",
+  domain: "code",
+  requires: {},
+  gating: false,
+  defaultConfig: { warnLines: 800, errorLines: 2500 },
+  async run(ctx) {
+    const { root, checkConfig } = ctx;
+    const findings = [];
+    for (const file of walkFiles(root)) {
+      if (!CODE_EXT.has(extname(file))) continue;
+      let lines;
+      try {
+        lines = readFileSync(file, "utf8").split("\n").length;
+      } catch {
+        continue;
+      }
+      if (lines >= checkConfig.errorLines)
+        findings.push(createFinding({ id: "oversized", title: "File far too large", severity: "error", file: relative(root, file), line: lines, message: `${lines} lines (≥ ${checkConfig.errorLines})` }));
+      else if (lines >= checkConfig.warnLines)
+        findings.push(createFinding({ id: "oversized", title: "Large file", severity: "warning", file: relative(root, file), line: lines, message: `${lines} lines (≥ ${checkConfig.warnLines})` }));
+    }
+    const errors = findings.filter((f) => f.severity === "error").length;
+    const report = findings.length
+      ? `# Oversized files\n\n${findings.map((f) => `- ${f.severity.toUpperCase()} ${f.file} — ${f.message}`).join("\n")}\n\nErrors: ${errors}\nWarnings: ${findings.length - errors}\n`
+      : "";
+    return { failed: errors > 0, findings, report };
+  },
+};

package/src/checks/code/sibling-consensus.mjs

@@ -0,0 +1,73 @@
+// CORE check — the CONFORMANCE ORACLE (consensus mode), distilled to a generic, project-agnostic shape.
+// A denylist enumerates known-bad and is forever one bug behind. An oracle declares what AGREEMENT looks
+// like across a FAMILY of sibling artifacts and flags the odd-one-out — catching divergence nobody named.
+// Default family: every package.json; default fingerprint: the `license` field. Both are configurable.
+// Refactored to delegate consensus logic to runFamilyConformance (keeps identical behavior + output).
+import { readFileSync } from "node:fs";
+import { relative, basename } from "node:path";
+import { createFinding } from "../../core/finding.mjs";
+import { walkFiles } from "../../core/fs-walk.mjs";
+import { runFamilyConformance } from "../../core/oracle/family-conformance.mjs";
+
+function getPath(obj, path) {
+  return path.split(".").reduce((o, k) => (o == null ? undefined : o[k]), obj);
+}
+
+export const audit = {
+  id: "sibling-consensus",
+  title: "Sibling files agree (consensus oracle)",
+  category: "consistency",
+  domain: "code",
+  requires: { ecosystems: ["npm"] },
+  gating: false,
+  defaultConfig: { family: "package.json", field: "license", minFamily: 3 },
+  async run(ctx) {
+    const { root, checkConfig } = ctx;
+
+    // Collect family members.
+    const members = [];
+    for (const file of walkFiles(root)) {
+      if (basename(file) === checkConfig.family) members.push({ path: file });
+    }
+    if (members.length < checkConfig.minFamily) return { failed: false, findings: [], report: "" };
+
+    // project() extracts the fingerprint for a member (the configured field from the JSON file).
+    const project = (member) => {
+      try {
+        return getPath(JSON.parse(readFileSync(member.path, "utf8")), checkConfig.field) ?? null;
+      } catch {
+        return null;
+      }
+    };
+
+    const { findings: divergences, consensusOrReference } = await runFamilyConformance({
+      family: members,
+      project,
+      mode: "consensus",
+    });
+
+    if (divergences === null || consensusOrReference === null) {
+      // No clear majority — nothing to flag.
+      return { failed: false, findings: [], report: "" };
+    }
+
+    const majorityKey = JSON.stringify(consensusOrReference);
+    const majorityCount = members.length - divergences.length;
+
+    const findings = divergences.map((d) =>
+      createFinding({
+        id: "consensus-divergence",
+        title: `Diverges from sibling consensus on '${checkConfig.field}'`,
+        severity: "warning",
+        file: relative(root, d.member.path),
+        message: `'${checkConfig.field}' = ${JSON.stringify(d.actual)}; ${majorityCount}/${members.length} siblings agree on ${majorityKey}`,
+        fix: `Set '${checkConfig.field}' to ${majorityKey} to match its siblings (or justify the difference).`,
+      }),
+    );
+
+    const report = findings.length
+      ? `# Sibling consensus — ${checkConfig.family} · ${checkConfig.field}\n\nMajority (${majorityCount}/${members.length}): ${majorityKey}\n\n${findings.map((f) => `- WARN ${f.file} — ${f.message}`).join("\n")}\n\nErrors: 0\nWarnings: ${findings.length}\n`
+      : "";
+    return { failed: false, findings, report };
+  },
+};

package/src/checks/code/tsconfig-conformance.mjs

@@ -0,0 +1,105 @@
+// CORE check — conformance oracle in REFERENCE mode applied to tsconfig.json compilerOptions.
+// Walks all tsconfig.json files; the reference (default: root tsconfig.json) defines the expected values
+// for any compilerOption key it declares. Any tsconfig whose values for those shared keys differ from the
+// reference is flagged. Uses runFamilyConformance in reference mode — catches drift nobody has named.
+import { readFileSync } from "node:fs";
+import { relative, join, basename } from "node:path";
+import { createFinding } from "../../core/finding.mjs";
+import { walkFiles } from "../../core/fs-walk.mjs";
+import { runFamilyConformance } from "../../core/oracle/family-conformance.mjs";
+
+/**
+ * Parse a tsconfig.json — returns { compilerOptions: {...} } or null on failure.
+ */
+function parseTsconfig(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export const audit = {
+  id: "tsconfig-conformance",
+  title: "tsconfig.json files conform to reference compilerOptions",
+  category: "conformance",
+  domain: "code",
+  requires: { ecosystems: ["npm"] },
+  gating: false,
+  defaultConfig: { referenceFile: "tsconfig.json" }, // relative to root
+  async run(ctx) {
+    const { root, checkConfig } = ctx;
+    const refPath = join(root, checkConfig.referenceFile);
+
+    // Parse the reference to extract its compilerOptions keys — these are the axes we judge.
+    const refParsed = parseTsconfig(refPath);
+    const refCompilerOptions = refParsed?.compilerOptions || {};
+    const refKeys = Object.keys(refCompilerOptions);
+    if (refKeys.length === 0) {
+      // No compilerOptions in reference — nothing to judge.
+      return { failed: false, findings: [], report: "" };
+    }
+
+    // Collect all tsconfig.json files (including the reference — the oracle skips it).
+    const members = [];
+    for (const file of walkFiles(root)) {
+      if (basename(file) === "tsconfig.json") members.push({ path: file });
+    }
+    if (members.length === 0) return { failed: false, findings: [], report: "" };
+
+    // Fingerprint = the subset of compilerOptions present in the REFERENCE — so we only compare apples to apples.
+    const project = (member) => {
+      const parsed = parseTsconfig(member.path);
+      const co = parsed?.compilerOptions || {};
+      // Build a sub-object with ONLY the keys from the reference's compilerOptions.
+      const subset = {};
+      for (const k of refKeys) {
+        if (Object.prototype.hasOwnProperty.call(co, k)) {
+          subset[k] = co[k];
+        }
+      }
+      return subset;
+    };
+
+    // Reference fingerprint is the subset of its OWN compilerOptions keys.
+    const { findings: divergences } = await runFamilyConformance({
+      family: members,
+      project,
+      mode: "reference",
+      referenceId: refPath,
+    });
+
+    if (!divergences || divergences.length === 0) {
+      return { failed: false, findings: [], report: "" };
+    }
+
+    const findings = [];
+    for (const d of divergences) {
+      const relPath = relative(root, d.member.path);
+      // Enumerate only the keys that actually differ.
+      const expected = d.expected || {};
+      const actual = d.actual || {};
+      const allKeys = new Set([...Object.keys(expected), ...Object.keys(actual)]);
+      const diffKeys = [...allKeys].filter(
+        (k) => JSON.stringify(expected[k]) !== JSON.stringify(actual[k]),
+      );
+      for (const k of diffKeys) {
+        findings.push(
+          createFinding({
+            id: "tsconfig-drift",
+            title: `tsconfig compilerOption '${k}' diverges from reference`,
+            severity: "warning",
+            file: relPath,
+            message: `compilerOptions.${k}: expected ${JSON.stringify(expected[k])}, got ${JSON.stringify(actual[k])} (reference: ${checkConfig.referenceFile})`,
+            fix: `Set compilerOptions.${k} to ${JSON.stringify(expected[k])} to match ${checkConfig.referenceFile}, or remove it from the reference if it should not be enforced globally.`,
+          }),
+        );
+      }
+    }
+
+    const report = findings.length
+      ? `# tsconfig conformance\n\nReference: ${checkConfig.referenceFile}\n\n${findings.map((f) => `- WARN ${f.file} — ${f.message}`).join("\n")}\n\nErrors: 0\nWarnings: ${findings.length}\n`
+      : "";
+    return { failed: false, findings, report };
+  },
+};