@codyswann/lisa 3.2.0 → 3.3.0

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/rules/eager/do-it-now.md

@@ -0,0 +1,11 @@
+# Do It Now (load-bearing)
+
+If something needs to happen eventually and **the factory is allowed to do it**, do it in this session. File the ticket, flip it to ready, add the lint rule, fix the flaky test, update the doc that just went stale. Not in a "follow-up" sentence — now.
+
+**"I'll get to that later" is not an acceptable close** for work that is in scope and permitted. A deferral costs a whole future session its context, and most of them are never picked up at all.
+
+The one exception is an **exterior human gate** — a protected deploy, a held-back PRD, a low-confidence learning, a product call only a person can make. There you do the allowed part now (file it, mark the gate, flip everything you may flip) and say plainly what is waiting on a human and why.
+
+Deferring is itself a decision. If you genuinely should not do it now, say so and say why; never leave it implied, and never leave it only in your own head.
+
+Full prose: [reference/do-it-now.md](../reference/do-it-now.md).

package/plugins/lisa-copilot/rules/eager/empirical-inquiry.md

@@ -16,6 +16,7 @@ Do not reason your way to a confident-sounding answer from documentation, prior
 - Presenting a guess, recollection, or doc summary as established fact when it was cheap to verify and you did not.
 - "Should work" / "probably" / "the docs say" as the basis for a load-bearing decision an experiment could have settled.
 - Skipping the probe because the answer "seems obvious" — those are exactly the ones that quietly drift from reality.
+- Interpreting a diff, or reporting scope, before establishing where your checkout sits: run `git rev-list --count HEAD..origin/<default>` first. A worktree 30 commits behind makes everyone else's changes read as yours, and the diff was reported as massive scope creep in reverse.
 - Treating a recorded "not yet" / "pending" / "blocked" / "human-gated" note as current state. It is a claim about the day it was written; probe the live state before planning around it, escalating it, or reporting it as a blocker (`stale-state-claims`).
 
 This is the inquiry counterpart to the `verification` rule (which proves completed work behaves correctly). Both reject "it looks correct" as evidence.

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

@@ -18,6 +18,8 @@ Each has been observed in real runs; each reported success while asserting nothi
 ## Mandatory
 
 - **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.
+- **Count the failures: introduce the exact regression the guard exists to prevent, and confirm **exactly one** test fails, then revert.** Zero means the guard is inert; many means it is over-broad and its next failure will not name the cause. A guard that pinned one field of a structure shipped with all 50 tests green while the regression walked straight through.
+- **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.

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

@@ -4,6 +4,11 @@ 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.
 
+Secrets are the same shape: every credential resolves through
+`lisa-secrets-access`, which owns the provider list, the note format, and the
+resolution order. Read it rather than restating it — and never ask a human to
+paste a value the provider can supply.
+
 Resolution order is the configured-provider token/CLI substrate first when its
 bootstrap credential is present and identity-matched, then the interactive MCP as
 fallback, then a loud error naming the exact credential to set. Identity-match is

package/plugins/lisa-copilot/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-copilot/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-copilot/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-copilot/rules/eager/session-status-updates.md

@@ -0,0 +1,19 @@
+# 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".
+- **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-copilot/rules/eager/wiki-knowledge-source.md

@@ -1,18 +1,13 @@
-# Wiki as Knowledge Source (load-bearing)
+# Wiki as Knowledge Source — Query It on Demand (load-bearing)
 
-If the project has an LLM Wiki, treat it as the canonical source of durable project knowledge. A project has a wiki when **either** a local `wiki/` directory with `index.md` exists **or** `.lisa.config.json` declares a `wiki.source` pointer to a remote wiki repo. Documentation rolls UP into that wiki; individual repos are not expected to carry their own prose docs beyond inline code comments.
+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.
 
-You never have to fetch or freshness-check the wiki yourself: the query and ingest skills resolve the wiki root and guarantee it exists and is current (via `scripts/ensure-wiki.mjs`) as their own first step — a local wiki resolves instantly, a remote wiki is mirrored/refreshed transparently into a gitignored working copy. Just call the skill.
+**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.
 
-Before researching background, conventions, ownership, architecture, glossary, or "how/why does X work here":
+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.
 
