@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-devin/rules/reference/reset-seed-coverage.md

@@ -0,0 +1,286 @@
+# Reset/Seed Coverage & State Classification
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## Reset/Seed Coverage & State Classification (load-bearing)
+
+**Every persistent entity a project owns carries exactly one declared reset policy, and a work item that adds or changes persistent state is not done until the reset/seed contract covers it.** An entity the running system holds but the contract does not classify is a contract violation, and the check that finds it **fails closed** — an unclassified entity is never treated as safe to keep and never treated as safe to delete.
+
+**One vendor-neutral contract, cited by** `lisa-research`, `lisa-acceptance-criteria`, `lisa-task-decomposition`, `lisa-test-strategy`, `lisa-implement`, `lisa-codify-verification`, `lisa-verification-lifecycle`, and `lisa-verify` (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never divergent per-skill prose). It never names a database engine, cloud, identity provider, or test runner — those are project configuration.
+
+## Why this exists
+
+Test suites create state. Without a contract, cleanup is a habit: a flow creates a uniquely-marked record and deletes it on the happy path only, so every early failure leaks one more. Nothing sweeps it, nothing complains, and the suite degrades until someone reads a flake as a product bug. The observed shape is always the same — leaked records accumulate silently until a list view, a uniqueness constraint, or a count assertion breaks. Per-flow self-cleanup is not coverage; it is the failure mode.
+
+## Membership
+
+Membership is **state, not repo name, ticket label, or storage engine**: an entity is in scope the moment something the project writes **outlives the process that wrote it**. That includes rows and tables, but rows are only one kind of state. Also in scope: identity-provider objects (accounts, groups, memberships, sessions), object storage (buckets, prefixes, uploaded files), search indexes, queues and topics (in-flight and dead-letter), caches with a persistence tier, materialized/derived views and projections, feature-flag and configuration overrides, scheduled jobs created at runtime, and analytics or third-party side effects a run leaves behind. Out of scope: values that live only in memory for the duration of one process.
+
+A work item is in scope when it **adds** such an entity, **changes what owns or writes** one, or **changes the lifetime** of one. Renames count as changes, not as new entities plus deletions.
+
+## The four policies
+
+Every entity is classified as exactly one of:
+
+- **`fixture-owned`** — the reset may create, mutate, and delete rows here, but only those it owns. Ownership is declared as a predicate (a reserved id shape, a reserved account or namespace, a marker attribute), never as "everything in this entity."
+- **`preserve`** — the reset must leave this untouched. Catalog, reference data, anything a migration seeds, anything expensive or impossible to rebuild, and any state belonging to someone who is not the fixture.
+- **`derived-rebuild`** — not authored by anyone; recomputed from its sources after the reset (projections, materialized views, search indexes, caches). The reset rebuilds it rather than clearing or preserving it, and proves it converged.
+- **`forbidden`** — the reset must be structurally unable to touch it: ledgers, payments, wallets, withdrawals, audit trails, anything irreversible. Declaring `forbidden` obliges naming the enforcement outside the script — a least-privilege role, a revoked grant, a separate account or credential boundary — because a script-only promise dies in the refactor that drops the safe caller.
+
+**Classify by provenance, never by observation.** "The table looked empty" is not evidence it is unused; runtime statistics are approximations, and a table that has never been analyzed reports rows it holds. Ask who writes it and whether anything can put it back.
+
+## Keep-lists are a detector, not the safety model
+
+Deriving the clear-list by subtracting a keep-list from a schema listing is a **useful detector** — run it, and let it flag entities the contract has not seen. It is not the boundary. It cannot model renames, multiple schemas, framework-generated entities, views, partitions, row-level ownership, or any of the non-DB state above, and "new entities are cleared unless exempted" erases unrelated data the first time something adds one. The boundary is the classification; subtraction only tells you the classification is stale.
+
+## Required assurances
+
+A reset contract is not complete until it declares, and points at evidence for, all of: non-fixture and catalog data survive; reserved fixture identifiers are rejected on collision with anything real; foreign references into preserved entities are refused rather than cascaded; every write is **acknowledged** (a mutation reported by the caller and not confirmed by the system is a failure, not a success); a second apply converges to the same state and reports no further change; the post-state is verified by **exact expected counts**, not "at least one"; and production fails closed with no override of any kind. Where the platform can enforce a boundary with roles, grants, or constraints, it does — the in-process guard remains as defense in depth, never as the primary control.
+
+## Definition of done
+
+A work item that adds or changes persistent state is not done until: (1) every entity it introduces or changes is classified in the project's state contract with a reason and an owner; (2) `fixture-owned` entities it introduces declare their ownership predicate **and** are actually swept by the reset — an entity a suite creates but nothing removes is the leak this rule exists to prevent; (3) `preserve`/`forbidden` entities it introduces name their enforcement; (4) any seed the suite depends on covers the new state, with the verify step asserting exact counts; and (5) the state-classification check passes in the same PR. **A missing or stale classification is a verification failure, not a warning** — it blocks completion exactly as a `PARTIAL` spec-conformance verdict does, and is never demoted to "optional", "if cheap", or a follow-up without a linked build-ready ticket created before merge.
+
+## Bootstrap, noop, and degradation
+
+A project with no state contract yet is not exempt: the first work item touching persistent state scaffolds the minimum (the contract file, its own entities classified, the check wired into CI) and covers **its own** state. It never backfills the whole system — pre-existing unclassified entities are recorded as burndown with an owner and a date, not treated as this item's blocker. A project that genuinely holds no persistent state declares a **machine-readable noop** (`mode: "declared-noop"` with reason, owner, and a capability-manifest reference) which the check verifies against the repo rather than taking on faith — a bare exit 0 is indistinguishable from a successful destructive run and never satisfies this rule. A project that cannot produce a runtime inventory records the checked sources and the absence, exactly as the regression-spec absence path in `verification` does; a silent skip is never one of the exits.
+
+## Command envelope
+
+Every reset, seed, verify, inventory, and classification adapter answers the **same interface** — one validated JSON result on stdout, exit 0 only when the operation both completed **and** verified, `--dry-run` mandatory before anything destructive, and a requested stage always re-checked against server-resolved identity rather than trusted. The envelope is specified in the reference body and is what makes "every repo answers the same question the same way" checkable instead of aspirational.
+
+**The production arm of this is executable, not advisory.** `scripts/lisa-destructive-guard.mjs` ships to every adopter and is wired into the envelope itself: a destructive run against a production-resolved — or unresolvable — environment has **no representable success envelope**, so it can never exit 0, and there is no parameter, field, or environment variable anywhere in the guard that changes the answer. A dry run is not an exemption, and `--dry-run` is the default rather than an opt-in. Read this as what it is: a check at the one interface every adapter passes through, which an adapter that misreports its own environment still defeats. The end state is a destructive capability that is **not deployed to production at all** — non-existence beats refusal — and that design, with the failure modes it must still close, is recorded in `docs/design/reset-production-absence.md`.
+
+---
+
+Automated suites create state, and the state outlives them. The historical pattern is per-flow
+self-cleanup: a flow creates a uniquely-marked record at the top and deletes it as its last step, so
+the record survives every failure that happens in between. Nothing sweeps the survivors and nothing
+reports them, so the leak is invisible until a list view, a uniqueness constraint, a pagination
+boundary, or an exact-count assertion breaks — at which point it presents as a product bug or an
+unreproducible flake. The same story has now played out on several entity types in several
+codebases, always with the same three ingredients: state a suite creates, cleanup that only runs on
+the happy path, and no inventory that would have noticed.
+
+This contract removes the discipline requirement. Instead of asking every author to remember to
+sweep what they created, it makes the *absence* of a decision a failing check.
+
+It is a **single vendor-neutral contract** consumed by `lisa-research` (specs state what persistent
+state the work introduces), `lisa-acceptance-criteria` and `lisa-task-decomposition` (the
+classification and the sweep are explicit deliverables on the work item, not implied work),
+`lisa-test-strategy` and `lisa-implement` (building the item includes both),
+`lisa-codify-verification` (the verify step asserts the post-reset baseline), and
+`lisa-verification-lifecycle` / `lisa-verify` (the check is run, and a miss fails the item). Those
+skills cite this slug; they do not restate it.
+
+## Vendor neutrality is the point
+
+This contract never names a database engine, a cloud, an identity provider, an object store, a
+search engine, a queue, or a test runner. Projects use different ones, several at once, and change
+them without touching this contract. What is fixed is the *obligation*: every entity that holds
+state across process boundaries carries exactly one policy, and the running system's inventory is
+compared against that declaration.
+
+The words "table" and "row" appear in this document only as examples. An entity is anything with a
+durable identity and a lifetime: a table, a collection, a bucket prefix, an index, a topic, a
+user-pool group, a materialized view, a scheduled job.
+
+## Why "new entities are cleared by default" is the wrong safety model
+
+An earlier version of this pattern derived the clear-list by subtracting a hand-maintained keep-list
+from a schema listing: anything new is cleared unless someone deliberately exempts it. It is
+attractive because it fails toward action, and the failure it prevents (a new entity silently
+accumulating) is real. It is still wrong as the *boundary*, for reasons that are structural rather
+than stylistic:
+
+- **It erases unrelated data on first contact.** The first change that adds an entity nobody has
+  classified deletes its contents on the next run, in whatever non-production environment happened
+  to run first. "Non-production" is not "worthless" — shared development environments hold hand-built
+  scenarios, support reproductions, and partner sandboxes.
+- **A migrations-directory diff does not model reality.** It cannot see renames (which read as one
+  deletion plus one unclassified addition), multiple schemas or namespaces, framework- or
+  ORM-generated entities that no migration file names, views, partitions and inheritance children,
+  entities created by a deploy rather than a migration, or row-level ownership — the common case
+  where an entity holds both fixture rows and rows that must survive.
+- **It only sees the database.** Identity-provider accounts, object-storage prefixes, search indexes,
+  queue backlogs, and third-party side effects are invisible to it, and those are precisely where
+  leaked test state is most expensive.
+
+Subtraction survives in this contract as a **detector**: run it, and treat every entity it finds
+that the contract has not classified as a finding. The safety decision is the classification.
+
+## The state contract
+
+Default location `state/state-contract.json` (a project with an equivalent artifact keeps its own
+path and records it in `.lisa.config.json`). It is checked in, reviewed like code, and versioned:
+
+| Field | Meaning |
+|---|---|
+| `schemaVersion` | The schema this document conforms to. Pinned; a bump is a deliberate migration. |
+| `contractVersion` | The project's own version for *its* declared state. Bumped whenever policies or ownership predicates change, so evidence from one run cannot be read as evidence for a different contract. |
+| `mode` | `contract` (the normal case) or `declared-noop`. |
+| `owner` | Who answers questions about this file. A team or role, not an individual's personal account. |
+| `environments` | The environments a reset may target, and the identity source each is resolved from. Never a list the caller can extend at runtime. |
+| `fixtureIdentity` | How fixture-owned records are recognized: reserved id shape, reserved account/namespace, marker attribute. This is the ownership predicate the whole model rests on. |
+| `entities[]` | One entry per persistent entity. |
+| `assurances` | The required properties below, each with a pointer to the evidence that proves it. |
+| `waivers[]` | Dated IOUs for entities that genuinely cannot be classified yet. |
+
+Each `entities[]` entry carries `id` (stable, fully qualified — namespace plus name), `kind` (the
+project's own vocabulary for what sort of state it is), `policy` (one of the four), `reason` (why,
+in one sentence a reviewer can check), `owner`, and policy-specific obligations:
+
+- `fixture-owned` → `ownership` (the predicate identifying rows/objects the reset may delete) and
+  `sweptBy` (the routine that removes them). An entity classified `fixture-owned` with no sweep is
+  the exact leak this rule exists to catch and fails the check.
+- `preserve` → `reason` must name the provenance (migration-seeded, ingested catalog, human-authored,
+  belongs to a real person) and, where available, `enforcedBy`.
+- `derived-rebuild` → `rebuiltFrom` (the sources) and `rebuiltBy` (the routine). The reset rebuilds
+  and proves convergence rather than clearing.
+- `forbidden` → `enforcedBy` is **required** and must name a control outside the reset process: a
+  least-privilege role, a revoked grant, a separate credential or account boundary, a database
+  constraint. "The script does not touch it" is not an enforcement.
+
+### Waivers are dated IOUs, never classifications
+
+An entity nobody can classify today is recorded with its id, a reason, an owner, a ticket, and a
+`recordedAt` date. It stays visible in the report, it never counts as classified, and it never
+authorizes the reset to touch the entity — a waived entity is treated as `preserve` for safety while
+remaining a finding. A waiver is invalid, and fails the check, when it names an entity that is not in
+the inventory, duplicates an existing classification, or carries no owner, ticket, or date.
+
+## The check
+
+The check compares a **runtime inventory** — what the system actually holds, enumerated from the
+running environment — against the contract. Static sources are inputs to discovery, never a
+substitute for the inventory: the whole point is to catch what the repository does not describe.
+
+Semantics, in order:
+
+1. **Contract absent** → `not-adopted`. Reported visibly, exits 0, and the context is not required.
+   Adoption is an explicit act; a not-yet-adopted repo is not silently passing a gate it never wired.
+2. **Contract malformed, unparseable, or failing schema validation** → fail. A broken contract is
+   never treated as an empty one.
+3. **`mode: "declared-noop"`** → the noop must carry a reason, an owner, and a capability-manifest
+   reference, **and** the detectors must find no persistence signals in the repository. A repo with
+   persistence cannot declare a reset noop; the check rejects it rather than trusting the
+   declaration.
+4. **Entity in the inventory with no classification and no waiver** → **fail closed**, naming the
+   entity. This is the primary failure this contract exists to produce.
+5. **Entity classified but absent from the inventory** → fail as stale, unless the entry is marked
+   retired with a date. A contract that describes a system that no longer exists is not protection.
+6. **Policy obligations unmet** — `fixture-owned` with no ownership predicate or no sweep,
+   `forbidden` with no external enforcement, `derived-rebuild` with no rebuild routine → fail.
+7. **A required assurance missing or unevidenced** → fail.
+8. **Detector findings that the inventory did not surface** (a schema or migration source naming an
+   entity the inventory did not return) → fail, because it means the inventory is incomplete and
+   every other conclusion is unsound.
+9. **No inventory available** → `detection-only`. The detectors run, findings are reported, and the
+   result is explicitly labeled non-authoritative. It never reports the same status as a verified
+   run, and it never satisfies the definition of done on its own.
+
+Every exit path emits the standard command envelope, so a caller can tell "verified clean" from
+"could not look" without parsing prose.
+
+### Non-database discovery
+
+The inventory is only complete when it enumerates every kind of state the project holds. At minimum,
+discovery asks each of these and records either the enumeration or a documented absence: identity
+provider (accounts, groups, memberships, long-lived sessions and devices), object storage (buckets
+and prefixes written by the app or by tests), search indexes and their aliases, queues and topics
+including dead-letter backlogs, caches with a persistence tier, derived views and projections,
+runtime-created scheduled jobs and webhooks, feature-flag and configuration overrides, and outbound
+side effects (email, SMS, billing, analytics events, third-party records). "We checked and there is
+none" is an acceptable answer and must be written down; not asking is not.
+
+## Required assurances
+
+These are the properties a reset must have. Each is declared in `assurances` with a pointer to the
+test, guard, or role that proves it — a declaration with no evidence pointer fails the check.
+
+| Assurance | What it means | Why |
+|---|---|---|
+| `preserves-non-fixture-data` | Catalog, reference, and any non-fixture data survive a reset unchanged. | The expensive-to-rebuild data is usually the data a blunt reset destroys, and it is often not restorable by re-running any seed in the repo. |
+| `rejects-reserved-id-collision` | A reserved fixture identifier that collides with a real record aborts rather than overwriting. | The ownership predicate is the entire safety boundary; a collision means it is no longer identifying. |
+| `rejects-foreign-references` | A fixture record referencing a preserved record it does not own is refused, never cascaded. | Cascades are how a fixture-scoped delete reaches outside its scope. |
+| `requires-write-acknowledgment` | Every mutation is confirmed by the system, not assumed from a returned status. | An unacknowledged write is an unknown state, and "unknown" reported as success is how a half-applied reset becomes a mystery failure downstream. |
+| `converges-on-second-apply` | Applying twice produces the same state and the second run reports no further change. | Convergence is what makes the reset safe to re-run, and re-running is what makes partial failure recoverable. |
+| `verifies-exact-counts` | Verification asserts the exact expected count per fixture entity. | "At least one" passes against a leak. Exact counts are what detect one. |
+| `production-fails-closed` | Production is refused with no override, escape hatch, or environment variable that changes the answer. | A single variable that authorizes production mutation will eventually be set by something that is not a person. |
+| `guard-at-the-choke-point` | The environment check runs immediately before every outbound mutation, not only at startup. | A startup-only check does not survive a refactor that adds a second code path. |
+| `enumerates-before-mutating` | `--dry-run` enumerates exactly what would change and fails on anything whose ownership it cannot establish. | Unknown ownership must block, not default to delete. |
+
+Prefer platform enforcement over process enforcement wherever it exists: a role that cannot see the
+forbidden entities, grants revoked rather than merely unused, constraints that make a cross-boundary
+reference impossible, separate credentials per environment. A test proves the code behaves today; a
+revoked grant makes the behavior unavailable.
+
+## Standard command envelope
+
+Every adapter in this family — reset, seed, verify, inventory, classification check — returns **one**
+JSON object on stdout and nothing else. Human-readable narration goes to stderr, redacted of secrets
+and personal data.
+
+```json
+{
+  "schemaVersion": "lisa-command-envelope-v1",
+  "capability": "<reset|seed|reset-verify|state-inventory|state-classification|...>",
+  "mode": "<real|declared-noop|not-applicable>",
+  "operation": "<the operation performed>",
+  "environment": "<server-resolved environment identity>",
+  "contractVersion": "<the project's state-contract version>",
+  "dryRun": true,
+  "status": "<completed|no-op|denied|invalid|failed|verification-mismatch|not-adopted|detection-only>",
+  "correlationId": "<stable id joining logs, audit records, and CI output>",
+  "summary": { "deleted": 0, "created": 0, "preserved": 0 }
+}
+```
+
+Rules that make the envelope load-bearing rather than decorative:
+
+- **Exit 0 means completed *and* verified.** Any nonzero exit means denied, invalid, failed, or
+  verification-mismatch, and the envelope's `status` says which. An adapter that mutated successfully
+  but could not verify exits nonzero.
+- **`--dry-run` is mandatory for every destructive adapter**, enumerates the intended mutations, and
+  fails on any entity whose ownership it cannot establish.
+- **`--stage` (or equivalent) is a *request*, never the source of truth.** The adapter resolves the
+  environment from server-side deployment identity and fails if the request disagrees. A
+  caller-supplied stage, URL, host, or public build-time variable never authorizes a destructive
+  operation.
+- **`--idempotency-key` is required in CI**, so a retried invocation is recognized rather than
+  repeated.
+- **A noop returns `mode: "declared-noop"`** with a reason, an owner, and a capability-manifest
+  reference. A bare exit 0 with no envelope is indistinguishable from a successful destructive run
+  and is never an acceptable noop.
+- **`correlationId` appears in the envelope, the audit record, and the CI log**, so a run can be
+  reconstructed after the fact.
+- The audit record for a destructive run additionally names the actor, the CI run, the resolved
+  environment and account, the contract version, and before/after counts — and contains no secrets
+  or personal data.
+
+## Bootstrap procedure
+
+1. Enumerate the runtime inventory from a non-production environment, including the non-database
+   sources listed above. Record what could not be enumerated and why.
+2. Classify every entity. Start from provenance: who writes it, and can anything put it back? Prefer
+   `preserve` when unsure — an over-preserved entity leaks; an over-cleared one destroys.
+3. Declare `fixtureIdentity` and the ownership predicate before classifying anything as
+   `fixture-owned`.
+4. Write the assurances with pointers to the tests or roles that prove them. Missing evidence is a
+   work item, not a field to leave blank.
+5. Wire the check into CI so the next unclassified entity fails the pull request that introduces it.
+6. Record everything still unclassified as dated waivers with owners, and burn them down.
+
+The first work item does not backfill the whole system. It classifies what it touches, scaffolds the
+file, and turns the check on; everything else is burndown that stays visible.
+
+## What this contract does not do
+
+It does not decide *how* a reset is executed, where it runs, or what invokes it. It does not
+prescribe intra-run isolation. It does not replace a threat model for a destructive control plane —
+where a reset is reachable from CI, that control plane has its own security obligations (identity,
+least privilege, leases, audit) which this contract assumes rather than specifies. What it
+guarantees is narrower and load-bearing: **no persistent state exists in the system that nobody has
+decided about, and no work item adds some without saying so.**

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

