connections-arkitect 0.3.4

package/README.md

@@ -0,0 +1,104 @@
+# connections-arkitect
+
+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.
+
+> One product, two halves: static **code** checks in your repo, and **hosted** checks against your live
+> cloud (your database on AWS RDS/Aurora — Supabase/generic Postgres transports are on the roadmap) —
+> distilled from Connections' internal code-audit and live-DB governance engines. Zero runtime
+> dependencies.
+
+## Use it
+
+```sh
+npx -y connections-arkitect init             # OPT-IN install: lay .arkitect/ (config + your-checks + spines)
+npx -y connections-arkitect                  # run every applicable check
+npx -y connections-arkitect --check no-secrets-committed
+npx -y connections-arkitect list             # what's discovered (core + your-checks)
+npx -y connections-arkitect --fail-on-drift  # exit 1 if a gating check fails (CI)
+```
+
+Output: `tmp/arkitect/FIX_QUEUE.md` (ranked) + `tmp/arkitect/manifest.json` whose `pass.nextAction`
+(`fix-errors` → `review-warnings` → `done`) is the one field an agent reads to know if it's finished.
+
+**Native telemetry — every check, always, no opt-in.** The runner itself records, per check, its
+**duration** and its **bounces** — every outbound round-trip the check made (vault DB/cloud calls and
+`fetch` HTTP calls), counted and timed at the seams, so a check's author writes zero telemetry code and
+can't forget to. "Login worked" is half a report; "login worked, 87 bounces at ~200ms each" is why it
+took 30 seconds. Aggregates ride the manifest + FIX_QUEUE lines (`[1.2s · 14 bounces]`); the per-hop
+trace is `tmp/arkitect/telemetry.json`.
+
+**Saved reports.** A bare repo stays stateless (outputs only in `tmp/arkitect/`, overwritten each run).
+But when the repo has a `.arkitect/`, every run is archived to `.arkitect/reports/<stamp>/` —
+manifest, fix queue, telemetry, and every check's **full** report — so you can pull any past run in
+depth later. Pruned to `reports.keep` (config, default 20).
+
+Installing is a **choice**: nothing but an explicit `init` (or the MCP `architect_install` tool, on a direct
+request) ever creates `.arkitect/` — a normal run writes only its `tmp/arkitect/` outputs. The split it
+lays down is the whole model: the **Architect Core** (this package: engine + generalist base checks) updates
+from Connections; **your-checks/** (your code checks) and **spines/** (your DB policy) are YOURS — a core
+update never touches them, so pulling the newest core never breaks your additions. Updating is also a
+choice: `update.autoUpdate: false` or `update.pinnedVersion` stops the pulls, and forking the core to own it
+outright is legitimate.
+
+## Two halves, one shape
+
+- **code** — checks that run statically in your repo. Work anywhere, offline, no account needed.
+- **hosted** — checks that run through the **Connections MCP** against _your own_ cloud, **credential-blind**:
+  you never paste a key. The MCP signs you in (browser sign-in), binds your workspace to your company, and
+  your cloud calls are signed **server-side** in the Connections vault — the standalone CLI physically
+  cannot reach a hosted check (no vault handle exists outside the MCP). Ships the `db-justify-existence`
+  governor: every table judged on the 3-axis model (exact live rows × app-code references × in-DB
+  references) against your **spine** — strictly read-only; it emits verdicts + a review-only
+  `remediation` block a human executes.
+
+To run hosted checks: connect the [Connections MCP](https://studio.connections.icu/mcp), sign in when it
+prompts (no key to paste), and invoke the `arkitect_run` tool with `scope: "hosted"` (or `"all"`). Declare
+your DB targets in `arkitect.config.json` → `hosted.targets` — non-secret coordinates only (ARNs, database
+name); the credential stays in the vault. Set `hosted.failOnBounty: true` to make CONDEMNED / PROVE-OR-DIE
+verdicts gate the run (CI-style), or leave it off for advisory reports.
+
+## 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
+`arkitect.config.json` (`update.pinnedVersion` / `update.autoUpdate: false`) to stop pulling the core and
+own it outright.
+
+Config + checks can live at the repo root (`arkitect.config.json`, `your-checks/`) **or** tucked under
+`.arkitect/` (`.arkitect/arkitect.config.json`, `.arkitect/your-checks/`) if you prefer to keep
+the Architect's footprint in one folder — the `.arkitect/` location wins when both exist.
+
+```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: "" };
+  },
+};
+```
+
+For the hosted half, your policy is the **spine** (`spine/justify-existence.json` or per-target via
+`hosted.targets[].spine`): each feature claims the tables it owns (`"payment_*"` prefix claims or exact
+names — `{ "tables": [...], "tablePrefixes": [...] }` is accepted too), and explicit
+`verdicts: { "table": "REMOVE" | "INVESTIGATE" }` (or `{ "verdict": "...", "reason": "..." }`) override
+any claim.
+
+Node ≥ 18. `node test/smoke.mjs` proves the engine end to end.
+
+## Roadmap
+
+| Phase                      | What                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **1 (shipped)**            | portable core engine (runner + two-root discovery + `requires` gating + FIX_QUEUE/manifest) + 3 generic checks + the `your-checks/` extension layer                                                                                                                                                                                                                                                                                                                                                                                                                |
+| **2 (shipped)**            | 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 (shipped)**            | 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 (shipped)**            | self-update machinery — version-gated manifest pull + SHA-pinned apply with `.prev` rollback (mirrors the MCP loader) + the release publisher                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| **5 (shipped 2026-06-30)** | public release: npm (`connections-arkitect`) + the S3 core-update channel + the MCP `arkitect_run` tool (code half + hosted-via-vault)                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| **6 (next)**               | grow the core, breadth-first: a **generalist base that does a good job checking everything, in-depth on nothing** — distill every concept from Connections' internal engines (generic code-check classes: dead code, duplication, circular deps, complexity, css, perf, security; generalized DB-governance blades: required roles, migration-chain gaps, TTL backstops) + the full conformance-oracle projection tier + more hosted target kinds (Supabase / generic Postgres). Depth stays in your-checks/ — the core is the floor, yours is the specialist tier |

package/arkitect.config.example.json

@@ -0,0 +1,10 @@
+{
+  "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/arkitect.mjs

@@ -0,0 +1,135 @@
+#!/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 { initWorkspace } from "../src/core/init.mjs";
+import { loadWorkspaceConfig } from "../src/core/config.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()));
+
+// `architect init` — the explicit OPT-IN install: lay the Architect's per-workspace layout under
+// <root>/.arkitect/ (config + your-checks/ + spines/). Runs ONLY when asked; a normal run never
+// creates .arkitect as a side effect. Idempotent — existing files are never overwritten.
+if (argv.includes("init")) {
+  const { created, skipped } = initWorkspace(root, PKG);
+  for (const p of created) console.log(`  + ${p}`);
+  for (const p of skipped) console.log(`  = ${p} (already yours — untouched)`);
+  console.log(
+    created.length
+      ? `\n✅ Architect installed. Your files: .arkitect/ (config + your-checks + spines) — a core update never touches them.`
+      : `\n✅ Already installed — nothing overwritten.`,
+  );
+  process.exit(0);
+}
+
+const failOnDrift = flag("--fail-on-drift");
+const failOnBounty = flag("--fail-on-bounty");
+const only = opt("--check", null); // accepts a comma list: --check a,b,c
+const wantList = argv.includes("list") || flag("--list");
+const quiet = flag("--quiet"); // suppress discovery chatter (shadow/load notes); the summary line always prints
+flag("--all"); // accepted for gate-script compatibility — running everything IS the default
+const excludeGroups = (opt("--exclude-group", "") || "").split(",").filter(Boolean); // e.g. --exclude-group infra
+
+// Anything the CLI itself doesn't consume is forwarded to the checks as ctx.checkArgs — specialized
+// scripts pass check-specific flags (--section, --live, --format …) exactly as the legacy runner did.
+const CONSUMED = new Set(["--root", "--check", "--group", "--out", "--exclude-group"]);
+const checkArgs = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "list" || a === "init" || ["--fail-on-drift", "--fail-on-bounty", "--list", "--quiet", "--all"].includes(a)) continue;
+  if (CONSUMED.has(a)) {
+    i++; // skip its value
+    continue;
+  }
+  checkArgs.push(a);
+}
+
+// Config (optional) lives in the TARGET repo — never in the core. One loader for every door:
+// .arkitect/arkitect.config.json first, then arkitect.config.json, with `extends` resolution
+// (inherit other config files — objects deep-merge, the extending file wins).
+const { config, errors: cfgErrors } = loadWorkspaceConfig(root);
+for (const ce of cfgErrors) console.error(`[architect] bad config ${ce.file}: ${ce.error}`);
+// Extension checks mirror the config placement: an explicit config.extensionDirs (array) or
+// config.extensionDir (string) wins; otherwise <root>/.arkitect/your-checks when it exists, else
+// <root>/your-checks. Multiple extension roots let a workspace mount MORE check corpora alongside its
+// own hand (e.g. a legacy check tree being converged) — later roots shadow earlier ones by id.
+const extensionDirs = Array.isArray(config.extensionDirs)
+  ? config.extensionDirs
+  : [config.extensionDir || (existsSync(join(root, ".arkitect", "your-checks")) ? join(".arkitect", "your-checks") : "your-checks")];
+const coreRoot = join(PKG, "src", "checks"); // shipped CORE — what self-update refreshes
+const userRoots = extensionDirs.map((d) => join(root, d)); // 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, ...userRoots]);
+for (const le of loadErrors) console.error(`[architect] FAILED TO LOAD check ${le.file}: ${le.error}`); // load failures are NEVER quiet
+if (!quiet) 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 group = opt("--group", null); // run one discovery folder (e.g. architecture, css) — harness/CI sharding
+const onlyIds = only
+  ? new Set(
+      only
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean),
+    )
+  : null;
+let selected = onlyIds ? audits.filter((a) => onlyIds.has(a.id)) : audits;
+if (group) selected = selected.filter((a) => a.__group === group);
+if (excludeGroups.length) selected = selected.filter((a) => !excludeGroups.includes(a.__group));
+if (onlyIds && selected.length < onlyIds.size) {
+  const found = new Set(selected.map((a) => a.id));
+  for (const id of onlyIds) if (!found.has(id)) console.error(`[architect] no check with id '${id}'. Try: architect list`);
+}
+if ((only || group) && selected.length === 0) {
+  console.error(`[architect] no check matching ${only ? `id(s) '${only}'` : `group '${group}'`}. Try: architect list`);
+  process.exit(2);
+}
+
+const project = detectProject(root);
+const ctxBase = { root, config, project, options: { failOnDrift, failOnBounty, checkArgs }, vault: null };
+const outDir = resolve(root, opt("--out", join("tmp", "arkitect"))); // --out: shard-safe output dir (harness/CI)
+const { manifest } = await runAudits(selected, ctxBase, { outDir });
+
+const t = manifest.telemetry || {};
+const fmtMs = (ms) => (ms >= 10_000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms || 0)}ms`);
+const line = `Architect · ${manifest.checks.length} checks · ${manifest.gatingErrors} gating error(s) · ${manifest.advisoryFindings ?? 0} advisory finding(s) · ${manifest.warnings} warning(s) · ${manifest.crashed} crash(es) · ${fmtMs(t.totalDurationMs)} · ${t.totalBounces ?? 0} bounce(s) · nextAction=${manifest.pass.nextAction}`;
+console.log(manifest.pass.clean ? `✅ ${line}` : `⚠️  ${line}`);
+console.log("   → tmp/arkitect/FIX_QUEUE.md  ·  tmp/arkitect/manifest.json");
+
+process.exit(failOnDrift && manifest.gatingErrors > 0 ? 1 : 0);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "connections-arkitect",
+  "version": "0.3.4",
+  "type": "module",
+  "description": "The Connections Arkitect — 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": {
+    "arkitect": "./bin/arkitect.mjs"
+  },
+  "exports": {
+    ".": "./src/core/index.mjs",
+    "./finding": "./src/core/finding.mjs",
+    "./oracle": "./src/core/oracle/family-conformance.mjs",
+    "./package.json": "./package.json",
+    "./bin/arkitect.mjs": "./bin/arkitect.mjs",
+    "./src/core/init.mjs": "./src/core/init.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "your-checks",
+    "spine",
+    "arkitect.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,8 @@
+{
+  "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/agnostic/rules-docs.mjs

@@ -0,0 +1,92 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { rulesDocsDir as RULES_DOCS_DIR } from "@lunawerx/arkitect-core/paths";
+
+export const audit = {
+  id: "rules-docs",
+  title: "Rules-Docs Catalog (codebase-agnostic)",
+  category: "meta",
+  defaultConfig: { enabled: true, includeInAll: false, outputPath: "tmp/audits/RULES_DOCS_CATALOG.md" },
+  async run(context) {
+    let entries;
+    try {
+      const files = (await fs.readdir(RULES_DOCS_DIR)).filter((name) => name.endsWith(".md")).sort();
+      entries = await Promise.all(
+        files.map(async (file) => {
+          const absolute = path.join(RULES_DOCS_DIR, file);
+          const content = await fs.readFile(absolute, "utf8");
+          return {
+            file,
+            relativePath: path.relative(context.root, absolute).replace(/\\/g, "/"),
+            sections: extractSections(content),
+            bytes: content.length,
+          };
+        }),
+      );
+    } catch (error) {
+      return {
+        failed: false,
+        report: `# Rules-Docs Catalog\n\nFailed to read ${RULES_DOCS_DIR}: ${error.message}\n`,
+        outputPath: context.checkConfig.outputPath,
+        jsonPayload: { entries: [], error: error.message },
+      };
+    }
+
+    const report = renderMarkdown(entries);
+
+    return {
+      failed: false,
+      report,
+      outputPath: context.checkConfig.outputPath,
+      jsonPayload: { totalDecks: entries.length, totalSections: entries.reduce((sum, entry) => sum + entry.sections.length, 0), entries },
+    };
+  },
+};
+
+function extractSections(markdown) {
+  return markdown
+    .split("\n")
+    .filter((line) => /^##\s+/.test(line))
+    .map((line) => line.replace(/^##\s+/, "").trim());
+}
+
+function renderMarkdown(entries) {
+  const totalSections = entries.reduce((sum, entry) => sum + entry.sections.length, 0);
+  const lines = [
+    "# Rules-Docs Catalog",
+    "",
+    "Cross-cutting engineering rule decks shipped with `arkitect-core/rules-docs/`.",
+    "These are codebase-agnostic markdown references; project policies can opt in to",
+    "any subset by importing them directly.",
+    "",
+    `- Decks: ${entries.length}`,
+    `- Sections (\`## ...\`): ${totalSections}`,
+    "",
+    "## Decks",
+    "",
+    "| Deck | Sections | Path |",
+    "| --- | ---: | --- |",
+  ];
+
+  for (const entry of entries) {
+    const title = entry.file.replace(/\.md$/, "");
+    lines.push(`| ${title} | ${entry.sections.length} | \`${entry.relativePath}\` |`);
+  }
+
+  lines.push("", "## Section index", "");
+  for (const entry of entries) {
+    const title = entry.file.replace(/\.md$/, "");
+    lines.push(`### ${title}`, "");
+    if (entry.sections.length === 0) {
+      lines.push("_no `##` sections detected_", "");
+      continue;
+    }
+    for (const section of entry.sections) {
+      lines.push(`- ${section}`);
+    }
+    lines.push("");
+  }
+
+  return `${lines.join("\n")}\n`;
+}

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

@@ -0,0 +1,82 @@
+// 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,112 @@
+// 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",
+]);
+// A PEM BEGIN marker alone is not a leak — UI hint/placeholder copy legitimately shows the format
+// ("-----BEGIN … KEY-----\n…paste the whole key file…\n-----END … KEY-----"). Only flag when actual
+// key MATERIAL is present: a run of 40+ base64 chars between the BEGIN and END markers (same source
+// line for embedded/escaped string literals, or within the next 50 physical lines for real PEM
+// bodies). Fails toward FLAGGING: any parse surprise returns true so the rule can never be disarmed.
+function confirmKeyMaterial(lines, i) {
+  const BASE64_RUN = /[A-Za-z0-9+/=]{40,}/;
+  const BEGIN = /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/;
+  const END = /-----END (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/;
+  const bm = lines[i].match(BEGIN);
+  if (!bm) return true;
+  const rest = lines[i].slice(bm.index + bm[0].length);
+  const endSame = rest.match(END);
+  if (endSame) return BASE64_RUN.test(rest.slice(0, endSame.index));
+  if (BASE64_RUN.test(rest)) return true;
+  for (let j = i + 1; j < lines.length && j <= i + 50; j++) {
+    const em = lines[j].match(END);
+    if (em) return BASE64_RUN.test(lines[j].slice(0, em.index));
+    if (BASE64_RUN.test(lines[j])) return true;
+  }
+  return false;
+}
+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",
+    confirm: confirmKeyMaterial,
+  },
+  { 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]) && (!p.confirm || p.confirm(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 };
+  },
+};