failproofai 0.0.11-beta.1 → 0.0.11-beta.3

package/src/audit/features.ts

@@ -0,0 +1,268 @@
+/**
+ * Behavioural feature layer for the audit dashboard.
+ *
+ * Both the archetype classifier (`archetypes.ts`) and the score derivation
+ * (`scoring.ts`) read from the *same* derived features so they can never
+ * drift. Everything here is a pure function of `AuditResult` (+ an optional
+ * seed string) — no I/O, no clock, no `Math.random()`. Given the same input,
+ * every output is byte-identical on every run.
+ *
+ * Design goals (see the audit redesign):
+ *   1. All 8 personas reachable. Five are mapped by *which* faults dominate
+ *      (`SIGNAL_MAP`); three are relational — `precision` (low fault rate),
+ *      `architect` (faults are over-verification), `goldfish` (scattered).
+ *   2. No artificial skew. The catalog is cowboy-heavy (20 of 47 signals), so
+ *      a raw argmax would almost always pick cowboy. We rank by *lift over a
+ *      self-calibrated baseline* instead — cowboy's large baseline means it
+ *      has to over-index to win, neutralising the surface-area advantage.
+ *   3. Deterministic personalisation. A `fingerprint` hash of the rounded
+ *      behaviour vector seeds tie-breaks and copy-variant selection, so two
+ *      different agents that land on the same primary still look distinct,
+ *      while the same agent is always identical.
+ */
+import type { AuditResult } from "./types";
+import type { ArchetypeKey } from "./archetypes";
+
+/** djb2-style hash. Stable across renders/processes, no crypto needed.
+ *  Lives here (not archetypes.ts) so the feature layer has no import cycle. */
+export function hashSeed(s: string): number {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  return h >>> 0;
+}
+
+/** Strip the `failproofai/` namespace so map keys match the bare policy name. */
+export function shortName(name: string): string {
+  const slash = name.indexOf("/");
+  return slash >= 0 ? name.slice(slash + 1) : name;
+}
+
+/** All eight archetype keys, including the two relational ones. */
+export const ALL_ARCHETYPE_KEYS: ArchetypeKey[] = [
+  "optimist", "cowboy", "explorer", "goldfish",
+  "architect", "precision", "hammer", "ghost",
+];
+
+/**
+ * Personas that receive direct signal mapping. `precision` and `goldfish`
+ * are NOT here — they are derived from the *shape* of the distribution, not
+ * from any single policy. `architect` is mapped (it owns the two "caution"
+ * detectors) but is primarily reached via its ratio rule.
+ */
+export const MAPPABLE_KEYS: ArchetypeKey[] = [
+  "cowboy", "explorer", "ghost", "optimist", "hammer", "architect",
+];
+
+/** Active-fault personas ranked by lift in the classifier's argmax step. */
+export const ACTIVE_FAULT_KEYS: ArchetypeKey[] = [
+  "cowboy", "explorer", "ghost", "optimist", "hammer",
+];
+
+/** The two detectors that define "the paranoid architect" — pure
+ *  over-verification. When these dominate an agent's signal it is classified
+ *  architect regardless of raw weight. */
+export const ARCHITECT_CAUTION_SIGNALS = new Set(["reread-after-edit", "redundant-cd-cwd"]);
+
+/**
+ * Mapping from policy/detector short-name → which archetype its hits feed,
+ * and how heavily (intensity within the cluster). Every one of the 39 builtin
+ * policies and 8 audit-only detectors maps exactly once — no overlaps, full
+ * coverage. Weights express *severity within* a persona; cross-persona
+ * fairness is handled later by lift normalisation, not by these numbers.
+ */
+export const SIGNAL_MAP: Record<string, { archetype: ArchetypeKey; weight: number }> = {
+  // ── cowboy ── destructive / forceful / bypasses guardrails (20) ───────────
+  "block-rm-rf":               { archetype: "cowboy", weight: 2.0 },
+  "block-failproofai-commands":{ archetype: "cowboy", weight: 2.0 },
+  "block-sudo":                { archetype: "cowboy", weight: 1.5 },
+  "block-curl-pipe-sh":        { archetype: "cowboy", weight: 1.5 },
+  "block-force-push":          { archetype: "cowboy", weight: 1.5 },
+  "block-push-master":         { archetype: "cowboy", weight: 1.5 },
+  "block-work-on-main":        { archetype: "cowboy", weight: 1.2 },
+  "warn-destructive-sql":      { archetype: "cowboy", weight: 1.5 },
+  "warn-schema-alteration":    { archetype: "cowboy", weight: 1.0 },
+  "git-commit-no-verify":      { archetype: "cowboy", weight: 1.5 },
+  "warn-git-amend":            { archetype: "cowboy", weight: 0.8 },
+  "warn-git-stash-drop":       { archetype: "cowboy", weight: 1.0 },
+  "warn-all-files-staged":     { archetype: "cowboy", weight: 0.6 },
+  "block-kubectl":             { archetype: "cowboy", weight: 1.5 },
+  "block-terraform":           { archetype: "cowboy", weight: 1.5 },
+  "block-helm":                { archetype: "cowboy", weight: 1.2 },
+  "block-aws-cli":             { archetype: "cowboy", weight: 1.2 },
+  "block-gcloud":              { archetype: "cowboy", weight: 1.2 },
+  "block-az-cli":              { archetype: "cowboy", weight: 1.2 },
+  "block-gh-pipeline":         { archetype: "cowboy", weight: 1.2 },
+
+  // ── explorer ── boundary crossing / secrets exposure (10) ─────────────────
+  "sanitize-private-key-content":{ archetype: "explorer", weight: 1.5 },
+  "block-env-files":           { archetype: "explorer", weight: 1.5 },
+  "block-secrets-write":       { archetype: "explorer", weight: 1.5 },
+  "sanitize-api-keys":         { archetype: "explorer", weight: 1.2 },
+  "sanitize-jwt":              { archetype: "explorer", weight: 1.2 },
+  "sanitize-connection-strings":{ archetype: "explorer", weight: 1.2 },
+  "block-read-outside-cwd":    { archetype: "explorer", weight: 1.2 },
+  "sanitize-bearer-tokens":    { archetype: "explorer", weight: 1.0 },
+  "protect-env-vars":          { archetype: "explorer", weight: 1.0 },
+  "find-from-root":            { archetype: "explorer", weight: 1.0 },
+
+  // ── ghost ── unfinished / unsupervised work (7) ───────────────────────────
+  // NOTE: the five require-*-before-stop policies only fire on `Stop` events,
+  // which the audit replay never synthesises, so in practice ghost is reached
+  // via warn-large-file-write + warn-background-process. They are mapped here
+  // for completeness and in case a future Stop-replay path is added.
+  "require-ci-green-before-stop":   { archetype: "ghost", weight: 1.2 },
+  "require-commit-before-stop":     { archetype: "ghost", weight: 1.2 },
+  "require-push-before-stop":       { archetype: "ghost", weight: 1.0 },
+  "require-pr-before-stop":         { archetype: "ghost", weight: 1.0 },
+  "require-no-conflicts-before-stop":{ archetype: "ghost", weight: 1.0 },
+  "warn-large-file-write":     { archetype: "ghost", weight: 1.0 },
+  "warn-background-process":   { archetype: "ghost", weight: 0.8 },
+
+  // ── optimist ── low-friction shortcuts / sloppy tool choice (6) ───────────
+  "warn-package-publish":      { archetype: "optimist", weight: 1.0 },
+  "warn-global-package-install":{ archetype: "optimist", weight: 0.8 },
+  "prefer-package-manager":    { archetype: "optimist", weight: 0.8 },
+  "prefer-edit-over-sed-awk":  { archetype: "optimist", weight: 0.8 },
+  "prefer-edit-over-read-cat": { archetype: "optimist", weight: 0.5 },
+  "prefer-write-over-heredoc": { archetype: "optimist", weight: 0.5 },
+
+  // ── hammer ── brute-force repetition (2) ──────────────────────────────────
+  "warn-repeated-tool-calls":  { archetype: "hammer", weight: 1.5 },
+  "sleep-polling-loop":        { archetype: "hammer", weight: 1.2 },
+
+  // ── architect ── over-verification "caution" signals (2) ──────────────────
+  "reread-after-edit":         { archetype: "architect", weight: 1.0 },
+  "redundant-cd-cwd":          { archetype: "architect", weight: 0.8 },
+};
+
+/** Builtin severity derived from the policy name prefix. The builtin
+ *  definitions carry no static severity field — the runtime decision lives in
+ *  the policy fn — but the name prefix encodes intent deterministically:
+ *    sanitize-* → sanitize (gentle)   warn-/protect-/prefer-/require-* → warn
+ *    block-*    → deny (severe)        anything else → deny (safe default)
+ *  Replaces the old hardcoded `"deny"` so the score's medium/gentle buckets
+ *  actually populate. */
+export function severityForBuiltin(name: string): string {
+  const n = shortName(name);
+  if (n.startsWith("sanitize-")) return "sanitize";
+  if (n.startsWith("block-")) return "deny";
+  if (
+    n.startsWith("warn-") || n.startsWith("protect-") ||
+    n.startsWith("prefer-") || n.startsWith("require-")
+  ) return "warn";
+  return "deny";
+}
+
+function emptyWeights(): Record<ArchetypeKey, number> {
+  return {
+    optimist: 0, cowboy: 0, explorer: 0, goldfish: 0,
+    architect: 0, precision: 0, hammer: 0, ghost: 0,
+  };
+}
+
+/**
+ * Each mappable persona's *expected* share of total signal, derived directly
+ * from `SIGNAL_MAP` (sum of its weights ÷ sum of all weights). Self-calibrates
+ * whenever a weight changes. Used to compute lift = observed-share ÷ baseline,
+ * which is what removes the cowboy surface-area skew.
+ */
+export const BASELINE_SHARE: Record<ArchetypeKey, number> = (() => {
+  const raw = emptyWeights();
+  let total = 0;
+  for (const { archetype, weight } of Object.values(SIGNAL_MAP)) {
+    raw[archetype] += weight;
+    total += weight;
+  }
+  const out = emptyWeights();
+  for (const k of MAPPABLE_KEYS) out[k] = total > 0 ? raw[k] / total : 0;
+  return out;
+})();
+
+/** Normalised Shannon entropy of a lift vector, base = number of mappable
+ *  clusters (6). 0 = all signal in one persona, 1 = perfectly even spread.
+ *  Two equally-lit clusters score ~0.39 (not goldfish); ~4 even clusters
+ *  cross 0.77 (goldfish territory). */
+function normalizedEntropy(vals: number[]): number {
+  const total = vals.reduce((s, v) => s + Math.max(0, v), 0);
+  if (total <= 0) return 0;
+  let h = 0;
+  for (const v of vals) {
+    if (v <= 0) continue;
+    const p = v / total;
+    h -= p * Math.log(p);
+  }
+  return h / Math.log(vals.length);
+}
+
+/** Volume floor — a 3-call session shouldn't divide-by-tiny and explode. */
+export const MIN_EVENTS = 50;
+
+export interface AuditFeatures {
+  /** Tool calls scanned, floored at MIN_EVENTS. */
+  events: number;
+  sessions: number;
+  totalHits: number;
+  /** totalHits / events — the cleanliness denominator the old scorer ignored. */
+  faultRate: number;
+  /** Per-persona Σ(hits × weight). Same shape the old classifier returned. */
+  clusterRaw: Record<ArchetypeKey, number>;
+  totalSignal: number;
+  /** Per-persona observed-share ÷ baseline-share. The ranking metric. */
+  clusterLift: Record<ArchetypeKey, number>;
+  /** Normalised entropy of the lift vector (goldfish detector). */
+  entropy: number;
+  /** Share of total signal coming from the two architect caution detectors. */
+  cautionShare: number;
+  cowboyLift: number;
+  /** Deterministic hash of the rounded behaviour vector + seed. Seeds
+   *  tie-breaks and copy-variant selection. */
+  fingerprint: number;
+}
+
+function sumHits(result: AuditResult): number {
+  let s = 0;
+  for (const r of result.results) s += r.hits;
+  return s;
+}
+
+/** Derive the behaviour feature vector. Pure over (result, seed). */
+export function deriveFeatures(result: AuditResult, seed = ""): AuditFeatures {
+  const events = Math.max(result.eventsScanned ?? 0, MIN_EVENTS);
+  const sessions = result.transcripts.scanned;
+  const totalHits = result.totals?.hits ?? sumHits(result);
+
+  const clusterRaw = emptyWeights();
+  let cautionRaw = 0;
+  for (const row of result.results) {
+    const short = shortName(row.name);
+    const sig = SIGNAL_MAP[short];
+    if (!sig) continue;
+    const w = row.hits * sig.weight;
+    clusterRaw[sig.archetype] += w;
+    if (ARCHITECT_CAUTION_SIGNALS.has(short)) cautionRaw += w;
+  }
+
+  const totalSignal = MAPPABLE_KEYS.reduce((s, k) => s + clusterRaw[k], 0);
+
+  const clusterLift = emptyWeights();
+  for (const k of MAPPABLE_KEYS) {
+    const share = totalSignal > 0 ? clusterRaw[k] / totalSignal : 0;
+    clusterLift[k] = BASELINE_SHARE[k] > 0 ? share / BASELINE_SHARE[k] : 0;
+  }
+
+  const entropy = normalizedEntropy(MAPPABLE_KEYS.map((k) => clusterLift[k]));
+  const cautionShare = totalSignal > 0 ? cautionRaw / totalSignal : 0;
+  const faultRate = totalHits / events;
+
+  // Fingerprint: stable over the rounded behaviour signature + seed. Rounding
+  // keeps it stable against floating-point noise while still varying between
+  // genuinely different agents.
+  const sig = MAPPABLE_KEYS.map((k) => Math.round(clusterRaw[k] * 10)).join(",");
+  const fingerprint = hashSeed(`${seed}|${sig}|${Math.round(faultRate * 1000)}`);
+
+  return {
+    events, sessions, totalHits, faultRate,
+    clusterRaw, totalSignal, clusterLift, entropy,
+    cautionShare, cowboyLift: clusterLift.cowboy, fingerprint,
+  };
+}

