@codyswann/lisa 3.2.0 → 3.4.0

package/plugins/lisa-cursor/rules/not-blocked-just-waiting-reference.mdc

@@ -0,0 +1,46 @@
+---
+description: "Waiting Is Not Blocked"
+alwaysApply: false
+---
+
+# 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-cursor/rules/not-blocked-just-waiting.mdc

@@ -0,0 +1,18 @@
+---
+description: "Waiting Is Not Blocked (load-bearing)"
+alwaysApply: true
+---
+
+# 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](not-blocked-just-waiting-reference.mdc).

package/plugins/lisa-cursor/rules/session-status-updates-reference.mdc

@@ -0,0 +1,65 @@
+---
+description: "Session Status Updates — Plain Language, and Always Say If It's Safe to Close"
+alwaysApply: false
+---
+
+# 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-cursor/rules/session-status-updates.mdc

@@ -0,0 +1,24 @@
+---
+description: "Session Status Updates — Plain Language, and Always Say If It's Safe to Close (load-bearing)"
+alwaysApply: true
+---
+
+# 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](session-status-updates-reference.mdc).

package/plugins/lisa-cursor/rules/wiki-knowledge-source-reference.mdc

@@ -14,13 +14,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/rules/wiki-knowledge-source.mdc

@@ -1,23 +1,18 @@
 ---
-description: "Wiki as Knowledge Source (load-bearing)"
+description: "Wiki as Knowledge Source — Query It on Demand (load-bearing)"
 alwaysApply: true
 ---
 
-# 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](wiki-knowledge-source-reference.mdc).