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

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, 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.

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 |