package/src/audit/findings.ts

@@ -0,0 +1,298 @@
+/**
+ * Build the FindingsSection cards from a live AuditResult.
+ *
+ * Each card has four blocks (per reference design):
+ *   - what happened (prose summary, hand-written per policy)
+ *   - what this costs (severity / radius framing)
+ *   - evidence (real examples from the AuditResult)
+ *   - the fix (policy slug + install command — only when not enabled)
+ *
+ * The body / cost copy is hand-curated per policy/detector when we have
+ * good copy for it; otherwise we fall back to the policy's authored
+ * `displayTitle` + `impact` strings.
+ */
+import type { AuditCount, AuditResult } from "./types";
+
+/** Plain-text body so this module stays JSX-free and can be imported
+ *  server-side. The React layer renders these as paragraphs. */
+export interface FindingCopy {
+  body: string;
+  cost: string;
+}
+
+/**
+ * Audit-detector → builtin-policy mapping.
+ *
+ * Each audit-only detector is paired with the closest real-time policy
+ * that catches the same class of behavior. The detector still does the
+ * specific pattern-matching; the "fix" prescribed in the report is the
+ * builtin policy. Removes the "audit-only — no real-time policy yet"
+ * framing so every finding looks like it has a failproofai fix.
+ *
+ * Mappings authored against the policy catalog in src/hooks/builtin-policies.ts.
+ * The first entry is the primary fix (shown in the "$ install" block);
+ * additional entries are listed alongside as "also covered by".
+ */
+const DETECTOR_TO_POLICY: Record<string, { primary: string; also?: string }> = {
+  // wasteful shell: repetitive cd && cmd burns tokens — same class as
+  // 3+ identical tool calls
+  "redundant-cd-cwd":         { primary: "warn-repeated-tool-calls" },
+  // wrong tool choice: bash cat/head/tail on source files crosses the
+  // same file-read surface block-read-outside-cwd gates; the repetition
+  // is what warn-repeated-tool-calls would have caught
+  "prefer-edit-over-read-cat":{ primary: "block-read-outside-cwd",   also: "warn-repeated-tool-calls" },
+  // wrong tool choice: sed -i / awk > file route a write through the
+  // shell — same class as the repeated-mis-use pattern
+  "prefer-edit-over-sed-awk": { primary: "warn-repeated-tool-calls" },
+  // bash file bypass: heredoc / echo > file is the layer that bypasses
+  // the Write tool — both .env and secret-key writes route through it
+  "prefer-write-over-heredoc":{ primary: "block-env-files",          also: "block-secrets-write" },
+  // wasted execution: long sleeps + while-sleep loops are the same
+  // shape as backgrounded processes that never get cleaned up
+  "sleep-polling-loop":       { primary: "warn-background-process" },
+  // risky filesystem: find /, /home, /usr is exactly the class of
+  // out-of-cwd reads that block-read-outside-cwd gates
+  "find-from-root":           { primary: "block-read-outside-cwd" },
+  // hook bypass: --no-verify is a dangerous-commit-flag pattern; the
+  // bypass means CI / hooks never ran — both warn-git-amend's "rewriting
+  // history" class and the require-ci-green stop-gate cover this
+  "git-commit-no-verify":     { primary: "warn-git-amend",           also: "require-ci-green-before-stop" },
+  // wasteful reads: read after edit/write is identical-tool-call
+  // overhead — same redundant-invocation class
+  "reread-after-edit":        { primary: "warn-repeated-tool-calls" },
+};
+
+const FINDING_COPY: Record<string, FindingCopy> = {
+  "redundant-cd-cwd": {
+    body: "the agent runs `cd <cwd>` before commands it would have run from the same directory anyway. mostly harmless. occasionally it gets the path wrong and manufactures a new bug.",
+    cost: "tokens burned on redundant navigation. low security risk. high noise.",
+  },
+  "block-push-master": {
+    body: "attempts to push directly to main. branch protection caught some, but the agent kept going. each retry costs a round-trip and pollutes the audit log.",
+    cost: "branch protection saved you most of the time. the rest landed or required a revert.",
+  },
+  "block-force-push": {
+    body: "force pushes to non-main branches. fast-forward errors rewritten by overwriting remote history — risky on shared branches even when not main.",
+    cost: "lost commits, broken PR diffs, confused reviewers downstream.",
+  },
+  "block-work-on-main": {
+    body: "commits or merges made while the agent was sitting on main / master. work that should land via PR skipped review.",
+    cost: "code that didn't pass review made it into the default branch.",
+  },
+  "block-read-outside-cwd": {
+    body: "reads outside the project root. some hit credential files (~/.aws/credentials, ~/.config/openai/key, out-of-tree .env). none made it back to stdout — but they made it into context.",
+    cost: "credential exposure risk. data crossed project boundaries into the agent's context window.",
+  },
+  "block-env-files": {
+    body: "the agent tried to read or write `.env` files directly. these typically contain API keys and database credentials in plaintext.",
+    cost: "high exposure risk. secrets one tool-call away from leaving the project.",
+  },
+  "block-secrets-write": {
+    body: "attempts to write credential-shaped strings to files that aren't typically credential stores.",
+    cost: "could have committed live secrets to the repo.",
+  },
+  "block-rm-rf": {
+    body: "recursive deletes against paths that could plausibly take out unrelated work. `rm -rf` is the agent's preferred way of cleaning up — even when it shouldn't be.",
+    cost: "irreversible. one wrong path argument = lost work.",
+  },
+  "block-sudo": {
+    body: "sudo invocations from inside the agent shell. escalating to root inside an unsupervised tool call is rarely the answer.",
+    cost: "privilege escalation in a context where the agent isn't meant to have it.",
+  },
+  "block-curl-pipe-sh": {
+    body: "curl | sh patterns — fetching a remote script and piping it straight into the shell. no checksum, no review, no rollback.",
+    cost: "supply-chain attack surface. arbitrary code execution from a URL.",
+  },
+  "warn-repeated-tool-calls": {
+    body: "same call, same args, multiple times under 90 seconds. no diagnosis between attempts. the call's been failing for the same reason every time.",
+    cost: "retry overhead. sessions stall before manual correction.",
+  },
+  "sleep-polling-loop": {
+    body: "long sleeps or busy-wait loops where the agent waits for a state it has no reason to expect.",
+    cost: "wall-clock burned. better to wait for an explicit signal.",
+  },
+  "find-from-root": {
+    body: "`find` invoked against `/`, `/home`, `/usr`, etc. — searching the whole filesystem when a project-scoped query would have answered the question.",
+    cost: "exhausts resources. surfaces files outside the project that taint context.",
+  },
+  "git-commit-no-verify": {
+    body: "commits made with `--no-verify` / `-n`, skipping pre-commit hooks. the hooks exist to catch lint errors, broken types, malformed configs — bypassing them means those checks never ran.",
+    cost: "broken or unsafe code lands without the safety net.",
+  },
+  "prefer-edit-over-read-cat": {
+    body: "`cat` / `head` / `tail` on source files routed through Bash output instead of the Read tool. round-trips the file through a less efficient channel.",
+    cost: "burns tokens on shell output that the Read tool would have returned cleanly.",
+  },
+  "prefer-edit-over-sed-awk": {
+    body: "in-place edits via `sed -i` or `awk … > file`. no diff to inspect, no rollback if the regex was wrong.",
+    cost: "destructive when the regex matches more than expected. no verification surface.",
+  },
+  "prefer-write-over-heredoc": {
+    body: "multi-line file writes via heredoc or `echo > file`. the Write tool handles escaping and produces a verifiable diff.",
+    cost: "subtle escape bugs. content arrives in the file with quoting drift.",
+  },
+  "reread-after-edit": {
+    body: "reads of files that were Edit'd or Write'n earlier in the same session. the editor already returned the updated content — the second read is wasted.",
+    cost: "tokens spent re-fetching content the tool already returned.",
+  },
+  "warn-large-file-write": {
+    body: "writes to files significantly larger than typical for the project. blast radius increases with file size; large writes deserve a second look.",
+    cost: "harder to review, harder to roll back, easier to break something downstream.",
+  },
+  "warn-background-process": {
+    body: "spawned a background process and moved on. nothing watches the process; if it crashes the agent doesn't know.",
+    cost: "silent failures. resource leaks if the process never exits.",
+  },
+  "require-commit-before-stop": {
+    body: "the agent reported a task complete while changes were still uncommitted in the working tree.",
+    cost: "unsaved work. next session starts with a dirty checkout the agent thinks is clean.",
+  },
+  "require-push-before-stop": {
+    body: "the agent stopped with commits sitting only on the local branch — nothing pushed to the remote.",
+    cost: "no one else can see the work. silent loss if the machine dies.",
+  },
+  "require-pr-before-stop": {
+    body: "the agent stopped without opening a PR. the commits are on a branch nobody reviewed.",
+    cost: "no review, no merge path, no record that the work happened.",
+  },
+  "require-ci-green-before-stop": {
+    body: "the agent declared completion before CI returned green (or while CI was already failing).",
+    cost: "false completion signal. broken main if anyone trusts the agent's word.",
+  },
+};
+
+function shortName(name: string): string {
+  const slash = name.indexOf("/");
+  return slash >= 0 ? name.slice(slash + 1) : name;
+}
+
+function relTimeAgo(iso?: string): string {
+  if (!iso) return "—";
+  const ms = Date.now() - new Date(iso).getTime();
+  if (Number.isNaN(ms) || ms < 0) return "—";
+  const m = Math.floor(ms / 60_000);
+  if (m < 60) return `${Math.max(1, m)}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 30) return `${d}d ago`;
+  const months = Math.floor(d / 30);
+  return `${months}mo ago`;
+}
+
+export interface FindingCard {
+  num: string;
+  title: string;
+  count: number;
+  /** Unique identifier for React keys. This is the original detector
+   *  or policy short slug (e.g. "redundant-cd-cwd", "block-push-master"),
+   *  NOT the prescribed-fix slug — which can repeat across cards when
+   *  multiple detectors share the same fix policy. */
+  sourceSlug: string;
+  /** Slug shown in the meta line — the prescribed-fix policy. May
+   *  repeat across cards (e.g. several detectors → warn-repeated-tool-calls). */
+  policy: string;
+  projects: number;
+  lastSeen: string;
+  body: string;
+  cost: string;
+  evidence: { text: string; kind: "cmd" | "comment" | "err" }[];
+  /** Prescribed fix. Always populated now — detectors route to their
+   *  closest builtin policy (see DETECTOR_TO_POLICY). */
+  fix: { slug: string; desc: string; install: string; alsoCoveredBy?: string };
+  /** True when the prescribed fix policy is already in the user's
+   *  enabled set. UI tones the fix block accordingly. */
+  alreadyEnabled: boolean;
+}
+
+/** Build the per-policy/detector finding cards. Ranks by hits desc and
+ *  drops rows that would otherwise be uninformative (zero hits). */
+export function deriveFindings(result: AuditResult): FindingCard[] {
+  const sorted = [...result.results]
+    .filter((r) => r.hits > 0)
+    .sort((a, b) => b.hits - a.hits);
+
+  const enabledSet = new Set(result.enabledBuiltinNames ?? []);
+  return sorted.map((r, i) => buildCard(r, i, enabledSet));
+}
+
+/** Lightweight metadata for a policy that we may need to display even
+ *  when the policy didn't fire on its own (a detector pointed at it).
+ *  Mirrors the relevant subset of `BuiltinPolicy` so this module stays
+ *  client-bundle-safe (no node imports). */
+const POLICY_META: Record<string, { displayTitle: string; impact: string }> = {
+  "warn-repeated-tool-calls": {
+    displayTitle: "Called the same tool 3+ times with identical arguments",
+    impact: "catches identical-arg retries before they spiral into a token-burning loop.",
+  },
+  "block-read-outside-cwd": {
+    displayTitle: "Tried to read files outside your project directory",
+    impact: "denies reads of files outside the project root, including symlinks.",
+  },
+  "block-env-files": {
+    displayTitle: "Tried to read or write a .env file",
+    impact: "blocks reads and writes of `.env` files at the tool layer.",
+  },
+  "block-secrets-write": {
+    displayTitle: "Tried to write a secret-key file",
+    impact: "blocks writes to .pem, id_rsa, credentials.json, and similar.",
+  },
+  "warn-background-process": {
+    displayTitle: "Started a long-lived background process",
+    impact: "warns on nohup / & / screen / tmux / disown patterns the agent forgets to clean up.",
+  },
+  "warn-git-amend": {
+    displayTitle: "Used git commit --amend",
+    impact: "warns before amending — same class as dangerous-commit-flag bypasses.",
+  },
+  "require-ci-green-before-stop": {
+    displayTitle: "Stopped with failing CI",
+    impact: "requires CI checks to pass on HEAD before declaring done.",
+  },
+};
+
+function buildCard(r: AuditCount, idx: number, enabledSet: Set<string>): FindingCard {
+  const slug = shortName(r.name);
+  const isDetector = r.source === "audit-detector";
+  const mapping = isDetector ? DETECTOR_TO_POLICY[slug] : undefined;
+
+  // For a detector, the prescribed fix points at its mapped policy.
+  // For a builtin row, it points at itself.
+  const fixSlug = mapping?.primary ?? slug;
+  const meta = POLICY_META[fixSlug];
+  const fixDesc = meta?.impact ?? r.impact ?? r.displayTitle;
+  const alsoCoveredBy = mapping?.also;
+
+  const alreadyEnabled = enabledSet.has(fixSlug)
+    || (r.source === "builtin" && r.enabledInConfig);
+
+  const copy = FINDING_COPY[slug];
+
+  const evidence: FindingCard["evidence"] = r.examples.slice(0, 4).map((e) => ({
+    text: e.example,
+    kind: "cmd" as const,
+  }));
+  if (evidence.length === 0) {
+    evidence.push({ text: "no example commands captured.", kind: "comment" });
+  }
+
+  return {
+    num: String(idx + 1).padStart(2, "0"),
+    title: r.displayTitle.toLowerCase(),
+    count: r.hits,
+    sourceSlug: slug,
+    policy: fixSlug,
+    projects: r.projects,
+    lastSeen: relTimeAgo(r.lastSeen),
+    body: copy?.body ?? r.impact ?? r.displayTitle,
+    cost: copy?.cost ?? r.impact ?? "see policy description above.",
+    evidence,
+    fix: {
+      slug: fixSlug,
+      desc: fixDesc,
+      install: `failproofai policy add ${fixSlug}`,
+      alsoCoveredBy,
+    },
+    alreadyEnabled,
+  };
+}