@codyswann/lisa 3.4.1 → 3.5.0

package/typescript/copy-overwrite/scripts/check-skipped-required-checks.mjs

@@ -11,6 +11,53 @@
  * Usage:
  *   node scripts/check-skipped-required-checks.mjs [rootDir] [--remote] [--json]
  *
+ * ## Where this runs
+ *
+ * Lisa's `quality.yml` runs the OFFLINE arm on every pull request, and the
+ * shipped `required-checks-drift.yml` runs `--remote` on a weekly schedule.
+ * That split is deliberate and is argued under "Why this is a DECLARATION
+ * guard" below: the enforced PR path may not depend on network or `gh` auth,
+ * and the snapshot it enforces may not be allowed to rot unwatched.
+ *
+ * ## `enforcement`
+ *
+ * A declaration may set `"enforcement": "warn"` to report violations without
+ * failing the build. The seeds Lisa ships start there ON PURPOSE: a seed cannot
+ * know which contexts a given repository's ruleset requires, so a seeded repo
+ * that has never been reviewed would otherwise go red on its first Lisa update
+ * for skips that may be entirely legitimate — and a gate that reddens a
+ * repository the day it arrives gets deleted, not fixed. Absent the key the
+ * guard ENFORCES: a declaration somebody hand-wrote is an opt-in.
+ *
+ * `warn` is a ramp, not a licence: `skipped_required_check` — the repository's
+ * own declaration stating that a token it really skips silences a context its
+ * ruleset really requires — blocks in every mode.
+ *
+ * ## `required_contexts` is a CACHE, and an unstamped cache is NOT AN ANSWER
+ *
+ * The single worst thing this guard can do is render a confident verdict from a
+ * list nobody ever compared against a real ruleset. Measured (#2476): the seed
+ * Lisa shipped claimed `🔗 Work-Item Traceability` was required — no ruleset
+ * required it — and OMITTED SIX contexts that genuinely were. A guard reading
+ * that would clear a genuinely-skipped required check and flag a non-required
+ * one. That is worse than a guard nobody runs, because it teaches people to
+ * trust it.
+ *
+ * So `required_contexts` is treated as a cache of a live fetch, not as
+ * testimony. It is trusted only while `ruleset.baseline_fetched_at` carries a
+ * parseable timestamp no older than SNAPSHOT_MAX_AGE_DAYS. Untranscribed or
+ * expired, the guard REFUSES to answer: every rule that depends on
+ * `required_contexts` is skipped, no ✅ is printed, and the report says NOT
+ * CHECKED and why. The rules that do NOT read `required_contexts` — an
+ * undeclared token, a token written with whitespace — still run, because they
+ * are true regardless of what the ruleset requires.
+ *
+ * Refusal is exit 1, so an explicit `npm run check:skipped-required-checks`
+ * cannot be mistaken for a pass. Under `"enforcement": "warn"` — which is what
+ * Lisa's seeds ship, and only its seeds — refusal is loud and exit 0, because
+ * reddening every repository in a fleet the day an untranscribed seed arrives
+ * is how a gate gets deleted rather than transcribed.
+ *
  * ## Why this exists
  *
  * **GitHub counts a `skipped` required status check as SATISFIED.** A job named
@@ -69,6 +116,18 @@ import { pathToFileURL } from "node:url";
 /** Repo-relative path of the per-repo declaration file. */
 export const DECLARATION_PATH = ".github/required-checks.json";
 
+/**
+ * How long a transcribed `required_contexts` snapshot stays trustworthy.
+ *
+ * A SOURCE CONSTANT, not an input: a ceiling somebody can widen from a config
+ * file fails open on exactly the runs nobody tests. Rulesets are edited in an
+ * admin console with no signal in the repository, so an old transcription is
+ * not evidence — it is a memory of evidence. Ninety days is long enough that
+ * the weekly `--remote` run refreshes it many times over, and short enough that
+ * an abandoned repository stops being told its skips are fine.
+ */
+export const SNAPSHOT_MAX_AGE_DAYS = 90;
+
 /**
  * Matches a `skip_jobs:` key and captures everything after the colon.
  *
@@ -110,8 +169,32 @@ export const VIOLATIONS = Object.freeze({
   orphaned: "orphaned_exemption",
   badExemption: "exemption_without_valid_ticket",
   remoteDrift: "ruleset_snapshot_drift",
+  whitespace: "whitespace_in_skip_token",
 });
 
+/** Enforcement modes a declaration may select. */
+const ENFORCEMENT_MODES = Object.freeze(["error", "warn"]);
+
+/**
+ * Violation kinds that block even under `"enforcement": "warn"`.
+ *
+ * `warn` is an ADOPTION RAMP for hygiene findings — an undeclared token, a
+ * snapshot that has drifted from the code — in a repository nobody has reviewed
+ * yet. It is not a licence for a PROVEN false green. Reaching
+ * `skipped_required_check` requires the repository's own declaration to say
+ * both that a context is ruleset-required AND that a token it actually skips
+ * silences it; that is a reviewed state, and shipping past it is the exact
+ * defect this file exists to refuse.
+ *
+ * `ruleset_snapshot_drift` blocks for the same reason: it only fires under an
+ * explicit `--remote` on a repository that filled in its ruleset ids, and it is
+ * measured against live truth rather than inferred from a seed.
+ */
+const ALWAYS_BLOCKING = Object.freeze([
+  VIOLATIONS.suppressesRequired,
+  VIOLATIONS.remoteDrift,
+]);
+
 /**
  * True when a line is a whole-line YAML comment.
  *
@@ -170,13 +253,25 @@ export function unquoteScalar(rawValue) {
 /**
  * Splits a comma list into unique, non-empty tokens.
  *
+ * `preserveWhitespace` keeps each token EXACTLY as written, which is the only
+ * way to see the defect in `skip_jobs: 'test, test:e2e'`. GitHub Actions has no
+ * string-replace in expression syntax, so the sentinel-comma idiom
+ * (`contains(format(',{0},', inputs.skip_jobs), ',test:e2e,')`) compares raw
+ * bytes: the token there is `" test:e2e"`, which never matches `,test:e2e,` and
+ * the job runs. That fails CLOSED, so it is a papercut rather than a hole — but
+ * it silently does not do what the operator asked, and nothing else in the
+ * pipeline can see it, because by the time the guard has trimmed it looks
+ * identical to a correctly written skip.
+ *
  * @param {string} commaList - Tokens joined by commas
+ * @param {boolean} [preserveWhitespace] - Return tokens exactly as written
  * @returns {string[]} Unique tokens in first-seen order
  */
-function tokenize(commaList) {
+function tokenize(commaList, preserveWhitespace = false) {
   const out = [];
-  for (const token of commaList.split(",").map(part => part.trim())) {
-    if (token !== "" && !out.includes(token)) out.push(token);
+  for (const part of commaList.split(",")) {
+    const token = preserveWhitespace ? part : part.trim();
+    if (token.trim() !== "" && !out.includes(token)) out.push(token);
   }
   return out;
 }
@@ -195,10 +290,12 @@ function tokenize(commaList) {
  * @param {string} contents - Full text of a workflow file
  * @param {string} sourcePath - Repo-relative path, used only to name the file in
  *   a throw. Never an absolute path.
+ * @param {{preserveWhitespace?: boolean}} [options] - `preserveWhitespace`
+ *   returns each token exactly as written instead of trimmed
  * @returns {string[]} Every declared skip token, de-duplicated
  * @throws {Error} When a `skip_jobs` key is not an inline scalar
  */
-export function readSkipJobs(contents, sourcePath) {
+export function readSkipJobs(contents, sourcePath, options = {}) {
   const all = [];
   contents.split("\n").forEach((line, index) => {
     if (isCommentLine(line)) return;
@@ -224,7 +321,7 @@ export function readSkipJobs(contents, sourcePath) {
             .map(found => found[1])
             .join(",");
 
-    for (const token of tokenize(source)) {
+    for (const token of tokenize(source, options.preserveWhitespace === true)) {
       if (!all.includes(token)) all.push(token);
     }
   });
@@ -270,6 +367,14 @@ export function loadDeclaration(rootDir) {
       `check-skipped-required-checks: \`workflows\` must list at least one workflow file whose \`skip_jobs\` this guard reads.`
     );
   }
+  if (
+    declaration.enforcement !== undefined &&
+    !ENFORCEMENT_MODES.includes(declaration.enforcement)
+  ) {
+    throw new Error(
+      `check-skipped-required-checks: \`enforcement\` must be one of ${ENFORCEMENT_MODES.map(mode => `"${mode}"`).join(", ")}, not ${JSON.stringify(declaration.enforcement)}. Omit it to enforce — a typo silently downgrading this guard to advice is the fail-open shape it exists to refuse.`
+    );
+  }
 
   // Validate the SHAPE of every declaration, not just its presence. A truthy
   // non-object entry (`"test:e2e": true`, or a string) reads as "declared" at
@@ -308,14 +413,21 @@ export function loadDeclaration(rootDir) {
  * guard that silently reads nothing reports a clean bill of health for a
  * repository it never looked at.
  *
+ * A token written with surrounding whitespace is reported HERE rather than
+ * downstream, because trimming has already erased the evidence by the time the
+ * coherence rules run. The trimmed form is still carried into the evaluation:
+ * over-reporting a skip that does not actually happen is the safe direction,
+ * and the whitespace violation beside it explains why the token appeared.
+ *
  * @param {string} rootDir - Repository root
  * @param {ReadonlyArray<string>} workflows - Repo-relative workflow paths
- * @returns {{tokens: string[], sources: Record<string, string[]>}} Tokens and where each came from
+ * @returns {{tokens: string[], sources: Record<string, string[]>, violations: object[]}} Tokens, where each came from, and how each was written
  */
 export function collectSkipJobTokens(rootDir, workflows) {
   const tokens = [];
   /** @type {Record<string, string[]>} */
   const sources = {};
+  const violations = [];
   for (const relative of workflows) {
     const path = resolve(rootDir, relative);
     if (!existsSync(path)) {
@@ -323,12 +435,75 @@ export function collectSkipJobTokens(rootDir, workflows) {
         `check-skipped-required-checks: \`workflows\` names ${relative}, which does not exist. A guard that reads nothing reports a clean bill of health for a repository it never looked at.`
       );
     }
-    for (const token of readSkipJobs(readFileSync(path, "utf8"), relative)) {
+    const contents = readFileSync(path, "utf8");
+    for (const token of readSkipJobs(contents, relative)) {
       if (!tokens.includes(token)) tokens.push(token);
       sources[token] = [...(sources[token] ?? []), relative];
     }
+    for (const raw of readSkipJobs(contents, relative, {
+      preserveWhitespace: true,
+    })) {
+      if (raw === raw.trim()) continue;
+      violations.push({
+        kind: VIOLATIONS.whitespace,
+        token: raw.trim(),
+        message: `\`skip_jobs\` in ${relative} lists ${JSON.stringify(raw)} — the token carries whitespace. GitHub Actions expression syntax has no string-replace, so \`skip_jobs\` is matched as an exact comma-delimited token and the surrounding space makes it match NOTHING: the job runs as if you had never listed it. That fails closed, so nothing unverified ships — but the skip you asked for silently did not happen. Write the list with no spaces: \`skip_jobs: 'a,b'\`, never \`skip_jobs: 'a, b'\`.`,
+      });
+    }
   }
-  return { tokens, sources };
+  return { tokens, sources, violations };
+}
+
+/**
+ * Decides whether `required_contexts` may be believed at all.
+ *
+ * The stamp is `ruleset.baseline_fetched_at`, and it means one specific thing:
+ * somebody read this list off a live ruleset on that date. An empty stamp is
+ * the state Lisa's seeds ship in, and the seeds are a GUESS — a guess that was
+ * measured wrong (#2476). No stamp, no answer.
+ *
+ * @param {object} declaration - The per-repo declaration
+ * @param {number} [now] - Current epoch milliseconds, injectable for tests
+ * @returns {{trusted: boolean, reason: string}} Whether to believe the snapshot, and why not
+ */
+export function snapshotTrust(declaration, now = Date.now()) {
+  const stamp = declaration.ruleset?.baseline_fetched_at;
+  if (typeof stamp !== "string" || stamp.trim() === "") {
+    return {
+      trusted: false,
+      reason: `\`ruleset.baseline_fetched_at\` is empty, so \`required_contexts\` has never been transcribed from a live ruleset. Lisa's seed ships a GUESS, and the guess was measured WRONG in this fleet: it claimed "🔍 Quality Checks / 🔗 Work-Item Traceability" was required when no ruleset required it, and omitted six contexts that were. Transcribe the real list, stamp the date, and this guard starts answering.`,
+    };
+  }
+  const fetchedAt = Date.parse(stamp);
+  if (Number.isNaN(fetchedAt)) {
+    return {
+      trusted: false,
+      reason: `\`ruleset.baseline_fetched_at\` is ${JSON.stringify(stamp)}, which is not a date this can read. Use an ISO-8601 timestamp, e.g. "2026-08-13".`,
+    };
+  }
+  const ageDays = (now - fetchedAt) / 86_400_000;
+  if (ageDays > SNAPSHOT_MAX_AGE_DAYS) {
+    return {
+      trusted: false,
+      reason: `\`required_contexts\` was last transcribed ${Math.floor(ageDays)} days ago, past the ${SNAPSHOT_MAX_AGE_DAYS}-day ceiling. Rulesets are edited in an admin console with no signal in this repository, so a stale transcription is a memory of evidence rather than evidence.`,
+    };
+  }
+  return { trusted: true, reason: "" };
+}
+
+/**
+ * The transcription instructions, printed wherever the snapshot is refused.
+ *
+ * @param {object} declaration - The per-repo declaration
+ * @returns {string} A copy-pasteable recipe
+ */
+export function transcriptionRecipe(declaration) {
+  const repo = declaration.ruleset?.repo || "OWNER/NAME";
+  return [
+    `  gh api repos/${repo}/rulesets --jq '.[] | "\\(.id) \\(.name)"'`,
+    `  gh api repos/${repo}/rulesets/RULESET_ID --jq '.rules[] | select(.type=="required_status_checks") | .parameters.required_status_checks[].context'`,
+    `Paste the output into \`required_contexts\` byte for byte, record the ids in \`ruleset.ids\`, and set \`ruleset.baseline_fetched_at\` to today.`,
+  ].join("\n");
 }
 
 /**
@@ -352,11 +527,25 @@ export function collectSkipJobTokens(rootDir, workflows) {
  *  5. An exemption for a token nobody skips any more is ORPHANED. Deleting it is
  *     one line, and leaving it teaches readers the exemption list is fiction.
  *
+ * Rules 2, 3 and 4 all read `required_contexts`, so all three are SUPPRESSED
+ * when `trustRequiredContexts` is false. Rules 1 and 5 do not read it and keep
+ * running: whether a token was reviewed, and whether an exemption still refers
+ * to a real skip, are true regardless of what any ruleset requires. Suppressing
+ * a rule is not the same as passing it — the caller reports NOT CHECKED.
+ *
  * @param {object} declaration - The per-repo declaration
  * @param {ReadonlyArray<string>} skipped - Tokens the workflows actually skip
+ * @param {{trustRequiredContexts?: boolean}} [options] - Set
+ *   `trustRequiredContexts: false` to suppress every rule that reads the
+ *   `required_contexts` snapshot
  * @returns {{violations: object[], checked: number}} Violations and how many tokens were examined
  */
-export function evaluateSkippedRequiredChecks(declaration, skipped) {
+export function evaluateSkippedRequiredChecks(
+  declaration,
+  skipped,
+  options = {}
+) {
+  const trustRequired = options.trustRequiredContexts !== false;
   const required = new Set(declaration.required_contexts);
   const declarations = declaration.skip_job_declarations ?? {};
   const ticketPattern = new RegExp(
@@ -374,6 +563,7 @@ export function evaluateSkippedRequiredChecks(declaration, skipped) {
       });
       continue;
     }
+    if (!trustRequired) continue;
     const suppressed = entry.suppressed_contexts ?? [];
     const hits = suppressed.filter(context => required.has(context));
 
@@ -490,25 +680,48 @@ export function compareRulesetBaseline(snapshot, live) {
 /**
  * Runs the guard.
  *
+ * `--remote` reads the ruleset live, so it does not need the cache to be
+ * trustworthy — it is the thing that MAKES it trustworthy. Under `--remote` the
+ * required-context rules therefore run regardless of the stamp, and any
+ * disagreement surfaces as `ruleset_snapshot_drift` rather than as a verdict
+ * about skips.
+ *
  * @param {ReadonlyArray<string>} argv - CLI arguments
- * @returns {{violations: object[], checked: number, tokens: string[]}} The result
+ * @returns {{violations: object[], checked: number, tokens: string[], enforcement: string, trust: {trusted: boolean, reason: string}, recipe: string}} The result
  */
 export function runGuard(argv) {
   const positional = argv.filter(arg => !arg.startsWith("--"));
   const rootDir = positional[0] ?? process.cwd();
   const declaration = loadDeclaration(rootDir);
-  const { tokens } = collectSkipJobTokens(rootDir, declaration.workflows);
-  const result = evaluateSkippedRequiredChecks(declaration, tokens);
-  const violations = [...result.violations];
-  if (argv.includes("--remote")) {
+  const collected = collectSkipJobTokens(rootDir, declaration.workflows);
+  const remote = argv.includes("--remote");
+  const live = remote
+    ? fetchLiveRequiredContexts(declaration.ruleset)
+    : undefined;
+  const trust = remote
+    ? { trusted: true, reason: "" }
+    : snapshotTrust(declaration);
+  const result = evaluateSkippedRequiredChecks(
+    live === undefined
+      ? declaration
+      : { ...declaration, required_contexts: live },
+    collected.tokens,
+    { trustRequiredContexts: trust.trusted }
+  );
+  const violations = [...collected.violations, ...result.violations];
+  if (live !== undefined) {
     violations.push(
-      ...compareRulesetBaseline(
-        declaration.required_contexts,
-        fetchLiveRequiredContexts(declaration.ruleset)
-      )
+      ...compareRulesetBaseline(declaration.required_contexts, live)
     );
   }
-  return { violations, checked: result.checked, tokens };
+  return {
+    violations,
+    checked: result.checked,
+    tokens: collected.tokens,
+    enforcement: declaration.enforcement ?? "error",
+    trust,
+    recipe: transcriptionRecipe(declaration),
+  };
 }
 
 /**
@@ -518,7 +731,7 @@ export function runGuard(argv) {
  * @returns {void}
  */
 function main(argv) {
-  /** @type {{violations: object[], checked: number, tokens: string[]}} */
+  /** @type {{violations: object[], checked: number, tokens: string[], enforcement: string, trust: {trusted: boolean, reason: string}, recipe: string}} */
   let result;
   try {
     result = runGuard(argv);
@@ -540,25 +753,78 @@ function main(argv) {
 
   if (argv.includes("--json")) {
     process.stdout.write(
-      `${JSON.stringify({ ok: result.violations.length === 0, ...result }, null, 2)}\n`
+      `${JSON.stringify(
+        {
+          ok: result.violations.length === 0 && result.trust.trusted,
+          answered: result.trust.trusted,
+          ...result,
+        },
+        null,
+        2
+      )}\n`
     );
     return;
   }
 
+  const warnOnly = result.enforcement === "warn";
+  /**
+   * True when a violation still fails the build under the active mode.
+   *
+   * @param {{kind: string}} violation - One violation
+   * @returns {boolean} True when it blocks
+   */
+  const blocks = violation =>
+    !warnOnly || ALWAYS_BLOCKING.includes(violation.kind);
+  const blocking = result.violations.filter(blocks);
   const lines = ["## 🔒 Skipped required checks", ""];
-  if (result.violations.length === 0) {
+
+  // The refusal comes FIRST and replaces the verdict. Printing "✅ none
+  // silences a required check" from a snapshot nobody transcribed is the one
+  // outcome that is worse than never running: it is a confident wrong answer,
+  // and it teaches people to trust it (#2476).
+  if (!result.trust.trusted) {
     lines.push(
-      `✅ ${result.checked} \`skip_jobs\` token(s) examined; none silences a ruleset-required status check.`
+      `⛔ **NOT CHECKED** — this guard cannot say whether any skip silences a required status check, and will not pretend to.`,
+      "",
+      result.trust.reason,
+      "",
+      "```",
+      result.recipe,
+      "```",
+      "",
+      `Meanwhile \`--remote\` answers WITHOUT the cache, because it reads the ruleset live: \`npm run check:skipped-required-checks:remote\`.`,
+      ""
+    );
+    process.stderr.write(
+      `::${warnOnly ? "warning" : "error"} title=Skipped-required checks NOT CHECKED::${result.trust.reason.split("\n")[0]}\n`
     );
+  }
+
+  if (result.violations.length === 0) {
+    if (result.trust.trusted) {
+      lines.push(
+        `✅ ${result.checked} \`skip_jobs\` token(s) examined; none silences a ruleset-required status check.`
+      );
+    } else {
+      lines.push(
+        `The rules that do NOT read \`required_contexts\` were still applied to ${result.checked} token(s) and found nothing.`
+      );
+    }
   } else {
     lines.push(
-      `❌ ${result.violations.length} violation(s) across ${result.checked} \`skip_jobs\` token(s):`,
+      `${blocking.length > 0 ? "❌" : "⚠️"} ${result.violations.length} violation(s) across ${result.checked} \`skip_jobs\` token(s):`,
       ""
     );
     for (const violation of result.violations) {
       lines.push(`- **${violation.kind}** — ${violation.message}`);
       process.stderr.write(
-        `::error title=${violation.kind}::${violation.message.split("\n")[0]}\n`
+        `::${blocks(violation) ? "error" : "warning"} title=${violation.kind}::${violation.message.split("\n")[0]}\n`
+      );
+    }
+    if (warnOnly) {
+      lines.push(
+        "",
+        `This declaration sets \`"enforcement": "warn"\`, so everything above except a proven false green (\`${VIOLATIONS.suppressesRequired}\`) is reported without failing the build. Review each finding, fix or declare it, then delete the \`enforcement\` key so this guard can block.`
       );
     }
   }
@@ -569,7 +835,13 @@ function main(argv) {
       appendFileSync(process.env.GITHUB_STEP_SUMMARY, report);
     });
   }
-  if (result.violations.length > 0) process.exitCode = 1;
+  // Refusal is a failure, not a pass: an explicit run must never be mistaken
+  // for a clean bill of health. `warn` — which only Lisa's untranscribed seeds
+  // ship — downgrades it, because reddening a whole fleet the day a seed
+  // arrives is how a gate gets deleted instead of transcribed.
+  if (blocking.length > 0 || (!result.trust.trusted && !warnOnly)) {
+    process.exitCode = 1;
+  }
 }
 
 if (

package/typescript/create-only/.github/required-checks.json

@@ -3,10 +3,15 @@
     "Two REVIEWED SNAPSHOTS that scripts/check-skipped-required-checks.mjs makes police each other.",
     "Neither is derivable from this repository: `required_contexts` lives in a GitHub ruleset that humans edit in an admin console, and the skip_jobs token -> job name map lives in Lisa's quality.yml, which is not vendored here.",
     "Why it matters: GitHub counts a SKIPPED required status check as SATISFIED. A job named in `skip_jobs` still reports green against its required context having run zero steps, so the merge gate can never be red and therefore can never block anything.",
-    "Transcribe `required_contexts` BYTE FOR BYTE from the ruleset, emoji and the ' / ' separator included. The guard compares with exact string equality on purpose: a repo routinely carries confusable pairs (an external app's required `SonarCloud Code Analysis` beside a skippable, not-required `SonarCloud SAST`; `Run Tests` beside `Run Unit Tests`), and a fuzzy match would raise a false alarm whose obvious fix is to delete the guard.",
-    "Run `node scripts/check-skipped-required-checks.mjs --remote` periodically: two snapshots in one repo can only catch each other drifting from the CODE, never from a ruleset edited in the console.",
-    "Fill in `ruleset.repo` / `ruleset.ids` before --remote can work. Find the ids with: gh api repos/OWNER/NAME/rulesets --jq '.[] | \"\\(.id) \\(.name)\"'"
+    "⚠️ `required_contexts` SHIPS EMPTY AND UNSTAMPED ON PURPOSE. Lisa cannot know what YOUR ruleset requires, and an earlier version of this seed shipped a guess that was measured WRONG (#2476): it claimed `🔗 Work-Item Traceability` was required when no ruleset required it, and omitted six contexts that were. Until `ruleset.baseline_fetched_at` carries the date you transcribed the real list, the guard reports NOT CHECKED rather than answering from fiction.",
+    "To arm it: gh api repos/OWNER/NAME/rulesets --jq '.[] | \"\\(.id) \\(.name)\"' to find the ids, then gh api repos/OWNER/NAME/rulesets/ID --jq '.rules[] | select(.type==\"required_status_checks\") | .parameters.required_status_checks[].context' for the contexts. Paste them into `required_contexts` BYTE FOR BYTE (emoji and the ' / ' separator included), fill in `ruleset.repo` / `ruleset.ids`, and set `baseline_fetched_at` to today.",
+    "The guard compares with exact string equality on purpose: a repo routinely carries confusable pairs (an external app's required `SonarCloud Code Analysis` beside a skippable, not-required `SonarCloud SAST`; `Run Tests` beside `Run Unit Tests`), and a fuzzy match would raise a false alarm whose obvious fix is to delete the guard.",
+    "A transcription expires after 90 days, because a ruleset can be edited with no signal in this repository. The shipped `.github/workflows/required-checks-drift.yml` runs `--remote` weekly to catch that; `--remote` reads the ruleset live and so answers even when the cache is untrusted.",
+    "Lisa's quality.yml runs the offline arm on every pull request. This seed ships `\"enforcement\": \"warn\"`, which downgrades findings AND the NOT-CHECKED refusal to reports so a fresh install does not go red on arrival. Delete the key once you have transcribed the list — then it blocks.",
+    "`skip_jobs` is matched as an exact comma-delimited token and GitHub Actions expression syntax has no string-replace, so write the list with no spaces: `skip_jobs: 'a,b'`, never `skip_jobs: 'a, b'`. A spaced token matches nothing and the job runs — reported as `whitespace_in_skip_token`.",
+    "`_example_required_contexts` below is a STARTING POINT FOR TYPING, never read by the guard. Verify every line against your own ruleset before promoting any of it."
   ],
+  "enforcement": "warn",
   "ruleset": {
     "repo": "",
     "ids": [],
@@ -14,15 +19,15 @@
   },
   "workflows": [".github/workflows/ci.yml"],
   "exemption_ticket_pattern": "^[A-Z][A-Z0-9]+-\\d+$",
-  "required_contexts": [
+  "required_contexts": [],
+  "_example_required_contexts": [
     "🔍 Quality Checks / 🧹 Lint",
     "🔍 Quality Checks / 🔍 Type Check",
     "🔍 Quality Checks / 🏗️ Build",
     "🔍 Quality Checks / 📐 Check Formatting",
     "🔍 Quality Checks / 🔒 Security Scan",
     "🔍 Quality Checks / 🧪 Run Unit Tests",
-    "🔍 Quality Checks / 🧪 Run Integration Tests",
-    "🔍 Quality Checks / 🔗 Work-Item Traceability"
+    "🔍 Quality Checks / 🧪 Run Integration Tests"
   ],
   "skip_job_declarations": {}
 }

package/typescript/create-only/.github/workflows/required-checks-drift.yml

@@ -0,0 +1,84 @@
+# This file was created by Lisa and is yours to edit.
+# -----------------------------------------------------------------------------
+# Required-checks snapshot drift — the REMOTE arm (#2426)
+# -----------------------------------------------------------------------------
+# `.github/required-checks.json` holds two reviewed snapshots that police each
+# other: the contexts your ruleset requires, and what each `skip_jobs` token
+# silences. Two snapshots inside one repository can only catch each other
+# drifting from the CODE. Neither can see the RULESET change, because rulesets
+# are edited in an admin console — which is exactly how one repo's list went
+# from ten required contexts to eleven with every test still green for a day.
+#
+# So this runs the `--remote` arm on a schedule, and the pull-request path stays
+# offline. That split is the whole design: an enforced gate that needed network
+# and `gh` auth on every run would flake, and a flaky gate gets skipped — which
+# reintroduces the false-green class the guard exists to refuse. This workflow
+# never runs on `pull_request`, so it cannot wedge a merge.
+#
+# `--remote` is also the arm that STRUCTURALLY CANNOT LIE (#2476). It evaluates
+# the skip rules against the contexts it just read from the live ruleset, not
+# against the committed cache, so it answers correctly even in a repository
+# whose `required_contexts` has never been transcribed — which is exactly the
+# state the offline arm refuses to answer in. Arming this workflow is therefore
+# the fastest way to get a real answer.
+#
+# Reading a repository ruleset needs a token with administration:read. The
+# default GITHUB_TOKEN generally does not have it, so provide a PAT as the
+# repository secret RULESET_READ_TOKEN. Without it this job goes red rather
+# than reporting a clean bill of health it never checked.
+#
+# Until `ruleset.repo` / `ruleset.ids` are filled in, this reports UNCONFIGURED
+# and passes. Find the ids with:
+#   gh api repos/OWNER/NAME/rulesets --jq '.[] | "\(.id) \(.name)"'
+
+name: 🔒 Required-Checks Drift
+
+on:
+  schedule:
+    # Weekly. A ruleset can be edited in the admin console on a day nobody
+    # touched the repository, so change-triggered checking alone would miss it.
+    - cron: '0 8 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  drift:
+    name: 🔒 Ruleset snapshot vs live ruleset
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: 🔧 Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          package-manager-cache: false
+          node-version: '22.21.1'
+
+      - name: 🔒 Compare the committed snapshot against the live ruleset
+        env:
+          GH_TOKEN: ${{ secrets.RULESET_READ_TOKEN || github.token }}
+        run: |
+          set -euo pipefail
+          if [ ! -f scripts/check-skipped-required-checks.mjs ]; then
+            echo "scripts/check-skipped-required-checks.mjs not present — project not yet on this template; skipping."
+            exit 0
+          fi
+          if [ ! -f .github/required-checks.json ]; then
+            echo "No .github/required-checks.json — nothing to compare. Lisa ships a seed; run \`lisa apply\` to get it."
+            exit 0
+          fi
+          configured="$(node -e "const d=require('./.github/required-checks.json');process.stdout.write(String(Boolean(d.ruleset&&d.ruleset.repo&&Array.isArray(d.ruleset.ids)&&d.ruleset.ids.length)))")"
+          if [ "$configured" != "true" ]; then
+            echo "UNCONFIGURED: .github/required-checks.json has no \`ruleset.repo\` / \`ruleset.ids\`, so drift cannot be checked."
+            echo "Fill them in to arm this: gh api repos/OWNER/NAME/rulesets --jq '.[] | \"\\(.id) \\(.name)\"'"
+            echo "::warning title=Required-checks drift UNCHECKED::Fill in ruleset.repo and ruleset.ids in .github/required-checks.json to arm the remote drift check."
+            exit 0
+          fi
+          node scripts/check-skipped-required-checks.mjs --remote

package/typescript/merge/.oxlintrc.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "extends": ["./node_modules/@codyswann/lisa/oxlint/typescript.json"],
+  "extends": ["./.lisa/lisa-oxlint/typescript.json"],
   "ignorePatterns": [
     "build/**",
     "dist/**",