@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-devin/rules/eager/falsifiable-checks.md

@@ -0,0 +1,48 @@
+# Falsifiable Checks — A Check That Cannot Fail Is Not Evidence (load-bearing)
+
+A passing test, a clean lint run, a zero-hit sweep, a green ratchet: each is evidence **only if that check is known to be capable of failing.** Otherwise it is a checkbox, and a green suite that protects nothing is worse than no suite — it actively suppresses the search for the defect.
+
+**Before reporting any clean, zero, or passing result from a check you authored or modified, prove it fails on known-bad input.** Break the thing being guarded, confirm the check fails *and names the right location*, then restore. That falsification is part of the deliverable, not an optional extra.
+
+This is the instrument-validity counterpart to the `verification` rule (which proves the *software* behaves) and `empirical-inquiry` (which proves a *fact*). All three reject "it looks correct." This one rejects "the check said so."
+
+When the check was **prescribed by a work item** rather than authored here — "that named test must go red, or the fix did nothing" — `control-reachability` governs instead, and it inverts the cost: a control whose fixture never reaches the changed path stays green for an unrelated reason, and the item's own stopping rule then reverts a correct fix.
+
+## The five ways a check silently measures nothing
+
+Each has been observed in real runs; each reported success while asserting nothing:
+
+1. **Self-matching guard** — the check's own explanatory comment, docstring, or ticket prose contains the token it searches for, so it matches itself. It passes with the guarded field deleted.
+2. **Fixture-validated assertion** — the assertion reads the test's own fixture rather than the artifact under test. Common when the production path consumes a *raw* input the fixture supplies directly.
+3. **Stale-artifact pass** — the revert-to-verify step silently failed (generator errored, cache served old output, build skipped), so the check re-read unchanged input and "passed".
+4. **Wrong-baseline sweep** — the detector ran against already-fixed state, so its zero is uninformative. Validate detectors against a ref where the defect still exists.
+5. **Pager-shadowed status** — the check ran and FAILED, but its result was read through a pipe. A shell pipeline's exit status is its LAST stage's, so `gate | tail -4; echo $?` reports `tail`'s success. Shortening output is exactly what one does while checking whether a gate passed, and the failure line is exactly what the shortening drops.
+
+## Mandatory
+
+- **Read the command's own status, never a pipeline's.** When the answer decides whether you are blocked, redirect first and read the status before shortening anything — one spelling, portable to every shell including POSIX `sh`:
+
+  ```sh
+  status=0
+  gate >gate.log 2>&1 || status=$?    # `||`, not `;` — see below
+  tail -n 20 gate.log                 # shorten for reading, not for deciding
+  [ "$status" -eq 0 ] || echo "FAILED ($status) — full output in gate.log"
+  ```
+
+  `|| status=$?` rather than `; status=$?`, because the `;` form is itself a silent-measurement bug under `set -e`: errexit kills the shell on the failing command and the assignment never runs, so the branch that reports the failure is unreachable in exactly the case it exists for. The left side of `||` is exempt from errexit, which is why this spelling survives both `set -e` and its absence — and why `status` is initialized, since on success nothing assigns it.
+
+  When the block's **own** status is what gets read — a hook, a CI step, a script someone runs with `&&` — end it with `exit "$status"` (or `return "$status"` in a function). Without that, the last command is the `echo` and the block exits 0 after printing `FAILED`: the same pager-shadowing one line further out.
+
+  This form is preferred over the alternatives because it is the only one that both survives `sh` and keeps the full output, which is what you need the moment the status says the gate failed. `set -o pipefail` is correct where it exists but is **not POSIX `sh`** — dash has no such option, and this repository runs hooks under `sh`. `${PIPESTATUS[0]}` is **bash-only** (zsh spells it `$pipestatus[1]`, 1-indexed) and is overwritten by the very next command, so it must be read immediately. Never report a gate as green from a status read through `| tail`, `| head`, or `| tee`.
+- **Falsify before reporting.** No clean result is reportable until the check has been shown to fail on a deliberate break. **"Mentally reverting" does not count** — reasoning that the assertion *would* fail is precisely the step that lets a non-functional guard ship, because the author already believes it is load-bearing. Run the break.
+- **Mutation-prove the guard, then read the cardinality.** Neuter the protection **in production code**, run the **whole suite**, count the failures and **read their names**, then revert. **Zero** ⇒ the guard is inert (one pinning a single field shipped with all 50 tests green while the regression walked through). **Many, unrelated** ⇒ over-broad; its next failure will not name the cause. **Exactly one, or several all named for the same regression** ⇒ load-bearing and correctly scoped. A **zero is robust to contention** — load only ever adds failures — so only the non-zero counts need a quiet machine.
+- **The automated mutation gate is language-scoped; the manual probe above is not.** Stryker instruments the JavaScript and TypeScript family plus Vue, HTML and Svelte — there is **no shell parser**, so a guard whose logic lives in `.sh` yields no mutants under **any** `mutate` list. Adding one does not measure it: it aborts the whole run (`No parser registered for .sh!` — measured, not inferred) and takes every other guard's score with it. So a mutation gate that stays grey or green on a shell-guard change **measured nothing about that guard**, and reading it as coverage is the fifth failure mode above wearing a config file. Shell guards are covered by **driving tests only**: execute the script against a payload table and assert the blocked/allowed verdict, with a control on **both** sides — a refusal case *and* an allowed case. A shell guard nothing executes has no bite evidence at all, whatever the gate printed.
+- **Never scope the probe by filename, and never infer absent coverage from a grep.** Suites split at the line cap, so a protection's tests often sit in a sibling file: a filename-scoped probe reported cardinality 0 on a live security fix that a whole-suite run showed failing 4 tests, every one named for it.
+- **Assert that no copy is wrong, not that some copy is right.** An existential assertion over duplicated content is satisfied by the correct copy and cannot see the broken one — rewriting one suite's assertions to universal negatives took the same mutation from **0 to 18** failures. Enumerate the property (*every* marker uses an em-dash), never the one known-bad spelling.
+- **Reconstruct a red state; never narrate one you did not run.** Evidence describing a failing or dirty state must come from a run you actually observed — an evidence file once claimed "working tree clean" while listing two untracked scripts in the same file. To observe a state that no longer exists, check that commit out in a **throwaway detached-HEAD worktree** and run it there. Writing down what the output would have said is fabrication, however confident the reasoning.
+- **Say how it was falsified.** "0 findings" alone is not a result; state what you broke and that the check caught it. A gate whose falsification is untested must be reported as *unvalidated*, not as passing.
+- **Prefer structural over textual checks.** Parse the AST/structure instead of matching source text: text matching cannot distinguish a field from a comment, an alias, or a nested occurrence, and it produces false positives that mask the real ones.
+- **A negative result is scoped to what the check can see.** State the blind spot. A presence check cannot see a wrong value; a per-file check cannot see a cross-file interaction; fixing one instance of a class is not fixing the class — sweep the class.
+- **When revert-to-verify is unreliable** (generated artifacts, schema-validated inputs, caches), unit-test the checker directly against synthetic known-bad input instead.
+
+Full prose, worked examples, and the reporting template: [reference/falsifiable-checks.md](../reference/falsifiable-checks.md).