@@ -0,0 +1,55 @@
+# Security Audit Handling
+
+If `git push` fails because the pre-push hook reports security vulnerabilities, work the decision ladder below **autonomously**. Only one rung pauses to ask a human. Never use `--no-verify`, `HUSKY=0`, `core.hooksPath`, or any other hook bypass to skip the security audit.
+
+## The decision ladder
+
+The remediation for any high/critical advisory is a simple, ordered decision — not a question to forward to the user. For each advisory, take the **first** action that is possible:
+
+1. **Update the offending package** to a patched version.
+2. **If that's not possible**, force a resolution/override on the vulnerable leaf package.
+3. **If that's not possible**, evaluate whether the advisory actually affects the project.
+4. **If it affects the project** (and 1 and 2 weren't possible), ask a human what to do.
+5. **If it doesn't affect the project**, add it to the ignore list yourself.
+
+Steps 1, 2, 3, and 5 are autonomous. Do not stop and ask the user except at step 4, and only after you have genuinely attempted steps 1 and 2 and performed the step-3 evaluation.
+
+## Node.js Projects (GHSA advisories)
+
+1. Note the GHSA ID(s), affected package(s), and advisory URL from the error output.
+2. Check the advisory URL to determine whether a patched version of the vulnerable package exists.
+3. **Step 1 — update:** If a patched version exists and is compatible, add a resolution/override in `package.json` to force the patched version (add to **both** `resolutions` and `overrides`), run the package manager install to regenerate the lockfile, commit, and retry the push.
+4. **Step 2 — force override:** If no straight upgrade lands the patched version but a compatible patched version exists somewhere on the graph, pin it via `resolutions` + `overrides` on the **leaf** package (see "Override the vulnerable package, not its parent" below), regenerate the lockfile, commit, and retry.
+5. **Step 3 — evaluate impact:** If neither an upgrade nor an override is possible (no fixed version exists, or every compatible pin breaks a dependent), determine whether the vulnerability actually affects this project. Consider: is the vulnerable code path reachable from this project's usage? Does it process untrusted input? Is the dependency runtime, or dev/build-only? Record the conclusion.
+6. **Step 4 — escalate:** If the evaluation shows the vulnerability **does** affect the project and neither step 1 nor step 2 was possible, ask the user what to do. This is the only step that pauses for a human.
+7. **Step 5 — ignore:** If the evaluation shows the vulnerability **does not** affect the project, add an exclusion entry to `audit.ignore.local.json` yourself, in the format `{"id": "GHSA-xxx", "package": "pkg-name", "reason": "<impact evaluation: why this advisory does not affect this project>"}`, then commit and retry the push. No human approval is required for this step — the `reason` field is the record of your evaluation.
+
+### Critical: Override the vulnerable package, not its parent
+
+When the audit output shows a dependency chain like `@expo/cli › glob › minimatch`, the vulnerable package is **minimatch**, not glob. Always override the **leaf package** that has the actual vulnerability.
+
+**Never override a parent package to force a lower major version** — other packages in the project may depend on a newer major version, and a resolution/override forces ALL installations to the specified version. For example, overriding `glob` to `^8.1.0` will break `@expo/cli` which requires `glob@^13.0.0`, causing `expo prebuild` to fail with `files.map is not a function`.
+
+Before adding a resolution/override (step 2), verify:
+- You are targeting the **actually vulnerable package**, not a parent in the chain.
+- The override version is **compatible with all dependents** (check with `bun why <package>` or `npm ls <package>`).
+- The override does not **downgrade** a package across a major version boundary that other dependencies require.
+
+If any of these checks fail, the override is "not possible" for the purposes of the ladder — drop to step 3 (evaluate impact).
+
+### Never
+
+- Never add a blanket audit bypass or lower the configured audit level.
+- Never jump to step 4 (ask a human) before genuinely attempting steps 1–3.
+- Never add a step-5 ignore entry without an impact evaluation recorded in its `reason`.
+
+## Rails Projects (bundler-audit)
+
+Same ladder, bundler mechanics:
+
+1. Note the advisory ID, affected gem, and advisory URL from the error output.
+2. Check whether a patched version of the gem exists.
+3. **Step 1 — update:** If a patched version exists:
+   - **Direct dependency** (in Gemfile): update its version constraint, run `bundle update <gem>`, commit, retry.
+   - **Transitive dependency** (only in Gemfile.lock): run `bundle update <gem>` to pull the patched version without changing the Gemfile, commit the lockfile change, retry.
+4. **Steps 3–5 — no patch:** If no patched version exists, evaluate whether the advisory affects the project. If it **does** and no fix is possible, ask the user (step 4). If it **does not**, document the exception and retry (step 5).

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

@@ -0,0 +1,111 @@
+# Session Status Updates — Plain Language, and Always Say If It's Safe to Close
+
+## Why this is a rule and not a style preference
+
+Lisa's premise is that a non-technical person can direct software work by describing outcomes. That premise already binds everything crossing a gate outward — intake rejections, clarifying questions, ticket descriptions, verification reports — because a non-technical operator is standing at the gate.
+
+In-session conversation was never held to the same bar, and the result was a split personality: careful, plain-language ticket prose and simultaneously a stream of chat messages full of file paths, rule slugs, and reasoning narrative. The human reading both is the same human. This rule closes the split.
+
+## The three-part shape
+
+Every update answers, in this order:
+
+1. **What changed** — what is different in the world now that was not before. Shipped, fixed, filed, deployed.
+2. **What's blocked** — using the strict meaning from `not-blocked-just-waiting`. If nothing is blocked, say so; "waiting on the CI run" belongs here labelled as waiting.
+3. **What needs a decision** — see below.
+
+What is deliberately excluded: how you found it. The files you read, the searches you ran, the hypotheses you discarded, the dead ends. That is your working memory, not their update. If they want it they will ask, and the offer to elaborate costs one clause.
+
+## Voice
+
+Write the way you would speak to a competent colleague who does not work on this system.
+
+- Prefer the user-visible name of a thing over its implementation name. "The login page broke" beats "the auth guard regressed at the controller boundary."
+- Do not use Lisa vocabulary (rung, gate, leaf, intake, ratchet) with someone who has not asked for it.
+- Do not use a file path where a description works. Paths are for when the human will open the file.
+- Short sentences. No preamble about what you are about to say.
+
+Two lines the user themselves offered as the target: *"just tell me what's going on and what my options are"* and *"give me the summary, I'll ask for detail if I want it."*
+
+## ASD-STE100 Simplified Technical English
+
+Every response you write to a human is written in ASD-STE100 Simplified Technical
+English — the controlled-language standard maintained by the AeroSpace and Defence
+Industries Association of Europe. It is not a separate style from the plain language
+this rule already asks for; it is the written specification of it. "Plain" is a
+preference and gets argued about. ASD-STE100 is a rulebook, so it does not.
+
+The scope is every response, not only a status update. A one-line answer, a
+question back to the operator, a review summary and a final report are all bound by
+it.
+
+### The writing rules that bind you
+
+- **One idea per sentence.** Split a compound thought into separate sentences.
+- **Sentences stay short.** 20 words at most for a descriptive sentence, 20 for a
+  procedural step. Break a longer one in two.
+- **Active voice.** "The test failed", not "a failure was observed".
+- **Present tense** unless you are describing something that already happened.
+- **One word, one meaning.** Use a word in a single sense throughout a response.
+  Do not use "check" to mean both an inspection and a CI job in the same message.
+- **Approved vocabulary.** Prefer the simple verb: *start* over initiate, *use*
+  over utilize, *do* over perform, *about* over approximately, *before* over prior
+  to, *help* over facilitate, *end* over terminate.
+- **No noun clusters longer than three words.** "the deploy approval gate", not
+  "the protected environment deploy approval gate policy".
+- **Say the subject.** Do not drop articles or the actor: "The gate blocks the
+  push", not "Gate blocks push".
+- **No idiom, no metaphor, no humour that depends on a shared culture.** The reader
+  may not speak English as a first language.
+- **Paragraphs stay short.** Six sentences at most.
+
+### What the standard does not forbid
+
+The proper name of a real thing is always permitted, even when it is technical: a
+command, a file path, a branch, an error string, a ticket id. ASD-STE100 keeps
+technical names — it constrains the words around them. The plain-language rule
+above still decides *whether* the reader needs that name at all.
+
+Numbers, units, measurements and quoted output are reproduced exactly. Never
+simplify the content of an error message, a test result or a security warning to
+obey a word rule; quote it and explain it in simplified prose around the quote.
+
+### Why it is worth the constraint
+
+Lisa's premise is that a non-technical person directs the work. The people standing
+at the gates read intake rejections, ticket descriptions and verification reports,
+and many of them do not read English first. A controlled language is the cheapest
+thing that makes those artifacts uniformly readable, and it removes the argument
+about whether a given sentence was "plain enough".
+
+## Decisions
+
+A decision presented as a paragraph of context is a decision the human has to excavate. State it as a decision:
+
+- **The decision** — one sentence naming the choice to be made.
+- **Your recommendation** — you have more context than they do; do not withhold it. Recommending is not deciding.
+- **The ramifications of each option** — one line apiece, in terms of consequences they care about (time, cost, risk, what breaks, what it forecloses), not in terms of implementation.
+
+An option you consider unacceptable is still listed, with the reason it is unacceptable. Presenting one option as if it were the only one is a decision you made on their behalf without saying so.
+
+## The close line
+
+Every update ends with exactly:
+
+```
+Safe to close: yes/no — <reason>
+```
+
+`yes` means killing the session right now loses nothing: work is committed and pushed, tickets are in the state they should be in, nothing is running that will not finish on its own.
+
+`no` names the specific in-flight thing that would be lost. Real examples: a local dev server or test run still going; a ticket filed but not yet flipped to ready, so nothing will pick it up; a commit that exists only in the working tree; a PR whose checks nobody is watching; a deploy mid-flight.
+
+The line exists because the human's most common question — asked or unasked — is "can I close this?" Making them ask it costs a round trip; making them guess costs them work.
+
+## Relationship to the other communication rules
+
+- `report-actionability` governs **completeness**: the denominator, every item accounted for, who acts on each. It is about what a report must contain.
+- `automation-runbook-contract` governs the **outcome line** a terminating flow opens with.
+- This rule governs the **voice** of a session update, its three-part shape, and the close line.
+
+None of the three is relaxed by the others. An update can satisfy all three at once and usually should: outcome line first, denominator stated, plain language throughout, close line last.

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

@@ -0,0 +1,39 @@
+# Settled Decisions
+
+Do not ask the operator to decide something that is already settled by standing preference, evidence you just gathered, or a conventional default. A question is appropriate only when the answer materially changes the work and the answer cannot be derived from available artifacts.
+
+## Decision Sources
+
+Check these sources before asking:
+
+1. Standing preferences recorded in memory, project config, project rules, instruction files, or earlier in the same conversation.
+2. Evidence already gathered during the current run. If research or code inspection resolves the choice, report the decision and cite the evidence.
+3. Conventional defaults where one option is clearly standard and the alternative needs a reason.
+
+If one of those sources answers the question, act on it and state the basis briefly.
+
+## When To Ask
+
+Ask only when the answer changes the deliverable and cannot be inferred. That includes product decisions, design vocabulary that does not exist yet, destructive or unsafe assumptions, or choices that would waste substantial work if guessed wrong.
+
+When asking, ask once, plainly, with a recommended option.
+
+## Common Violations
+
+Half-applying a standing instruction is a violation. If a preference covers a multi-step behavior, apply the whole behavior instead of doing one part and asking about the rest.
+
+Asking after the research answered the question is also a violation. When gathered evidence points one way unambiguously, treat it as a decision and make the reasoning auditable in the report.
+
+## Reporting
+
+Record settled decisions in a short clause, such as "auto-merge on, per standing preference" or "scoped app-wide, because the Android finding decides it." This gives the operator a chance to correct the decision without requiring an avoidable question first.
+
+## Re-read the instruction file from disk before escalating
+
+This rule is delivered at session start; the re-read it requires happens at the escalation boundary. Re-reading at session start would re-read the same moment the context was built from.
+
+Before forming an escalation, handing a decision back, or re-opening 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 rather than to assess the context, because context completeness is not observable from inside. An instruction file is injected at session start and can arrive shortened, and a cut landing on a section boundary is indistinguishable from a document that never carried that section. Rulings are also written after sessions begin, so an injected copy is a snapshot of the moment the session started.
+
+This is a pointer, not a copy. It stays correct as rulings accumulate and survives a shortened copy of the file it points at, because it does not travel inside that file.

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

@@ -0,0 +1,88 @@
+# Stale State Claims — Reference
+
+Eager head: [eager/stale-state-claims.md](../eager/stale-state-claims.md).
+
+## Why this rule exists
+
+Most bad documentation is *wrong*. This kind was **right** — and that is what makes it dangerous. A note saying "not wired up yet" earned its credibility honestly, so the next reader has no reason to doubt it. There is no defect to find, no test that goes red, no reviewer who objects. The claim simply keeps being read after the world moved.
+
+The cost is not confusion, it is confident misdirection in a specific direction: **toward doing nothing**. An expired blocker never causes someone to break production. It causes work to be skipped, re-planned, or escalated — outcomes that look like caution and are indistinguishable from good judgment at the moment they happen.
+
+The `falsifiable-checks` rule covers instruments that cannot fail. This one covers assertions that *could* fail but are never re-evaluated, because nothing re-runs prose. Both produce the same end state — a confident answer with no live evidence behind it — from opposite directions.
+
+## The four failure modes, in detail
+
+### 1. Expired blocker note
+
+A comment, docstring, config value, or README line records that something is not available yet. The condition clears. The note does not.
+
+Observed: a deployment stage's endpoint was left unset with an adjacent comment explaining that its routing had "not yet been promoted." The routing had been live for days. An agent read the comment, believed it, and planned work to enable a capability that was already enabled — then reported the capability as pending.
+
+Countermeasures:
+- Treat any not-yet claim as a **hypothesis with an expiry you cannot see**. Resolve it with one live probe (a request, a query, a status read) before it enters a plan, a status report, or an escalation.
+- Cite the probe, not the comment: "verified live at <time>" is evidence; "the comment says" is hearsay about the past.
+- When you are the one who promotes/enables/provisions the thing, the note describing its absence is part of the change. Grep for it.
+
+### 2. Stale gate marker
+
+A config entry, flag, or checklist item is annotated as awaiting a human decision or an unfulfilled prerequisite. The prerequisite arrives, or the decision gets made elsewhere. The marker persists and keeps routing work to a gate that is no longer closed.
+
+Observed: an entry marked human-gated because no client had been provisioned. The client had existed for twelve days. The gate was honored anyway and the question escalated to a person who had already decided it and was surprised to be asked.
+
+This mode is corrosive twice over: it wastes the human's attention, and it teaches the agent that gates are noise — which is exactly the wrong lesson to carry into a gate that is still real.
+
+Countermeasures:
+- Before honoring a gate, verify the condition that justifies it still holds. A gate whose stated reason is falsifiable and false is not a gate.
+- Record gates as **conditions**, not as verdicts: "gated until <checkable condition>" can be evaluated; "human-gated" cannot.
+- When escalating, state the evidence that the gate is still live. If you cannot, you are escalating a comment.
+
+### 3. Prediction buried by closure
+
+Someone records a correct warning — "this will fail until X is fixed", "this leaves Y broken" — as a comment on a work item, and the item then closes. Closure is a filter: closed items are not read. The prediction is deleted in every practical sense while feeling like it was recorded.
+
+Observed: a comment correctly predicted a defect. The item closed 25 minutes later with no follow-up filed. The defect sat unnoticed for **eight days**, blocking a dependent item that was itself parked waiting for it — two items, both stalled, and the explanation was already written down in a place nobody would look.
+
+Countermeasures:
+- A prediction is either **real work or a retraction**. If real, it is a tracked leaf with an explicit blocking link to what it blocks (`tracked-work`), created **before** the parent item closes. If not real, say so in the same thread so the next reader is not left holding an unresolved warning.
+- Never let closing be the last action on an item that carries an open prediction. Check the comment thread as part of closing.
+- Blocking links are the mechanism that makes the parked dependent item legible. A prediction with no link is invisible from the side that is actually waiting.
+
+### 4. Silent waiting gate
+
+An approval, queue, or review state holds work and emits nothing. Its duration is therefore set by how often somebody happens to look, which is not a property of the work's urgency.
+
+Observed: a deploy approval gate held a security-relevant fix undeployed for two days. Nothing was broken, nobody was wrong, and nothing surfaced that the gate was waiting.
+
+Countermeasures:
+- Every waiting state needs a surfacing mechanism proportional to what it can hold: notification, dashboard row, scheduled sweep, or an automatic expiry.
+- **Fix the gate, not your habits.** "Remember to check" is not a mechanism; it is the same failure with a person's name on it.
+- When you add a gate, state how long it may silently hold work and what surfaces it. If the answer is "indefinitely" and "nothing", the gate is not finished.
+
+## Expiry-resistant forms
+
+Prefer, in order:
+
+1. **State what is true.** "Serves from <path>" outlives "not yet serving from <path>", because it stays wrong-detectably wrong instead of quietly-stale.
+2. **Bind the claim to a check.** A test, guard, or assertion that fails when the temporal claim goes false converts a silent expiry into a red build. (That check is itself subject to `falsifiable-checks` — a guard that cannot fail re-creates the problem it was added to solve.)
+3. **Bind the claim to a work item.** "Blocked by <ref>" is resolvable by anyone; "waiting on the migration" is resolvable only by whoever wrote it.
+4. **Timestamp and scope it.** If prose is genuinely the only option, write "as of <date>" and name the condition that ends it. A dated claim at least advertises its own age.
+
+Avoid: bare "not yet", "TODO once", "temporarily", "for now", "pending" with no owner, condition, date, or link. Each is a claim that can only be falsified by someone who already knows the truth — which is the one person who does not need to read it.
+
+## How to apply
+
+1. Reading a note that asserts a pending/blocked/not-yet state: **do not act on it yet.**
+2. Identify the cheapest live probe that settles the underlying fact.
+3. Run it. Report the observation, not the note.
+4. If the note is stale, **delete or correct it in the same change** — leaving it is handing the next reader the trap you just escaped.
+5. If the note is accurate, upgrade it while you are there: attach the condition, the link, or the check that will make it self-expiring.
+
+And when you are the one clearing a condition: sweep for the notes that described it. The change is not complete while the repository still asserts the old state.
+
+## Interaction with other rules
+
+- **`falsifiable-checks`** — the sibling failure. That rule prevents an instrument that cannot fail; this one prevents an assertion that never gets re-evaluated. A check bound to a temporal claim (form 2 above) sits under both rules at once.
+- **`empirical-inquiry`** — supplies the discipline this rule depends on: settle the fact with the cheapest probe rather than reasoning from what is written down. A stale note is exactly the "confident-sounding answer from a prior assumption" that rule forbids.
+- **`verification`** — a status derived from a comment is not runtime evidence. Reporting "still blocked" on the strength of a note is the same error as reporting "works" on the strength of the code looking correct.
+- **`tracked-work`** — the destination for any prediction that survives its item's closure: one live leaf, explicit blocking link, carried on the branch and PR.
+- **`claim-archaeology`** — the recovery path once mode 3 has already happened. Lifecycles are one-way, so a warning lost to closure resurfaces only as a fresh item whose ancestry has to be reconstructed. Archaeology is the cleanup; this rule is the prevention.