-1. **Consult the wiki first.** Use the wiki query skill (`/lisa-wiki-query`), which resolves the wiki root for you; for a local wiki you may also start from `wiki/index.md` directly.
-2. **Use what the wiki says** as the authoritative answer when it covers the question — do not re-derive it from raw sources.
-3. **Fall back to primary sources** (code, tickets, commit history, external docs) only when the wiki is silent, ambiguous, or contradicted by what you observe.
-4. **Surface gaps.** If the wiki is wrong, stale, or missing knowledge that belongs there, flag it — and where the workflow supports it, capture the correction via `/lisa-wiki-ingest`.
+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.
 
-The wiki documents knowledge; it does NOT override executable behavior. When wiki and running code disagree about what the system does, trust the code and treat the wiki as out of date.
-
-If the project has neither a local `wiki/` nor a `wiki.source` pointer, this rule does not apply.
+**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).

package/plugins/lisa-copilot/rules/reference/do-it-now.md

@@ -0,0 +1,37 @@
+# Do It Now
+
+## The failure
+
+An agent notices something that needs doing — a lint rule that would have caught the bug it just fixed, a stale comment, a real defect found beside the one it was sent for, a ticket that should be flipped to ready — and writes a sentence about it instead of doing it. "Worth adding a rule for this later." "We should file that." "Follow-up: update the doc."
+
+Almost none of those happen. The note lands in a session transcript nobody re-reads, or in a report the human skims once. Even when it survives, the next session pays full price to rebuild the context that made the work obvious — which is the moment you are in right now, and it will not come back this cheap.
+
+The originating example: a session closed a non-reproducing bug, found a genuine defect next to it, filed a ticket for the real defect, and then left the ticket sitting outside the ready lane. Every individual step was correct. The handoff was incomplete, and the work sat.
+
+## The rule
+
+**If the factory is allowed to do it, do it in this session.** Allowed means: within scope, within your permissions, and not behind an exterior human gate. That covers the great majority of "later" items:
+
+- Filing the ticket — and flipping it to the ready role so something picks it up (`tracked-work`).
+- Adding the lint rule, ast-grep pattern, or test that prevents the recurrence (`promotion-contract` — and note that promotion is atomic: enable the control, fix the existing violations, ship the diagnostic, delete the superseded prose).
+- Fixing the flaky test rather than re-running it.
+- Updating the doc, comment, or rule your change just made wrong (`stale-state-claims`).
+- Cleaning up the scaffolding you introduced.
+
+## The exception, and its shape
+
+Lisa's exterior gates exist on purpose and this rule does not override them. A protected deployment, a held-back PRD, a low-confidence learning awaiting human review, a product judgement only a person can make — these wait for the human, by design.
+
+The exception is narrower than it first appears, because it applies to the **gated step**, not to the whole item. Do everything up to the gate now:
+
+1. Do the allowed part — file it, write it, prepare it, get it to the edge of the gate.
+2. Mark the gate explicitly, in the tracker, so it is visible outside your session.
+3. Say plainly, in your update, what is waiting on a human and what will happen once they act.
+
+"Waiting on a human" is a state you report, never a place you leave work silently.
+
+## Deferring is a decision
+
+Sometimes not doing it now is genuinely right: the change is out of scope, it would balloon the diff past reviewability, it depends on a decision not yet made, or it belongs to a different work item. Those are legitimate — and they are **decisions**, which means they get said out loud with a reason, and the deferred item becomes tracked work rather than a sentence.
+
+What is never acceptable is the implied deferral: noticing, saying nothing, and moving on. The human cannot act on what you did not tell them, and neither can the next session.

package/plugins/lisa-copilot/rules/reference/empirical-inquiry.md

@@ -21,6 +21,7 @@ This is the inquiry counterpart to the `verification` rule: `verification` prove
 ## What this rule forbids
 
 - Presenting a guess, a recollection, or a documentation summary as established fact when it was cheap to verify and you did not.