package/plugins/lisa-devin/rules/eager/history-audit.md

@@ -0,0 +1,27 @@
+# History Audit — Before Removing or Changing Existing Behavior (load-bearing)
+
+When a proposed change would **remove, gate, skip, consolidate, weaken, or relax existing behavior** — and the motivation is your own assessment that the code looks redundant, wasteful, slow, or wrong (rather than a ticket, bug report, or spec) — audit the history **before presenting the change as safe or implementing it**.
+
+## How to apply
+
+1. `git log --follow` the affected files and `git log --grep` for related keywords.
+2. Read **full commit bodies** (never just subjects), code comments, and covering tests — the defense usually lives there, often naming the exact incident the behavior prevents.
+3. Deliver every such recommendation with an explicit verdict:
+   - **Defended by \<commit/comment/test\>** — adapt the proposal to preserve that reason.
+   - **No defense found** — genuinely accidental; safe to change, and say so.
+
+## Scope
+
+- **Diagnosis doesn't need the audit; prescriptions do.** Analyzing what is slow or broken is free; recommending that existing behavior stop happening is what triggers the audit. If presenting unaudited ideas, label them as such.
+- Changes driven by an external requirement may cite that requirement as their defense and move on.
+- "Nothing was deleted" is not an exemption — a change that weakens a guarantee (e.g. adding a cache/stamp that skips a self-healing pass) alters existing behavior and needs the same audit.
+
+## Forbidden
+
+- Recommending removal or weakening of existing behavior as "safe" without the verdict.
+- Auditing subjects only (`--oneline` skims miss the evidence).
+- Treating redundant-looking behavior as accidental by default — defended is the norm, not the exception.
+
+This rule compounds with commit discipline: documenting the **why** in commit bodies is what makes future audits cheap.
+
+Full prose: [reference/history-audit.md](../reference/history-audit.md).

package/plugins/lisa-devin/rules/eager/integration-access-layer.md

@@ -0,0 +1,19 @@
+# Integration Access Layer
+
+Skills and rules that use external integrations route through the matching
+`*-access` skill. Do not call vendor MCP tools or REST APIs directly from a
+consumer skill.
+
+Resolve credentials through `lisa-secrets-access`; do not duplicate its
+provider configuration or ask a human to paste a value it can supply.
+
+For missing AWS credentials, use its `LISA_AWS_BOOTSTRAP_JSON` recovery guidance
+before proposing an interactive login.
+
+Use the configured-provider token/CLI first when its bootstrap credential is
+present, then interactive MCP, then an error naming the missing credential.
+Every method must match the intended tenant; skip mismatched identities.
+Resolution order:
+[reference/credential-substrate-precedence.md](../reference/credential-substrate-precedence.md);
+full matrix and migration rules:
+[reference/integration-access-layer.md](../reference/integration-access-layer.md).

package/plugins/lisa-devin/rules/eager/intent-routing.md

@@ -0,0 +1,18 @@
+# Intent Routing (load-bearing)
+
+**On the first user message of a session**, before responding to the substance of the request, before running any tool, before asking any clarifying question:
+
+1. **Classify the flow.** One of: Research, Plan, Implement (Build/Fix/Improve/Investigate-Only), Verify, Monitor, Intake, Debrief, or No flow. If a slash command was invoked, the flow is already determined.
+2. **Echo the chosen flow** with a one-sentence justification. Example:
+   > **Flow: Implement/Fix** — bug report with reproduction steps.
+3. **Echo orchestration mode in the same message.** One of:
+   > **Orchestration: agent team** — Research, Plan, Implement, Intake, Debrief, and any flow that invokes Review. (For Intake, the team is created by the per-item lifecycle skill — `lisa-plan` / `lisa-implement` — that Intake dispatches in-session; Intake itself is a thin dispatcher and never creates a team or spawns the lifecycle flow as a subagent.)
+   > **Orchestration: single agent** — Verify (standalone), Monitor (standalone), product-walkthrough standalone, debrief-apply, one-off diagnostic sessions.
+4. **Check the readiness gate.** If gate fails interactively, ask for what's missing with recommended answers; do not start work. Headless/`-p` sessions infer from available context instead of blocking.
+5. **Cascade rule.** You are inside an agent team only if you are yourself a spawned teammate/subagent (spawned into a team context, or reporting to a team lead). In that case do **not** create a second team — add specialists through the existing lead: on Claude, teams are flat, so message the lead with teammate + assignment; on Codex, use `multi_agent_v1.spawn_agent`. A lead session that spawned subagents earlier is still the lead — a lifecycle skill invoked there (including by `lisa-intake`) creates its team normally.
+
+Once a flow is established, **do not re-classify** on later messages, even if a follow-up looks vague ("now run the tests", "thanks"). Subsequent messages inherit the established flow unless the user explicitly changes scope.
+
+Skipping classification or orchestration echo leads to unstructured responses that bypass readiness gates.
+
+Full reference (flow definitions, readiness gates, orchestration matrix, sub-flows): [reference/intent-routing.md](../reference/intent-routing.md).

