supipowers 1.5.3 → 2.0.0

package/src/harness/anti_slop/installer.ts

@@ -0,0 +1,227 @@
+/**
+ * Anti-slop backend installer.
+ *
+ * Writes the per-backend config, ensures `.desloppify/` is gitignored when desloppify is
+ * the chosen backend, and triggers `desloppify update-skill <client>` for each agent-skill
+ * distribution target the user opted into during Design.
+ *
+ * Idempotent: running the installer twice with the same inputs is a no-op (existing config
+ * files are read first, then either overwritten with identical content or left untouched).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { Platform, PlatformPaths } from "../../platform/types.js";
+import type { HarnessAntiSlopBackend, HarnessLayerRule } from "../../types.js";
+import {
+  getHarnessFallowConfigPath,
+} from "../project-paths.js";
+
+export interface InstallInput {
+  cwd: string;
+  backend: HarnessAntiSlopBackend;
+  /** Layer rules from Design — used to seed fallow's architecture-boundaries section. */
+  layerRules: readonly HarnessLayerRule[];
+  /** Agent-skill distribution targets (e.g. "claude", "cursor"). */
+  skillTargets: readonly string[];
+  /** Detected entry points (binaries, packages). Used by fallow's entry section. */
+  entryPoints: readonly string[];
+  /** When false, the installer dry-runs (writes nothing; returns the planned actions). */
+  apply: boolean;
+}
+
+export interface InstallResult {
+  ok: boolean;
+  actions: string[];
+  warnings: string[];
+}
+
+/**
+ * Build the .fallowrc.json content from layer rules + entry points. The schema is a
+ * loose JSON object; fallow tolerates unknown keys, so we keep the shape forward-compatible.
+ */
+export function buildFallowConfig(input: {
+  layerRules: readonly HarnessLayerRule[];
+  entryPoints: readonly string[];
+}): Record<string, unknown> {
+  const architecture = input.layerRules.map((rule) => ({
+    layer: rule.layer,
+    files: rule.globs,
+    allowed: rule.allowedImports,
+    forbidden: rule.forbiddenImports,
+    ...(rule.description ? { description: rule.description } : {}),
+  }));
+  return {
+    "$schema": "https://fallow.dev/schema/v1/.fallowrc.json",
+    entryPoints: [...input.entryPoints],
+    architecture,
+    audits: {
+      duplicates: { enabled: true, threshold: 0.85, minTokens: 30 },
+      deadCode: { enabled: true },
+      complexity: { enabled: true, fileLineLimit: 600 },
+      circularDependencies: { enabled: true },
+    },
+  };
+}
+
+/**
+ * Install the fallow side: writes `.fallowrc.json` with detected entry points + layer
+ * boundaries.
+ */
+export async function installFallow(
+  paths: PlatformPaths,
+  input: InstallInput,
+): Promise<InstallResult> {
+  const actions: string[] = [];
+  const warnings: string[] = [];
+  const configPath = getHarnessFallowConfigPath(paths, input.cwd);
+  const config = buildFallowConfig({
+    layerRules: input.layerRules,
+    entryPoints: input.entryPoints,
+  });
+  const serialized = `${JSON.stringify(config, null, 2)}\n`;
+
+  let existing: string | null = null;
+  try {
+    if (fs.existsSync(configPath)) existing = fs.readFileSync(configPath, "utf8");
+  } catch (error) {
+    warnings.push(`unable to read existing ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  if (existing === serialized) {
+    actions.push(`.fallowrc.json already up-to-date (no write)`);
+    return { ok: true, actions, warnings };
+  }
+
+  if (!input.apply) {
+    actions.push(`would write ${configPath}`);
+    return { ok: true, actions, warnings };
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, serialized);
+    actions.push(`wrote ${configPath}`);
+  } catch (error) {
+    return {
+      ok: false,
+      actions,
+      warnings: [...warnings, `failed to write ${configPath}: ${error instanceof Error ? error.message : String(error)}`],
+    };
+  }
+  return { ok: true, actions, warnings };
+}
+
+/** Ensure `.desloppify/` is gitignored. */
+export async function ensureDesloppifyGitignore(input: { cwd: string; apply: boolean }): Promise<InstallResult> {
+  const actions: string[] = [];
+  const warnings: string[] = [];
+  const gitignorePath = path.join(input.cwd, ".gitignore");
+  const desiredEntry = ".desloppify/";
+
+  let content = "";
+  try {
+    if (fs.existsSync(gitignorePath)) content = fs.readFileSync(gitignorePath, "utf8");
+  } catch (error) {
+    warnings.push(`unable to read .gitignore: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const lines = content.split(/\r?\n/);
+  const has = lines.some((line) => line.trim() === desiredEntry || line.trim() === ".desloppify");
+  if (has) {
+    actions.push(`.gitignore already contains ${desiredEntry}`);
+    return { ok: true, actions, warnings };
+  }
+  if (!input.apply) {
+    actions.push(`would append ${desiredEntry} to .gitignore`);
+    return { ok: true, actions, warnings };
+  }
+  try {
+    const append = content.length === 0 || content.endsWith("\n")
+      ? `${desiredEntry}\n`
+      : `\n${desiredEntry}\n`;
+    fs.writeFileSync(gitignorePath, content + append);
+    actions.push(`appended ${desiredEntry} to .gitignore`);
+  } catch (error) {
+    return {
+      ok: false,
+      actions,
+      warnings: [...warnings, `failed to update .gitignore: ${error instanceof Error ? error.message : String(error)}`],
+    };
+  }
+  return { ok: true, actions, warnings };
+}
+
+/**
+ * Run `desloppify update-skill <client>` for each agent-skill distribution target. We
+ * never abort on a single client failure — we report the warning and continue so a missing
+ * client doesn't block the rest of the install.
+ */
+export async function distributeAgentSkills(
+  platform: Platform,
+  input: { cwd: string; targets: readonly string[]; apply: boolean },
+): Promise<InstallResult> {
+  const actions: string[] = [];
+  const warnings: string[] = [];
+  if (input.targets.length === 0) {
+    actions.push("no skill targets selected; nothing to distribute");
+    return { ok: true, actions, warnings };
+  }
+
+  if (!input.apply) {
+    for (const target of input.targets) {
+      actions.push(`would run desloppify update-skill ${target}`);
+    }
+    return { ok: true, actions, warnings };
+  }
+
+  for (const target of input.targets) {
+    try {
+      const result = await platform.exec(
+        "desloppify",
+        ["update-skill", target],
+        { cwd: input.cwd, timeout: 30_000 },
+      );
+      if (result.code !== 0) {
+        warnings.push(`desloppify update-skill ${target} exited ${result.code}: ${result.stderr.trim()}`);
+        continue;
+      }
+      actions.push(`desloppify update-skill ${target} ok`);
+    } catch (error) {
+      warnings.push(
+        `desloppify update-skill ${target} threw: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  return { ok: warnings.length === 0, actions, warnings };
+}
+
+/**
+ * Compose the per-backend install steps. Stage callers should pass `apply: true`; design
+ * preview can pass `apply: false` to display the plan.
+ */
+export async function installAntiSlopBackend(
+  platform: Platform,
+  paths: PlatformPaths,
+  input: InstallInput,
+): Promise<InstallResult> {
+  const aggregated: InstallResult = { ok: true, actions: [], warnings: [] };
+  const fold = (step: InstallResult) => {
+    aggregated.actions.push(...step.actions);
+    aggregated.warnings.push(...step.warnings);
+    if (!step.ok) aggregated.ok = false;
+  };
+
+  if (input.backend === "fallow" || input.backend === "hybrid") {
+    fold(await installFallow(paths, input));
+  }
+  if (input.backend === "desloppify" || input.backend === "hybrid") {
+    fold(await ensureDesloppifyGitignore({ cwd: input.cwd, apply: input.apply }));
+    fold(await distributeAgentSkills(platform, { cwd: input.cwd, targets: input.skillTargets, apply: input.apply }));
+  }
+  if (input.backend === "supi-native") {
+    aggregated.actions.push("supi-native backend selected; no external CLI install required");
+  }
+  return aggregated;
+}

package/src/harness/anti_slop/queue.ts

@@ -0,0 +1,216 @@
+/**
+ * Persistent slop queue.
+ *
+ * One JSONL file per project, keyed by violation id. The id is content-addressed (hash
+ * over normalized `(file, range, kind, source-rule)`) so the same violation reported by
+ * fallow and desloppify collapses to one entry — that's the deduplication strategy for the
+ * `hybrid` backend.
+ *
+ * Operations:
+ *  - `appendOpen(entry)` — atomic append-only write of a fresh `state: "open"` entry.
+ *  - `resolve(id)` / `markWontfix(id)` — atomic rewrite of the file with the entry's state
+ *    updated. (We rewrite rather than append because the queue is conceptually a set keyed
+ *    by id, not a log.)
+ *  - `next()` — returns the highest-severity, oldest-`open` entry (FIFO within severity).
+ *  - `backlog(filter?)` — every open entry matching the filter.
+ *  - `findById(id)` — single-entry lookup.
+ *
+ * Crash semantics: writes go through `temp + rename`. Readers tolerate one trailing partial
+ * line (the storage layer already strips it).
+ */
+
+import { createHash } from "node:crypto";
+
+import type { PlatformPaths } from "../../platform/types.js";
+import type {
+  HarnessSlopQueueEntry,
+  HarnessSlopSource,
+  HarnessSlopState,
+  HarnessSlopViolationKind,
+  UltraPlanStorageResult,
+} from "../../types.js";
+import {
+  appendSlopQueueEntry,
+  readSlopQueue,
+  rewriteSlopQueue,
+} from "../storage.js";
+
+// ---------------------------------------------------------------------------
+// Identity helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a stable, content-addressed id for a violation. Two backends reporting the same
+ * `(file, range, kind, source-rule)` collapse to the same id, which lets the hybrid backend
+ * deduplicate transparently.
+ */
+export function computeQueueEntryId(input: {
+  kind: HarnessSlopViolationKind;
+  file: string;
+  range: HarnessSlopQueueEntry["range"];
+  /** Optional rule id from the source backend (e.g. fallow rule slug). */
+  ruleHint?: string;
+}): string {
+  const range = input.range
+    ? `${input.range.startLine}-${input.range.endLine}`
+    : "*";
+  const fingerprint = `${input.kind}|${input.file}|${range}|${input.ruleHint ?? ""}`;
+  return createHash("sha256").update(fingerprint).digest("hex").slice(0, 16);
+}
+
+// ---------------------------------------------------------------------------
+// Queue operations
+// ---------------------------------------------------------------------------
+
+export interface BacklogFilter {
+  kind?: HarnessSlopViolationKind;
+  source?: HarnessSlopSource;
+  state?: HarnessSlopState;
+  file?: string;
+}
+
+const SEVERITY_ORDER: Record<HarnessSlopQueueEntry["severity"], number> = {
+  blocker: 0,
+  warning: 1,
+  info: 2,
+};
+
+/**
+ * Append a fresh entry. Existing entries with the same id are NOT updated by this call —
+ * use `resolve`/`markWontfix` for state transitions. Re-appending the same id is a no-op
+ * at the consumer level (we deduplicate on read).
+ */
+export function appendOpen(
+  paths: PlatformPaths,
+  cwd: string,
+  entry: Omit<HarnessSlopQueueEntry, "state"> & { state?: HarnessSlopState },
+): UltraPlanStorageResult<string> {
+  const filled: HarnessSlopQueueEntry = {
+    ...entry,
+    state: entry.state ?? "open",
+  };
+  return appendSlopQueueEntry(paths, cwd, filled);
+}
+
+/**
+ * Read every entry. Duplicate ids are collapsed: the most recent record wins so resolve /
+ * wontfix appended after the original takes precedence even when no rewrite happened.
+ */
+export function readAll(
+  paths: PlatformPaths,
+  cwd: string,
+): UltraPlanStorageResult<HarnessSlopQueueEntry[]> {
+  const result = readSlopQueue(paths, cwd);
+  if (!result.ok) return result;
+  const seen = new Map<string, HarnessSlopQueueEntry>();
+  for (const entry of result.value) {
+    seen.set(entry.id, entry);
+  }
+  return { ok: true, value: [...seen.values()] };
+}
+
+/** Pop the highest-severity, oldest open entry. Returns null when the queue is empty. */
+export function next(
+  paths: PlatformPaths,
+  cwd: string,
+): UltraPlanStorageResult<HarnessSlopQueueEntry | null> {
+  const all = readAll(paths, cwd);
+  if (!all.ok) return all;
+  const open = all.value.filter((e) => e.state === "open");
+  if (open.length === 0) return { ok: true, value: null };
+  open.sort((a, b) => {
+    const sev = SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+    if (sev !== 0) return sev;
+    return a.ts.localeCompare(b.ts);
+  });
+  return { ok: true, value: open[0] };
+}
+
+/** Every open entry matching the filter. */
+export function backlog(
+  paths: PlatformPaths,
+  cwd: string,
+  filter: BacklogFilter = {},
+): UltraPlanStorageResult<HarnessSlopQueueEntry[]> {
+  const all = readAll(paths, cwd);
+  if (!all.ok) return all;
+  const targetState = filter.state ?? "open";
+  return {
+    ok: true,
+    value: all.value.filter((e) => {
+      if (e.state !== targetState) return false;
+      if (filter.kind && e.kind !== filter.kind) return false;
+      if (filter.source && e.source !== filter.source) return false;
+      if (filter.file && e.file !== filter.file) return false;
+      return true;
+    }),
+  };
+}
+
+export function findById(
+  paths: PlatformPaths,
+  cwd: string,
+  id: string,
+): UltraPlanStorageResult<HarnessSlopQueueEntry | null> {
+  const all = readAll(paths, cwd);
+  if (!all.ok) return all;
+  return { ok: true, value: all.value.find((e) => e.id === id) ?? null };
+}
+
+function setState(
+  paths: PlatformPaths,
+  cwd: string,
+  id: string,
+  state: HarnessSlopState,
+  resolvedAt?: string,
+): UltraPlanStorageResult<HarnessSlopQueueEntry | null> {
+  const all = readAll(paths, cwd);
+  if (!all.ok) return all;
+  let updated: HarnessSlopQueueEntry | null = null;
+  const next: HarnessSlopQueueEntry[] = all.value.map((entry) => {
+    if (entry.id !== id) return entry;
+    updated = {
+      ...entry,
+      state,
+      resolvedAt: resolvedAt ?? new Date().toISOString(),
+    };
+    return updated;
+  });
+  if (!updated) return { ok: true, value: null };
+  const written = rewriteSlopQueue(paths, cwd, next);
+  if (!written.ok) return written;
+  return { ok: true, value: updated };
+}
+
+export function resolve(
+  paths: PlatformPaths,
+  cwd: string,
+  id: string,
+): UltraPlanStorageResult<HarnessSlopQueueEntry | null> {
+  return setState(paths, cwd, id, "resolved");
+}
+
+export function markWontfix(
+  paths: PlatformPaths,
+  cwd: string,
+  id: string,
+): UltraPlanStorageResult<HarnessSlopQueueEntry | null> {
+  return setState(paths, cwd, id, "wontfix");
+}
+
+/**
+ * Clear resolved entries from the queue. Returns the number of entries removed. Used
+ * during GC to keep the file from growing without bound.
+ */
+export function compact(
+  paths: PlatformPaths,
+  cwd: string,
+): UltraPlanStorageResult<{ removed: number }> {
+  const all = readAll(paths, cwd);
+  if (!all.ok) return all;
+  const before = all.value.length;
+  const kept = all.value.filter((e) => e.state !== "resolved");
+  const written = rewriteSlopQueue(paths, cwd, kept);
+  if (!written.ok) return written;
+  return { ok: true, value: { removed: before - kept.length } };
+}

package/src/harness/anti_slop/recommend.ts

@@ -0,0 +1,84 @@
+/**
+ * Anti-slop backend recommendation.
+ *
+ * Inputs come from Discover (`HarnessDiscoverArtifact.languageCoverage`). We pick a
+ * backend per the algorithm spelled out in the plan §3.5:
+ *
+ *   languages = unique(detect_languages(repo))
+ *   if languages == {typescript, javascript}:
+ *     recommend "fallow + supi-native"
+ *   elif languages.size >= 3 OR python in languages OR rust in languages OR go in languages:
+ *     recommend "desloppify under the hood"
+ *   elif languages == {typescript} but pkg has subdirs in other languages:
+ *     recommend "hybrid"
+ *   else:
+ *     recommend "supi-native only"
+ *
+ * The "subdirs in other languages" check uses the `languageCoverage` array — when the
+ * dominant language has share <90% AND a non-TS-family language has >0 files, the repo is
+ * polyglot enough to warrant the hybrid backend.
+ */
+
+import type { HarnessAntiSlopBackend } from "../../types.js";
+
+const TS_FAMILY = new Set(["typescript", "javascript", "tsx", "jsx"]);
+const HEAVY_LANGUAGES = new Set(["python", "rust", "go"]);
+
+export interface RecommendInput {
+  languageCoverage: { language: string; fileCount: number; share: number }[];
+}
+
+export interface Recommendation {
+  backend: HarnessAntiSlopBackend;
+  reason: string;
+}
+
+export function recommendBackend(input: RecommendInput): Recommendation {
+  const languages = input.languageCoverage
+    .map((c) => c.language.toLowerCase())
+    .filter((l) => l.length > 0);
+
+  if (languages.length === 0) {
+    return {
+      backend: "supi-native",
+      reason: "no detectable language coverage; defer to manual lint/dupe per stack",
+    };
+  }
+
+  const langSet = new Set(languages);
+
+  // TS-family-only repo → fallow (deepest supipowers integration, no Python dep).
+  const allTsFamily = languages.every((lang) => TS_FAMILY.has(lang));
+  if (allTsFamily && langSet.size <= 2) {
+    return {
+      backend: "fallow",
+      reason: "TS/JS-only repo; fallow ships native binaries for all three OSes",
+    };
+  }
+
+  // ≥3 languages or any heavy non-TS language → desloppify (29-language coverage).
+  const heavyPresent = languages.some((lang) => HEAVY_LANGUAGES.has(lang));
+  if (langSet.size >= 3 || heavyPresent) {
+    return {
+      backend: "desloppify",
+      reason:
+        langSet.size >= 3
+          ? "polyglot repo (≥3 languages); desloppify covers 29 languages with one CLI"
+          : `non-TS heavy language present (${[...langSet].filter((l) => HEAVY_LANGUAGES.has(l)).join(", ")}); desloppify covers it`,
+    };
+  }
+
+  // TS-dominant but with non-TS subtrees → hybrid.
+  const dominant = [...input.languageCoverage].sort((a, b) => b.share - a.share)[0];
+  if (dominant && TS_FAMILY.has(dominant.language.toLowerCase()) && dominant.share < 0.9) {
+    return {
+      backend: "hybrid",
+      reason: `TS-dominant (${Math.round(dominant.share * 100)}%) with non-TS subtrees; fallow on TS, desloppify on the rest`,
+    };
+  }
+
+  return {
+    backend: "supi-native",
+    reason: "no clear backend match; defer to manual lint/dupe per stack",
+  };
+}

package/src/harness/anti_slop/score.ts

@@ -0,0 +1,180 @@
+/**
+ * Lenient + strict score computation.
+ *
+ * Score is computed from the persistent slop queue and an optional set of additional
+ * dimensions (file health, test health, etc.). Each dimension contributes a 0–100 number
+ * to both lenient and strict; the aggregate is the unweighted average.
+ *
+ * - **Lenient** treats `wontfix` items as resolved — useful for "are we converging?".
+ * - **Strict**  treats `wontfix` items as cost — closes the gaming loophole. Release
+ *   blocking and CI gates use strict, never lenient.
+ *
+ * The same input always produces the same output (no Date.now() in the body), so callers
+ * who need an `_at` timestamp pass it through `computedAt`.
+ */
+
+import type {
+  HarnessScore,
+  HarnessScoreDimension,
+  HarnessSlopQueueEntry,
+} from "../../types.js";
+
+// ---------------------------------------------------------------------------
+// Dimension builders
+// ---------------------------------------------------------------------------
+
+const DIMENSION_NAMES = ["duplicates", "deadCode", "layerViolations", "other"] as const;
+
+interface DimensionBucket {
+  open: number;
+  resolved: number;
+  wontfix: number;
+  total: number;
+}
+
+function emptyBucket(): DimensionBucket {
+  return { open: 0, resolved: 0, wontfix: 0, total: 0 };
+}
+
+/**
+ * Bucket queue entries into the four canonical dimensions. Unknown kinds map to `other`.
+ */
+function bucketize(entries: readonly HarnessSlopQueueEntry[]): Record<string, DimensionBucket> {
+  const buckets: Record<string, DimensionBucket> = {
+    duplicates: emptyBucket(),
+    deadCode: emptyBucket(),
+    layerViolations: emptyBucket(),
+    other: emptyBucket(),
+  };
+
+  for (const entry of entries) {
+    const bucket = (() => {
+      switch (entry.kind) {
+        case "duplicate":
+          return buckets.duplicates;
+        case "dead-code":
+          return buckets.deadCode;
+        case "layer-violation":
+          return buckets.layerViolations;
+        default:
+          return buckets.other;
+      }
+    })();
+    bucket.total += 1;
+    if (entry.state === "open") bucket.open += 1;
+    else if (entry.state === "resolved") bucket.resolved += 1;
+    else if (entry.state === "wontfix") bucket.wontfix += 1;
+  }
+
+  return buckets;
+}
+
+/**
+ * Per-dimension score: 100 - 100 * (cost / max(total, 1)). Lenient excludes wontfix from
+ * cost; strict counts wontfix as cost.
+ */
+function dimensionScores(bucket: DimensionBucket): { lenient: number; strict: number } {
+  const total = Math.max(bucket.total, 1);
+  const lenientCost = bucket.open;
+  const strictCost = bucket.open + bucket.wontfix;
+  return {
+    lenient: Math.round(100 * (1 - lenientCost / total)),
+    strict: Math.round(100 * (1 - strictCost / total)),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface ComputeScoreInput {
+  computedAt: string;
+  entries: readonly HarnessSlopQueueEntry[];
+  /** Optional trend rows (oldest first). Forwarded to the result unchanged. */
+  trend?: { ts: string; lenient: number; strict: number }[];
+}
+
+export function computeScore(input: ComputeScoreInput): HarnessScore {
+  const buckets = bucketize(input.entries);
+
+  const dimensions: HarnessScoreDimension[] = DIMENSION_NAMES.map((name) => {
+    const bucket = buckets[name];
+    const { lenient, strict } = dimensionScores(bucket);
+    return {
+      name,
+      lenient,
+      strict,
+      total: bucket.total,
+      open: bucket.open,
+      resolved: bucket.resolved,
+      wontfix: bucket.wontfix,
+    };
+  });
+
+  // When no entries exist at all, every dimension is 100 — the harness has no recorded
+  // failures. We compute an unweighted average; rounding is post-hoc to keep the output
+  // close to integer scores even when the input is uniformly empty.
+  const lenient = Math.round(
+    dimensions.reduce((sum, d) => sum + d.lenient, 0) / dimensions.length,
+  );
+  const strict = Math.round(
+    dimensions.reduce((sum, d) => sum + d.strict, 0) / dimensions.length,
+  );
+
+  return {
+    computedAt: input.computedAt,
+    lenient,
+    strict,
+    dimensions,
+    ...(input.trend ? { trend: input.trend } : {}),
+  };
+}
+
+/**
+ * Compute whether the score passes the configured floor. Strict floor is the binding one
+ * (lenient is informational). When `release_blocking` is true and strict < strictFloor, the
+ * caller should exit non-zero (CI integration).
+ */
+export function scoreFloorPassed(
+  score: HarnessScore,
+  floor: { strict: number; lenient: number },
+): { passed: boolean; reason: string } {
+  if (score.strict < floor.strict) {
+    return {
+      passed: false,
+      reason: `strict score ${score.strict} below floor ${floor.strict}`,
+    };
+  }
+  if (score.lenient < floor.lenient) {
+    return {
+      passed: false,
+      reason: `lenient score ${score.lenient} below floor ${floor.lenient}`,
+    };
+  }
+  return { passed: true, reason: "score floor satisfied" };
+}
+
+// ---------------------------------------------------------------------------
+// Badge rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a tiny SVG shield-style badge. Tests assert deterministic output (no fonts, no
+ * external assets). Width is fixed; the strict score determines the fill color.
+ */
+export function renderScoreBadge(score: HarnessScore): string {
+  const color =
+    score.strict >= 90 ? "#3fb950"
+    : score.strict >= 75 ? "#9e6a03"
+    : "#cf222e";
+  const text = `harness ${score.strict}`;
+  // 88 px width, 20 px height — same as shields.io flat badges.
+  return [
+    '<svg xmlns="http://www.w3.org/2000/svg" width="120" height="20" role="img" aria-label="harness score">',
+    `<rect width="120" height="20" fill="${color}" />`,
+    '<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">',
+    `<text x="60" y="14">${text}</text>`,
+    "</g>",
+    "</svg>",
+  ].join("");
+}