+- **Interpreting a diff, or reporting scope, without first establishing your branch position.** Run `git rev-list --count HEAD..origin/<default>` before you read a diff and before you describe how large a change is. A worktree that is thirty commits behind renders everyone else's merged work as though it were part of your change — the observed incident reported it as massive scope creep, in reverse, and the reviewer nearly acted on it. The count is one command and it turns an ambiguous diff into an unambiguous one.
 - "Should work" / "probably" / "the docs say" as the basis for a load-bearing decision that an experiment could have settled.
 - Skipping the probe because the answer "seems obvious" — obvious answers are exactly the ones that quietly drift from reality.
 

package/plugins/lisa-copilot/rules/reference/falsifiable-checks.md

@@ -62,11 +62,33 @@ A clean result is a statement about what the check can perceive, not about the c
 ## How to apply
 
 1. Author the check.
-2. Deliberately break the guarded property.
-3. Confirm the check **fails and names the right file/line**. A failure that does not localize is weak evidence the check is measuring the right thing.
+2. Deliberately break the guarded property — specifically, introduce **the exact regression the guard exists to prevent**, not a nearby or convenient break.
+3. Confirm the check **fails, names the right file/line, and that exactly one test fails**. A failure that does not localize is weak evidence the check is measuring the right thing.
 4. Restore, and confirm green again.
 5. Report the falsification alongside the result.
 
+### The failure count is part of the evidence
+
+Step 3's cardinality is not pedantry; each deviation names a distinct defect.
+
+- **Zero failures** — the guard is inert. It was authored, it is green, and it asserts nothing about the property it names. The originating incident: a guard pinned one field of a structure and the regression it was written to stop walked straight through it with all fifty tests green, because nothing in the suite touched the field that actually moved.
+- **More than one failure** — the break is too coarse, the guard is over-broad, or unrelated tests share the fixture. Any of the three means the guard's next real failure will not tell the reader what broke, which is most of a guard's value.
+- **Exactly one failure** — the guard localizes. That is the evidence, and it is what gets reported.
+
+### Never narrate a red state you did not run
+
+A guard's red leg, a "before" state, a reproduction of a fixed defect: each is an **observation**, and an observation you did not make is a fabrication however sound the reasoning behind it. The originating incident here was an evidence file asserting "working tree clean" while listing two untracked scripts a few lines further down — internally contradictory, because the clean-tree line was reasoned rather than run.
+
+When the red state no longer exists in your working tree — it was fixed, or it lives at an earlier commit — **reconstruct it in a throwaway detached-HEAD worktree** and run it there:
+
+```
+git worktree add --detach <scratch-path> <sha>
+# run the check in <scratch-path>, capture the real output
+git worktree remove <scratch-path>
+```
+
+This costs seconds, leaves your working tree untouched, and produces genuine output. There is no situation in which writing down what the command *would* have printed is preferable to running it.
+
 For generated or validated inputs, replace steps 2–4 with a direct unit test of the checker against synthetic bad input.
 
 **A check whose failure has never been observed is reported as `unvalidated`, not as passing.** "Mentally reverting" does not satisfy step 3 — the author of a guard already believes it is load-bearing, so reasoning about the failure reproduces the belief rather than testing it. `unvalidated` is a legitimate state to report and land; silently presenting an unfalsified gate as a passing one is not.

package/plugins/lisa-copilot/rules/reference/integration-access-layer.md

@@ -1,5 +1,13 @@
 # Integration Access Layer
 
+## Secrets resolve through `lisa-secrets-access`
+
+Credentials follow the same chokepoint discipline as vendor integrations: every secret a session needs resolves through the `lisa-secrets-access` skill, which owns the supported provider list (Bitwarden, 1Password, AWS, Doppler, Vault, env), the note format attached to each secret, the `tool:` declaration of which CLIs a credential drives, and the resolution and verification order.
+
+That contract is deliberately **not restated here or anywhere else.** A second copy of the note format is a copy that drifts, and a drifted copy of a credential contract is worse than no copy, because it is followed. Read the skill.
+
+The one operational consequence worth stating in an always-loaded rule: **do not ask a human to paste a value the configured provider can supply**, and do not read keychains, `.env` files, or provider CLIs directly to work around the skill. If resolution fails, the failure is a bug in the provider bootstrap and gets reported as one.
+
 Every Lisa skill or rule that consumes an external integration MUST route through
 the integration's `*-access` skill instead of calling that vendor's MCP tools or
 REST API directly.

