@codyswann/lisa 3.7.0 → 3.8.1

package/plugins/src/base/rules/reference/derived-branch-plan.md

@@ -85,9 +85,25 @@ Stated plainly, because the session that produced this contract exists to make e
 
 This is **not** an executable control. `ready-role-filing`'s sibling guard is a hook that exits 2 and physically refuses a tool call; nothing here refuses anything. What enforces this contract is a validator agent reading `SKILL.md` and choosing to apply it — the same rung of the ladder that failed to bind 13 filings out of 13.
 
-What the regression suite adds is narrower than enforcement and worth naming precisely: it pins the **wording** across all six generated skill roots, so the contract cannot be silently deleted, softened, or lost in a regeneration. It cannot catch a validator that documents the rule and then ignores it at runtime.
+The regression suite has two halves. **Why they bind differently is `falsifiable-checks`' subject, not this rule's** — read the quantifier guidance there. What belongs here is the measurement, because this contract happens to be where it was taken.
 
-That is the ceiling for now rather than a shortcut, because `SKILL.md` *is* the validators' execution substrate — there is no compiled artifact underneath to attach a hook to. The honest summary is: absence-as-`false` was undecidable and is now *decidable*, which is a real improvement and a strictly weaker claim than *enforced*. Treat a gate verdict resting on this contract as evidence, not proof, until a deterministic checker exists to read the declaration off a live item.
+- `runtime-behavior-change-decidability.test.ts` asserts the wording is *present* across all six generated skill roots. It pins the contract against silent deletion or a lossy regeneration, and proves nothing about any particular copy.
+- `runtime-behavior-change-consistency.test.ts` asserts no copy says the *wrong* thing, over every occurrence in the corpus: every declaration marker uses the em-dash discriminator, every absence-derivation site resolves to *underivable* within its own sentence, and no phrasing maps an absent section to `false` or hands authority back to the caller.
+
+This document states its rule **twice** — once in gate S8, once in the execution step — which is what made the gap observable. `lisa-linear-validate-issue` once spelled the discriminator with an ASCII hyphen in its execution step while its own S8 used the em-dash, and 192 assertions stayed green through that mutation twice running. The fix pinned the execution step and left S8's copy bare. Mutating each site separately, whole suite, before and after the second half landed:
+
+| mutated site | before | after |
+|---|---|---|
+| execution step reads an absent section as `false` | 18 | 36 |
+| **gate S8's prose reads an absent section as `false`** | **0** | **18** |
+| writers stop rendering the section | 36 | 54 |
+| a caller's assertion beats the stored declaration | 18 | 36 |
+
+Zero out of 11,270 — same file, same rule, same commit, one site pinned and its twin bare.
+
+(The wrong spelling is deliberately not written out above. This section sits inside the corpus the consistency suite scans, and the first draft of it quoted the defect as an illustration and failed its own check.)
+
+**The executable half of this contract is nothing.** Both suites read markdown. `SKILL.md` *is* the validators' execution substrate — there is no compiled artifact underneath to attach a hook to, so there is no function to call and no return value to assert. What they prove is that the instruction the agent reads is internally consistent; what neither can prove is that the agent then obeys it. Absence-as-`false` was undecidable, is now *decidable* and *non-contradictory*, and both of those are strictly weaker than *enforced*. Treat a gate verdict resting on this contract as evidence, not proof, until a deterministic checker exists to read the declaration off a live item.
 
 This costs nothing in derivation difficulty. A single-environment project — Lisa itself is one, `deploy.branches: { production: main }` — recomputes every applicable item to the same branch. The gate was never hard to satisfy; it was impossible to *audit*, and those are different problems with different fixes. Weakening S19 would have fixed neither.
 

package/plugins/src/base/rules/reference/falsifiable-checks.md

@@ -63,17 +63,69 @@ A clean result is a statement about what the check can perceive, not about the c
 
 1. Author the check.
 2. Deliberately break the guarded property — specifically, introduce **the exact regression the guard exists to prevent**, not a nearby or convenient break.
-3. Confirm the check **fails, names the right file/line, and that exactly one test fails**. A failure that does not localize is weak evidence the check is measuring the right thing.
+3. Confirm the check **fails and names the right file/line**, then read the failure count and the failing test *names* per the yardstick below.
 4. Restore, and confirm green again.
 5. Report the falsification alongside the result.
 
 ### The failure count is part of the evidence
 
