connections-arkitect 0.3.4

package/src/core/init.mjs

@@ -0,0 +1,64 @@
+// initWorkspace — the OPT-IN install: put the Architect into a codebase, under `.arkitect/`.
+// This runs ONLY when explicitly chosen (`architect init`, or the MCP `architect_install` tool on a
+// direct request like "I want the Architect in this codebase"). Nothing in the Architect ever creates
+// `.arkitect/` as a side effect of a normal run — installing is a choice, never a surprise.
+//
+// What it lays down (the core/yours split, physically):
+//   .arkitect/arkitect.config.json    — your config (update channel, check tuning, hosted targets)
+//   .arkitect/your-checks/             — YOUR code checks (core never writes here; same-id shadows core)
+//   .arkitect/spines/                  — YOUR DB policy (the hosted half's "yours" space)
+// The CORE lives in the package itself (npm + the self-update channel) — pulling a newer core never
+// touches any of the files below, so updating is always safe and always a choice (autoUpdate /
+// pinnedVersion / fork-and-own).
+//
+// Idempotent + additive: every file is written ONLY if absent; re-running installs nothing over you.
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+const DEFAULT_CONFIG = {
+  $note:
+    "The Architect's per-workspace config. YOUR files are this one + your-checks/ + spines/ — a core update never touches them. hosted.targets take NON-SECRET coordinates only (ARNs, database names); credentials stay in the Connections vault (hosted checks run credential-blind through the MCP).",
+  version: 1,
+  update: { channel: "stable", pinnedVersion: null, autoUpdate: true },
+  checks: {},
+  hosted: { failOnBounty: false, targets: [] },
+};
+
+/**
+ * Install the Architect's per-workspace layout under `<root>/.arkitect/`.
+ * @param {string} root    - target repo root
+ * @param {string} pkgRoot - this package's root (templates are copied from the shipped examples)
+ * @returns {{ created: string[], skipped: string[] }} repo-relative paths written vs already-present
+ */
+export function initWorkspace(root, pkgRoot) {
+  const created = [];
+  const skipped = [];
+  const put = (rel, content) => {
+    const abs = join(root, rel);
+    if (existsSync(abs)) {
+      skipped.push(rel);
+      return;
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content, "utf8");
+    created.push(rel);
+  };
+  const template = (rel, fallback) => {
+    try {
+      return readFileSync(join(pkgRoot, rel), "utf8");
+    } catch {
+      return fallback;
+    }
+  };
+
+  // Deliberately MINIMAL: the Architect needs no workspace state to RUN (core-only runs create
+  // nothing but tmp/arkitect/), so this scaffolds only the extension space — a config and the
+  // README that teaches the format. No example check is seeded (a seeded check would show up in
+  // `list` as noise that isn't yours); the README carries the copy-paste skeleton instead.
+  put(join(".arkitect", "arkitect.config.json"), JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
+  put(
+    join(".arkitect", "your-checks", "README.md"),
+    template(join("your-checks", "README.md"), "# your-checks/\n\nYour own Architect checks. The core never touches this folder.\n"),
+  );
+  return { created, skipped };
+}

package/src/core/oracle/family-conformance.mjs

@@ -0,0 +1,77 @@
+// Generic, project-agnostic conformance oracle — the reference-mode counterpart to sibling-consensus'
+// consensus mode. Distilled from arkitect's `family-conformance-engine`: declare what CORRECT looks like
+// (a reference member OR the majority) and flag any diverger. One oracle replaces dozens of point-checks
+// and catches divergence nobody has named yet.
+//
+// Usage:
+//   const { findings } = await runFamilyConformance({ family, project, mode, referenceId });
+//   // findings: Array<{ member, expected, actual }> — raw divergences; the CALLER creates Finding objects.
+
+/**
+ * Run conformance checking over a family of members.
+ *
+ * @param {object} opts
+ * @param {Array<{path:string, [key:string]:any}>} opts.family   Members to compare; each must have `path`.
+ * @param {function(member): any}                  opts.project  Extracts a comparable fingerprint per member.
+ * @param {"reference"|"consensus"}                opts.mode     How to derive the expected fingerprint.
+ * @param {string}                                 [opts.referenceId]  (reference mode) path or id to use as truth.
+ * @returns {Promise<{findings: Array<{member,expected,actual}>, consensusOrReference: any}>}
+ */
+export async function runFamilyConformance({ family, project, mode, referenceId }) {
+  if (!Array.isArray(family) || family.length === 0) {
+    return { findings: [], consensusOrReference: null };
+  }
+
+  // Compute fingerprints for all members. `project` may be async.
+  const projected = await Promise.all(
+    family.map(async (member) => {
+      let fingerprint;
+      try {
+        fingerprint = await project(member);
+      } catch {
+        fingerprint = null;
+      }
+      return { member, fingerprint, key: JSON.stringify(fingerprint ?? null) };
+    }),
+  );
+
+  let expectedKey;
+  let consensusOrReference;
+
+  if (mode === "reference") {
+    // Find the reference member by `path` (or `.id` as fallback).
+    const ref = projected.find((p) => p.member.path === referenceId || p.member.id === referenceId);
+    if (!ref) {
+      // No reference found — cannot judge; return clean.
+      return { findings: [], consensusOrReference: null };
+    }
+    expectedKey = ref.key;
+    consensusOrReference = ref.fingerprint;
+  } else {
+    // Consensus: the most common fingerprint across the family.
+    const counts = new Map();
+    for (const p of projected) counts.set(p.key, (counts.get(p.key) || 0) + 1);
+    const [topKey] = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+    const topCount = counts.get(topKey);
+    // Only meaningful when a clear majority (> half) exists.
+    if (topCount <= projected.length / 2) {
+      return { findings: [], consensusOrReference: null };
+    }
+    expectedKey = topKey;
+    consensusOrReference = JSON.parse(topKey);
+  }
+
+  const findings = [];
+  for (const p of projected) {
+    // In reference mode, skip the reference member itself.
+    if (mode === "reference") {
+      const isRef = p.member.path === referenceId || p.member.id === referenceId;
+      if (isRef) continue;
+    }
+    if (p.key !== expectedKey) {
+      findings.push({ member: p.member, expected: JSON.parse(expectedKey), actual: p.fingerprint });
+    }
+  }
+
+  return { findings, consensusOrReference };
+}

package/src/core/project-detect.mjs

@@ -0,0 +1,126 @@
+// THE portability primitive (distilled from arkitect's project-detect + `requires` gating).
+// Detect what a repo IS (languages / ecosystems / frameworks) from the filesystem, then let each check
+// declare `requires:{…}` and SKIP itself when the repo doesn't match. A generic CORE check declares
+// `requires:{}` (or omits it) → runs on ANY repo. This is what makes a check portable to a stranger's codebase.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, extname } from "node:path";
+
+const MANIFEST_ECOSYSTEM = {
+  "package.json": "npm",
+  "Cargo.toml": "cargo",
+  "go.mod": "go",
+  "requirements.txt": "pip",
+  "pyproject.toml": "pip",
+  Gemfile: "gem",
+  "composer.json": "composer",
+  "pom.xml": "maven",
+  "build.gradle": "gradle",
+};
+const EXT_LANG = {
+  ".ts": "typescript",
+  ".tsx": "typescript",
+  ".js": "javascript",
+  ".jsx": "javascript",
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".py": "python",
+  ".rs": "rust",
+  ".go": "go",
+  ".rb": "ruby",
+  ".java": "java",
+  ".php": "php",
+  ".vue": "vue",
+  ".svelte": "svelte",
+};
+export const IGNORE_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  "cdk.out",
+  ".next",
+  ".nuxt",
+  "coverage",
+  "tmp",
+  ".turbo",
+  "vendor",
+  "target",
+  ".codegraph",
+]);
+
+// Generated dir-name FAMILIES (dist-consent, dist-login, cdk.out.api, …) — a plain Set can't hold
+// a prefix. `cdk.out.` covers the dotted synth-output variants a plane mints per stack; the bare
+// `cdk.out` stays in IGNORE_DIRS above.
+const IGNORE_DIR_PREFIXES = ["dist-", "cdk.out."];
+
+// Generated trees whose leaf names are too generic to ignore by name alone — a real source
+// `public/` exists in every web root; only the Capacitor webDir COPIES are generated.
+// Matched as posix path-suffixes of the DIRECTORY being considered.
+export const IGNORE_PATH_MARKERS = ["android/app/src/main/assets/public", "ios/App/App/public"];
+
+/** One canonical answer to "is this directory generated/vendored output?" — name + optional full path. */
+export function isIgnoredDir(name, dirPath = "") {
+  if (IGNORE_DIRS.has(name)) return true;
+  if (IGNORE_DIR_PREFIXES.some((prefix) => name.startsWith(prefix))) return true;
+  if (!dirPath) return false;
+  const posix = dirPath.replace(/\\/g, "/");
+  return IGNORE_PATH_MARKERS.some((marker) => posix.endsWith(`/${marker}`) || posix === marker);
+}
+
+export function detectProject(root) {
+  const ecosystems = new Set();
+  for (const [f, eco] of Object.entries(MANIFEST_ECOSYSTEM)) if (existsSync(join(root, f))) ecosystems.add(eco);
+
+  const frameworks = new Set();
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    if (deps.vue || deps.nuxt) frameworks.add("vue");
+    if (deps.react || deps.next) frameworks.add("react");
+    if (deps.svelte) frameworks.add("svelte");
+    if (deps.express || deps.fastify) frameworks.add("node-server");
+  } catch {
+    /* no/unreadable package.json — fine */
+  }
+
+  // Sample file extensions with a bounded walk (don't traverse the whole tree).
+  const languages = new Set();
+  let budget = 4000;
+  const walk = (dir) => {
+    if (budget <= 0) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (budget <= 0) return;
+      if (e.name.startsWith(".")) continue;
+      if (e.isDirectory()) {
+        if (!isIgnoredDir(e.name, join(dir, e.name))) walk(join(dir, e.name));
+        continue;
+      }
+      budget--;
+      const lang = EXT_LANG[extname(e.name)];
+      if (lang) languages.add(lang);
+    }
+  };
+  walk(root);
+
+  return { root, languages: [...languages], ecosystems: [...ecosystems], frameworks: [...frameworks] };
+}
+
+// A check runs only if every dimension it requires is satisfied. Empty/absent `requires` ⇒ always runs.
+export function checkAppliesToProject(requires, project) {
+  if (!requires) return true;
+  const ok = (key) => {
+    const need = requires[key];
+    if (!need || need.length === 0) return true;
+    const have = project[key] || [];
+    return need.some((v) => have.includes(v));
+  };
+  return ok("languages") && ok("ecosystems") && ok("frameworks");
+}