package/plugins/lisa-copilot/rules/reference/learnings-ladder.md

@@ -0,0 +1,41 @@
+# Learnings Ladder — Where Does This Go?
+
+## The problem this solves
+
+The taxonomy was never missing. Lisa has had the six-rung ladder since the `skill-evaluator` agent shipped, and the gardener has always routed by it. What was missing is that the taxonomy lived inside an agent definition most sessions never open, so the practical answer to "where does this learning go?" was whichever knowledge file the agent happened to have in context — which is how a single project rules file accretes lint rules, product specs, and incident notes into one undifferentiated blob that every session pays for.
+
+This rule is a pointer, not a second taxonomy. It exists so the routing question is answerable without opening anything.
+
+## The rungs, ordered by what they cost to carry
+
+| Rung | Destination | Enters context | Admission |
+| --- | --- | --- | --- |
+| EXECUTABLE-CONTROL | Lint / ast-grep / type / test / hook / `package.lisa.json` force | Never — the diagnostic fires on violation | Mechanically decidable, stable, and it has recurred |
+| EAGER-RULE | The host rules directory `.agents/rules/`; Lisa's own shipped rules originate in the plugin rules tree | Unconditionally, every session | Earned by failure evidence — repeated misses despite the knowledge being reachable |
+| SKILL | A `SKILL.md` procedure | Description eager; body on invoke | Procedural, multi-step, with a recognizable trigger |
+| WIKI | Wiki page plus an index entry | Only when queried | Durable declarative reference knowledge |
+| KEEP-IN-LEDGER | The learnings ledger (`.lisa/PROJECT_LEARNINGS.md`, or the configured `learnings.file`) | Bounded contract projection only | The default landing zone; probationary and expiring |
+| RETIRE | Nowhere — the prose is deleted | Never | Redundant with a mechanical owner, stale, or superseded |
+
+Each rung also carries an orthogonal **scope**: `project` (apply here) or `upstream` (raise to `CodySwannGT/lisa`). Scope changes where the promotion work is filed; it never changes the rung.
+
+## How to choose
+
+Work down the list and stop at the first honest yes:
+
+1. **Can a machine decide it?** Then it is EXECUTABLE-CONTROL, and prose describing it is redundant. This is the strongest rung and the cheapest to carry: it costs nothing until someone violates it, and then it says exactly what is wrong.
+2. **Is it a procedure with a trigger?** SKILL. The description is what gets loaded eagerly; the body arrives only when invoked.
+3. **Is it reference knowledge someone would go and look up?** WIKI. Deep project knowledge belongs on a rung that is paid for only when routed to — which is why `wiki-knowledge-source` is query-on-demand rather than load-at-startup.
+4. **Otherwise, KEEP-IN-LEDGER.** This is the default and it is not a failure state. Most learnings are provisional, and the ledger is where a candidate proves whether it recurs.
+
+**EAGER-RULE is not on that list on purpose.** It is not something you choose; it is something a candidate earns, on cited evidence that agents repeatedly missed the knowledge even though it was already reachable. The eager tier charges every session on every agent, so admission is demotion-biased and the gardener re-audits the tier on every run — including Lisa's own shipped eager rules. A candidate with no recurrence evidence can reach WIKI, KEEP-IN-LEDGER, or RETIRE, and can never reach EAGER-RULE.
+
+## Capture is yours; promotion is not
+
+The division is deliberate and it is what keeps knowledge surfaces from silently growing:
+
+- **You capture.** Record the learning through `lisa-persist-learning`, with its provenance and evidence. That is the whole of a session's authority here.
+- **The gardener promotes.** `/lisa:learnings:audit` — available as an opt-in weekly automation via `lisa-setup-automations` — audits the ledger, rules trees, skills, and wiki, routes candidates through the `skill-evaluator`, and files **human-gated tracker tickets** for promotions, demotions, and retirements. A human approves each one.
+- **Nothing hand-appends.** Never write a learning directly into `AGENTS.md`, a host rules file, or the human decree surface. Those are human-authored, and an automated append to them is exactly the accretion this ladder exists to stop.
+
+Promotion tickets are themselves governed: `promotion-contract` requires an EXECUTABLE-CONTROL promotion to be atomic — enable the control, fix the existing violation population, ship a remediation-teaching diagnostic, and delete the superseded prose, all in one PR. Promote-without-remove double-pays forever.

