@codyswann/lisa 2.241.0 → 2.243.0

package/plugins/lisa-copilot/hooks/threshold-ratchet.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * Threshold ratchet gate — quality thresholds may tighten, never weaken.
+ *
+ * Deterministic comparator shared by three enforcement layers:
+ *   1. Agent-time soft block: PostToolUse hook via threshold-ratchet.sh
+ *      (`--hook`, exit 2 on weakening so the agent gets actionable feedback).
+ *   2. Pre-commit backstop: husky / lefthook (`--staged`, exit 1).
+ *   3. CI gate: reusable quality workflows (`--base <ref>`, exit 1),
+ *      comparing against the merge-base so nothing weakened lands in a PR.
+ *
+ * Tier 1 — designed tunables: vitest/jest/simplecov/e2e thresholds
+ * (minimums) and eslint/rubocop thresholds (maximums). Tier 2 — stryker's
+ * break score and k6 expression bounds. Tier 3 — exemption additions
+ * (audit-ignore entries, stryker mutate exclusions, thresholdRatchet.allow
+ * entries) which weaken a gate without touching a number.
+ *
+ * Human override: `.lisa.config.json` → `thresholdRatchet.allow` entries
+ * ({ file, key, reason }). Honored ONLY from the baseline side (HEAD /
+ * merge-base), never from the change under review — an agent cannot grant
+ * itself an exception in the same change that weakens a gate. `key: "*"`
+ * allows every key in the file.
+ *
+ * Extraction lives in threshold-ratchet-families.mjs; comparison rules in
+ * threshold-ratchet-compare.mjs. Zero dependencies.
+ */
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  extractAllowEntries,
+  familyFor,
+  parseJson,
+} from "./threshold-ratchet-families.mjs";
+import {
+  applyAllowList,
+  compareFile,
+  formatReport,
+} from "./threshold-ratchet-compare.mjs";
+
+/**
+ * Standard git locations, checked in order so the executable comes from a
+ * fixed, unwriteable directory rather than a PATH lookup. The bare "git"
+ * fallback keeps unusual layouts (e.g. Windows git-bash) working.
+ */
+const GIT_LOCATIONS = [
+  "/usr/bin/git",
+  "/usr/local/bin/git",
+  "/opt/homebrew/bin/git",
+];
+const GIT = GIT_LOCATIONS.find(candidate => fs.existsSync(candidate)) ?? "git";
+
+/** Git flag shared by every changed-file listing. */
+const NAME_ONLY = "--name-only";
+
+/**
+ * Run git, returning stdout or null on any failure.
+ * @param {string[]} args Git arguments
+ * @param {string} [cwd] Working directory
+ * @returns {string | null} Captured stdout, or null when git failed
+ */
+function git(args, cwd) {
+  try {
+    return execFileSync(GIT, args, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve mode-specific candidate files and content readers.
+ * @param {"hook"|"staged"|"base"} mode Comparison mode
+ * @param {string} root Repo root
+ * @param {string | undefined} baseRef Base ref (base mode only)
+ * @param {string[] | undefined} onlyFiles Restrict to these repo-relative
+ *   paths (hook mode with a known edited file)
+ * @returns {{ files: string[], baselineRef: string, readCurrent: (f: string) => string | null } | null}
+ *   The comparison plan, or null when git state can't support the mode
+ */
+function resolvePlan(mode, root, baseRef, onlyFiles) {
+  if (mode === "staged") {
+    const diff = git(["diff", "--cached", NAME_ONLY], root);
+    if (diff === null) return null;
+    return {
+      files: diff.split("\n").filter(Boolean),
+      baselineRef: "HEAD",
+      readCurrent: f => git(["show", `:${f}`], root),
+    };
+  }
+  if (mode === "base") {
+    if (!baseRef) return null;
+    const mergeBase = git(["merge-base", baseRef, "HEAD"], root)?.trim();
+    if (!mergeBase) return null;
+    const diff = git(["diff", NAME_ONLY, mergeBase, "HEAD"], root);
+    if (diff === null) return null;
+    return {
+      files: diff.split("\n").filter(Boolean),
+      baselineRef: mergeBase,
+      readCurrent: f => git(["show", `HEAD:${f}`], root),
+    };
+  }
+  const diff = git(["diff", NAME_ONLY, "HEAD"], root);
+  if (diff === null) return null;
+  return {
+    files: onlyFiles ?? diff.split("\n").filter(Boolean),
+    baselineRef: "HEAD",
+    readCurrent: f => {
+      try {
+        return fs.readFileSync(path.join(root, f), "utf-8");
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Run the ratchet for a mode, print the report, and return the exit code.
+ * @param {"hook"|"staged"|"base"} mode Comparison mode
+ * @param {string | undefined} [baseRef] Base ref (base mode only)
+ * @param {string[] | undefined} [onlyFiles] Restrict to these paths (hook mode)
+ * @returns {number} Process exit code (2 for hook mode, 1 otherwise; 0 clean)
+ */
+function run(mode, baseRef, onlyFiles) {
+  const root = git(["rev-parse", "--show-toplevel"])?.trim();
+  if (!root) return 0;
+  const plan = resolvePlan(mode, root, baseRef, onlyFiles);
+  if (!plan) return 0;
+
+  const watched = plan.files.filter(f => familyFor(f));
+  if (watched.length === 0) return 0;
+
+  const findings = watched.flatMap(f =>
+    compareFile(
+      f,
+      git(["show", `${plan.baselineRef}:${f}`], root),
+      plan.readCurrent(f)
+    )
+  );
+  if (findings.length === 0) return 0;
+
+  const baselineConfig = parseJson(
+    git(["show", `${plan.baselineRef}:.lisa.config.json`], root)
+  );
+  const { blocked, allowed } = applyAllowList(
+    findings,
+    extractAllowEntries(baselineConfig)
+  );
+  for (const finding of allowed) {
+    process.stdout.write(
+      `threshold-ratchet: allowed by .lisa.config.json exception — ${finding.message}\n`
+    );
+  }
+  if (blocked.length === 0) return 0;
+  process.stderr.write(`${formatReport(blocked)}\n`);
+  return mode === "hook" ? 2 : 1;
+}
+
+/**
+ * Handle `--hook` mode: parse the tool-use event from stdin and scope the
+ * check to the edited file (Edit/Write/NotebookEdit) or every changed
+ * watched file (Bash).
+ * @returns {number} Process exit code
+ */
+function runHookMode() {
+  const state = { stdin: "" };
+  try {
+    state.stdin = fs.readFileSync(0, "utf-8");
+  } catch {
+    return 0;
+  }
+  const input = parseJson(state.stdin);
+  if (!input || typeof input !== "object") return 0;
+  if (input.tool_name === "Bash") return run("hook");
+  if (!["Edit", "Write", "NotebookEdit"].includes(input.tool_name)) return 0;
+  const filePath = input.tool_input?.file_path;
+  if (typeof filePath !== "string") return 0;
+  const root = git(["rev-parse", "--show-toplevel"])?.trim();
+  if (!root) return 0;
+  const rel = path
+    .relative(root, path.resolve(filePath))
+    .split(path.sep)
+    .join("/");
+  if (rel.startsWith("..") || !familyFor(rel)) return 0;
+  return run("hook", undefined, [rel]);
+}
+
+/**
+ * CLI entrypoint.
+ * @returns {number} Process exit code
+ */
+function main() {
+  const args = process.argv.slice(2);
+  if (args[0] === "--staged") return run("staged");
+  if (args[0] === "--base") return run("base", args[1]);
+  if (args[0] === "--hook") return runHookMode();
+  process.stderr.write(
+    "usage: threshold-ratchet.mjs --hook | --staged | --base <ref>\n"
+  );
+  return 0;
+}
+
+const isDirectRun =
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isDirectRun) {
+  process.exit(main());
+}

package/plugins/lisa-copilot/hooks/threshold-ratchet.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# PostToolUse hook for Edit|Write|NotebookEdit|Bash: the threshold ratchet.
+# Quality thresholds (coverage minimums, complexity maximums, mutation break
+# score, e2e route floors, k6 bounds, audit-ignore lists) may tighten but never
+# weaken. The deterministic comparator lives in threshold-ratchet.mjs and is
+# shared with the pre-commit (husky/lefthook --staged) and CI (--base) layers,
+# so this hook is fast feedback — not the only line of defense.
+#
+# Exit 2 on weakening (soft block: the agent gets the report on stderr and can
+# fix the code or escalate to a human). Every infrastructure gap — no node, no
+# git repo, unreadable stdin — exits 0: the CI layer still guarantees the gate,
+# and a broken hook must never wedge an agent session.
+set -euo pipefail
+
+input="$(cat)"
+
+command -v node >/dev/null 2>&1 || exit 0
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+printf '%s' "$input" | node "$script_dir/threshold-ratchet.mjs" --hook

package/plugins/lisa-copilot/rules/eager/config-resolution.md

@@ -29,9 +29,12 @@ Project tracker (`jira` / `github` / `linear`) is read from `.lisa.config.json`
 
 Resolve hand-authored project rules from `.lisa.config.json`
 `projectRulesFile`, defaulting to `.claude/rules/PROJECT_RULES.md`. Automated
-learnings never append to that file: they use the separate
-`PROJECT_LEARNINGS.md` sibling derived from the configured rules directory.
-Both writers and budget checks import the executable contract from
+learnings never append to that file: they use the separate machine-managed
+ledger resolved from `.lisa.config.json` — the optional `learnings.file`
+override, else the default `.lisa/PROJECT_LEARNINGS.md`. The ledger lives in the
+cold `.lisa/` tree (never an auto-loaded rules directory) and is consumed only
+through the contract's bounded projection, never read raw wholesale. Both
+writers and budget checks import the executable contract from
 `@codyswann/lisa/learnings`; they must not copy its numeric limits.
 
 ## Env → base branch

package/plugins/lisa-copilot/rules/eager/project-learnings.md

@@ -1,11 +1,17 @@
 # Project Learnings (load-bearing)
 
 Before normal task work, resolve this repository's committed `.lisa.config.json`
-and derive the canonical learnings file as the sibling of `projectRulesFile`
-(default: `.claude/rules/PROJECT_LEARNINGS.md`). If that file exists, consume it
-through the executable Lisa learnings contract exported by
-`@codyswann/lisa/learnings` before relying on ad-hoc memory or prior-session
-notes.
+and derive the machine-managed learnings ledger: the optional `learnings.file`
+override, else the default `.lisa/PROJECT_LEARNINGS.md`. The ledger lives cold in
+`.lisa/`, NOT in an auto-loaded rules tree — so it is never injected raw into the
+session.
+
+Consume it ONLY through the executable Lisa learnings contract exported by
+`@codyswann/lisa/learnings`: parse and validate with `parseLearningsFile`, then
+take the bounded serving slice from `projectLearnings` (the highest-priority
+entries within the token/entry budget). **Never read the raw ledger file
+wholesale into context** — the whole point of the relocation is that sessions
+receive the contract's bounded projection, not the full file.
 
 Missing learnings are a silent no-op. Malformed, non-canonical, unsafe, or
 over-budget learnings produce one readable warning, apply no entry, and must not

package/plugins/lisa-copilot/rules/reference/config-resolution.md

@@ -179,7 +179,8 @@ fi
 |-------|----------|---------|-------|
 | `tracker` | **yes** | — | Destination for ticket writes. One of `"jira"`, `"github"`, `"linear"`. Missing → fail with instruction to run the matching `/lisa:setup:*` skill. |
 | `source` | no | — | Default PRD source for batch skills (`/lisa:intake`) and arg-less single-PRD skills. One of `"notion"`, `"confluence"`, `"linear"`, `"github"`, `"jira"`. Explicit URLs/keys passed to a skill always win over `source`; this is a default, not a lock. |
-| `projectRulesFile` | no | `.claude/rules/PROJECT_RULES.md` | Safe repo-relative Markdown path for hand-authored project rules. The bounded learning writer derives a separate `PROJECT_LEARNINGS.md` sibling in the same directory; there is intentionally no second path setting. |
+| `projectRulesFile` | no | `.claude/rules/PROJECT_RULES.md` | Safe repo-relative Markdown path for hand-authored project rules. Independent of the learnings ledger — relocating the rules file never moves the ledger. |
+| `learnings.file` | no | `.lisa/PROJECT_LEARNINGS.md` | Safe repo-relative Markdown path for the machine-managed learnings ledger, overriding the `.lisa/` default. Rejected if it resolves inside any auto-loaded rules tree (`.claude/rules`, `.cursor/rules`, `.github/instructions`, `.agents/rules`) — the ledger must stay out of eager context. |
 | `usage` | no | — | Optional token/cost pricing metadata consumed by the `usage-accounting` rule. Missing pricing never blocks a lifecycle flow; Lisa records token counts with `estimated_cost: null` when no trustworthy price source is configured. |
 | `wiki` | no | — | Wiki location for the `wiki-knowledge-source` rule. Omit for a local in-repo wiki (`wiki/`). See **Wiki source** below. |
 

package/plugins/lisa-copilot/rules/reference/project-learnings.md

@@ -1,14 +1,21 @@
 # Project Learnings
 
-Project learnings are Lisa's bounded, repo-local memory surface. They are stored
-in `PROJECT_LEARNINGS.md`, derived as the sibling of the configured
-`.lisa.config.json` `projectRulesFile` value. With no config override, the path
-is `.claude/rules/PROJECT_LEARNINGS.md`.
-
-Consume learnings before normal task work whenever the file exists. Use the
-executable contract from `@codyswann/lisa/learnings` to parse, validate, and
-budget-check the document. Do not duplicate numeric caps in rules or prompts;
-the exported contract is the source of truth.
+Project learnings are Lisa's bounded, repo-local memory surface. The
+machine-managed ledger is `PROJECT_LEARNINGS.md`, resolved from
+`.lisa.config.json`: the optional `learnings.file` override, else the default
+`.lisa/PROJECT_LEARNINGS.md`. The ledger deliberately lives in the cold `.lisa/`
+directory — **not** under `.claude/rules/` or any other auto-loaded rules tree —
+because anything in those trees is injected raw into every session, which
+double-loads the file and bypasses the contract's budget and validation.
+
+Consume learnings before normal task work whenever the file exists, and consume
+them ONLY through the executable contract from `@codyswann/lisa/learnings`:
+`parseLearningsFile` to parse and validate, then `projectLearnings` to take the
+bounded serving slice (the highest-priority entries — ordered by confidence,
+then recency — that fit the token/entry budget, plus how many were omitted).
+**Never read the raw ledger file wholesale into context**; the session receives
+the bounded projection, not the full document. Do not duplicate numeric caps in
+rules or prompts; the exported contract is the source of truth.
 
 Each persisted entry has seven fields:
 

package/plugins/lisa-copilot/skills/lisa-persist-learning/SKILL.md

@@ -139,7 +139,7 @@ Continue to Phase 3.
 No learning content is ever committed without a PR — there is no other write path, and the PR must touch **only** the learnings surface (any other changed file is a bug).
 
 1. **PR dedupe.** Search all PRs for the marker `[lisa-learning-pr] key=<fingerprint>` in the body (`gh pr list --state all --search '"<marker>" in:body' --json number,url`), with the stale-index guard above. If one exists, reference it and stop — never open a duplicate.
-2. **Resolve the learnings surface path — never hardcode it.** The canonical path is `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the `PROJECT_LEARNINGS.md` sibling of the configured `.lisa.config.json` `projectRulesFile` (default `.claude/rules/PROJECT_LEARNINGS.md`):
+2. **Resolve the learnings surface path — never hardcode it.** The canonical path is `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the machine-managed ledger resolved from `.lisa.config.json` (the `learnings.file` override, else the default `.lisa/PROJECT_LEARNINGS.md` — a cold path, never an auto-loaded rules tree):
 
    ```bash
    LEARNINGS_FILE=$(node -e 'import("@codyswann/lisa/learnings").then(async m => { const c = await m.readProjectConfig(process.cwd()); console.log(m.resolveProjectLearningsFile(c)); })')

package/plugins/lisa-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.241.0",
+  "version": "2.243.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cursor/hooks/hooks.json

@@ -10,6 +10,10 @@
       {
         "command": "${CURSOR_PLUGIN_ROOT}/hooks/shell-write-nudge.sh",
         "matcher": "Bash"
+      },
+      {
+        "command": "${CURSOR_PLUGIN_ROOT}/hooks/threshold-ratchet.sh",
+        "matcher": "Edit|Write|NotebookEdit|Bash"
       }
     ],
     "preToolUse": [

package/plugins/lisa-cursor/hooks/threshold-ratchet-compare.mjs

@@ -0,0 +1,315 @@
+/**
+ * Threshold ratchet — comparison rules and reporting.
+ *
+ * Pure comparison layer: given a watched file's baseline and current
+ * contents, report every weakening. No filesystem or git access. See
+ * threshold-ratchet-families.mjs for extraction and threshold-ratchet.mjs
+ * for the CLI.
+ */
+import {
+  extractAllowEntries,
+  extractExemptionEntries,
+  extractK6Constraints,
+  extractNumericLeaves,
+  extractRubocopThresholds,
+  extractStrykerConstraints,
+  extractStrykerMutate,
+  familyFor,
+  parseJson,
+} from "./threshold-ratchet-families.mjs";
+
+/** Finding type: a numeric bound or boolean gate moved the weakening way. */
+const TYPE_WEAKENED = "weakened";
+/** Finding type: an exemption entry was added (Tier 3). */
+const TYPE_EXEMPTION_ADDED = "exemption-added";
+/** Family kind for .lisa.config.json (the thresholdRatchet.allow carrier). */
+const KIND_ALLOW_LIST = "allow-list";
+
+/**
+ * @typedef {object} Finding
+ * @property {string} file Repo-relative path of the gate file
+ * @property {string} key Dotted key path within the file
+ * @property {"weakened"|"removed"|"exemption-added"|"file-deleted"|"allow-added"|"unparseable"} type
+ *   Which ratchet rule the change violated
+ * @property {number|string} [base] Baseline value
+ * @property {number|string} [current] Current value
+ * @property {string} message Operator-readable explanation
+ */
+
+/**
+ * Build the "file could not be parsed" finding.
+ * @param {string} relPath Repo-relative path
+ * @returns {Finding} The unparseable-file finding
+ */
+function unparseable(relPath) {
+  return {
+    file: relPath,
+    key: "*",
+    type: "unparseable",
+    message: `${relPath} is no longer valid JSON — a broken gate file disables the gate.`,
+  };
+}
+
+/**
+ * Compare two constraint maps: report removals and direction violations.
+ * @param {string} relPath Repo-relative path the constraints came from
+ * @param {Map<string, { value: number, direction: "min"|"max" }>} base
+ *   Baseline constraints
+ * @param {Map<string, { value: number, direction: "min"|"max" }>} current
+ *   Current constraints
+ * @returns {Finding[]} One finding per removed or weakened constraint
+ */
+export function compareConstraints(relPath, base, current) {
+  const findings = [];
+  for (const [key, baseC] of base) {
+    const currentC = current.get(key);
+    if (!currentC) {
+      findings.push({
+        file: relPath,
+        key,
+        type: "removed",
+        base: baseC.value,
+        message: `${relPath}: ${key} was removed — the tuned floor would silently fall back to a default.`,
+      });
+      continue;
+    }
+    const weakened =
+      baseC.direction === "min"
+        ? currentC.value < baseC.value
+        : currentC.value > baseC.value;
+    if (weakened) {
+      const verb =
+        baseC.direction === "min" ? "may only increase" : "may only decrease";
+      findings.push({
+        file: relPath,
+        key,
+        type: TYPE_WEAKENED,
+        base: baseC.value,
+        current: currentC.value,
+        message: `${relPath}: ${key} changed ${baseC.value} → ${currentC.value} (this value ${verb}).`,
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Compare a stryker.conf.json pair: the break threshold plus mutate-list
+ * exemptions (new negations or removed targets shrink the gate).
+ * @param {string} relPath Repo-relative path
+ * @param {unknown} base Parsed baseline config
+ * @param {unknown} current Parsed current config
+ * @returns {Finding[]} Break-threshold and mutate-scope findings
+ */
+function compareStryker(relPath, base, current) {
+  const findings = compareConstraints(
+    relPath,
+    extractStrykerConstraints(base),
+    extractStrykerConstraints(current)
+  );
+  const baseMutate = extractStrykerMutate(base);
+  const currentMutate = extractStrykerMutate(current);
+  for (const negation of currentMutate.negations) {
+    if (!baseMutate.negations.has(negation)) {
+      findings.push({
+        file: relPath,
+        key: `mutate ${negation}`,
+        type: TYPE_EXEMPTION_ADDED,
+        message: `${relPath}: new mutation-testing exclusion "${negation}" — excluding files from a gate is a weakening.`,
+      });
+    }
+  }
+  for (const positive of baseMutate.positives) {
+    if (!currentMutate.positives.has(positive)) {
+      findings.push({
+        file: relPath,
+        key: `mutate ${positive}`,
+        type: TYPE_EXEMPTION_ADDED,
+        message: `${relPath}: mutation-testing target "${positive}" was removed — shrinking a gate's coverage is a weakening.`,
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Compare a k6 thresholds pair: numeric bounds plus abortOnFail downgrades.
+ * @param {string} relPath Repo-relative path
+ * @param {unknown} base Parsed baseline thresholds
+ * @param {unknown} current Parsed current thresholds
+ * @returns {Finding[]} Bound and abortOnFail findings
+ */
+function compareK6(relPath, base, current) {
+  const baseC = extractK6Constraints(base);
+  const currentC = extractK6Constraints(current);
+  const findings = compareConstraints(relPath, baseC.numeric, currentC.numeric);
+  for (const [key, wasOn] of baseC.booleans) {
+    // k6 defaults abortOnFail to false, so DELETING an explicit `true` is as
+    // much a weakening as flipping it — anything but a current `true` blocks.
+    if (wasOn && currentC.booleans.get(key) !== true) {
+      findings.push({
+        file: relPath,
+        key,
+        type: TYPE_WEAKENED,
+        base: "true",
+        current: "false",
+        message: `${relPath}: ${key} turned off — the gate no longer stops the run on failure.`,
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Compare an exemption-list pair (audit ignore files): report added entries.
+ * @param {string} relPath Repo-relative path
+ * @param {unknown} base Parsed baseline list
+ * @param {unknown} current Parsed current list
+ * @returns {Finding[]} One finding per newly added ignore entry
+ */
+function compareExemptions(relPath, base, current) {
+  const baseEntries = extractExemptionEntries(base);
+  const findings = [];
+  for (const entry of extractExemptionEntries(current)) {
+    if (!baseEntries.has(entry)) {
+      findings.push({
+        file: relPath,
+        key: entry,
+        type: TYPE_EXEMPTION_ADDED,
+        message: `${relPath}: new security-audit ignore entry "${entry}" — ignoring a finding weakens the gate and needs a human's sign-off.`,
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Compare .lisa.config.json allow lists: report added exception entries so a
+ * change can never grant itself an exception.
+ * @param {string} relPath Repo-relative path
+ * @param {unknown} base Parsed baseline config
+ * @param {unknown} current Parsed current config
+ * @returns {Finding[]} One finding per newly added allow entry
+ */
+function compareAllowList(relPath, base, current) {
+  const baseKeys = new Set(
+    extractAllowEntries(base).map(e => `${e.file} ${e.key}`)
+  );
+  const findings = [];
+  for (const entry of extractAllowEntries(current)) {
+    if (!baseKeys.has(`${entry.file} ${entry.key}`)) {
+      findings.push({
+        file: relPath,
+        key: `thresholdRatchet.allow ${entry.file}#${entry.key}`,
+        type: "allow-added",
+        message: `${relPath}: new threshold exception for ${entry.file} → ${entry.key}. Exceptions are a human decision: land this entry in its own human-approved change first, then make the threshold change.`,
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Compare one watched file's baseline and current contents and report every
+ * weakening. Pure: no filesystem or git access.
+ * @param {string} relPath Repo-relative path (forward slashes)
+ * @param {string | null} baselineText Baseline contents (null = file is new)
+ * @param {string | null} currentText Current contents (null = file deleted)
+ * @returns {Finding[]} Every ratchet violation in the change (empty = clean)
+ */
+export function compareFile(relPath, baselineText, currentText) {
+  const family = familyFor(relPath);
+  if (!family || baselineText === null || baselineText === undefined) return [];
+
+  if (currentText === null || currentText === undefined) {
+    if (family.kind === KIND_ALLOW_LIST) return [];
+    return [
+      {
+        file: relPath,
+        key: "*",
+        type: "file-deleted",
+        message: `${relPath} was deleted — deleting a quality gate is a weakening.`,
+      },
+    ];
+  }
+
+  if (family.kind === "rubocop-yaml") {
+    return compareConstraints(
+      relPath,
+      extractRubocopThresholds(baselineText, family.direction),
+      extractRubocopThresholds(currentText, family.direction)
+    );
+  }
+
+  const base = parseJson(baselineText);
+  const current = parseJson(currentText);
+  if (base === undefined) return [];
+  if (current === undefined) {
+    return family.kind === KIND_ALLOW_LIST ? [] : [unparseable(relPath)];
+  }
+  switch (family.kind) {
+    case "json-num":
+      return compareConstraints(
+        relPath,
+        extractNumericLeaves(base, family.direction),
+        extractNumericLeaves(current, family.direction)
+      );
+    case "stryker":
+      return compareStryker(relPath, base, current);
+    case "k6":
+      return compareK6(relPath, base, current);
+    case "exemption-list":
+      return compareExemptions(relPath, base, current);
+    case KIND_ALLOW_LIST:
+      return compareAllowList(relPath, base, current);
+    default:
+      return [];
+  }
+}
+
+/**
+ * Drop findings covered by baseline-side allow entries. `allow-added`
+ * findings are never dropped — an exception cannot approve its own creation.
+ * @param {Finding[]} findings All findings from the change
+ * @param {Array<{ file: string, key: string }>} allowEntries Baseline
+ *   (already-merged) allow list
+ * @returns {{ blocked: Finding[], allowed: Finding[] }} Findings that still
+ *   block vs. findings covered by a recorded exception
+ */
+export function applyAllowList(findings, allowEntries) {
+  const blocked = [];
+  const allowed = [];
+  for (const finding of findings) {
+    const isAllowed =
+      finding.type !== "allow-added" &&
+      allowEntries.some(
+        e =>
+          (finding.file === e.file || finding.file.endsWith(`/${e.file}`)) &&
+          (e.key === "*" || e.key === finding.key)
+      );
+    if (isAllowed) allowed.push(finding);
+    else blocked.push(finding);
+  }
+  return { blocked, allowed };
+}
+
+/**
+ * Render the operator-facing block message.
+ * @param {Finding[]} findings Blocked findings
+ * @returns {string} Multi-line report explaining what weakened and the
+ *   human-approved exception path
+ */
+export function formatReport(findings) {
+  return [
+    "⛔ Quality gate weakened — blocked by the threshold ratchet.",
+    "",
+    ...findings.map(f => `  • ${f.message}`),
+    "",
+    "Quality thresholds are a one-way ratchet: they may tighten but never",
+    "loosen. Fix the code so it meets the current gate instead of lowering the",
+    "gate. If a human decides an exception is genuinely correct, they record it",
+    "in .lisa.config.json under thresholdRatchet.allow (with a reason) in a",
+    "separate human-approved change; this check honors exceptions only after",
+    "they are merged.",
+  ].join("\n");
+}