@codyswann/lisa 4.54.13 → 4.55.0

package/plugins/src/base/hooks/operational-hazards.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Hook wrapper for the short-lived operational-hazard ledger
+# (CodySwannGT/lisa#3681).
+#
+# Two events, one script:
+#   --session-start   SessionStart / SubagentStart — deliver every hazard that
+#                     applies right now, and stamp what this session was born
+#                     knowing. This is the half a fan-out cannot reach: a
+#                     session that starts after the warning still gets it.
+#   --hook            PostToolUse — announce only what was declared or lifted
+#                     since this session started, once each. This is the only
+#                     thing that reaches a session already running.
+#
+# Advisory by construction — ALWAYS exit 0. A session that cannot read the
+# ledger must keep working; a broken hook that wedges every tool call would be
+# a far worse defect than the one this closes. Every infrastructure gap (no
+# node, unreadable stdin) is also exit 0, and `bun run check:operational-hazards`
+# is what guarantees the ledger itself still parses.
+set -uo pipefail
+
+input="$(cat 2>/dev/null || true)"
+
+command -v node >/dev/null 2>&1 || exit 0
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+printf '%s' "$input" | node "$script_dir/operational-hazards.mjs" "$@" || true
+exit 0

package/plugins/src/base/hooks/parity-safety-net.sh

@@ -118,6 +118,27 @@ trap 'printf "%s\n" "Blocked by safety-net: hook failed while parsing its input;
 
 input="$(cat)"
 
+# Evaluate once per tool call when this guard is registered on both channels.
+#
+# Lisa reaches an agent through the repository dispatcher AND the plugin
+# manifest, and where both are live the harness runs this guard twice for one
+# tool call. `guard-dedupe.bash` short-circuits the second run ONLY when a
+# byte-identical copy already ALLOWED this exact payload on this exact tool
+# call; a differing vintage, a refusal, and a host with one channel all
+# evaluate exactly as before. Nothing is de-registered by it
+# (CodySwannGT/lisa#3814).
+#
+# Absent library means no dedupe, which is the pre-existing behaviour, so an
+# older channel copy that predates it is unaffected.
+lisa_guard_hook_dir="${BASH_SOURCE[0]%/*}"
+lisa_guard_dedupe_lib="$lisa_guard_hook_dir/guard-dedupe.bash"
+if [ -r "$lisa_guard_dedupe_lib" ]; then
+  # shellcheck source=guard-dedupe.bash
+  . "$lisa_guard_dedupe_lib"
+  trap 'lisa_guard_dedupe_record $?' EXIT
+  lisa_guard_dedupe parity-safety-net "$input"
+fi
+
 tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')"
 if [ "$tool_name" != "Bash" ]; then
   exit 0
@@ -244,12 +265,19 @@ later with `git apply "$patch"`.
 
 If the work is NOT yours -- a concurrent agent dirtied this worktree and your
 judgement is "none of this is mine" -- that same capture is how you return the
-tree to HEAD:
+tree to HEAD. This block is self-contained; paste it as it stands:
 
+  patch="$(mktemp "${TMPDIR:-/tmp}/lisa-preserve-XXXXXX")"
   git reset
   git diff --binary HEAD > "$patch"
   git apply -R "$patch"
 
+It names the file itself rather than inheriting one from the block above,
+because the two blocks are alternatives and only one of them gets run. A remedy
+printed at the moment an agent is blocked is followed literally; one that
+depends on a variable the reader never set fails on its first line, and the
+guard that printed it stops being believed.
+
 `git reset` clears staged and unmerged entries first, so the capture sees the
 whole tree as one diff; reversing it leaves the tree at HEAD with "$patch" as
 the record of what you discarded. Untracked files survive, exactly as they

package/plugins/src/base/hooks/threshold-ratchet-compare.mjs