package/plugins/lisa-copilot/rules/reference/local-ci-first.md

@@ -0,0 +1,34 @@
+# Local CI First — CI Is Not a Debugger
+
+End-to-end suites — Playwright, Maestro, Cypress, and anything else that only runs in a workflow on a normal day — fail differently from unit tests. The failure is usually environmental (a selector that moved, a fixture that did not seed, a simulator that booted slowly), and the instinct is to guess, push, and read the next CI run.
+
+That instinct is what this rule exists to break. A CI round trip is five to twenty minutes, produces one bit of information per attempt, gives no interactive access to the failing state, and occupies a runner that other work is queued behind. Three speculative pushes cost the better part of an hour and still leave you without a reproduction. The same three attempts run locally take minutes and hand you the actual DOM, the actual screenshot, and the actual stack.
+
+## Reconstruct the invocation, do not approximate it
+
+The workflow file is the specification of what CI ran. Read it and mirror it:
+
+- The **exact command**, including the config file, project/suite selector, and tag filters (`--project=chromium`, `--grep`, `include_tags`).
+- The **environment**: env vars the job sets, the base URL it points at, whether it runs headless, and which secrets it injects. Anything you cannot supply locally is a known difference — write it down rather than assuming it is irrelevant.
+- The **target**: browser version, device or simulator model, OS. Mobile e2e is especially sensitive here; a Maestro flow that passes on one iOS version fails on the next over accessibility-label matching alone.
+- The **fixture and data state**: seed scripts, migrations, and whether the job runs against a fresh database or a shared environment.
+
+Setting all of that up — installing the browser, booting the simulator, seeding the database — is part of doing the work. "Local setup would take a while" is not a reason to use the shared CI queue as a REPL.
+
+## When it genuinely will not reproduce
+
+Some failures are real and local-only-invisible: a race that appears only on a slower runner, a secret that exists only in CI, an artifact that only the CI build produces. That case is legitimate, and the rule's requirement is honesty about it, not denial:
+
+1. **Say so explicitly**, and name what differs — runner OS, CPU count, headless mode, network latency, a device you do not have, a secret you cannot read.
+2. **Change one thing per push, and state what that push is testing.** A push that alters four things and goes green teaches you nothing about which one mattered.
+3. **Add the observability you are missing** — a trace, a video, a screenshot on failure, a verbose log — in the same push, so the next run answers the question rather than repeating it.
+
+## Forbidden
+
+- Pushing a speculative fix "to see if it helps" when the suite has never been run locally.
+- Re-running a failed CI job unchanged in the hope of a different outcome, without labelling the failure as suspected-flake and investigating it as one.
+- Reporting a fix as verified on the strength of a green CI run that followed several red ones, without knowing which change was responsible.
+
+## Relationship to other rules
+
+`empirical-inquiry` says to run the cheapest probe that settles a question; local reproduction *is* that probe for an e2e failure. `verification` requires proof by using the software — a local run of the same suite produces that proof directly, and produces it faster.

package/plugins/lisa-copilot/rules/reference/not-blocked-just-waiting.md