-Step 3's cardinality is not pedantry; each deviation names a distinct defect.
+Step 3's cardinality is not pedantry; each deviation names a distinct defect. Run it as four steps, in this order:
 
-- **Zero failures** — the guard is inert. It was authored, it is green, and it asserts nothing about the property it names. The originating incident: a guard pinned one field of a structure and the regression it was written to stop walked straight through it with all fifty tests green, because nothing in the suite touched the field that actually moved.
-- **More than one failure** — the break is too coarse, the guard is over-broad, or unrelated tests share the fixture. Any of the three means the guard's next real failure will not tell the reader what broke, which is most of a guard's value.
-- **Exactly one failure** — the guard localizes. That is the evidence, and it is what gets reported.
+1. **Neuter the protection in production code** — delete the branch, drop the token from the enum, remove the check. Editing a *test* proves nothing about the guard; it only proves the test file is loaded.
+2. **Run the whole suite.** Never a single test file, and never a path filter.
+3. **Count the failures and read their names.** The count alone is ambiguous; the names are what separate "several failures of one regression" from "several unrelated failures."
+4. **Revert, and confirm green again.**
+
+Then read the result:
+
+- **Zero failures** — the guard is inert. It was authored, it is green, and it asserts nothing about the property it names. Two real instances: a guard pinned one field of a structure and the regression it was written to stop walked through it with all fifty tests green; and removing either `conflicting` or `unreadable` from `design-source-gate.mjs`'s `VIOLATION_STATUSES` failed **0 of 38 tests** while flipping the gate's verdict from FAIL to PASS.
+- **Many failures, unrelated to each other** — the break is too coarse, the guard is over-broad, or unrelated tests share a fixture. Any of the three means the guard's next real failure will not tell the reader what broke, which is most of a guard's value.
+- **Exactly one failure, or several all named for the same regression** — the guard localizes. Both readings are load-bearing and correctly scoped. Removing the two-token `--config-env` check failed **3** tests and pinning an index failed **5**; every failing name in both runs described the removed behaviour, so both guards were correct. This is a reading exercise, not arithmetic — "more than one is bad" is the wrong rule.
+
+### A zero is robust to contention; a positive count is not
+
+The obvious objection to any cardinality measured on a shared machine — *"your probe ran on a loaded box, so how do you trust the number?"* — has an asymmetric answer, and the asymmetry is worth stating because it decides which numbers you must re-measure.
+
+**Load can only add failures, never remove them.** A test that passes under contention would also have passed on a quiet machine; contention causes timeouts and lock races, which turn green into red, never red into green. So:
+
+- **A zero stands regardless of what else was running.** If the whole suite reports zero failures attributable to your mutation on a loaded box, a quiet box cannot produce fewer. `0 of 11,270` is `0 of 11,270`.
+- **A non-zero count needs a quiet machine**, because contention inflates it. Failures that are really flakes get miscounted as the guard's, which reads as "over-broad" and gets a correctly-scoped guard deleted.
+
+Practical consequence: an inert-guard finding is safe to report from a busy machine, while the "exactly one, or several all named alike" reading is only trustworthy once you have separated your mutation's failures from the load-flake population — which is what reading the *names* is for.
+
+### Two reasons a real protection reports zero
+
+A cardinality of zero has two distinct innocent causes, and they need different fixes. Rule out both before concluding a guard is inert:
+
+1. **Wrong probe scope** — the probe was scoped to a filename or path and is blind to a split suite. Fix: run the whole suite.
+2. **Wrong quantifier** — the assertions are existential over a corpus that contains duplicates, so a correct copy satisfies them on the broken copy's behalf. Fix: assert the universal negative.
+
+### Never scope the probe by filename
+
+**A cardinality probe scoped to a filename reports zero when a suite splits. Follow the protection, not the path.**
+
+Observed live: a reviewer neutered `before_end_of_options` (an end-of-options security fix), grepped `block-direct-issue-create.test.ts` for coverage, found none, and reported **cardinality 0 — the fix ships untested**. It was relayed as fact and used to question the author's discipline. Re-measuring against the whole suite showed neutering the protection fails **4** tests, each named for it: the suite had split at the 300-effective-line lint ceiling, and the declaration arm — including all five end-of-options tests — had moved to `block-direct-issue-create-declarations.test.ts`.
+
+The false negative fires exactly where this repo is most likely to split a file: at the line cap, on the suites that have grown *because* someone added protections to them. So:
+
+- Never scope the probe by filename or path filter.
+- Never infer absence of coverage from a grep. A grep locates text; it cannot enumerate what a mutation breaks.
+- A prior cardinality-0 finding measured with a path-scoped probe must be **re-measured** with a whole-suite probe before anyone acts on it.
+
+### Assert that no copy is wrong, not that some copy is right
+
+A test asserting that the **correct** marker is *present* passes trivially when the corpus happens to state it twice — the second statement satisfies the assertion no matter what the first one says, so the test survives the exact edit it exists to catch. The falsifiable form asserts the **wrong** spelling is *absent*: it has no second copy to fall back on, and it goes red the moment the wrong form reappears.
+
+Stated as quantifiers, which is the general form:
+
+- **Existential** — *"some copy says the right thing"* — is trivially satisfied by any other copy. A wrong copy is undetectable.
+- **Universal negative** — *"no copy says the wrong thing"* — cannot be satisfied by a correct copy elsewhere.
+
+Observed: a suite over a corpus containing two copies of the same rule returned **cardinality 0** on a real mutation because every assertion was existential. Rewriting the assertions to universal negatives — same code, same corpus, only the quantifier changed — took the same mutation from **0 to 18** failures. The defect it had been hiding: one PR pinned the *execution-step* copy of a rule and left the *gate* copy entirely unpinned, so reverting the gate's "absent section means underivable — never `false`" back to "means `false`" failed **0 of 11,270 tests** while the validator's documented gate contradicted its own execution step.
+
+### Enumerate the property, not the known-bad instance
+
+A universal negative against one hard-coded wrong spelling still only sees that spelling. Assert the **property** instead: *every* marker uses an em-dash catches the en-dash and the missing dash too, which `not.toContain("<one wrong spelling>")` never would. When that generalisation was made, it went red immediately on a wrong marker its own author had just written into rule prose — the discipline catching the person applying it, in the same run.
 
 ### Never narrate a red state you did not run
 