package/src/core/runner.mjs

@@ -0,0 +1,369 @@
+// The runner — per-check gating, crash≠drift, gating-vs-advisory, and the agent-facing FIX_QUEUE.md +
+// manifest.json with `pass.nextAction`. Splits checks by domain: `code` checks always run; `hosted`
+// checks run only when a vault handle is present (so plain `npx architect` runs the code half with no
+// cloud creds). Also writes findings.sarif (SARIF 2.1.0) and DECISION_BRIEF.json.
+//
+// NATIVE TELEMETRY (core feature — every check gets it, forever, with zero effort from the check's
+// author): the runner itself records, per check, (a) wall-clock DURATION and (b) BOUNCES — every
+// outbound network round-trip the check made, counted and timed at the two seams the runner controls:
+// the vault handle (hosted DB/cloud calls) and global fetch (HTTP). "It worked" is half a report; the
+// other half is "it went out 87 times at 200ms each" — that's how a green check explains a 30-second
+// login. Aggregates land in the manifest + FIX_QUEUE; the per-hop detail lands in telemetry.json.
+//
+// SAVED REPORTS: when the target repo has a `.arkitect/` (the user opted into workspace state),
+// every run is archived to `.arkitect/reports/<stamp>/` — manifest + FIX_QUEUE + telemetry + each
+// check's full report — so "what did it find last Tuesday" is a folder, not a memory. Pruned to
+// `reports.keep` (default 20). No `.arkitect/` ⇒ no archive (a bare run stays stateless).
+import { mkdirSync, writeFileSync, existsSync, readdirSync, rmSync, copyFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { countSeverities } from "./finding.mjs";
+import { checkAppliesToProject } from "./project-detect.mjs";
+import { toSarif } from "./sarif.mjs";
+
+const now = () => globalThis.performance?.now?.() ?? Date.now();
+const HOP_DETAIL_CAP = 500; // per-hop entries kept for telemetry.json (aggregates are never capped)
+
+// REPORT-ONLY checks (legacy style: `{ failed, report }`, no findings[]) still count correctly: derive
+// error/warning totals from the report's own summary lines — every `Errors:`/`Warnings:` line SUMMED
+// (multi-section reports emit one per section), `**bold**` and parenthetical-qualifier forms included,
+// with a `## rule — 3 (error|warning)` heading fallback. Same semantics the legacy manifest used, so a
+// check that never emits findings[] gates and reports identically under this engine.
+const SUM_ERR_RE = /(?:\*\*)?errors(?:\s*\([^)]*\))?\s*:(?:\*\*)?\s*(\d+)/gi;
+const SUM_WARN_RE = /(?:\*\*)?warnings(?:\s*\([^)]*\))?\s*:(?:\*\*)?\s*(\d+)/gi;
+const HEADING_SEV_RE = /^#{2,}[^\n]*?—\s*(\d+)\s*\((error|warning)s?\)/gim;
+function countsFromReport(text) {
+  const sum = (re) => {
+    re.lastIndex = 0;
+    let total = 0,
+      matched = false,
+      m;
+    while ((m = re.exec(text)) !== null) {
+      total += Number.parseInt(m[1], 10) || 0;
+      matched = true;
+    }
+    return { total, matched };
+  };
+  const e = sum(SUM_ERR_RE);
+  const w = sum(SUM_WARN_RE);
+  if (e.matched || w.matched) return { errors: e.total, warnings: w.total };
+  let errors = 0,
+    warnings = 0,
+    m;
+  HEADING_SEV_RE.lastIndex = 0;
+  while ((m = HEADING_SEV_RE.exec(text)) !== null) {
+    if (m[2].toLowerCase() === "error") errors += Number.parseInt(m[1], 10) || 0;
+    else warnings += Number.parseInt(m[1], 10) || 0;
+  }
+  return { errors, warnings };
+}
+
+// Wrap the vault handle so every awsCall is counted + timed. Preserves the handle's shape.
+// Sets tel.inVault during the call so the fetch seam does NOT double-count the HTTP request a vault
+// call rides on — one real round-trip is one bounce, whichever seam it entered through.
+function instrumentVault(vault, tel) {
+  if (!vault || typeof vault.awsCall !== "function") return vault;
+  return {
+    ...vault,
+    async awsCall(...args) {
+      const t0 = now();
+      tel.inVault++;
+      try {
+        return await vault.awsCall(...args);
+      } finally {
+        tel.inVault--;
+        const ms = now() - t0;
+        tel.count++;
+        tel.totalMs += ms;
+        if (ms > tel.maxMs) tel.maxMs = ms;
+        if (tel.hops.length < HOP_DETAIL_CAP) tel.hops.push({ seam: "vault", ms: Math.round(ms * 10) / 10 });
+      }
+    },
+  };
+}
+
+export async function runAudits(audits, ctxBase, { outDir }) {
+  mkdirSync(outDir, { recursive: true });
+  const results = [];
+  for (const audit of audits) {
+    if (!checkAppliesToProject(audit.requires, ctxBase.project)) {
+      results.push({ id: audit.id, audit, status: "skipped", reason: "requires-not-met" });
+      continue;
+    }
+    if (audit.domain === "hosted" && !ctxBase.vault) {
+      results.push({ id: audit.id, audit, status: "skipped", reason: "no-vault: run via the Connections MCP to enable hosted checks" });
+      continue;
+    }
+    const checkConfig = { ...(audit.defaultConfig || {}), ...((ctxBase.config?.checks || {})[audit.id] || {}) };
+    // A workspace may override a check's gating in config (checks.<id>.gating: false ⇒ advisory) —
+    // the visible, reviewable way to acknowledge known findings without silencing the check.
+    const effectiveGating = typeof checkConfig.gating === "boolean" ? checkConfig.gating : audit.gating;
+
+    // Telemetry seams for THIS check: instrumented vault + instrumented global fetch. The runner is
+    // sequential, so the fetch swap cannot bleed across checks; it is ALWAYS restored.
+    const tel = { count: 0, totalMs: 0, maxMs: 0, hops: [], inVault: 0 };
+    // checkArgs is ALWAYS an array (single-check CLI invocations may carry extra args; suite runs get
+    // []) — checks are entitled to call ctx.checkArgs.filter(...) without guarding.
+    const ctx = { ...ctxBase, checkArgs: ctxBase.options?.checkArgs || [], checkConfig, vault: instrumentVault(ctxBase.vault, tel) };
+    const realFetch = globalThis.fetch;
+    if (typeof realFetch === "function") {
+      globalThis.fetch = async (...args) => {
+        // A fetch made INSIDE a vault call is that same round-trip's transport — already counted.
+        if (tel.inVault > 0) return realFetch(...args);
+        const t0 = now();
+        try {
+          return await realFetch(...args);
+        } finally {
+          const ms = now() - t0;
+          tel.count++;
+          tel.totalMs += ms;
+          if (ms > tel.maxMs) tel.maxMs = ms;
+          if (tel.hops.length < HOP_DETAIL_CAP) tel.hops.push({ seam: "fetch", ms: Math.round(ms * 10) / 10 });
+        }
+      };
+    }
+
+    const started = now();
+    let out;
+    try {
+      out = await audit.run(ctx);
+    } catch (e) {
+      // A check that THROWS always fails the run, separately from findings — never a silent pass.
+      results.push({
+        id: audit.id,
+        audit,
+        status: "crashed",
+        gating: effectiveGating,
+        error: String(e?.stack || e?.message || e)
+          .split("\n")
+          .slice(0, 3)
+          .join("\n"),
+        findings: [],
+        failed: true,
+        durationMs: Math.round(now() - started),
+        bounces: { count: tel.count, totalMs: Math.round(tel.totalMs), maxMs: Math.round(tel.maxMs) },
+        hops: tel.hops,
+      });
+      if (typeof realFetch === "function") globalThis.fetch = realFetch;
+      continue;
+    } finally {
+      if (typeof realFetch === "function") globalThis.fetch = realFetch;
+    }
+    const durationMs = Math.round(now() - started);
+    const findings = out?.findings || [];
+    // Normalize severity dialects ONCE, here — every consumer downstream (counts, gating, SARIF,
+    // DECISION_BRIEF ordering) then agrees. "warn"/"review"→warning, "err"/"fatal"→error, "note"→info.
+    // (Only adjudicated dialects are mapped — domain scales like axe's minor/serious pass through.)
+    for (const f of findings) {
+      if (f && typeof f.severity === "string") {
+        const s = f.severity.toLowerCase();
+        f.severity =
+          s === "warn" || s === "review"
+            ? "warning"
+            : s === "err" || s === "fatal"
+              ? "error"
+              : s === "note" || s === "information"
+                ? "info"
+                : s;
+      }
+    }
+    const counts = findings.length ? countSeverities(findings) : out?.report ? countsFromReport(out.report) : countSeverities(findings);
+    const failed = out?.failed ?? counts.errors > 0;
+    // Write the report whenever the check surfaced ANYTHING — including the thermometer shape
+    // (error-severity findings from a check that chose not to fail): an advisory finding with no
+    // report on disk is invisible to the AI-first reader, which is the disarmed-check failure mode.
+    if (out?.report && (failed || counts.errors > 0 || counts.warnings > 0)) {
+      const path = out.outputPath || join(outDir, `${audit.id}.md`);
+      try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, out.report);
+      } catch {
+        /* best-effort report write */
+      }
+    }
+    results.push({
+      id: audit.id,
+      audit,
+      status: failed ? "failed" : counts.warnings ? "warned" : "clean",
+      gating: effectiveGating,
+      findings,
+      counts,
+      failed,
+      report: out?.report || "",
+      durationMs,
+      bounces: { count: tel.count, totalMs: Math.round(tel.totalMs), maxMs: Math.round(tel.maxMs) },
+      hops: tel.hops,
+    });
+  }
+  return summarize(results, outDir, ctxBase);
+}
+
+function rank(r) {
+  if (r.status === "crashed") return 0;
+  if (r.status === "failed") return 1;
+  return 2;
+}
+
+const SEV_ORDER = { error: 0, warning: 1, info: 2 };
+const fmtMs = (ms) => (ms >= 10_000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms)}ms`);
+
+function summarize(results, outDir, ctxBase = {}) {
+  let totalErrors = 0,
+    gatingErrors = 0,
+    advisoryFindings = 0,
+    warnings = 0,
+    crashed = 0;
+  for (const r of results) {
+    if (r.status === "crashed") {
+      crashed++;
+      gatingErrors++;
+      continue;
+    }
+    const c = r.counts || { errors: 0, warnings: 0 };
+    totalErrors += c.errors;
+    warnings += c.warnings;
+    // `gating !== false` ⇒ a check MAY gate the run; it actually gates only when it also FAILED.
+    // Every error-severity finding that does NOT block — from a gating:false check OR from a check
+    // that emitted errors but chose not to fail (the thermometer shape: crap-score/complexity emit
+    // per-site error findings yet only warn) — is counted SEPARATELY as an advisory. In the roll-up,
+    // "error" must only ever mean "fix me" (AI-first legibility, owner directive 2026-07-04): an
+    // agent reading the summary should never reverse-engineer which errors block and which are
+    // thermometer readings a living codebase never drives to zero.
+    if ((r.gating ?? r.audit.gating) !== false && r.failed) gatingErrors += c.errors || 1;
+    else advisoryFindings += c.errors;
+  }
+  const clean = gatingErrors === 0;
+  const nextAction = gatingErrors > 0 ? "fix-errors" : warnings > 0 ? "review-warnings" : "done";
+
+  // Run-level telemetry rollup.
+  const ran = results.filter((r) => typeof r.durationMs === "number");
+  const totalDurationMs = ran.reduce((s, r) => s + r.durationMs, 0);
+  const totalBounces = ran.reduce((s, r) => s + (r.bounces?.count || 0), 0);
+  const slowest = [...ran]
+    .sort((a, b) => b.durationMs - a.durationMs)
+    .slice(0, 3)
+    .map((r) => ({ id: r.id, durationMs: r.durationMs, bounces: r.bounces?.count || 0 }));
+
+  const telLine = (r) =>
+    typeof r.durationMs === "number"
+      ? `  [${fmtMs(r.durationMs)}${r.bounces?.count ? ` · ${r.bounces.count} bounce${r.bounces.count === 1 ? "" : "s"}` : ""}]`
+      : "";
+  const offenders = results
+    .filter((r) => r.status === "failed" || r.status === "crashed" || r.status === "warned")
+    .sort((a, b) => rank(a) - rank(b));
+  const queue = offenders.map((r) => {
+    const configAdvisory = (r.gating ?? r.audit.gating) === false;
+    // Non-blocking errors — config-advisory checks AND warned-not-failed thermometer checks —
+    // count "a", never "e", so a scan of the queue for `e/` finds only genuinely blocking work
+    // (the same AI-first legibility rule as the summary counts).
+    const nonBlocking = configAdvisory || (r.status !== "failed" && r.status !== "crashed");
+    const tag = r.status === "crashed" ? "CRASH" : configAdvisory ? "ADVISORY" : r.status === "warned" ? "WARN" : "ERROR";
+    const detail =
+      r.status === "crashed"
+        ? `  ${r.error?.split("\n")[0] || ""}`
+        : `  (${r.counts?.errors || 0}${nonBlocking ? "a" : "e"}/${r.counts?.warnings || 0}w)`;
+    return `- [${tag}] ${r.id} — ${r.audit.title}${detail}${telLine(r)}`;
+  });
+  writeFileSync(
+    join(outDir, "FIX_QUEUE.md"),
+    `# Architect — Fix Queue\n\nnextAction: ${nextAction}\ntotal: ${fmtMs(totalDurationMs)} · ${totalBounces} bounce${totalBounces === 1 ? "" : "s"} across ${ran.length} check(s)\n\n${queue.join("\n") || "✅ all clean"}\n`,
+  );
+
+  const manifest = {
+    totalErrors,
+    gatingErrors,
+    // Error-severity findings from ADVISORY (gating:false) checks — thermometer readings
+    // (complexity/duplication/churn) to harvest worst-first, never a block-the-run signal.
+    advisoryFindings,
+    warnings,
+    crashed,
+    telemetry: { totalDurationMs, totalBounces, slowest },
+    checks: results.map((r) => ({
+      id: r.id,
+      group: r.audit.__group ?? null,
+      status: r.status,
+      // Per-row: `gating` = the check's configuration; `blocking` = whether THIS run's errors
+      // actually gate (config-gating AND failed) — so an agent never cross-references which
+      // errors block. A gating:true/blocking:false row is the thermometer shape.
+      gating: (r.gating ?? r.audit.gating) !== false,
+      blocking: (r.gating ?? r.audit.gating) !== false && (r.status === "failed" || r.status === "crashed"),
+      errors: r.counts?.errors || 0,
+      warnings: r.counts?.warnings || 0,
+      ...(typeof r.durationMs === "number" ? { durationMs: r.durationMs, bounces: r.bounces } : {}),
+      ...(r.reason ? { reason: r.reason } : {}),
+    })),
+    pass: { clean, nextAction },
+  };
+  writeFileSync(join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+
+  // Per-hop telemetry detail — the "pull the actual trace" file for any check whose aggregate looks off.
+  try {
+    const telemetry = ran.map((r) => ({ id: r.id, durationMs: r.durationMs, bounces: r.bounces, hops: r.hops || [] }));
+    writeFileSync(join(outDir, "telemetry.json"), JSON.stringify({ totalDurationMs, totalBounces, checks: telemetry }, null, 2));
+  } catch {
+    /* best-effort */
+  }
+
+  // SARIF 2.1.0 output.
+  try {
+    writeFileSync(join(outDir, "findings.sarif"), JSON.stringify(toSarif(results), null, 2));
+  } catch {
+    /* best-effort */
+  }
+
+  // DECISION_BRIEF — flat, sorted array of all findings enriched with check metadata.
+  try {
+    const brief = [];
+    for (const r of results) {
+      for (const f of r.findings || []) {
+        brief.push({ ...f, checkId: r.id, checkTitle: r.audit?.title ?? r.id });
+      }
+    }
+    brief.sort((a, b) => {
+      const sa = SEV_ORDER[a.severity] ?? 99;
+      const sb = SEV_ORDER[b.severity] ?? 99;
+      if (sa !== sb) return sa - sb;
+      return (a.checkId ?? "").localeCompare(b.checkId ?? "");
+    });
+    writeFileSync(join(outDir, "DECISION_BRIEF.json"), JSON.stringify(brief, null, 2));
+  } catch {
+    /* best-effort */
+  }
+
+  // SAVED REPORTS — archive this run under .arkitect/reports/<stamp>/ when (and only when) the
+  // target repo has a .arkitect/ (opted-in state). Every check's FULL report is kept here, even the
+  // ones the live outDir omits (it only writes failing/warning reports), so depth is never lost.
+  try {
+    const root = ctxBase.root;
+    if (root && existsSync(join(root, ".arkitect"))) {
+      const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+      const dir = join(root, ".arkitect", "reports", stamp);
+      mkdirSync(dir, { recursive: true });
+      for (const f of ["manifest.json", "FIX_QUEUE.md", "telemetry.json", "DECISION_BRIEF.json"]) {
+        try {
+          copyFileSync(join(outDir, f), join(dir, f));
+        } catch {
+          /* file may not exist on this run */
+        }
+      }
+      for (const r of results) {
+        if (r.report) {
+          try {
+            writeFileSync(join(dir, `${r.id}.md`), r.report);
+          } catch {
+            /* best-effort */
+          }
+        }
+      }
+      // Prune to reports.keep (default 20), oldest first — an archive that grows forever is a leak.
+      const keep = Number(ctxBase.config?.reports?.keep ?? 20);
+      const runs = readdirSync(join(root, ".arkitect", "reports")).sort();
+      for (const old of runs.slice(0, Math.max(0, runs.length - keep))) {
+        rmSync(join(root, ".arkitect", "reports", old), { recursive: true, force: true });
+      }
+    }
+  } catch {
+    /* archiving must never break a run */
+  }
+
+  return { results, manifest, outDir };
+}