@@ -0,0 +1,41 @@
+# Waiting Is Not Blocked
+
+Three failure modes share one root: a session that stops producing while still consuming the human's clock and attention. Each was observed directly.
+
+## 1. Poll; do not wait for a message
+
+An agent dispatches a subagent, a CI run, a deploy, or a long build — and then waits for a notification that never arrives, or arrives long after it mattered. Callbacks are best-effort. Notification channels drop. A background process can exit without anything telling you.
+
+**While the session is active, go and check.** Roughly every five minutes, run the command that answers the question: `gh run list`, `gh pr checks`, a status query, a log tail, a file existence check. Polling is cheap; an idle session is not.
+
+This is not an instruction to busy-wait. It is the opposite: between polls you should be doing other work (see rule 3). The poll is a periodic check, not an occupation.
+
+Two corollaries:
+
+- **An absent result is information.** If a subagent has produced nothing after several polls, investigate whether it is running at all rather than assuming it needs more time.
+- **Never claim an outcome you have not observed.** "The tests are probably green by now" is a fabrication; go look. See `falsifiable-checks` and `claim-evidence-mapping`.
+
+## 2. Blocked means you physically cannot proceed
+
+The word is load-bearing and it gets diluted. **Blocked** means there is no action available to you: a credential you cannot obtain, an API that rejects you, a decision whose answer changes what you would build, a dependency that does not exist yet.
+
+These are **not** blocked:
+
+- Waiting for a review, a CI run, a deploy, or a build.
+- Waiting for a human to confirm something you could reasonably proceed on and correct later.
+- Waiting for a subagent you dispatched.
+- Not yet having done the work.
+
+Report those as **waiting**, and say what you are doing in the meantime. Reporting them as blocked misinforms the human twice: it suggests they must act when they need not, and it devalues the word for the times you genuinely cannot proceed.
+
+## 3. Plan phases are parallel unless stated otherwise
+
+A numbered plan is a decomposition, not a dependency graph. Unless a phase's input is another phase's output — or the user said the order matters — the phases run concurrently. An agent that serializes a plan because it is written as a list turns a parallel workload into a queue and multiplies the wall-clock cost by the number of steps.
+
+Practically: when you would otherwise idle waiting on rule 1, start the next independent phase. When you dispatch subagents, dispatch every independent one in the same breath rather than one at a time.
+
+Where a real dependency exists, name it — "phase 3 needs the schema from phase 2" — so the human can see why the order is what it is.
+
+## Scope: sessions, not the tracker
+
+This rule governs **session** stuckness. It does not touch the factory's tracker lifecycle vocabulary — the `blocked` role and the `human_needed` outcome used by `lisa-implement`, `lisa-repair-intake`, and the intake flows. That vocabulary is stricter and deliberately so: an item marked `human_needed` is one an adversarial gate decided a person must resolve, and nothing in this rule permits a session to re-classify it. If you are unsure which vocabulary you are in, ask whether you are describing your own next five minutes (this rule) or the state of a tracked work item (the factory contract).

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

@@ -0,0 +1,60 @@
+# 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."*
+
+## 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-copilot/rules/reference/wiki-knowledge-source.md

@@ -9,13 +9,29 @@ A project has a wiki in one of two shapes:
 
 Either way, freshness is not your concern. The query and ingest skills run `scripts/ensure-wiki.mjs` as their own first step, which resolves the wiki root and — for a remote wiki — clones the mirror if missing and fast-forwards it when stale (subject to a short TTL, and tolerant of being offline: it proceeds with the existing mirror and warns rather than blocking). The freshness guarantee lives in the tool, not in the caller's discipline. Do **not** add a separate "make sure the wiki is current" step to your own workflow — calling the skill already does it.
 
-Before researching project background, conventions, ownership, architecture, glossary terms, or "how/why does X work here":
+## Load posture: on demand, not at session start
 
