@codyswann/lisa 3.2.0 → 3.4.0

package/plugins/src/base/rules/reference/design-source-of-truth.md

@@ -0,0 +1,195 @@
+# Design Source of Truth
+
+Design has always leaked in one direction. A ticket arrives with a Figma frame, the frame gets
+built, and then — during implementation, during a bug fix, during a "quick" empty state nobody
+specified — new UI gets invented directly in code. Nothing ever carries it back. A year later the
+Figma file describes a product that no longer exists, and the only way to answer "what is this
+screen supposed to look like?" is to read the code, which is precisely the question the design
+source was supposed to answer.
+
+Lisa had every design obligation conditioned on a design artifact *already existing*. Ticket gate
+S12 fires only `when artifacts_attached = true`. `work-item-definition-of-ready` requires
+design-source precedence "when artifacts exist". `lisa-implement` treats a linked Figma file as a
+required tool and hard-stops when access to it fails. The nearest adjacent behavior —
+`lisa-tracker-source-artifacts` asking UI tickets to flag design-vs-code divergence — files that
+divergence as a *ticket comment*, which closes with the ticket.
+
+Every one of those is about UI that has a source. **None of them govern UI that has none.** That is
+the gap this contract closes, and it closes it on the code side, where the invented UI actually
+lives.
+
+## What the contract asks
+
+One question, per UI surface a change touches: **where did this design come from?**
+
+Not "is it pretty", not "does it use the right token", not "should this component exist" — those are
+the host design system's questions, and it answers them far better than a vendor-neutral contract
+could. This contract asks only whether the answer to the provenance question is written down.
+
+## Membership
+
+A file is a UI surface when a change makes it render something user-observable: a screen,
+component, layout, style token, visual state, or markup a user reads. The gate's default detection
+is two-tier, and the split is deliberate:
+
+- **Extensions that always render** — `.tsx`, `.jsx`, `.vue`, `.svelte` — count wherever they live.
+- **Markup and style extensions** — `.css`, `.scss`, `.sass`, `.less`, `.styl`, `.html`, `.erb`,
+  `.haml`, `.slim`, `.swift`, `.kt`, `.dart`, `.xml` — count only inside a rendering directory
+  (`components`, `screens`, `views`, `pages`, `ui`, `widgets`, `layouts`, `templates`, `atoms`,
+  `molecules`, `organisms`).
+
+The second tier is why a `.ts` barrel under `components/` is out: `src/components/atoms/index.ts`
+re-exports and renders nothing, so demanding a design source from it would be noise, and noise is
+how a gate earns its way into an ignore list. Tests, specs, stories, snapshots, `.d.ts` declarations,
+`node_modules`, and build output are excluded for the same reason.
+
+Projects tune this in `.lisa.config.json`:
+
+```json
+{
+  "designSource": {
+    "include": ["**/*.mjml"],
+    "exclude": ["src/legacy/**"]
+  }
+}
+```
+
+`include` widens the surface; `exclude` narrows it. Neither turns the obligation off — a project that
+excluded its whole UI tree would be declaring it has no UI, which review can see.
+
+## The marker grammar
+
+Exactly one declaration per file, written as an ordinary comment in whatever syntax the file already
+uses. The gate reads the annotation, not the comment characters around it, so all of these are the
+same declaration:
+
+```tsx
+// DESIGN-SOURCE: https://www.figma.com/design/AbC123/Checkout?node-id=412-1187
+```
+
+```css
+/* DESIGN-SOURCE: none — not in Figma */
+```
+
+```svelte
+<!-- DESIGN-SOURCE: none — not in Figma — internal-only debug affordance -->
+```
+
+### `DESIGN-SOURCE: <figma-url>` — sealed
+
+The surface is backed by a design node. Only a `figma.com` URL counts. A screenshot link, a Slack
+permalink, a Jira attachment, or a path to a PNG in the repo is **malformed**, not proof: those are
+copies of a design, and a copy cannot be updated when the design changes. Prefer a URL carrying a
+`node-id` so the citation resolves to the frame rather than the file.
+
+### `DESIGN-SOURCE: none — not in Figma` — the recorded exception
+
+The spelling is fixed, including the em dash, and it is load-bearing: the gate, the rule, the review
+path, and the implement path all cite the same string, so a drifted spelling silently disarms the
+gate rather than failing loudly. An optional trailing ` — <reason>` records why the surface is not
+captured at the source, and the gate surfaces reasonless markers separately (below).
+
+### Everything else
+
+`DESIGN-SOURCE:` followed by anything that is neither form is **malformed** and fails. This is not
+pedantry — it is what stops the annotation from degrading into a comment that says "design source:
+ask Priya" and passes. **Silence is a violation, never a pass.**
+
+A file that carries both a Figma URL and the none-marker is **conflicting** and fails. It is
+asserting two contradictory things about the same surface, and the gate does not pick a winner.
+
+## Sync-back is the default
+
+The order of preference is not decorative:
+
+1. **The surface already exists in Figma.** Cite the node. Nothing else to do.
+2. **Figma access is available and the surface belongs in the design source.** Reflect it in Figma,
+   then cite the node. This is the expected outcome for real product UI, and the whole reason the
+   `tool-access-gate` probe enumerates Figma as a required tool when the work item links one.
+3. **The surface genuinely does not belong in the design source.** Mark it. Debug affordances,
+   dev-only playgrounds, internal tooling, and diagnostics live here.
+
+The marker is the exception, not the default. When Figma access has been proven and a marked
+exception records no reason, the gate reports it under `syncBackPreferred` — non-blocking, because
+turning a preference into a second hard gate would make the honest exception more expensive than a
+copy-pasted Figma link, which is exactly the wrong incentive. It is a review prompt: *you could have
+synced this back — why didn't you?*
+
+## Host design-system rules stay authoritative
+
+Several Lisa host projects already carry a design-system rule of their own —
+`figma-design-system.md`, `design-system.md`, `use-the-design-library.md`. Those files are
+**host-owned**. They define the component hierarchy, the closed token vocabulary, the atom layer,
+the escape hatches, and the lint manifest that enforces all of it, and they are specific to a product
+in ways no shared contract can or should be.
+
+**This contract governs whether the design source is declared, never what to build.** It adds one
+orthogonal obligation on top of whatever the host rule already says. Where a host rule already
+mandates a Figma mapping, this contract is satisfied by that mapping — cite the node and move on.
+
+Two consequences worth stating plainly:
+
+- **Do not duplicate host content into this contract, and do not rewrite host rules to restate this
+  one.** Wire them: the host rule points at this slug for the provenance obligation, this contract
+  points at the host rule for everything else.
+- **Several host design-system rules are generated artifacts** carrying a "generated from
+  `docs/design-system-rfc.md` — do not edit this file directly" provenance header. Respect it:
+  **amend the RFC and regenerate.** A hand-edit to a generated rule is lost on the next
+  regeneration, which is worse than not making the change at all, because it looks like it shipped.
+
+## Gate semantics
+
+`scripts/design-source-gate.mjs` is the executable arm of this contract, and it **fails closed**.
+
+```
+node design-source-gate.mjs --base=origin/main [--head=HEAD] [--figma-access] [--json]
+```
+
+Exit `0` = PASS, `1` = FAIL, `2` = usage error. It classifies every changed file into one status:
+
+| Status | Verdict | Meaning |
+|---|---|---|
+| `figma-source` | pass | Sealed by a Figma node. |
+| `marked-exception` | pass | Explicitly declared as not captured at the source. |
+| `not-applicable` | pass | Not a UI surface, or a deletion — nothing to declare. |
+| `undeclared` | **fail** | A UI surface with no annotation at all. |
+| `malformed` | **fail** | An annotation whose value is neither form. |
+| `conflicting` | **fail** | Cites Figma *and* denies having a source. |
+| `unreadable` | **fail** | The changed file could not be read. |
+
+Plus two change-level failures that exist purely so the gate cannot pass on ignorance:
+`changed-files-unresolved` (the file list never materialized) and `diff-unresolved` (git could not
+compute the range). **A gate that returns PASS when it could not look proves nothing.** This is the
+same discipline `claim-evidence-mapping` applies to verification evidence and `bdd-e2e-coverage`
+applies to a missing runner: the absence of a check is never a passing check.
+
+The gate aggregates — it reports every violating file, not the first one — so a single run tells the
+implementer everything they need to fix.
+
+## Where it is enforced
+
+- **`lisa-implement`** — building or changing a UI surface includes declaring its design source, and
+  the sync-back preference applies while the work is being done, when reflecting the surface in Figma
+  is cheap. The `tool-access-gate` probe already establishes whether Figma access exists.
+- **`lisa-tdd-implementation`** — the declaration lands with the implementation, in the same commit
+  as the surface it describes.
+- **`lisa-review-local` and `lisa-quality-review`** — the gate runs on the branch diff, and a FAIL is
+  a **blocking** finding. It qualifies under `convergent-review` because it names a concrete failure
+  scenario: the design source silently diverges from the shipped product, and nobody can tell which
+  one is authoritative.
+- **`lisa-tracker-source-artifacts`** — its existing design-vs-code divergence note covers the
+  *ticket* side of the same event. It points here for the code side, so the two are one behavior
+  rather than two half-behaviors.
+
+## Bootstrap and degradation
+
+Adoption is never a backfill project. The gate judges only the surfaces the current change touched,
+so a repository with hundreds of unannotated legacy components can adopt the contract on a Tuesday
+and be green on Tuesday. Pre-existing unannotated UI is **burndown**: recorded, worked down
+opportunistically as files are touched, never treated as the current work item's blocker.
+
+A project with no Figma at all is not exempt. Every changed surface carries the marker, and the
+resulting exception list is the honest, mounting record of how much of the product lives outside its
+design source — which is far more useful than an exemption flag that makes the question disappear.
+Deleting or excluding a surface to make the gate green is a violation of the same kind as deleting a
+BDD scenario to improve coverage: mark it, do not drop it.

package/plugins/src/base/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/src/base/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/src/base/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/src/base/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/src/base/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/src/base/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/src/base/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/src/base/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/src/base/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.