package/plugins/src/base/scripts/design-source-gate.mjs

@@ -294,8 +294,17 @@ export function classifyDesignSource(file, config) {
   return { ...base, status: "undeclared" };
 }
 
-/** Per-file statuses that fail the gate. */
-const VIOLATION_STATUSES = new Set([
+/**
+ * Per-file statuses that fail the gate.
+ *
+ * Exported so the suite can pin the set itself, not just its members' behavior.
+ * Classifying a file `unreadable` is not a guard; *failing the change* because
+ * of it is. Issue #2492 measured the difference: with only classification
+ * asserted, deleting `conflicting` or `unreadable` from this list flipped the
+ * verdict to PASS with the whole suite still green. The pinning test now fails
+ * on any edit to this set — a removal and an addition alike.
+ */
+export const VIOLATION_STATUSES = new Set([
   "undeclared",
   "malformed",
   "conflicting",

package/plugins/src/base/skills/lisa-drive-pr-to-merge/SKILL.md

@@ -291,7 +291,22 @@ Delegate to the `pull-request-review` skill with the PR number. It owns the whol
 comment cycle: fetch every unresolved human + bot thread (with resolution state via
 GraphQL), implement valid feedback (commit + push), reply to invalid feedback, and
 resolve every thread via `resolveReviewThread` so the branch-protection
-thread-resolution gate clears. If that skill needs to push a commit, leave
+thread-resolution gate clears.
+
+**A green review check is not proof a review happened.** That skill's Step 1b
+returns a `reviewed` / `NOT REVIEWED` verdict — record it, and repeat it in this
+skill's final report. Measured (CodySwannGT/lisa#2497): `CodeRabbit` was a
+*required* context and posted `success — "Review rate limited"` on #2483 and
+#2484, so branch protection recorded a satisfied review gate for two
+security-relevant PRs nothing had read; both merged and shipped in `v3.5.1`.
+
+`NOT REVIEWED` is **not a blocker** — do not hold the merge on it, do not treat
+it as a failing check, and do not try to force the bot to re-run. A hollow
+review check is usually an org-wide vendor spending cap, which is a billing
+matter no amount of driving will clear, and whether such a check belongs in the
+required set at all is an open owner decision. It is a **reporting** obligation:
+the PR merged unreviewed, and the report has to say so instead of implying a
+review it did not get. If that skill needs to push a commit, leave
 auto-merge armed (section 1); when it returns, re-read `headRefOid` and reset
 `verify_commit` to the returned/pushed head, then continue. Do not re-implement review handling here
 — it is the single source of truth for review-thread handling.
@@ -452,3 +467,16 @@ At every terminal state, release the babysitter lease
 (`gh pr edit <pr> --remove-label "lisa:babysitter-on-duty"`) so the CI
 auto-fix workflow can take over as fixer of last resort if the branch goes
 red later with nobody driving it.
+
+**Every terminal report carries the step-(d) review verdict**, including a
+successful `MERGED`. "Merged, all checks green" is exactly the sentence that hid
+#2483 and #2484: both were green, both were merged, and neither had been read by
+anything. Green means *no gate objected*; it does not mean *something looked*.
+So state the verdict alongside the outcome:
+
+- `MERGED — reviewed (CodeRabbit "Review approved")`
+- `MERGED — NOT REVIEWED: CodeRabbit posted success but "Review rate limited"`
+
+This is reporting, never a terminal state of its own. `NOT REVIEWED` does not
+turn a merged PR into a blocked one, and it must never be used to withhold a
+merge — it changes what the record says, not what the loop does.

package/plugins/src/base/skills/lisa-pull-request-review/SKILL.md

@@ -37,8 +37,49 @@ gh api graphql -f query='
   -F owner=<owner> -F repo=<repo> -F pr=<pr>
 ```
 
-Keep only threads where `isResolved == false`. If there are none, report success
-and exit (nothing to do).
+Keep only threads where `isResolved == false`.
+
+**If there are none, you have not yet learned anything — run Step 1b before
+concluding.** Zero unresolved threads has two completely different causes, and
+this query cannot tell them apart: *a reviewer looked and found nothing*, or
+*nothing ever looked*. Reporting the first when it was the second is the defect
+in CodySwannGT/lisa#2497.
+
+## Step 1b: Did any review actually happen? (required before reporting)
+
+A required review check can post `success` having reviewed nothing. Measured on
+PRs #2483 and #2484: `CodeRabbit` reported `success — "Review rate limited"`,
+zero reviews, and both merged on that green carrying security-relevant changes.
+
+```bash
+gh pr checks <pr> --json name,state,bucket,description \
+  --jq '.[] | select(.name | test("(?i)coderabbit|review")) | "\(.name)\t\(.state)\t\(.description)"'
+```
+
+**The state column reads `SUCCESS` whether the review was real or hollow — only
+the description distinguishes them.** `Review approved` / `Review completed` is
+a real review; `Review rate limited`, `Review queued`, or a missing context is
+not. Never read `gh pr view --json statusCheckRollup` for this: CodeRabbit posts
+a legacy commit status, which that route returns *without* the description.
+
+Where the project ships Lisa's guard, prefer its machine-readable form, which
+also says whether the check is ruleset-required (so whether branch protection
+recorded a satisfied review gate for a review that did not happen):
+
+```bash
+node scripts/check-skipped-required-checks.mjs --pr=<pr> --json
+```
+
+It reports and never fails — a hollow check is often a vendor spending cap, not
+a repository defect, and it is not this skill's call to block on one.
+
+Carry the finding into your Step 4 report. **Do not write "no unresolved review
+threads" on its own** — it is true of an unreviewed PR too. Say which you
+observed:
+
+- `reviewed — CodeRabbit "Review approved", 0 unresolved threads`
+- `NOT REVIEWED — CodeRabbit success but "Review rate limited" (vacuous); 0 threads means nobody looked`
+- `NOT REVIEWED — no review check reported on this PR at all`
 
 ## Step 2: Triage and act on each unresolved thread
 
@@ -75,6 +116,13 @@ judgment. This skill resolves **threads**; it does not dismiss review-decision
 gates (`CHANGES_REQUESTED`) or merge the PR — the caller (`drive-pr-to-merge`)
 owns those.
 
+**Open the report with the Step 1b verdict, before the thread counts.** A thread
+summary describes what was done about review findings; it says nothing about
+whether a review produced any. State `reviewed` or `NOT REVIEWED (<why>)` first,
+then the counts. A caller that records "reviews addressed" in evidence must
+carry that verdict through verbatim — a PR whose only review check was vacuous
+has not been reviewed, no matter how clean its thread list is.
+
 ## Composition
 
 - **Standalone**: `/lisa:pull-request:review <pr>`.

package/scripts/lisa-github-rulesets.sh

@@ -351,6 +351,82 @@ strip_config_dropped_checks() {
     else . end'
 }
 
+# Per-repo opt-IN, the mirror of dropRequiredChecks above. Some repositories run
+# a high-signal check that only exists in THAT repository, so it cannot live in
+# a shared template: putting it there would ship a context host projects never
+# report, and a required check that never reports blocks every pull request
+# forever (the #2476 "aspirational seed a guard then trusts" defect).
+#
+# Keyed by ruleset name, because more than one shipped template carries a
+# required_status_checks rule (`base` and `quality checks` both do) and an
+# unkeyed list could not say which one it meant:
+#   { "github": { "rulesets": { "addRequiredChecks": {
+#       "quality checks": [
+#         { "context": "🧩 Plugin artifacts match source", "integration_id": 15368 }
+#       ] } } } }
+#
+# `integration_id` is optional and defaults to GitHub Actions. Contexts already
+# present are not duplicated, and a ruleset with no required_status_checks rule
+# gets one created so an addition is never silently dropped.
+#
+# Additions are applied FIRST, before the no-workflows strip and before
+# dropRequiredChecks, so both of those still win over an addition. That is
+# deliberate: the no-workflows strip is a safety rule (a required Actions check
+# on a repository with no workflows can never report, and would block every pull
+# request), and naming the same context in both lists is operator error whose
+# safe resolution is to drop it rather than to require it.
+add_config_required_checks() {
+  local json="$1"
+  local project_path="$2"
+  local ruleset_name="$3"
+  local config="$project_path/.lisa.config.json"
+
+  if [[ ! -f "$config" ]]; then
+    echo "$json"
+    return 0
+  fi
+
+  local added
+  if ! added=$(jq -c --arg name "$ruleset_name" \
+    '.github.rulesets.addRequiredChecks[$name] // []' "$config" 2>/dev/null); then
+    log_warning ".lisa.config.json could not be parsed — ignoring github.rulesets overrides" >&2
+    added="[]"
+  fi
+
+  if [[ "$added" == "[]" || "$added" == "null" ]]; then
+    echo "$json"
+    return 0
+  fi
+
+  echo "$json" | jq --argjson added "$added" --argjson actions "$ACTIONS_INTEGRATION_ID" '
+    ($added
+      | map(select(type == "object" and (.context | type) == "string"))
+      | map({ context: .context, integration_id: (.integration_id // $actions) })
+    ) as $checks
+    | if ($checks | length) == 0 then .
+      elif ((.rules // []) | map(select(.type == "required_status_checks")) | length) > 0 then
+        .rules |= map(
+          if .type == "required_status_checks" then
+            .parameters.required_status_checks |= (
+              . as $existing
+              | . + ($checks | map(
+                  select(.context as $c | ($existing | map(.context) | index($c)) | not)
+                ))
+            )
+          else . end
+        )
+      else
+        .rules = ((.rules // []) + [{
+          type: "required_status_checks",
+          parameters: {
+            strict_required_status_checks_policy: false,
+            do_not_enforce_on_create: true,
+            required_status_checks: $checks
+          }
+        }])
+      end'
+}
+
 apply_ruleset() {
   local repo="$1"
   local template_file="$2"
@@ -365,6 +441,7 @@ apply_ruleset() {
 
   local clean_template
   clean_template=$(strip_readonly_fields "$template_content")
+  clean_template=$(add_config_required_checks "$clean_template" "$project_path" "$ruleset_name")
   clean_template=$(strip_actions_checks_if_no_workflows "$clean_template" "$project_path")
   clean_template=$(strip_config_dropped_checks "$clean_template" "$project_path")
 

package/typescript/copy-overwrite/ast-grep/rules/no-missing-fs-extra-namespace-member-js.yml

@@ -0,0 +1,71 @@
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+#
+# JavaScript-language twin of `no-missing-fs-extra-namespace-member.yml`.
+#
+# ast-grep binds one parser per rule: `language: typescript` scans only
+# .ts/.mts/.cts, so .js/.mjs/.cjs would otherwise be an unguarded gap — and a
+# guard with a silent hole is the failure mode this rule exists to prevent.
+# Build scripts and tooling in TypeScript projects are routinely .mjs, and
+# fs-extra is exactly the kind of dependency they reach for.
+#
+# The `constraints` block MUST stay byte-identical to the TypeScript rule.
+# `tests/unit/config/ast-grep-template.test.ts` asserts both files carry the
+# same allow list AND that it still equals the set real Node reports, so these
+# two cannot drift apart or drift away from reality unnoticed.
+#
+# See the TypeScript rule for the full rationale on why this is an allow list
+# rather than a deny list, and why the set is stable across fs-extra 11.x.
+id: no-missing-fs-extra-namespace-member-js
+language: javascript
+severity: error
+message: |
+  `fs-extra` does not expose this member on its ESM namespace object.
+
+  `import * as fse from "fs-extra"` resolves to fs-extra's CommonJS entry, so
+  Node derives the namespace keys with cjs-module-lexer. Only fs-extra's own
+  directly-assigned functions survive that. Absent members include every JSON
+  helper (readJson, readJSON, writeJson, outputJson, and their Sync forms),
+  every node:fs passthrough (readFile, writeFile, readdir, stat, existsSync,
+  appendFile, ...), and copySync, moveSync, removeSync, pathExistsSync and
+  outputFileSync.
+
+  The call is `undefined` at run time and throws a TypeError, and unit tests
+  cannot see it — Vitest and Jest resolve the import through CJS interop and
+  hand back the default export's properties.
+
+  Fix by importing the concrete API instead:
+    - file I/O     -> `readFile` / `writeFile` from `node:fs/promises`
+    - JSON         -> read the file, then `JSON.parse` / `JSON.stringify`
+    - whole module -> `import fse from "fs-extra"`. The DEFAULT export does
+                      carry every member and is deliberately not flagged here.
+# Test trees are excluded on purpose — see the TypeScript rule for the full
+# rationale. In short: the defect class is "works under a bundler, `undefined`
+# under real Node", so it can only bite code Node executes directly, and the
+# runtime control in the Lisa monorepo already scopes itself to source trees
+# for exactly that reason. Keep this list in step with the TypeScript rule.
+ignores:
+  - '**/tests/**'
+  - '**/test/**'
+  - '**/__tests__/**'
+  - '**/__mocks__/**'
+  - '**/*.test.js'
+  - '**/*.test.mjs'
+  - '**/*.test.cjs'
+  - '**/*.test.jsx'
+  - '**/*.spec.js'
+  - '**/*.spec.mjs'
+  - '**/*.spec.cjs'
+  - '**/*.spec.jsx'
+rule:
+  all:
+    - pattern: $NS.$MEMBER
+    - inside:
+        kind: program
+        stopBy: end
+        has:
+          pattern: import * as $NS from "fs-extra"
+constraints:
+  MEMBER:
+    not:
+      regex: ^(copy|createFile|createFileSync|createLink|createLinkSync|createSymlink|createSymlinkSync|default|emptyDir|emptyDirSync|emptydir|emptydirSync|ensureDir|ensureDirSync|ensureFile|ensureFileSync|ensureLink|ensureLinkSync|ensureSymlink|ensureSymlinkSync|exists|mkdirp|mkdirpSync|mkdirs|mkdirsSync|move|outputFile|pathExists|read|readv|remove|write|writev)$

package/typescript/copy-overwrite/ast-grep/rules/no-missing-fs-extra-namespace-member.yml

@@ -0,0 +1,90 @@
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+#
+# Bans `fs-extra` namespace members that do not exist under real Node ESM.
+#
+# The allow list below is an ALLOW list, not a deny list, and that is
+# deliberate. A deny list fails open: any absent member nobody thought to
+# enumerate passes silently, which is the exact rot this rule exists to
+# prevent. An allow list fails closed — an unrecognised member is flagged
+# loudly and a human decides.
+#
+# The list is the set of keys real Node reports for
+# `import * as fse from "fs-extra"`. It is byte-identical across fs-extra
+# 11.1.1, 11.3.3, 11.3.4 and 11.3.5, because the bare specifier always routes
+# through the package `exports` map to the CommonJS entry (`./lib/index.js`)
+# and Node derives the namespace keys with cjs-module-lexer from a re-export
+# shape that has not changed. `lib/esm.mjs` — which does export the JSON
+# helpers — is reachable only via the `fs-extra/esm` subpath, which is a
+# different import.
+#
+# Anti-rot: `tests/unit/core/fs-extra-namespace-callsites.test.ts` in the Lisa
+# monorepo derives this same set from real Node at run time, and
+# `tests/unit/config/ast-grep-template.test.ts` asserts the list below still
+# equals it. If fs-extra ever changes its namespace surface, that pairing goes
+# red centrally instead of this list silently drifting in every host project.
+id: no-missing-fs-extra-namespace-member
+language: typescript
+severity: error
+message: |
+  `fs-extra` does not expose this member on its ESM namespace object.
+
+  `import * as fse from "fs-extra"` resolves to fs-extra's CommonJS entry, so
+  Node derives the namespace keys with cjs-module-lexer. Only fs-extra's own
+  directly-assigned functions survive that. Absent members include every JSON
+  helper (readJson, readJSON, writeJson, outputJson, and their Sync forms),
+  every node:fs passthrough (readFile, writeFile, readdir, stat, existsSync,
+  appendFile, ...), and copySync, moveSync, removeSync, pathExistsSync and
+  outputFileSync.
+
+  The call is `undefined` at run time and throws a TypeError. Unit tests are
+  structurally blind to it: Vitest and Jest resolve the import through CJS
+  interop and hand back the default export's properties, so the call is a
+  function in every test and `undefined` in production. Lisa shipped this
+  defect three times in one release window (#2482, #2487) — once as a crash
+  that stranded seven merged PRs, twice inside error-swallowing `catch` blocks
+  where the TypeError replaced the error being handled.
+
+  Fix by importing the concrete API instead:
+    - file I/O     -> `readFile` / `writeFile` from `node:fs/promises`
+    - JSON         -> read the file, then `JSON.parse` / `JSON.stringify`
+    - whole module -> `import fse from "fs-extra"`. The DEFAULT export does
+                      carry every member and is deliberately not flagged here.
+# Test trees are excluded on purpose, matching the scope the runtime control
+# already chose. The defect class is "works under a bundler, `undefined` under
+# real Node" — so it can only bite code that Node executes directly. Vitest and
+# Jest resolve `import * as fse from "fs-extra"` through CJS interop and hand
+# back the default export's properties, which is precisely why test files can
+# call `fse.writeJson` forever without ever being wrong.
+#
+# `tests/unit/core/fs-extra-namespace-callsites.test.ts` scopes itself to
+# ["src", "scripts"] for this reason — "trees whose code is executed by Node
+# directly, not through a bundler". This rule matches that scope rather than
+# inventing a second, wider one. Path globs are used instead of a src/scripts
+# allowlist because host project layouts vary (apps/, packages/, lib/) while
+# test directory conventions do not.
+ignores:
+  - '**/tests/**'
+  - '**/test/**'
+  - '**/__tests__/**'
+  - '**/__mocks__/**'
+  - '**/*.test.ts'
+  - '**/*.test.mts'
+  - '**/*.test.cts'
+  - '**/*.test.tsx'
+  - '**/*.spec.ts'
+  - '**/*.spec.mts'
+  - '**/*.spec.cts'
+  - '**/*.spec.tsx'
+rule:
+  all:
+    - pattern: $NS.$MEMBER
+    - inside:
+        kind: program
+        stopBy: end
+        has:
+          pattern: import * as $NS from "fs-extra"
+constraints:
+  MEMBER:
+    not:
+      regex: ^(copy|createFile|createFileSync|createLink|createLinkSync|createSymlink|createSymlinkSync|default|emptyDir|emptyDirSync|emptydir|emptydirSync|ensureDir|ensureDirSync|ensureFile|ensureFileSync|ensureLink|ensureLinkSync|ensureSymlink|ensureSymlinkSync|exists|mkdirp|mkdirpSync|mkdirs|mkdirsSync|move|outputFile|pathExists|read|readv|remove|write|writev)$