-1. Consult the wiki first via the wiki query skill (`/lisa-wiki-query`, or the runtime's wiki query skill), which resolves the wiki root for you. For a local wiki you may also start from `wiki/index.md` and follow links.
-2. Use what the wiki says as the authoritative answer when it covers the question. Do not re-derive it from raw sources when the wiki already documents it.
-3. Fall back to primary sources (code, tickets, commit history, external docs) only when the wiki is silent, ambiguous, or contradicted by what you observe in the code.
+The wiki is **not** read during session bootstrap, and no flow may add a "load the wiki" step to its startup. This is a deliberate reversal of the rule's earlier "consult the wiki first" posture, recorded in `wiki/decisions/2026-08-12-agent-neutral-host-rules-path.md` section 6 (decision D3). The reasoning is context budget: the wiki is deep declarative knowledge, which is the WIKI rung of the learnings ladder precisely *because* it should be paid for only when routed to. Loading it unconditionally converts an on-demand rung into an eager one and charges every session — including the large majority that never ask a knowledge question — for knowledge they do not use.
+
+What survives the softening is discoverability. An agent must **know the wiki exists and know how to query it**, so that a question needing depth goes to the curated answer instead of a fresh scrape of the codebase. What is dropped is the obligation to consult it before every piece of research, and the framing of the wiki as the authority that outranks primary sources.
+
+When you do need project depth:
+
+1. Call the wiki query skill (`/lisa-wiki-query`, or the runtime's equivalent), which resolves the wiki root for you. For a local wiki you may also start from `wiki/index.md` and follow links.
+2. Prefer what the wiki says over re-deriving the same answer from raw sources — that is what it is curated for.
+3. Fall back to primary sources (code, tickets, commit history, external docs) when the wiki is silent, ambiguous, or contradicted by what you observe in the code.
 4. If you find the wiki is wrong, stale, or missing knowledge that belongs there, surface the gap — and where the project's workflow supports it, capture the correction back into the wiki via its ingestion path (`/lisa-wiki-ingest` or equivalent) rather than leaving the knowledge only in this session.
 
 The wiki documents knowledge; it does not override executable behavior. When the wiki and the running code disagree about what the system actually does, trust the code and treat the wiki as out of date. See the `documentation-source-paths` rule for how source-material directories relate to the wiki.
 
-If the project has neither a local `wiki/` nor a `wiki.source` pointer in `.lisa.config.json`, this rule does not apply.
+## Applicability is the plugin gate, not just the wiki content
+
+This rule ships in the **base** plugin, but the skill it directs you to (`lisa-wiki-query`) ships in the **wiki** plugin. Those are gated differently, and for a period a base-only project received this rule pointing at a skill it did not have — a rule with a dangling instruction, which teaches an agent to distrust its rules.
+
+The applicability condition is therefore stated as the *installation* gate rather than as "does a `wiki/` folder exist". The `lisa-wiki` plugin is selected when `wiki/lisa-wiki.config.json` exists **or** `.lisa.config.json` declares a top-level `wiki` key (`src/core/lisa-plugin-selection.ts`); on Claude Code it is additionally gated by `enabledPlugins["lisa-wiki@lisa"]` in `.claude/settings.json`. When that gate is not satisfied:
+
+- This rule does not apply. There is no wiki to query and no query skill to call.
+- The recovery path is `/lisa-wiki-install`, the bootstrap skill that **base** ships precisely so a project that never enabled the wiki plugin can still discover it. Naming a base-shipped skill is what keeps the instruction reachable in every install.
+- **Never block on the absent skill.** Degrade to primary sources and continue, per the same degrade-never-block posture `readiness-rubric` and `rejection-detection` use for surfaces that may not be installed.
+
+A remote-only wiki declared through `wiki.source` is covered by the `wiki` config key, so the pointer form satisfies the same gate.

package/plugins/lisa-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cursor/rules/do-it-now-reference.mdc

@@ -0,0 +1,42 @@
+---
+description: "Do It Now"
+alwaysApply: false
+---
+
+# Do It Now
+
+## The failure
+
+An agent notices something that needs doing — a lint rule that would have caught the bug it just fixed, a stale comment, a real defect found beside the one it was sent for, a ticket that should be flipped to ready — and writes a sentence about it instead of doing it. "Worth adding a rule for this later." "We should file that." "Follow-up: update the doc."
+
+Almost none of those happen. The note lands in a session transcript nobody re-reads, or in a report the human skims once. Even when it survives, the next session pays full price to rebuild the context that made the work obvious — which is the moment you are in right now, and it will not come back this cheap.
+
+The originating example: a session closed a non-reproducing bug, found a genuine defect next to it, filed a ticket for the real defect, and then left the ticket sitting outside the ready lane. Every individual step was correct. The handoff was incomplete, and the work sat.
+
+## The rule
+
+**If the factory is allowed to do it, do it in this session.** Allowed means: within scope, within your permissions, and not behind an exterior human gate. That covers the great majority of "later" items:
+
+- Filing the ticket — and flipping it to the ready role so something picks it up (`tracked-work`).
+- Adding the lint rule, ast-grep pattern, or test that prevents the recurrence (`promotion-contract` — and note that promotion is atomic: enable the control, fix the existing violations, ship the diagnostic, delete the superseded prose).
+- Fixing the flaky test rather than re-running it.
+- Updating the doc, comment, or rule your change just made wrong (`stale-state-claims`).
+- Cleaning up the scaffolding you introduced.
+
+## The exception, and its shape
+
+Lisa's exterior gates exist on purpose and this rule does not override them. A protected deployment, a held-back PRD, a low-confidence learning awaiting human review, a product judgement only a person can make — these wait for the human, by design.
+
+The exception is narrower than it first appears, because it applies to the **gated step**, not to the whole item. Do everything up to the gate now:
+
+1. Do the allowed part — file it, write it, prepare it, get it to the edge of the gate.
+2. Mark the gate explicitly, in the tracker, so it is visible outside your session.
+3. Say plainly, in your update, what is waiting on a human and what will happen once they act.
+
+"Waiting on a human" is a state you report, never a place you leave work silently.
+
+## Deferring is a decision
+
+Sometimes not doing it now is genuinely right: the change is out of scope, it would balloon the diff past reviewability, it depends on a decision not yet made, or it belongs to a different work item. Those are legitimate — and they are **decisions**, which means they get said out loud with a reason, and the deferred item becomes tracked work rather than a sentence.
+
+What is never acceptable is the implied deferral: noticing, saying nothing, and moving on. The human cannot act on what you did not tell them, and neither can the next session.

package/plugins/lisa-cursor/rules/do-it-now.mdc

@@ -0,0 +1,16 @@
+---
+description: "Do It Now (load-bearing)"
+alwaysApply: true
+---
+
+# Do It Now (load-bearing)
+
+If something needs to happen eventually and **the factory is allowed to do it**, do it in this session. File the ticket, flip it to ready, add the lint rule, fix the flaky test, update the doc that just went stale. Not in a "follow-up" sentence — now.
+
+**"I'll get to that later" is not an acceptable close** for work that is in scope and permitted. A deferral costs a whole future session its context, and most of them are never picked up at all.
+
+The one exception is an **exterior human gate** — a protected deploy, a held-back PRD, a low-confidence learning, a product call only a person can make. There you do the allowed part now (file it, mark the gate, flip everything you may flip) and say plainly what is waiting on a human and why.
+
+Deferring is itself a decision. If you genuinely should not do it now, say so and say why; never leave it implied, and never leave it only in your own head.
+
+Full prose: [reference/do-it-now.md](do-it-now-reference.mdc).

package/plugins/lisa-cursor/rules/empirical-inquiry-reference.mdc

@@ -26,6 +26,7 @@ This is the inquiry counterpart to the `verification` rule: `verification` prove
 ## What this rule forbids
 
 - Presenting a guess, a recollection, or a documentation summary as established fact when it was cheap to verify and you did not.
+- **Interpreting a diff, or reporting scope, without first establishing your branch position.** Run `git rev-list --count HEAD..origin/<default>` before you read a diff and before you describe how large a change is. A worktree that is thirty commits behind renders everyone else's merged work as though it were part of your change — the observed incident reported it as massive scope creep, in reverse, and the reviewer nearly acted on it. The count is one command and it turns an ambiguous diff into an unambiguous one.
 - "Should work" / "probably" / "the docs say" as the basis for a load-bearing decision that an experiment could have settled.
 - Skipping the probe because the answer "seems obvious" — obvious answers are exactly the ones that quietly drift from reality.
 

package/plugins/lisa-cursor/rules/empirical-inquiry.mdc

@@ -21,6 +21,7 @@ Do not reason your way to a confident-sounding answer from documentation, prior
 - Presenting a guess, recollection, or doc summary as established fact when it was cheap to verify and you did not.
 - "Should work" / "probably" / "the docs say" as the basis for a load-bearing decision an experiment could have settled.
 - Skipping the probe because the answer "seems obvious" — those are exactly the ones that quietly drift from reality.
+- Interpreting a diff, or reporting scope, before establishing where your checkout sits: run `git rev-list --count HEAD..origin/<default>` first. A worktree 30 commits behind makes everyone else's changes read as yours, and the diff was reported as massive scope creep in reverse.
 - Treating a recorded "not yet" / "pending" / "blocked" / "human-gated" note as current state. It is a claim about the day it was written; probe the live state before planning around it, escalating it, or reporting it as a blocker (`stale-state-claims`).
 
 This is the inquiry counterpart to the `verification` rule (which proves completed work behaves correctly). Both reject "it looks correct" as evidence.