@@ -7,6 +7,9 @@
  * for the CLI.
  */
 import {
+  ALLOW_STATE,
+  classifyAllowEntry,
+  describeAllowScope,
   extractAllowEntries,
   extractK6Constraints,
   extractLighthouseAssertions,
@@ -221,7 +224,7 @@ function compareAllowList(relPath, base, current) {
         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.`,
+        message: `${relPath}: new threshold exception — ${describeAllowScope(entry)}. Exceptions are a human decision: land this entry in its own human-approved change first, then make the threshold change. It needs a reason saying what resolves it and an "until": "YYYY-MM-DD" naming the day it is reviewed, because an exemption that cannot end is a permanent reduction in what the ratchet covers.`,
       });
     }
   }
@@ -311,29 +314,106 @@ export function compareFile(relPath, baselineText, currentText) {
 }
 
 /**
- * Drop findings covered by baseline-side allow entries. `allow-added`
- * findings are never dropped — an exception cannot approve its own creation.
+ * Whether an allow entry's file and key cover a finding.
+ * @param {{ file: string, key: string }} entry An allow entry
+ * @param {Finding} finding A finding from the change
+ * @returns {boolean} True when the entry's scope reaches this finding
+ */
+function entryCovers(entry, finding) {
+  return (
+    (finding.file === entry.file || finding.file.endsWith(`/${entry.file}`)) &&
+    (entry.key === "*" || entry.key === finding.key)
+  );
+}
+
+/**
+ * Report the allow entries a human has to act on, whether or not this change
+ * touched anything they cover.
+ *
+ * Separate from {@link applyAllowList} because the two answer different
+ * questions and only one of them depends on the change under review. An
+ * exemption that has outlived its condition is dead weight the moment the
+ * condition passes — the way `_thresholdsDivergence` is stale the moment the
+ * two floors agree — and saying so is not conditional on anybody happening to
+ * touch the gate it covered.
+ * @param {Array<{ file: string, key: string, reason?: string, until?: unknown }>} allowEntries
+ *   The allow list being honoured
+ * @param {number} [now] Clock reading, injected so the check is deterministic
+ * @returns {string[]} One line per entry that is expired or unevaluable; empty
+ *   when every entry still names a condition that holds
+ */
+export function describeAllowList(allowEntries, now = Date.now()) {
+  const lines = [];
+  for (const entry of allowEntries) {
+    const { state, detail } = classifyAllowEntry(entry, now);
+    if (state !== ALLOW_STATE.LIVE) lines.push(detail);
+  }
+  return lines;
+}
+
+/**
+ * Drop findings covered by a LIVE baseline-side allow entry.
+ *
+ * Three ways a finding leaves here, and they are deliberately distinct:
+ *
+ *   allowed  a covering entry's condition still holds. Reported, not blocked —
+ *            a project mid-migration is not red-walled by expiry.
+ *   expired  every covering entry's condition has passed. The weakening the
+ *            entry used to permit is REFUSED again, and the refusal names the
+ *            entry, its scope, its reason and the remedy. An expiry that
+ *            lapsed into "allowed" would be worse than no expiry.
+ *   blocked  nothing covered it, or everything that covered it has expired.
+ *
+ * An entry whose condition nothing can evaluate counts as covering, so the
+ * allow list keeps working for entries written before `until` existed;
+ * `describeAllowList` reports those every run instead.
+ *
+ * `allow-added` findings are never dropped, by any entry in any state — an
+ * exception cannot approve its own creation, which is the baseline-side fence
+ * and is untouched here.
  * @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
+ * @param {Array<{ file: string, key: string, reason?: string, until?: unknown }>} allowEntries
+ *   Baseline (already-merged) allow list
+ * @param {number} [now] Clock reading, injected so the check is deterministic
+ * @returns {{
+ *   blocked: Finding[],
+ *   allowed: Array<{ finding: Finding, entry: { file: string, key: string }, message: string }>,
+ *   expired: Array<{ finding: Finding, entry: { file: string, key: string }, message: string }>,
+ * }} Findings that still block, findings a live exemption covers, and the
+ *   refusals produced by exemptions that have ended
  */
-export function applyAllowList(findings, allowEntries) {
+export function applyAllowList(findings, allowEntries, now = Date.now()) {
+  const classified = allowEntries.map(entry => ({
+    entry,
+    ...classifyAllowEntry(entry, now),
+  }));
   const blocked = [];
   const allowed = [];
+  const expired = [];
   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);
+    const covering =
+      finding.type === "allow-added"
+        ? []
+        : classified.filter(c => entryCovers(c.entry, finding));
+    const live = covering.find(c => c.state !== ALLOW_STATE.EXPIRED);
+    if (live) {
+      allowed.push({
+        finding,
+        entry: live.entry,
+        message: `allowed by ${live.scope}, which ${live.summary}. It covers: ${finding.message}`,
+      });
+      continue;
+    }
+    blocked.push(finding);
+    for (const dead of covering) {
+      expired.push({
+        finding,
+        entry: dead.entry,
+        message: `${dead.detail} It used to cover: ${finding.message}`,
+      });
+    }
   }
-  return { blocked, allowed };
+  return { blocked, allowed, expired };
 }
 
 /**
@@ -351,8 +431,9 @@ export function formatReport(findings) {
     "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.",
+    "in .lisa.config.json under thresholdRatchet.allow — with a reason saying",
+    'what resolves it, and an "until": "YYYY-MM-DD" naming the day it is',
+    "reviewed — in a separate human-approved change; this check honors an",
+    "exception only after it is merged, and only until its until date passes.",
   ].join("\n");
 }

package/plugins/src/base/hooks/threshold-ratchet-families.mjs

@@ -379,8 +379,8 @@ export function extractK6Constraints(conf) {
 /**
  * Extract thresholdRatchet.allow entries from parsed .lisa.config.json.
  * @param {unknown} config Parsed config (may be undefined)
- * @returns {Array<{ file: string, key: string, reason?: string }>} The
- *   well-formed allow entries; malformed entries are dropped
+ * @returns {Array<{ file: string, key: string, reason?: string, until?: unknown }>}
+ *   The well-formed allow entries; malformed entries are dropped
  */
 export function extractAllowEntries(config) {
   const raw = config?.thresholdRatchet?.allow;
@@ -389,3 +389,131 @@ export function extractAllowEntries(config) {
     e => e && typeof e.file === "string" && typeof e.key === "string"
   );
 }
+
+/**
+ * The three states an allow entry's expiry condition can be in.
+ *
+ * THE DEFECT THESE EXIST FOR (#3856). An allow entry is the human-approved way
+ * for a weakening to pass the ratchet, and it had no expiry, no review and no
+ * removal path — nothing read the `reason`, so an exemption granted for a
+ * temporary condition (a migration in flight, a suite being rewritten, a
+ * dependency waiting upstream) outlived the condition and kept applying,
+ * silently, forever. The set of gates actually enforced therefore shrank
+ * monotonically while every individual decision that shrank it was correct at
+ * the time. A control whose exception list only grows converges on no control.
+ *
+ * The shape is taken from `_thresholdsDivergence` in `stryker.conf.json`,
+ * governed by `src/sync/stryker-thresholds-ownership.ts` — the one exemption
+ * surface in this repository that already stops exempting when it goes stale.
+ * Its three properties are reproduced here: the entry records its condition in
+ * a form something can evaluate, the reason says what resolves it, and once the
+ * condition passes the entry stops exempting AND says so, naming the remedy.
+ *
+ * `unchecked` is deliberately NOT `expired`. An entry written before `until`
+ * existed names a condition nothing can evaluate, which is the prose situation
+ * the ticket describes — it is reported every run, loudly, and it keeps
+ * exempting. Refusing it instead would red-wall every project mid-migration
+ * that carries a valid exception, which is the failure the ticket names as
+ * worse than the defect.
+ * @type {Readonly<Record<string, "live"|"expired"|"unchecked">>}
+ */
+export const ALLOW_STATE = Object.freeze({
+  LIVE: "live",
+  EXPIRED: "expired",
+  UNCHECKED: "unchecked",
+});
+
+/** A calendar condition, and the only shape `until` may take. */
+const ISO_DAY = /^(\d{4})-(\d{2})-(\d{2})$/u;
+
+/** An entry is live through the END of its named day, not up to its start. */
+const DAY_MS = 86_400_000;
+
+/**
+ * The instant an `until` condition stops holding.
+ *
+ * Round-tripped through `toISOString` on purpose: `Date.UTC` accepts
+ * out-of-range components and slides them, so `2026-02-31` would silently
+ * become March 3rd and `0099-01-01` would become 1999. An exemption dated a day
+ * that does not exist is a condition nobody can evaluate, and saying so is the
+ * honest answer — quietly moving it would hand the entry a different, longer
+ * life than the one written down.
+ * @param {unknown} until The entry's `until` field
+ * @returns {number | undefined} Epoch ms after which the entry has expired, or
+ *   undefined when `until` is not a calendar day anything can evaluate
+ */
+export function allowEntryExpiry(until) {
+  if (typeof until !== "string") return undefined;
+  const day = until.trim();
+  const match = ISO_DAY.exec(day);
+  if (!match) return undefined;
+  const midnight = Date.UTC(
+    Number(match[1]),
+    Number(match[2]) - 1,
+    Number(match[3])
+  );
+  if (new Date(midnight).toISOString().slice(0, 10) !== day) return undefined;
+  return midnight + DAY_MS;
+}
+
+/**
+ * Name an allow entry so a report says WHICH exemption it is talking about,
+ * and how much it covers.
+ *
+ * File-wide and key-scoped entries are spelled differently because they are
+ * different risks wearing the same shape: `key: "*"` turns off ratchet
+ * protection for every threshold in the file, and in a config diff that reads
+ * as one more approved exception.
+ * @param {{ file: string, key: string }} entry An allow entry, already
+ *   well-formed — `extractAllowEntries` is the only source of these
+ * @returns {string} Operator-readable identification of the entry
+ */
+export function describeAllowScope(entry) {
+  return entry.key === "*"
+    ? `thresholdRatchet.allow entry ${entry.file} → * (file-wide: every key in the file)`
+    : `thresholdRatchet.allow entry ${entry.file} → ${entry.key} (key-scoped)`;
+}
+
+/**
+ * Classify one allow entry's expiry condition, and say what to do about it.
+ * @param {{ file: string, key: string, reason?: unknown, until?: unknown }} entry
+ *   An allow entry
+ * @param {number} now Clock reading, injected so the check is deterministic
+ * @returns {{ state: "live"|"expired"|"unchecked", scope: string, summary: string, detail: string }}
+ *   The state, the entry's identification, a short phrase for a one-line
+ *   mention, and the full sentence naming the entry, its reason and the remedy
+ */
+export function classifyAllowEntry(entry, now) {
+  const scope = describeAllowScope(entry);
+  const because =
+    typeof entry.reason === "string" && entry.reason.trim() !== ""
+      ? ` Reason on record: ${entry.reason.trim()}`
+      : " No reason is recorded.";
+  const expiresAt = allowEntryExpiry(entry.until);
+  if (expiresAt === undefined) {
+    const summary = `names no condition anything can evaluate (until = ${JSON.stringify(entry.until ?? null)})`;
+    return {
+      state: ALLOW_STATE.UNCHECKED,
+      scope,
+      summary,
+      detail: `${scope} ${summary}, so nothing can ever end it. Give it "until": "YYYY-MM-DD" naming the day the exemption is reviewed, or delete it.${because}`,
+    };
+  }
+  const day = String(entry.until).trim();
+  if (now >= expiresAt) {
+    const summary = `expired after ${day}`;
+    return {
+      state: ALLOW_STATE.EXPIRED,
+      scope,
+      summary,
+      detail: `${scope} ${summary} and no longer exempts anything. Delete it, or record a fresh human-approved entry naming the new condition.${because}`,
+    };
+  }
+  const summary = `is live until ${day}`;
+  return {
+    state: ALLOW_STATE.LIVE,
+    scope,
+    summary,
+    detail: `${scope} ${summary}.`,
+  };
+}

package/plugins/src/base/hooks/threshold-ratchet.mjs

@@ -19,10 +19,20 @@
  * every entry carries a written decision.
  *
  * Human override: `.lisa.config.json` → `thresholdRatchet.allow` entries
- * ({ file, key, reason }). Honored ONLY from the baseline side (HEAD /
+ * ({ file, key, reason, until }). 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.
+ * allows every key in the file, and reports as file-wide so it is not mistaken
+ * for a key-scoped one.
+ *
+ * Exemptions END (#3856). `until` is a `YYYY-MM-DD` day the entry is live
+ * through; past it the entry stops exempting and the weakening it permitted is
+ * refused again, naming the entry, its scope, its reason and the remedy. An
+ * entry naming no evaluable condition still exempts — that keeps a project
+ * mid-migration off a red wall — but is reported on every run until somebody
+ * gives it a condition or deletes it. Modelled on `_thresholdsDivergence` in
+ * `stryker.conf.json`, the sibling exemption that already stops exempting when
+ * it goes stale; see `threshold-ratchet-families.mjs` `ALLOW_STATE`.
  *
  * One exception, and only one: a PROMOTION between deploy-chain branches
  * (`--base` + `--head`, both named in `deploy.branches`, head upstream of
@@ -46,6 +56,7 @@ import {
 import {
   applyAllowList,
   compareFile,
+  describeAllowList,
   formatReport,
 } from "./threshold-ratchet-compare.mjs";
 
@@ -387,6 +398,13 @@ function run(mode, baseRef, onlyFiles, headRef) {
     );
   }
 
+  const allow = resolveAllowList(
+    root,
+    plan.baselineRef,
+    mode,
+    baseRef,
+    headRef
+  );
   const findings = watched.flatMap(f =>
     compareFile(
       f,
@@ -394,28 +412,60 @@ function run(mode, baseRef, onlyFiles, headRef) {
       plan.readCurrent(f)
     )
   );
-  if (findings.length === 0) return 0;
+  // The allow-list inventory is printed whether or not the change produced
+  // findings. An exemption that has outlived its condition is dead weight the
+  // moment the condition passes, and reporting it only when something else has
+  // already failed is how a list nobody reads stays a list nobody reads.
+  if (findings.length === 0) {
+    reportAllowList(allow.entries, []);
+    return 0;
+  }
+  return reportFindings(findings, allow, mode);
+}
 
-  const allow = resolveAllowList(
-    root,
-    plan.baselineRef,
-    mode,
-    baseRef,
-    headRef
-  );
+/**
+ * Print the allow entries a human has to act on, minus the ones a refusal is
+ * about to name in full.
+ * @param {object[]} entries The resolved allow list
+ * @param {Array<{ message: string }>} expired Refusals already being printed
+ * @returns {void}
+ */
+function reportAllowList(entries, expired) {
+  for (const line of describeAllowList(entries)) {
+    if (expired.some(item => item.message.startsWith(line))) continue;
+    process.stdout.write(`threshold-ratchet: ${line}\n`);
+  }
+}
+
+/**
+ * Print the verdict for a change that produced findings.
+ * @param {object[]} findings Findings from every watched file
+ * @param {{ entries: object[], promotion: boolean, note: string | null }} allow
+ *   The resolved allow list and its provenance
+ * @param {"hook"|"staged"|"base"} mode Comparison mode
+ * @returns {number} Process exit code (2 for hook mode, 1 otherwise; 0 clean)
+ */
+function reportFindings(findings, allow, mode) {
   const split = partitionCarriedEntries(findings, allow.promotion);
-  const { blocked, allowed } = applyAllowList(split.rest, allow.entries);
+  const { blocked, allowed, expired } = applyAllowList(
+    split.rest,
+    allow.entries
+  );
   if (allow.note) process.stdout.write(`${allow.note}\n`);
+  reportAllowList(allow.entries, expired);
   for (const finding of split.carried) {
     process.stdout.write(
       `threshold-ratchet: carried forward by this promotion, approved upstream — ${finding.message}\n`
     );
   }
-  for (const finding of allowed) {
+  for (const item of allowed) {
     process.stdout.write(
-      `threshold-ratchet: allowed by .lisa.config.json exception — ${finding.message}\n`
+      `threshold-ratchet: ${item.message} (.lisa.config.json exception)\n`
     );
   }
+  for (const item of expired) {
+    process.stderr.write(`threshold-ratchet: refused — ${item.message}\n`);
+  }
   if (blocked.length === 0) return 0;
   process.stderr.write(`${formatReport(blocked)}\n`);
   return mode === "hook" ? 2 : 1;