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

package/src/audit/report.ts

@@ -0,0 +1,349 @@
+/**
+ * Output renderers for `failproofai audit`:
+ *   • formatText      — ANSI table to stdout (GTM-oriented "moment of truth")
+ *   • formatMarkdown  — shareable sectioned report written to a file
+ *   • formatJson      — machine-readable
+ *
+ * The text renderer is the user's first impression of the audit. It leads
+ * with a headline-box, splits findings into "already protected" vs "slipping
+ * through" so the conversion ask is obvious, and ends with a copy-pasteable
+ * install command + report path + star link.
+ */
+import type { AuditCount, AuditResult, RunAuditOptions } from "./types";
+
+const ANSI = {
+  reset: "\x1B[0m",
+  dim: "\x1B[2m",
+  bold: "\x1B[1m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m",
+  green: "\x1B[32m",
+  cyan: "\x1B[36m",
+  magenta: "\x1B[35m",
+};
+
+/** Honor https://no-color.org / NO_COLOR=1 and FORCE_COLOR=0 by stripping all
+ *  ANSI sequences from the final output. Detected once per renderer call. */
+function noColorEnabled(): boolean {
+  if (process.env.NO_COLOR && process.env.NO_COLOR !== "") return true;
+  if (process.env.FORCE_COLOR === "0") return true;
+  return false;
+}
+
+function stripAnsi(s: string): string {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1B\[[0-9;]*m/g, "");
+}
+
+/** Human-readable "time ago" — "30m ago", "2h ago", "3d ago", "2w ago".
+ *  Returns "just now" for <1 minute. */
+function formatTimeAgo(iso: string | undefined): 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 < 1) return "just now";
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 14) return `${d}d ago`;
+  const w = Math.floor(d / 7);
+  if (w < 8) return `${w}w ago`;
+  return `${Math.floor(d / 30)}mo ago`;
+}
+
+/** Width of the headline box and section dividers. Adapts to narrow terminals
+ *  down to a 60-char floor. */
+function getWidth(): number {
+  const cols = process.stdout.columns ?? 80;
+  return Math.max(60, Math.min(78, cols));
+}
+
+/** Box-drawing helpers using unicode round-corner glyphs. */
+function topBorder(w: number): string { return `╭${"─".repeat(w - 2)}╮`; }
+function bottomBorder(w: number): string { return `╰${"─".repeat(w - 2)}╯`; }
+function boxLine(text: string, w: number): string {
+  const inner = w - 4; // 2 chars of border + 1 char padding each side
+  const visible = stripAnsi(text);
+  const pad = Math.max(0, inner - visible.length);
+  return `│ ${text}${" ".repeat(pad)} │`;
+}
+function divider(w: number): string { return "─".repeat(w); }
+
+/** Short, qualified policy slug — `failproofai/foo` → `foo` for display. */
+function shortName(name: string): string {
+  const slash = name.indexOf("/");
+  return slash >= 0 ? name.slice(slash + 1) : name;
+}
+
+/** Sum hits across an AuditCount[] subset. */
+function sumHits(rows: AuditCount[]): number {
+  return rows.reduce((acc, r) => acc + r.hits, 0);
+}
+
+/** Render one row in the table-of-findings form:
+ *      31× Tried to read files outside your project
+ *           Stops the agent from peeking at neighboring repos…
+ *           Last seen 2h ago · 6 projects
+ *           › Already enforced — failproofai is blocking these in real time.
+ *           Example: grep -n …
+ */
+function renderRow(r: AuditCount, opts: { showExamples?: boolean }): string[] {
+  const out: string[] = [];
+  const sev = r.severity;
+  const titleColor =
+    sev === "deny" ? ANSI.red
+      : sev === "warn" ? ANSI.red
+        : sev === "info" || sev === "instruct" ? ANSI.yellow
+          : ANSI.cyan;
+  const countStr = String(r.hits).padStart(4);
+  out.push(`  ${titleColor}${ANSI.bold}${countStr}×${ANSI.reset}  ${r.displayTitle}`);
+  if (r.impact) {
+    out.push(`        ${ANSI.dim}${r.impact}${ANSI.reset}`);
+  }
+  out.push(
+    `        ${ANSI.dim}Last seen ${formatTimeAgo(r.lastSeen)} · ${r.projects} project${r.projects === 1 ? "" : "s"}${ANSI.reset}`,
+  );
+  if (opts.showExamples && r.examples[0]) {
+    out.push(`        ${ANSI.dim}Example: ${r.examples[0].example}${ANSI.reset}`);
+  }
+  if (r.installHint) {
+    const arrowColor = r.enabledInConfig ? ANSI.green : ANSI.cyan;
+    out.push(`        ${arrowColor}›${ANSI.reset} ${r.installHint}`);
+  }
+  out.push("");
+  return out;
+}
+
+export function formatText(result: AuditResult, opts: RunAuditOptions = {}): string {
+  const w = getWidth();
+  const limit = opts.limit ?? 20;
+  const showExamples = !!opts.showExamples;
+
+  // Split rows by enforcement state.
+  const enabledRows = result.results.filter((r) => r.source === "builtin" && r.enabledInConfig);
+  const unenabledBuiltinRows = result.results.filter((r) => r.source === "builtin" && !r.enabledInConfig);
+  const detectorRows = result.results.filter((r) => r.source === "audit-detector");
+  // "Slipping through" combines unenabled-builtins + audit-detectors, ranked by hits.
+  const slippingRows = [...unenabledBuiltinRows, ...detectorRows].sort((a, b) => b.hits - a.hits);
+
+  const totalProtected = sumHits(enabledRows);
+  const totalSlipping = sumHits(slippingRows);
+  const totalHits = totalProtected + totalSlipping;
+  const sinceLabel = result.scope.since ? `the last ${result.scope.since}` : "all time";
+
+  const lines: string[] = [];
+
+  // ── Header ──────────────────────────────────────────────────────
+  lines.push(`${ANSI.cyan}🛡  failproofai audit${ANSI.reset} ${ANSI.dim}[beta]${ANSI.reset}  ·  ${sinceLabel}`);
+  lines.push(
+    `   ${ANSI.dim}${result.transcripts.scanned} sessions · ${result.totals.projectsWithHits} project${result.totals.projectsWithHits === 1 ? "" : "s"} with hits · scanned in ${(result.transcripts.durationMs / 1000).toFixed(1)}s${ANSI.reset}`,
+  );
+  lines.push("");
+
+  // ── Headline box ────────────────────────────────────────────────
+  if (totalHits === 0) {
+    lines.push(topBorder(w));
+    lines.push(boxLine(`${ANSI.green}🎉 Clean run!${ANSI.reset}  Nothing matched your policies in this window.`, w));
+    lines.push(bottomBorder(w));
+    lines.push("");
+    return noColorEnabled() ? stripAnsi(lines.join("\n")) : lines.join("\n");
+  }
+  lines.push(topBorder(w));
+  lines.push(boxLine(
+    `${ANSI.bold}Your agent did ${totalHits} wasteful or risky things in ${sinceLabel}.${ANSI.reset}`,
+    w,
+  ));
+  if (totalSlipping > 0) {
+    lines.push(boxLine(
+      `${totalSlipping} of those would've been caught if more policies were on.`,
+      w,
+    ));
+  }
+  lines.push(bottomBorder(w));
+  lines.push("");
+
+  // ── Section: ALREADY PROTECTED ──────────────────────────────────
+  if (enabledRows.length > 0) {
+    lines.push(
+      `${ANSI.green}✓ ALREADY PROTECTED${ANSI.reset}  ${ANSI.dim}(${totalProtected} action${totalProtected === 1 ? "" : "s"} stopped by your current policies)${ANSI.reset}`,
+    );
+    lines.push("");
+    for (const row of enabledRows.slice(0, limit)) {
+      lines.push(...renderRow(row, { showExamples }));
+    }
+    if (enabledRows.length > limit) {
+      lines.push(`  ${ANSI.dim}… ${enabledRows.length - limit} more (use --limit ${enabledRows.length})${ANSI.reset}`);
+      lines.push("");
+    }
+  }
+
+  // ── Section: SLIPPING THROUGH ───────────────────────────────────
+  if (slippingRows.length > 0) {
+    lines.push(
+      `${ANSI.yellow}○ SLIPPING THROUGH${ANSI.reset}  ${ANSI.dim}(${totalSlipping} action${totalSlipping === 1 ? "" : "s"} caught by audit, not blocked in real time)${ANSI.reset}`,
+    );
+    lines.push("");
+    for (const row of slippingRows.slice(0, limit)) {
+      lines.push(...renderRow(row, { showExamples }));
+    }
+    if (slippingRows.length > limit) {
+      lines.push(`  ${ANSI.dim}… ${slippingRows.length - limit} more (use --limit ${slippingRows.length})${ANSI.reset}`);
+      lines.push("");
+    }
+  }
+
+  // ── Footer / NEXT step ──────────────────────────────────────────
+  lines.push(divider(w));
+  if (unenabledBuiltinRows.length > 0) {
+    const installNames = unenabledBuiltinRows.map((r) => shortName(r.name));
+    lines.push(
+      `${ANSI.bold}NEXT${ANSI.reset}  Enable the ${installNames.length} unenabled real-time polic${installNames.length === 1 ? "y" : "ies"} in one command:`,
+    );
+    lines.push("");
+    lines.push(`      ${ANSI.cyan}failproofai policies --install ${installNames.join(" ")}${ANSI.reset}`);
+    lines.push("");
+  } else if (slippingRows.length > 0) {
+    lines.push(
+      `${ANSI.bold}NEXT${ANSI.reset}  Everything blockable is already enabled. Audit-only findings will show up in your next ${ANSI.cyan}failproofai audit${ANSI.reset}.`,
+    );
+    lines.push("");
+  } else {
+    lines.push(`${ANSI.bold}NEXT${ANSI.reset}  ${ANSI.green}You have the relevant policies enabled. failproofai is blocking these in real time.${ANSI.reset}`);
+    lines.push("");
+  }
+
+  // Mirror the actual --report path so the printed footer matches what was
+  // (or will be) written. Suppressed entirely with --no-report.
+  if (!opts.noReport) {
+    const reportPath = opts.reportPath ?? "./failproofai-audit.md";
+    lines.push(`      📄 Shareable report:  ${ANSI.cyan}${reportPath}${ANSI.reset}`);
+  }
+  lines.push(`      ⭐ Star us:           ${ANSI.cyan}https://github.com/FailproofAI/failproofai${ANSI.reset}`);
+  lines.push("");
+
+  return noColorEnabled() ? stripAnsi(lines.join("\n")) : lines.join("\n");
+}
+
+export function formatJson(result: AuditResult): string {
+  return JSON.stringify(result, null, 2);
+}
+
+/** Escape characters that would break a markdown table row. Pipes split
+ *  columns; backslashes escape the next char; leading newlines end the row. */
+function escapeTableCell(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/[\r\n]+/g, " ");
+}
+
+function escapeBackticks(s: string): string {
+  return s.replace(/`/g, "\\`");
+}
+
+export function formatMarkdown(result: AuditResult): string {
+  const out: string[] = [];
+
+  const enabledRows = result.results.filter((r) => r.source === "builtin" && r.enabledInConfig);
+  const unenabledBuiltinRows = result.results.filter((r) => r.source === "builtin" && !r.enabledInConfig);
+  const detectorRows = result.results.filter((r) => r.source === "audit-detector");
+  const slippingRows = [...unenabledBuiltinRows, ...detectorRows].sort((a, b) => b.hits - a.hits);
+
+  const totalProtected = sumHits(enabledRows);
+  const totalSlipping = sumHits(slippingRows);
+  const totalHits = totalProtected + totalSlipping;
+  const sinceLabel = result.scope.since ? `last ${result.scope.since}` : "all time";
+
+  out.push(`# Agent behavior audit · ${sinceLabel}`);
+  out.push("");
+  out.push("> _Generated by `failproofai audit` (**beta**) — flags and output may change between releases. Going live shortly._");
+  out.push("");
+  out.push(`*Generated ${result.scannedAt} — scanned ${result.transcripts.scanned} sessions across ${result.totals.projectsWithHits} project(s) in ${(result.transcripts.durationMs / 1000).toFixed(1)}s.*`);
+  out.push("");
+
+  // TL;DR — readable to someone who doesn't know failproofai.
+  out.push("## TL;DR");
+  out.push("");
+  if (totalHits === 0) {
+    out.push("Clean run — the AI coding agent didn't do anything `failproofai` catches in this window.");
+  } else {
+    out.push(
+      `Over ${result.transcripts.scanned} sessions, my AI coding agent did **${totalHits} things \`failproofai\` would have stopped**: ` +
+      `${totalProtected} were already blocked in real time by my current config; ` +
+      `**${totalSlipping} slipped through** (would've been caught if more policies were on).`,
+    );
+  }
+  out.push("");
+  out.push("> [failproofai](https://github.com/FailproofAI/failproofai) is a hook-based policy engine for Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, and Gemini CLI. The `audit` command replays past agent sessions through every builtin policy to surface patterns that were (or could've been) stopped.");
+  out.push("");
+
+  if (totalHits === 0) return out.join("\n");
+
+  // What was blocked
+  if (enabledRows.length > 0) {
+    out.push(`## ✓ Already protected (${totalProtected} action${totalProtected === 1 ? "" : "s"} stopped)`);
+    out.push("");
+    out.push("These are real-time policies you have on — `failproofai` blocked the agent before each action took effect.");
+    out.push("");
+    out.push("| Issue | Hits | Projects | Last seen | Policy |");
+    out.push("|---|---:|---:|---|---|");
+    for (const r of enabledRows) {
+      out.push(
+        `| ${escapeTableCell(r.displayTitle)} | ${r.hits} | ${r.projects} | ${formatTimeAgo(r.lastSeen)} | \`${escapeTableCell(shortName(r.name))}\` |`,
+      );
+    }
+    out.push("");
+  }
+
+  // What's slipping through
+  if (slippingRows.length > 0) {
+    out.push(`## ○ Slipping through (${totalSlipping} action${totalSlipping === 1 ? "" : "s"} caught by audit, not yet blocked)`);
+    out.push("");
+    out.push("Patterns the audit detected but real-time enforcement isn't on for. The CTA column shows how to fix each.");
+    out.push("");
+    out.push("| Issue | Hits | Projects | Last seen | Fix |");
+    out.push("|---|---:|---:|---|---|");
+    for (const r of slippingRows) {
+      const fix = r.source === "builtin"
+        ? `\`failproofai policies --install ${shortName(r.name)}\``
+        : "_audit-only_";
+      out.push(
+        `| ${escapeTableCell(r.displayTitle)} | ${r.hits} | ${r.projects} | ${formatTimeAgo(r.lastSeen)} | ${fix} |`,
+      );
+    }
+    out.push("");
+
+    if (unenabledBuiltinRows.length > 0) {
+      out.push(`### Enable everything in one command`);
+      out.push("");
+      out.push("```bash");
+      out.push(`failproofai policies --install ${unenabledBuiltinRows.map((r) => shortName(r.name)).join(" ")}`);
+      out.push("```");
+      out.push("");
+    }
+  }
+
+  // Examples appendix (only if non-trivial)
+  const rowsWithExamples = [...enabledRows, ...slippingRows].filter((r) => r.examples.length > 0);
+  if (rowsWithExamples.length > 0) {
+    out.push("## Examples");
+    out.push("");
+    for (const r of rowsWithExamples) {
+      out.push(`### ${escapeBackticks(r.displayTitle)} (\`${escapeBackticks(shortName(r.name))}\`)`);
+      out.push("");
+      if (r.impact) {
+        out.push(`> ${r.impact}`);
+        out.push("");
+      }
+      for (const e of r.examples) {
+        out.push(`- \`${escapeBackticks(e.example)}\` _(${e.cwd || "?"}, ${formatTimeAgo(e.timestamp)})_`);
+      }
+      out.push("");
+    }
+  }
+
+  out.push("---");
+  out.push("");
+  out.push("⭐ Star failproofai on GitHub: <https://github.com/FailproofAI/failproofai>");
+  out.push("");
+  return out.join("\n");
+}

package/src/audit/scoring.ts

@@ -0,0 +1,174 @@
+/**
+ * Score derivation for the audit dashboard.
+ *
+ * Score is on 0-100, mapped to letter grades that anchor the leaderboard
+ * + tier prose. The thresholds match the reference design (assets/audit):
+ *
+ *     ≥ 90  S    "s tier"
+ *     ≥ 80  A    "a tier"
+ *     ≥ 71  B    "b tier"
+ *     ≥ 55  C    "c tier"
+ *     ≥ 40  D    "d tier"
+ *     <  40 F    "f tier"
+ *
+ * The "projected score" is the hypothetical score after enabling every
+ * recommended unenabled-builtin policy — used by the prescription section
+ * to motivate enabling them.
+ */
+import type { AuditResult } from "./types";
+
+export type Grade = "S" | "A" | "B" | "C" | "D" | "F";
+
+export function gradeFor(score: number): Grade {
+  if (score >= 90) return "S";
+  if (score >= 80) return "A";
+  if (score >= 71) return "B";
+  if (score >= 55) return "C";
+  if (score >= 40) return "D";
+  return "F";
+}
+
+const TIER_NAME: Record<Grade, string> = {
+  S: "s tier", A: "a tier", B: "b tier",
+  C: "c tier", D: "d tier", F: "f tier",
+};
+
+export function tierName(g: Grade): string {
+  return TIER_NAME[g];
+}
+
+/**
+ * Heuristic score on 0-100. Three properties make it *dynamic* — distinct
+ * inputs (almost) never collide on a fixed threshold the way the old
+ * hard-capped scorer did:
+ *
+ *   1. Rate-normalised. Penalty scales with the *rate* of weighted faults per
+ *      tool call (× REF_EVENTS), not the absolute count. A 1000-call session
+ *      with 25 denies scores higher than a 100-call one with 25 denies — and
+ *      heavy users no longer all pile onto the same cap.
+ *
+ *   2. Saturating, not clipped. Each severity bucket asymptotes to a cap via
+ *      `cap·(1 − e^(−p/k))` instead of `min(p, cap)`. One bad area still can't
+ *      tank the score, but the curve is *strictly monotonic*, so every extra
+ *      hit still moves the number — no two counts land on the same value.
+ *
+ *   3. Credited. Up to +5 from the derived strengths, so clean agents spread
+ *      upward instead of all sitting at 100.
+ *
+ * Per-hit weights (pre-normalisation): deny 1.2, warn/instruct 0.7,
+ * sanitize 0.4, audit detector 0.5. Bucket caps 50 / 28 / 16 / 30 (they sum
+ * past 100 so a multi-dimension reckless agent can bottom out at F).
+ *
+ * Sessions with zero scanned transcripts return 0 (no signal, no grade).
+ */
+import { MIN_EVENTS } from "./features";
+import { deriveStrengths } from "./strengths";
+
+/** Reference tool-call volume the rate is normalised against — chosen so a
+ *  moderate footprint lands around C/B and the demo anchor (~58 → C) holds.
+ *  Calibrated via __tests__/audit/scoring.test.ts. */
+const REF_EVENTS = 300;
+
+/** Concave saturator: → `cap` as `p → ∞`, strictly increasing for all p ≥ 0. */
+function saturate(p: number, cap: number, k: number): number {
+  return cap * (1 - Math.exp(-p / k));
+}
+
+/** Total weighted penalty for a set of rows, rate-normalised against `events`.
+ *  Shared by `deriveScore` and `projectedScore` so they can't diverge. */
+function penaltyFor(rows: AuditResult["results"], events: number): number {
+  const norm = REF_EVENTS / Math.max(events, MIN_EVENTS);
+  let deny = 0, instruct = 0, sanitize = 0, detector = 0;
+  for (const row of rows) {
+    if (row.source === "audit-detector") {
+      detector += row.hits * 0.5;
+      continue;
+    }
+    const sev = row.severity;
+    if (sev === "deny") deny += row.hits * 1.2;
+    else if (sev === "instruct" || sev === "warn") instruct += row.hits * 0.7;
+    else sanitize += row.hits * 0.4; // sanitize-* and any other gentle category
+  }
+  // Per-bucket (cap, k). The cap bounds any single failure mode; k sets how
+  // fast it ramps. k is small relative to the cap so penalties bite early and
+  // the score uses the full S→F range rather than clustering near 100. Caps
+  // sum past 100 on purpose, so a multi-dimension reckless agent can reach F.
+  return (
+    saturate(deny * norm, 50, 12) +
+    saturate(instruct * norm, 28, 10) +
+    saturate(sanitize * norm, 16, 8) +
+    saturate(detector * norm, 30, 14)
+  );
+}
+
+/** Positive credit (0-5) from the heuristic strengths. Deliberately small so a
+ *  reckless agent's "absence" strengths (e.g. "no credential leaks") can't
+ *  inflate it back into the top tier. */
+function creditFor(result: AuditResult): number {
+  return Math.min(deriveStrengths(result).length * 1.0, 5);
+}
+
+/** Exact (unrounded) score — used by tests to prove strict monotonicity and
+ *  the absence of threshold collisions. */
+export function deriveScoreExact(result: AuditResult): number {
+  if (result.transcripts.scanned === 0) return 0;
+  const events = result.eventsScanned ?? 0;
+  const score = 100 - penaltyFor(result.results, events) + creditFor(result);
+  return Math.max(0, Math.min(100, score));
+}
+
+export function deriveScore(result: AuditResult): number {
+  return Math.round(deriveScoreExact(result));
+}
+
+/**
+ * Projected score after enabling every unenabled builtin. Doesn't actually
+ * re-run the audit — instead it credits back the hits the user would have
+ * blocked by enabling those policies, applying the same weighted penalty
+ * scheme used by `deriveScore`.
+ *
+ * Caps at 92 so the prescription never promises a guaranteed S — the user
+ * still has to keep the policies on.
+ */
+export function projectedScore(result: AuditResult, currentScore: number): number {
+  const events = result.eventsScanned ?? 0;
+  // Penalty as-is vs. penalty with every unenabled builtin's hits removed
+  // (enabling those policies would have blocked them). The delta is what the
+  // user recovers — computed through the same saturating, rate-normalised
+  // curve as `deriveScore`, so the projection is consistent rather than a
+  // naive per-hit sum.
+  const full = penaltyFor(result.results, events);
+  const fixedRows = result.results.filter(
+    (r) => !(r.source === "builtin" && !r.enabledInConfig),
+  );
+  const fixed = penaltyFor(fixedRows, events);
+  const recoverable = Math.max(0, full - fixed);
+  // Cap at 92 so the prescription never promises a guaranteed S.
+  const proj = Math.min(92, currentScore + Math.round(recoverable));
+  return Math.max(currentScore, proj);
+}
+
+/**
+ * Approximate global rank in the cohort. We don't have a real leaderboard
+ * yet — this is a deterministic synthetic rank derived from the score so
+ * the UI doesn't feel jittery as the user re-runs.
+ *
+ * Distribution roughly matches a bell-shape centered at 60. Cohort size
+ * is fixed at 2316 to match the reference design.
+ */
+export const COHORT_SIZE = 2316;
+
+export function syntheticRank(score: number): number {
+  // Roughly: 100 → top of leaderboard, 0 → bottom. Use a smooth curve so
+  // small score changes feel meaningful but not catastrophic.
+  const percentile = scoreToPercentile(score);
+  return Math.max(1, Math.min(COHORT_SIZE, Math.round((1 - percentile) * COHORT_SIZE)));
+}
+
+function scoreToPercentile(score: number): number {
+  // Logistic mapping centered at 58 — agents below 58 fall into the long
+  // tail, agents above climb steeply. Anchors the default demo (58 → ~p20).
+  const z = (score - 58) / 14;
+  const p = 1 / (1 + Math.exp(-z));
+  return p;
+}

package/src/audit/strengths.ts

@@ -0,0 +1,138 @@
+/**
+ * Derive the StrengthsSection rows from a live AuditResult.
+ *
+ * The reference (assets/audit/audit.jsx) ships 5 hand-curated strengths
+ * with placeholder numbers. Here we compute each one off the actual
+ * scanned data. Output shape mirrors the original.
+ *
+ * Most strengths are "absences" — the cleaner the agent, the more
+ * strengths we surface (e.g. "0 credential leaks" only counts as a
+ * strength when no sanitize-* policies fired).
+ */
+import type { AuditResult } from "./types";
+
+export interface Strength {
+  metric: string;
+  unit: string;
+  headline: string;
+  detail: string;
+}
+
+function shortName(name: string): string {
+  const slash = name.indexOf("/");
+  return slash >= 0 ? name.slice(slash + 1) : name;
+}
+
+function hitsForShort(result: AuditResult, names: string[]): number {
+  const set = new Set(names);
+  let total = 0;
+  for (const r of result.results) {
+    if (set.has(shortName(r.name))) total += r.hits;
+  }
+  return total;
+}
+
+/** Pick up to 5 derived strengths. Each strength has a true-or-not test —
+ *  only included when the agent actually demonstrates the behavior. */
+export function deriveStrengths(result: AuditResult): Strength[] {
+  const out: Strength[] = [];
+  const events = result.eventsScanned ?? 0;
+  const totalHits = result.totals.hits;
+  const detectorsTriggered = result.results.filter((r) => r.source === "audit-detector").length;
+  const cleanRate = events > 0 ? Math.max(0, Math.min(100, Math.round(((events - totalHits) / events) * 100))) : 100;
+
+  // 1. Always show the "X tool calls, Y detectors triggered" headline.
+  if (events > 0) {
+    out.push({
+      metric: `${cleanRate}%`,
+      unit: "clean tool calls",
+      headline: `ran ${events.toLocaleString()} tool calls. ${detectorsTriggered} detector${detectorsTriggered === 1 ? "" : "s"} triggered.`,
+      detail: `${cleanRate}% of tool calls came back clean before today's audit.`,
+    });
+  }
+
+  // 2. Zero credential exposure to stdout — only when no sanitize-* and no
+  //    block-env-files / block-secrets-write / block-read-outside-cwd hits.
+  const credentialPolicies = [
+    "sanitize-api-keys", "sanitize-jwt", "sanitize-connection-strings",
+    "sanitize-private-key-content", "sanitize-bearer-tokens",
+    "block-env-files", "block-secrets-write", "block-read-outside-cwd",
+    "protect-env-vars",
+  ];
+  if (hitsForShort(result, credentialPolicies) === 0) {
+    out.push({
+      metric: "0",
+      unit: "credential leaks",
+      headline: "zero credential exposure to stdout.",
+      detail: "no env files, secret writes, or sanitize hits across the audit window.",
+    });
+  }
+
+  // 3. Average sessions task length — `events / sessions`. Faster than
+  //    median (50) is celebrated; slower than it is mentioned in findings.
+  if (result.transcripts.scanned > 0 && events > 0) {
+    const avgTurns = Math.max(1, Math.round(events / result.transcripts.scanned));
+    if (avgTurns < 30) {
+      out.push({
+        metric: String(avgTurns),
+        unit: "avg turns / session",
+        headline: `sessions complete in ${avgTurns} turns on average.`,
+        detail: avgTurns < 15
+          ? "faster than the median agent in this cohort."
+          : "comfortably within the typical session length envelope.",
+      });
+    }
+  }
+
+  // 4. No retry storms — `warn-repeated-tool-calls` + `sleep-polling-loop`
+  //    are both quiet.
+  const retryHits = hitsForShort(result, ["warn-repeated-tool-calls", "sleep-polling-loop"]);
+  if (retryHits === 0) {
+    out.push({
+      metric: "0",
+      unit: "retry storms",
+      headline: "no retry storms or polling loops detected.",
+      detail: "failed calls were diagnosed or moved on from. no six-times-in-a-row spirals.",
+    });
+  }
+
+  // 5. No production-shape git mistakes.
+  const gitHits = hitsForShort(result, [
+    "block-push-master", "block-force-push", "block-work-on-main",
+    "git-commit-no-verify",
+  ]);
+  if (gitHits === 0) {
+    out.push({
+      metric: "0",
+      unit: "push-to-main attempts",
+      headline: "kept changes off main without prompting.",
+      detail: "no direct pushes, force pushes, or hook bypasses across every session.",
+    });
+  }
+
+  // 6. No double-writes / re-reads — agent is efficient with edits.
+  const wastefulEdits = hitsForShort(result, [
+    "reread-after-edit", "prefer-edit-over-sed-awk", "prefer-write-over-heredoc",
+  ]);
+  if (wastefulEdits === 0 && events > 0) {
+    out.push({
+      metric: "0",
+      unit: "double-writes",
+      headline: "no double-writes across production projects.",
+      detail: "the agent never re-read a file it had just edited, or rewrote via shell.",
+    });
+  }
+
+  // Cap to 5. If we somehow have <2 strengths, surface a generic "no
+  // findings in this category" so the section never looks empty.
+  if (out.length < 2) {
+    out.push({
+      metric: "—",
+      unit: "audit window",
+      headline: "audit complete.",
+      detail: `${result.transcripts.scanned} session${result.transcripts.scanned === 1 ? "" : "s"} scanned across ${result.totals.projectsWithHits} project${result.totals.projectsWithHits === 1 ? "" : "s"}.`,
+    });
+  }
+
+  return out.slice(0, 5);
+}