package/plugins/lisa-devin/rules/eager/learnings-ladder.md

@@ -0,0 +1,18 @@
+# Learnings Ladder — Where Does This Go? (load-bearing)
+
+When you learn something durable, route it by **what it costs to carry**, not by whichever file you happen to have open. Six rungs, strongest enforcement first:
+
+| Rung | Destination | Enters context |
+| --- | --- | --- |
+| EXECUTABLE-CONTROL | Lint / ast-grep / type / test / hook / `package.lisa.json` force | Never — the diagnostic fires on violation |
+| EAGER-RULE | The host rules directory `.agents/rules/` (Lisa's own shipped rules live in the plugin rules tree) | Unconditionally, every session |
+| SKILL | A `SKILL.md` procedure | Description only; body on invoke |
+| WIKI | Wiki page plus an index entry | Only when queried |
+| KEEP-IN-LEDGER | The learnings ledger (`.lisa/PROJECT_LEARNINGS.md`) | Bounded projection only |
+| RETIRE | Nowhere — delete the prose | Never |
+
+**Take the cheapest rung that actually works.** Anything a machine can decide is EXECUTABLE-CONTROL. KEEP-IN-LEDGER is the default landing zone. EAGER-RULE is earned only by evidence of repeated misses despite the knowledge already being reachable, and the tier is demotion-biased — every session pays for it.
+
+**You capture; you do not promote.** Record the learning through `lisa-persist-learning`. The gardener (`/lisa:learnings:audit`, an opt-in weekly automation) routes candidates through the `skill-evaluator` and files human-gated promotion tickets. Never hand-append a learning to `AGENTS.md` or a host rules file.
+
+Full prose: [reference/learnings-ladder.md](../reference/learnings-ladder.md).

package/plugins/lisa-devin/rules/eager/local-ci-first.md

@@ -0,0 +1,15 @@
+# Local CI First — CI Is Not a Debugger (load-bearing)
+
+When an end-to-end suite fails in CI — Playwright, Maestro, Cypress, or any runner you normally only see in a workflow — **reproduce it locally with the same configuration before pushing another commit.**
+
+Push-and-watch is a ten-minute debugger with no breakpoints, and every red run costs the shared queue as well as your session.
+
+## Mandatory
+
+1. **Reconstruct the invocation from the workflow file**, not from memory: the same command, env vars, config file, browser/device target, and tags CI uses.
+2. **Fix it locally, confirm it green locally, then push once.** Never push a speculative fix "to see if it helps."
+3. **If it genuinely will not reproduce locally, say so explicitly** and name what differs — runner OS, secrets, headless mode, timing, a device CI has and you do not — before you use CI to bisect. Then change one thing per push and say what you are testing.
+
+Setting up the local runner (installing the browser, booting the simulator, seeding the fixture) is part of the work, not a reason to skip this.
+
+Full prose: [reference/local-ci-first.md](../reference/local-ci-first.md).

package/plugins/lisa-devin/rules/eager/measurement-integrity.md

@@ -0,0 +1,18 @@
+# Measurement Integrity (load-bearing)
+
+**Before you report a count, a population, or "N items affected", run the checks — because every way this goes wrong produces output that looks exactly like an answer.** No exception, no warning, no partial flag: the wrong number is indistinguishable from the right one by reading it.
+
+That is why "be careful about scope" is not a remedy. **Every check below is performed or not performed**, never noticed:
+
+1. **State the population boundary** before enumerating — what is in, and what is adjacent and out.
+2. **Prove the enumeration complete** — paginate, and *assert* the end-of-pages signal rather than trusting it. A silent cap looks exactly like a population.
+3. **Validate the detector against known-true items.** If it cannot find the examples you already have, its total means nothing.
+4. **Treat search results as candidates, never members** — read each one directly and confirm the literal.
+5. **Control the instrument in both directions** — it must report a real absence, and must not invent one.
+6. **Report pattern-derived totals as floors**, and **state the unit** beside any count whose argument rests on how many *independent* observations you have.
+
+No single check covers the others: validating against known items is blind to truncation, and reading every candidate can only ever see what enumeration handed it.
+
+**And one that fires while reading rather than measuring:** a filter built from the failure shapes you already expect cannot show you a shape you did not. Read gate and tool output **unfiltered** on a refusal — the diagnosis is usually already in it.
+
+Full method (six modes in two families, the membership test for adding a seventh, and which check is blind to what): [reference/measurement-integrity.md](../reference/measurement-integrity.md).

package/plugins/lisa-devin/rules/eager/never-name-a-downstream-project.md

@@ -0,0 +1,9 @@
+# Never Name a Downstream Project
+
+Refer to a downstream project by its **role in the argument** — never by organization, product, or repository name — in tracker items, pull requests, commits, rules, skills, anything that outlives the session.
+
+Write the evidence, not the identity: "a caller repo", "repo A" / "repo B" when two are contrasted.
+
+Default-deny: it covers names nobody listed. `block-host-name-leak` catches some of them and is a rate reduction, never a proof.
+
+Full prose: [reference/never-name-a-downstream-project.md](../reference/never-name-a-downstream-project.md).

package/plugins/lisa-devin/rules/eager/not-blocked-just-waiting.md

@@ -0,0 +1,13 @@
+# Waiting Is Not Blocked (load-bearing)
+
+Three rules that keep an active session from stalling:
+
+1. **Poll, don't wait.** While the session is active, go check status yourself — roughly every 5 minutes. Never sit idle waiting for a subagent callback, a CI notification, or any automated message to arrive. If a result matters, go look for it.
+2. **Blocked means you physically cannot proceed.** Waiting on a confirmation, a review, a running job, or someone's opinion is *waiting*, not blocked. Report it as waiting — and keep working on everything that does not depend on it.
+3. **Plan phases are not sequential unless the user said so.** Absent a stated dependency, run them in parallel.
+
+Idling is the expensive failure here: a session that waits produces nothing while still costing the human their attention and their clock.
+
+This governs **session** stuckness only. The factory's tracker vocabulary — `human_needed` and the `blocked` lifecycle role used by `lisa-implement` and `lisa-repair-intake` — is stricter, unchanged, and not reclassified by this rule.
+
+Full prose: [reference/not-blocked-just-waiting.md](../reference/not-blocked-just-waiting.md).

package/plugins/lisa-devin/rules/eager/operational-hazards.md

@@ -0,0 +1,50 @@
+# Operational Hazards — Short-Lived, Expiring, and Read by Sessions That Do Not Exist Yet
+
+**A broadcast cannot reach a session that starts after it, and the sessions that missed it never
+knew there was something to miss.** The lanes most likely to collide on a port, saturate the
+workers, or re-hit a defect somebody diagnosed an hour ago are precisely the ones that just
+started — so the population a fan-out structurally cannot reach is the population most exposed.
+
+Enumerating peers does not fix it: two sessions listing peers at the same moment returned different
+rosters, so "I told everyone" carries an unknown hole.
+
+## Mandatory
+
+- **Declare a transient hazard instead of announcing it.** A condition another session will hit —
+  a port another lane holds, a saturated resource, a command that dumps credentials, a gate that is
+  red for an environmental reason — is not communicated until this has run:
+
+  ```
+  node "$CLAUDE_PLUGIN_ROOT/hooks/operational-hazards.mjs" --declare <id> \
+    --hazard "<what will go wrong>" \
+    --avoid "<what to do instead>" \
+    --until <YYYY-MM-DD>
+  ```
+
+  `--until` is required and has no default. **An entry that never expires is doctrine, and doctrine
+  belongs in a rule** — a hazard surface without an expiry becomes permanent scripture, which is
+  the failure this exists against. Past its `until`, an entry stops being shown with nobody
+  remembering to remove it.
+
+- **Lift it when it ends.** A declaration nothing can void is the defect the QA-failure signal and
+  the human gate each closed:
+
+  ```
+  node "$CLAUDE_PLUGIN_ROOT/hooks/operational-hazards.mjs" --lift <id> --because "<what resolved it>"
+  ```
+
+- **Read it where no hook runs:** `node "$CLAUDE_PLUGIN_ROOT/hooks/operational-hazards.mjs" --list`.
+
+## What arrives on its own
+
+On Claude Code the ledger is read for you at SessionStart **and SubagentStart** — a subagent
+spawned an hour from now reads it, which no fan-out reaches at all — and re-checked after every
+tool call, so a hazard declared or lifted **while you are running** arrives on your next tool
+result. Two `stat` calls when nothing changed.
+
+An entry naming no evaluable expiry still applies and is reported as `unchecked`, loudly. An expiry
+that lapsed into "no longer shown" would restore permanent scripture while every signal read
+healthy.
+
+Both ledger tiers, what belongs here versus in a rule, and the surfaces with no hook runtime:
+[reference/operational-hazards.md](../reference/operational-hazards.md).

package/plugins/lisa-devin/rules/eager/report-actionability.md

@@ -0,0 +1,26 @@
+# Report Actionability — Every Report Says What the Reader Must Do (load-bearing)
+
+Reports must distinguish completed work, remaining work, and decisions the reader
+needs to make. Account for the whole reviewed scope and clearly label any subset.
+
+## Mandatory
+
+1. **State the denominator first.** Any report of findings, failures, checks, or review comments opens with the total — "6 findings: 3 fixed, 2 open, 1 needs your decision". A reader must never have to ask how many there were.
+2. **Account for every item.** Each one gets an explicit disposition. Nothing is omitted because it is minor, because it was fixed, or because it is embarrassing. An item you have not yet read is itself a disposition — say **"not read yet"** rather than leaving it out.
+3. **Label each item with who acts.** Exactly one of:
+   - **DONE** — handled; no action from the reader. Say so in the same breath as describing it.
+   - **OPEN** — needs work; state whether you are about to do it or waiting.
+   - **DECISION** — blocked on the reader; state the question and the options.
+4. **Never describe a fixed item as if it were live.** If you are reporting a defect you already fixed — which is often right, because the reader may need to know it existed — mark it fixed in the *first* sentence, not the last.
+5. **A subset must announce itself as one.** "Here are the two most serious" is fine. "Here is what the review said", when it was two of six, is not.
+6. **Lead the whole report with the action line**, per `automation-runbook-contract` — which already requires a terminating flow to open with its outcome and the operator action. This rule extends that requirement to reports that do **not** terminate a flow: a mid-run status update, a review summary, a "here is what CI said". The originating incident was one of those, which is how it slipped past a contract that only bound final messages.
+
+## Applies to
+
+Code-review findings, CI failures, test results, audit output, security scans, deploy status, and any list of problems handed to a human. It applies equally to reports you are proud of and reports that expose your own mistake — the second kind is where the temptation to describe a flattering subset is strongest.
+
+## Agent attribution
+
+Follow `lisa-tracker-sync` — **Agent attribution** for agent-composed tracker comments and review messages. The short convention lives in that portable skill so agents without a rules surface receive it too.
+
+Detail, worked examples and the failure taxonomy: [reference/report-actionability.md](../reference/report-actionability.md).

package/plugins/lisa-devin/rules/eager/security-audit-handling.md

@@ -0,0 +1,40 @@
+# Security Audit Handling (load-bearing)
+
+If `git push` fails because the pre-push hook reports security vulnerabilities, work the decision ladder below **autonomously**. Do not stop to ask the user except at the one rung that explicitly requires it. **Never use `--no-verify`**, `HUSKY=0`, `core.hooksPath`, or any other hook bypass to skip the security audit.
+
+## Decision ladder (do not skip rungs)
+
+For each high/critical advisory the gate reports, take the **first** action that is possible:
+
+1. **Update the offending package.** Upgrade the actually-vulnerable leaf package to a patched compatible version, regenerate the lockfile, retry the gate. Done.
+2. **If an upgrade isn't possible** (no compatible patched version on the dependency graph): **force a resolution/override** on the vulnerable leaf package (both `resolutions` and `overrides`), regenerate the lockfile, retry. Done.
+3. **If an override isn't possible either** (would break a dependent, or no fixed version exists anywhere): **evaluate whether the advisory actually affects this project** — is the vulnerable code path reachable, does it process untrusted input, is it runtime vs. dev/build-only?
+4. **If it does affect the project** and neither (1) nor (2) was possible: **ask a human** what to do. This is the only rung that pauses for a person.
+5. **If it does not affect the project**: **add a documented exclusion yourself** to `audit.ignore.local.json` (`{"id", "package", "reason"}` — reason states the impact evaluation), commit, retry. No human approval needed.
+
+Steps 1, 2, 3, and 5 are autonomous. Only step 4 escalates.
+
+## Core override rule
+
+Override the actually-vulnerable **leaf package**, not its parent. The audit chain shows `parent › intermediate › vulnerable` — only the vulnerable leaf needs the override.
+
+**Never override a parent package to force a lower major version.** Other packages may depend on the newer major; a forced downgrade breaks them.
+
+Before adding any override (step 2), verify:
+- You are targeting the actually-vulnerable package, not a parent in the chain.
+- The override is compatible with all dependents (check via `bun why <pkg>` or `npm ls <pkg>`).
+- The override does not downgrade across a major version boundary other deps require.
+
+If those checks fail, the override is "not possible" — drop to step 3.
+
+## Never
+
+- Never add a blanket audit bypass or lower the configured audit level.
+- Never escalate to a human (step 4) before genuinely attempting steps 1–3.
+- Never add an ignore entry (step 5) without an impact evaluation recorded in its `reason`. (This is a policy requirement enforced by convention. The `reason` field is not programmatically validated by Lisa tooling, so its presence relies on Claude following this rule faithfully.)
+
+## Rails (bundler-audit)
+
+Same ladder. Note advisory ID, gem, URL. (1) Direct dep with patch → update Gemfile constraint, `bundle update <gem>`, retry. (2) Transitive with patch → `bundle update <gem>` to bump the lockfile only, retry. (3) No patch → evaluate impact. (4) Affects the project → ask a human. (5) Doesn't affect → document the exception, retry.
+
+Full procedure with examples: [reference/security-audit-handling.md](../reference/security-audit-handling.md).

package/plugins/lisa-devin/rules/eager/session-status-updates.md

@@ -0,0 +1,20 @@
+# Session Status Updates — Plain Language, and Always Say If It's Safe to Close (load-bearing)
+
+Every update you give a human answers three things: **what changed, what's blocked, and what needs a decision.** Not how you found it, not what you searched, not the story of your reasoning. They will ask for detail if they want it.
+
+Assume the reader is **non-technical** — the same obligation Lisa already places on everything crossing a gate outward (intake rejections, ticket descriptions, verification reports). Session chat is held to that bar, so factory output and conversation sound alike.
+
+## Mandatory
+
+- **Plain, conversational language.** No jargon, no Lisa vocabulary, no tool or file names the reader has no use for. Say "the login page broke", not "the auth guard regressed at the controller boundary".
+- **Write every response in ASD-STE100 Simplified Technical English.** All responses, not only status updates. One idea per sentence, active voice, present tense, sentences under 20 words, approved vocabulary — "start" not "initiate", "use" not "utilize". The proper name of a real thing (a command, a file, an error) is always permitted.
+- **A decision is presented as a decision** — never buried in a status paragraph the reader has to mine. State the choice, give **your recommendation**, and name the **ramifications** of each option in one line apiece.
+- **End every update with a close line**, exactly this shape:
+
+  `Safe to close: yes/no — <reason>`
+
+  `no` names the in-flight thing that would be lost: a local process still running, a ticket not yet flipped to ready, an unpushed commit, a PR nobody is watching. A human must be able to glance at your last message and know whether killing the session costs them work.
+
+This is the *voice* rule. `report-actionability` governs what a report must account for, and `automation-runbook-contract` governs the outcome line a terminating flow opens with; neither is relaxed here.
+
+Full prose: [reference/session-status-updates.md](../reference/session-status-updates.md).

package/plugins/lisa-devin/rules/eager/settled-decisions.md

@@ -0,0 +1,75 @@
+# Settled Decisions (load-bearing)
+
+**Never ask the operator a question that a standing preference or your own gathered evidence has
+already answered.** Re-asking a settled decision is not caution — it hands back a choice the
+operator already made and makes them make it twice.
+
+## The test
+
+Before asking anything, check the three sources that may already hold the answer:
+
+1. **A standing preference** — something the operator has told you once and expects to hold:
+   recorded in project memory, `.lisa.config.json`, a project rule, `CLAUDE.md`/`AGENTS.md`, or
+   stated earlier in this conversation. "Every PR gets auto-merge and gets watched to merge" is a
+   standing preference; asking "want me to watch this PR?" violates it.
+2. **Evidence you already gathered** — if the research, measurement or code read you just performed
+   resolves the question, the question is answered. Report the decision and the evidence for it.
+3. **A convention with an obvious default** — where one option is clearly conventional and the other
+   needs a reason, take the conventional one and say so in one line.
+
+If any source answers it: **act, and state the decision in a clause.** Do not convert it into a
+question.
+
+## When asking IS right
+
+Ask when the answer would change the work *and* you genuinely cannot derive it:
+
+- The options lead to materially different deliverables and nothing in scope decides between them.
+- Proceeding on a wrong assumption would be unsafe, destructive, or waste substantial work.
+- The answer is a human judgement the artifacts do not contain — a product decision, a design
+  vocabulary that does not exist yet, a risk the operator owns.
+
+That kind of question is load-bearing and should be asked plainly, once, with a recommendation.
+
+## The failure mode this rule exists to stop
+
+Asking feels collaborative, so it gets over-applied — especially at the end of a report, where a
+trailing question reads as deference. It is not deference when the answer was already given; it is
+work handed back. Two specific tells:
+
+- **Half-applying an instruction.** Doing the first half of a standing preference automatically and
+  asking permission for the second half of the same preference.
+- **Asking after the research answered it.** Completing an investigation that points one direction
+  unambiguously, then presenting the conclusion as an open question.
+
+## Partial application is worse than either extreme
+
+If a standing preference covers a multi-step behavior, apply **all** of it. Applying part and asking
+about the rest produces the worst outcome: the operator is interrupted *and* the instruction was not
+honored.
+
+## Recording, not asking
+
+When you take a settled decision, make it auditable in one clause — "auto-merge on, per your standing
+preference", "scoped app-wide, because the Android finding decides it". That gives the operator the
+chance to correct it without requiring them to answer first.
+
+## Before you escalate, re-read the instruction file from disk
+
+**This rule is delivered at session start; the re-read it demands happens at the escalation
+boundary.** Re-reading at session start would re-read the same moment your context was built from
+and buys nothing.
+
+So before you form an escalation, hand a decision back, or re-open a question that may already be
+settled: **open `AGENTS.md` (or `CLAUDE.md`) from disk and read its `## Standing rulings` section.**
+If the file has no such heading, re-read the file.
+
+The instruction is to open the file — not to "check whether your context looks complete", because
+**context completeness is not observable from inside.** An instruction file is injected at session
+start and can arrive shortened, and the cut can land on a clean section boundary, where a truncated
+document is indistinguishable from one that never had that section: your copy ends tidily, so you
+conclude you read all of it. Rulings are also written *after* sessions begin — your copy is a
+snapshot of the moment you started, and nothing tells you when it stops being current.
+
+This is a **pointer, not a copy**. It stays correct as rulings accumulate, and it survives a
+shortened copy of the file it points at precisely because it does not travel inside that file.

package/plugins/lisa-devin/rules/eager/stale-state-claims.md

@@ -0,0 +1,26 @@
+# Stale State Claims — "Not Yet" Expires, the Note Does Not (load-bearing)
+
+A comment, docstring, config annotation, or work-item note that records a **temporary** state — "not yet", "pending", "waiting on X", "human-gated", "will flip once Y ships" — was accurate the day it was written and is believed long after it stopped being true. Nobody revisits prose when the condition clears.
+
+It then misdirects with full authority: work gets skipped as blocked when nothing blocks it, re-planned as undone when it already shipped, or escalated to a person who made that exact decision weeks ago.
+
+This is the sibling of `falsifiable-checks`. That rule is about **instruments that cannot fail**; this one is about **assertions of state that have expired**. Both read as authoritative and neither announces its own decay.
+
+## The four ways a recorded state outlives its truth
+
+Each has been observed; each was believed long after it went false:
+
+1. **Expired blocker note** — prose asserting a not-yet condition that has since cleared. An endpoint left unset under a comment saying its routing was "not yet promoted" had been serving live for days; an agent planned work to enable what was already enabled.
+2. **Stale gate marker** — a "pending human approval / not provisioned yet" annotation whose precondition is satisfied. One held for twelve days after the thing it waited on existed, and the decision was escalated to a person surprised to be asked.
+3. **Prediction buried by closure** — a warning recorded in a comment on an item that then closes. Closure deletes the warning: one correctly predicted a defect, the item closed 25 minutes later, and the defect sat unnoticed for eight days while a dependent item was parked waiting on it.
+4. **Silent waiting gate** — a queue or approval state with no surfacing mechanism, which holds work for exactly as long as nobody happens to look. One held a security-relevant fix undeployed for two days.
+
+## Mandatory
+
+- **A recorded blocker is a claim about the past — check the present before acting on it.** Before planning around it, escalating it, or reporting it as a blocker, probe the live state (`empirical-inquiry`). One command is cheap; inheriting a false premise is not.
+- **Whoever clears the condition deletes the claim.** Removing the block is not done until the note describing it is gone. A cleared gate whose comment survives is the next reader's false premise, and you are the last person who knows it is false.
+- **Prefer expiry-resistant forms.** State what **is** true rather than what is pending. Where a temporal claim is unavoidable, anchor it to something that fails when it goes stale — a check, a linked work item — never to prose nobody re-reads.
+- **A prediction on a closing item becomes tracked work or is retracted.** If the warning is real it is a work item with an explicit blocking link (`tracked-work`); if it is not real, retract it. Prose on a closed item is neither, and the one-way lifecycle means only `claim-archaeology` can recover it.
+- **A gate that can hold work silently is a defect in the gate.** Any waiting state needs a surfacing mechanism — notification, dashboard, scheduled sweep. Fix the gate; do not resolve to look more often.
+
+Full prose, worked examples, and the rewrite patterns: [reference/stale-state-claims.md](../reference/stale-state-claims.md).

package/plugins/lisa-devin/rules/eager/tool-access-gate.md

@@ -0,0 +1,23 @@
+# Tool Access Gate (load-bearing)
+
+- If you can't reach something you need, such as a repository, a secret, an API, or a connector, say exactly what's missing in your first message and stop. Don't substitute, mock, or guess.
+
+If the missing access is discovered after work begins, say exactly what's
+missing in your next message and stop.
+
+Only take on work you can finish. Before implementation starts — and again the
+moment a new requirement surfaces mid-flow — enumerate every external tool the
+work item needs (implementation, proof command, remote verification: AWS CLI,
+Figma, Jam, Sentry, SonarCloud, PostHog, device/browser harnesses, databases,
+deploy targets, …) and **prove access with a cheap read-only probe**, routing
+through the matching `*-access` skill where one exists. Resolve credentials through the documented access path before probing;
+presence on PATH is not access. If that path or the probe cannot provide the
+required access, report the gap and stop.
+
+The message must name the missing resource, the operation it blocks, and any
+known access requirement, without exposing secret values. Substituting weaker
+verification, mocking the inaccessible system, guessing at its contents, or
+narrowing scope to dodge the gap are all forbidden.
+
+Full contract (probe table, blocker report, resume path):
+[reference/tool-access-gate.md](../reference/tool-access-gate.md).

package/plugins/lisa-devin/rules/eager/tracked-work.md

@@ -0,0 +1,9 @@
+# Tracked Work
+
+Apply `do-it-now` before creating work from incidental findings. Declining an observation needs no new ticket. Related small accepted repairs may share one bounded maintenance leaf; traceability does not require a separate item for every nit.
+
+Before the first durable project mutation (code, tests, config, docs, committed research/plans/findings, commits, or PRs), establish exactly one live tracker leaf through `lisa-track`. Read-only discussion and orientation are exempt only while they produce no durable artifact.
+
+The mandatory order is: live-validate an explicit ref, or conservatively search and create exactly one valid leaf through `lisa-tracker-write` when no unique match exists; idempotently claim it through `lisa-tracker-claim`; then persist and verify the worktree-local binding with `node scripts/lisa-work-item.mjs link <ref>`. A tracker that answers no, and any claim or binding failure, blocks durable work; a tracker that cannot be reached does not block a commit — the offline checks still run, the skip is loud on stderr, and the required `Work-Item Traceability` check re-runs the live checks with credentials before anything merges.
+
+Carry that canonical ref through the branch, every ordinary commit's `Work-Item:` trailer, the PR, usage/evidence, and `lisa-tracker-sync`. Hooks and CI never create tickets. Anything that READS a `Work-Item:` trailer — a gate, an audit, a count, a report — must import `workItemLines` from the shipped `scripts/lisa-work-item.mjs` rather than reach for `git interpret-trailers` or `%(trailers)`, which see only a message's final block and miss 92% of this fleet's trailers; read the `work-item-trailer-definition` rule before writing such a reader. Keep the binding through interruptions or blocked outcomes; run `node scripts/lisa-work-item.mjs clear` only after merge/deploy/verification, two-way linkage/evidence, and the tracker item have all reached true terminal completion.

package/plugins/lisa-devin/rules/eager/upstream-to-lisa.md

@@ -0,0 +1,14 @@
+# Upstream To Lisa (load-bearing)
+
+When a worthwhile fix belongs to a Lisa-distributed template, rule, skill, agent, hook, or CI workflow, fix its source upstream so other projects benefit. Apply `do-it-now`'s **Worth doing** guidance first: Lisa ownership determines where accepted work belongs, not whether every imperfection deserves a ticket.
+
+For an accepted defect:
+
+1. Apply the smallest safe local stopgap if needed to unblock the current task.
+2. Search open and closed Lisa issues. Reuse a matching open issue. Honor **Not planned** decisions under `rejection-detection` before filing the concrete consequence and smallest durable fix; do not refile an accepted limitation.
+
+For **copy-overwrite** files, a local fix may be overwritten on the next `lisa apply`. For **create-only** templates, the local fix survives, but new projects still inherit the source defect. Both can justify an upstream fix; neither bypasses the value decision.
+
+Decline low-value observations without filing or escalating them. Group related small worthwhile repairs when appropriate. Do not add permanent machinery merely because an enforcement gap can be described.
+
+Inside Lisa, repair the shared source and regenerate the equivalent agent surfaces. Full procedure: [reference/upstream-to-lisa.md](../reference/upstream-to-lisa.md).

package/plugins/lisa-devin/rules/eager/verification.md

@@ -0,0 +1,33 @@
+# Empirical Verification (load-bearing)
+
+**Verification is not linting, typechecking, or testing.** Those are *quality checks* — necessary prerequisites, but NOT verification.
+
+**Verification is using the resulting software the way a user would** — interacting with the UI, calling the API, running the CLI, observing behavior. Tests pass in isolation; verification proves the system works as a whole.
+
+**Verification IS UAT** (User Acceptance Testing) — the same single gate, not two concepts. "Use the software as a user, against the acceptance criteria" *is* UAT. Everything below makes that one process concrete: a committed evidence artifact, a codified check that re-runs in CI, and a per-change requirement.
+
+## Mandatory
+
+- **Never claim success without runtime evidence.** "The code looks correct" is not evidence.
+- **If all you did was run tests, typecheck, and lint — you have NOT verified.**
+- **A check that cannot fail is not evidence either.** Every gate, probe, sweep, and codified spec you author is subject to the `falsifiable-checks` rule: break the guarded property, observe the check fail and name the location, then restore — and report that falsification with the result. "Mentally reverting" does not count, and an unfalsified gate is reported as *unvalidated*, never as passing.
+- **Browser-controller neutrality.** For UI work, control a live browser and perform the Validation Journey as a human would. An in-app Browser/Chrome tool, interactive Playwright control (MCP, API, or ad hoc script), CDP, computer use, the optional Lisa-owned Kane adapter, or an equivalent controller is acceptable. Kane requires explicit upload approval, a passing `lisa kane probe`, an allow-listed non-production environment, and mutation policy `full`; its provider failure is not a product failure. Do not block merely because one preferred backend is unavailable when another interactive controller can drive the browser. Running an automated Playwright or Maestro test alone is still a quality gate, not the initial empirical evidence; after the live journey passes, codify it in the applicable native runner(s). Kane never replaces those regression gates.
+- **Before starting implementation, state your verification plan** — how you will USE the resulting software to prove it works. A plan that only lists `test`/`typecheck`/`lint` commands is not a plan. Do not begin until confirmed.
+- **After verifying empirically, codify it as a regression test** via the `codify-verification` skill — Playwright for UI, integration test for API/DB/auth, benchmark for performance. Codification is mandatory for every verification type except PR/Documentation/Deploy and Investigate-Only spikes. For **frontend work**, codification is multi-runner and governed by the `bdd-e2e-coverage` rule: the verified journey is encoded in the project's configured runner for **every** platform the behavior's scenario requires — one runner is never a substitute for another, because they guard different platforms of the same behavior. Cite that rule; do not restate its obligations or name a runner as though the contract mandated one.
+- **The codified proof re-runs in CI.** Codified runtime verification lives wherever the project's own configured e2e runner(s) already look for tests — its own config and conventions, never a Lisa-assumed path or tool — and runs as a required CI check for types with verification enforced, so the proof re-runs on every PR, not once by hand. For **frontend work** specifically, where that runner lives and how many runners are required is governed by the `bdd-e2e-coverage` rule, not this bullet.
+- **Commit the evidence.** Write a durable artifact to `evidence/<ticket>/` — the acceptance criteria with per-criterion pass/fail + note, the observed state, screenshots/recording, and a `verdict.json`. The transient `.lisa/verification-status.json` is the session gate; `evidence/<ticket>/` is the committed proof.
+- **Evidence markers are typed artifacts, not assertion labels.** A Validation Journey marker is `[EVIDENCE: <artifact-type>: <name>]` where the type (screenshot, recording, http-transcript, cli-output, log-snippet, db-query-output, perf-trace, test-run-log, deploy-log, state-dump) says HOW the proof is captured and the name says WHAT it proves. `[EVIDENCE: works-gracefully]` is a claim, not evidence — write `[EVIDENCE: screenshot: load-failure-error-state]`. Completion requires a captured artifact **of the declared type** per marker. To cite another work item's artifact without claiming it, write `[EVIDENCE-REF: <work-item-ref> | <artifact-type>: <kebab-case-name>]`. The Lisa 2.223.0 colon form `[EVIDENCE-REF: <tracker-ref>: <artifact-type>: <kebab-case-name>]` remains accepted as a legacy non-claiming alias but must not be newly authored. A reference never enters or satisfies the local S14 manifest; malformed references fail S14, and agents must not quote sibling `[EVIDENCE: ...]` markers directly.
+- **Per-change verification is mandatory.** Every `feat`/`fix` adds or extends a verification (e2e) spec mapped to its acceptance criteria. The only exception is a genuinely non-behavioral change explicitly marked with the **logged** `verification-exempt` label — never a silent skip.
+- **Frontend work also seals its behavior contract.** Per the `bdd-e2e-coverage` rule, a work item that adds or changes a user-observable surface is not done until its behavior exists as Gherkin scenarios with stable IDs, every required scenario-platform obligation is mapped to aligned e2e automation (or carries a dated waiver), and the coverage gate passes with the matrix regenerated. Missing BDD coverage is a verification failure, not a warning.
+- **Drive the playthrough with `/lisa:product-walkthrough`** (it walks the live product through a real browser); each project type plugs in its own drive mechanism (e.g. a Phaser game is driven through Playwright + an in-game verification test bridge that seeds RNG, reads state, injects input, and steps frames).
+- **Every PR must include reviewer replay steps** — the exact human steps to use the software and confirm the change works. Not test commands. If a reviewer can't reproduce from the PR description alone, the PR is incomplete.
+- **Exhaust credential sources before deferring runtime verification** — check project e2e / Playwright config and fixtures first, then `.lisa.config.local.json` / environment variables, then documented ticket credentials such as `Sign-in Required`.
+- **Never mark required runtime verification done on artifact-only evidence** — if credentials are genuinely unavailable after all sources are checked, post the blocker, transition the item to the configured blocked state, apply the configured `needs-human` / `human-review` label, and label the evidence as `artifact-only / verification deferred`.
+
+## Roles
+
+- **Builder agent** — implements the change.
+- **Verifier agent** — acts as the end user / API client / operator. Independent from Builder when possible.
+- **Human overseer** — approves risky operations and anything agents cannot fully verify.
+
+Full operational contract (verification types, evidence formats, escalation protocol): [reference/verification.md](../reference/verification.md).

package/plugins/lisa-devin/rules/eager/wiki-knowledge-source.md

@@ -0,0 +1,13 @@
+# Wiki as Knowledge Source — Query It on Demand (load-bearing)
+
+If the project has an LLM Wiki, it is the curated store of durable project knowledge: background, conventions, ownership, architecture, glossary, "how and why does X work here". Documentation rolls UP into that wiki; individual repos are not expected to carry their own prose docs beyond inline code comments.
+
+**Do not load the wiki at session start.** It is deep knowledge, and paying for it on every session is exactly the cost the on-demand rungs of the `learnings-ladder` exist to avoid. Know it is there; go get it when you actually need depth.
+
+When you do need it, call `/lisa-wiki-query`. You never have to fetch or freshness-check the wiki yourself — the query and ingest skills resolve the wiki root and guarantee it is current (`scripts/ensure-wiki.mjs`) as their own first step: a local wiki resolves instantly, a remote wiki is mirrored and refreshed transparently. Prefer what the wiki says over re-deriving it from raw sources, and fall back to code, tickets, and history when it is silent, ambiguous, or contradicted by what you observe.
+
+If the wiki is wrong, stale, or missing knowledge that belongs there, capture the correction via `/lisa-wiki-ingest` rather than leaving it in this session. The wiki documents knowledge; it does NOT override executable behavior — when wiki and running code disagree about what the system does, trust the code.
+
+**Applicability.** This rule applies only when the `lisa-wiki` plugin is installed, which is gated on `wiki/lisa-wiki.config.json` existing or `.lisa.config.json` declaring a `wiki` key. Without that, the query skill is not present and this rule does not apply — run `/lisa-wiki-install` (shipped in base) to enable the wiki. Never treat the absent skill as a blocker.
+
+Full prose: [reference/wiki-knowledge-source.md](../reference/wiki-knowledge-source.md).