@codyswann/lisa 3.2.0 → 3.4.0

package/expo/create-only/.github/workflows/nightly-e2e-health.yml

@@ -12,7 +12,7 @@ name: 🌙 Nightly E2E Health
 #
 # All the logic lives in Lisa's reusable `nightly-e2e-health.yml` plus the
 # Lisa-shipped guard `scripts/check-nightly-e2e-health.mjs`. The contract —
-# including the 25-row fail-closed truth table and the bypass rules — is
+# including the 30-row fail-closed truth table and the bypass rules — is
 # `docs/nightly-e2e-gate.md` in Lisa. This caller owns only the project-specific
 # values: which suites, which branch, and where the gate is required.
 #
@@ -25,7 +25,10 @@ name: 🌙 Nightly E2E Health
 #   2. Leave `bootstrap_until` set to a date ~2 weeks out while you burn the
 #      suite down. Missing evidence will report but not block, with the expiry
 #      visible on every PR. A red suite still blocks. When the date passes the
-#      gate arms itself with no further action.
+#      gate arms itself with no further action. LATER, when you add a suite to
+#      the armed repo, do NOT re-open this window — give that one suite a
+#      `first_seen` anchor instead (see the note above `suites`), so the suites
+#      that were already gating stay armed.
 #   3. Add the required status check to the ruleset for the branch below. The
 #      context is `🌙 Nightly E2E Health / 🌙 Gate` — the composite of THIS
 #      job's name and the reusable's job name, byte for byte, emoji included.
@@ -130,6 +133,22 @@ jobs:
       #
       # Do NOT add a suite whose job `ci.yml` skips — a skipped job never
       # reports, and the gate would read it as missing evidence forever.
+      #
+      # ADDING A SUITE TO AN ALREADY-ARMED REPO: give it a `first_seen` anchor
+      # rather than re-opening `bootstrap_until`. A new suite has no nightly of
+      # its own yet, so without one it is row 9 (no run at all) and blocks every
+      # pull request from the moment you save this file. `first_seen` forgives
+      # THAT SUITE for 14 days (`grace_days` may shorten it) while every other
+      # suite stays armed — which is exactly what widening the global window
+      # would have destroyed. It may not be in the future, and the window may
+      # not run beyond `bootstrap_max_days`; both are hard failures, not clamps.
+      #
+      #   {
+      #     "label": "Playwright browser e2e",
+      #     "workflow": "ci.yml",
+      #     "match": { "mode": "run" },
+      #     "first_seen": "2026-08-10T00:00:00Z"
+      #   }
       suites: |
         [
           {

package/package.json

@@ -120,7 +120,7 @@
     }
   },
   "name": "@codyswann/lisa",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

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

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

package/plugins/lisa/.codex-plugin/plugin.json

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

package/plugins/lisa/.codex-plugin/skills/lisa-implement/SKILL.md

@@ -155,7 +155,9 @@ IF it is a Fix (bug), execute the Reproduce sub-flow FIRST:
 
 For any Fix flow, and for any Build flow that changes user-visible behavior, regression coverage is a required deliverable at the highest practical observation level for the reported surface. If the project has a browser, device, or end-to-end harness for that platform (for example Playwright, Maestro, Detox, Cypress, or an equivalent runtime), the task plan and definition of done MUST include a deterministic regression spec against the reported surface, using mocked or seeded data where needed. This is alongside unit or integration coverage, not a substitute for it. For **frontend work** the deliverable is defined by the `bdd-e2e-coverage` rule and has two halves, both landing in this PR: the Gherkin scenario (stable ID, required platforms) added or updated in the project's behavior contract, and aligned automation in the project's configured runner for **every** platform that scenario requires — no runner substitutes for another, because they guard different platforms of the same behavior. The coverage gate must pass and the matrix and burndown be regenerated before the item is done. Cite the rule; do not restate its scenario, waiver, or bootstrap mechanics here.
 
-For work that adds or changes **persistent state**, the `reset-seed-coverage` rule adds a second non-demotable deliverable landing in this same PR: every entity the item introduces or changes is classified in the project's state contract (`fixture-owned` / `preserve` / `derived-rebuild` / `forbidden`) with a reason and an owner, anything `fixture-owned` declares its ownership predicate and is actually swept, and the state-classification check passes. Writing a flow that creates a record and deletes it only on its happy path does NOT satisfy this — that is the leak, not the coverage. Cite the rule; do not restate its policy, waiver, or bootstrap mechanics here.
+For work that adds or changes a **UI surface**, the `design-source-of-truth` rule adds a second non-demotable deliverable landing in this same PR: every UI surface the change touches declares where its design came from. Figma is the source of truth, so **prefer sync-back** — if the surface is not in Figma yet and the tool-access preflight proved Figma access, reflect it there and cite the node with `DESIGN-SOURCE: <figma-url>`. Only when the surface genuinely does not belong in the design source (debug affordance, dev-only playground, internal tooling) does it carry the exception marker `DESIGN-SOURCE: none — not in Figma`, ideally with a trailing reason. `scripts/design-source-gate.mjs` decides this deterministically and fails closed on anything it cannot resolve; a FAIL blocks the item exactly as a failing coverage gate does. Host design-system rules (`figma-design-system`, `design-system`, `use-the-design-library`, or the project's equivalent) stay authoritative about *what* to build — this obligation is only about declaring the source. Cite the rule; do not restate its marker grammar, host-precedence, or bootstrap mechanics here.
+
+For work that adds or changes **persistent state**, the `reset-seed-coverage` rule adds a third non-demotable deliverable landing in this same PR: every entity the item introduces or changes is classified in the project's state contract (`fixture-owned` / `preserve` / `derived-rebuild` / `forbidden`) with a reason and an owner, anything `fixture-owned` declares its ownership predicate and is actually swept, and the state-classification check passes. Writing a flow that creates a record and deletes it only on its happy path does NOT satisfy this — that is the leak, not the coverage. Cite the rule; do not restate its policy, waiver, or bootstrap mechanics here.
 
 The team lead may not waive, defer, demote, or phrase this regression spec as "optional", "if cheap", "nice to have", or equivalent. The only permitted exits are:
 

package/plugins/lisa/.codex-plugin/skills/lisa-quality-review/SKILL.md

@@ -16,6 +16,13 @@ For each changed file, evaluate:
 3. **Test coverage** -- Tests present? Testing behavior, not implementation details? Edge cases covered?
 4. **Documentation** -- JSDoc on new functions explaining "why"? Preambles on new files?
 5. **Code clarity** -- Readable variable names? Unnecessary complexity? Could a new team member understand this?
+6. **Design source** -- For UI surfaces, does each changed file say where its design came from? Run the deterministic gate rather than judging by eye:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/design-source-gate.mjs" --base=main --head=HEAD
+   ```
+
+   Exit 1 is a **Critical** finding under the `design-source-of-truth` rule -- the change is blocked until every UI surface either cites a Figma node (`DESIGN-SOURCE: <figma-url>`, the preferred fix -- sync it back) or carries the exception marker `DESIGN-SOURCE: none — not in Figma`. The gate fails closed: an unreadable file or an uncomputable diff is a FAIL, not a pass. Host design-system rules (`figma-design-system`, `design-system`, `use-the-design-library`, or the project's equivalent) stay authoritative about what to build; this checks only that the source is declared. If the gate script is absent, say so in the review rather than skipping silently.
 
 ## Output Format
 

package/plugins/lisa/.codex-plugin/skills/lisa-review-local/SKILL.md

@@ -14,6 +14,33 @@ maintainability feedback are non-blocking unless a repository rule or work item
 explicitly makes them release criteria. A blocking finding without a concrete
 failure scenario is malformed and must be filtered out.
 
+One deterministic gate runs ahead of the judgement-based review and is exempt
+from the confidence filtering below, because it is decided by a script rather
+than by an agent's opinion.
+
+**Design-source gate (`design-source-of-truth` rule).** Run it against the
+branch diff before step 1:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/design-source-gate.mjs" --base=main --head=HEAD
+```
+
+Exit 0 = PASS, exit 1 = FAIL. A FAIL is a **blocking** review finding and is
+reported verbatim at the top of the review — it is never scored, never filtered
+by confidence, and never demoted to a nitpick. 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. The gate fails closed, so an unresolvable diff or an unreadable
+file is a FAIL too. Each violation is fixed one of two ways, sync-back first:
+reflect the surface in Figma and cite the node with `DESIGN-SOURCE: <figma-url>`,
+or — only when the surface genuinely does not belong in the design source — mark
+it `DESIGN-SOURCE: none — not in Figma`. Host design-system rules
+(`figma-design-system`, `design-system`, `use-the-design-library`, or the
+project's equivalent) remain authoritative about what to build; this gate only
+asks whether the source is declared. If the gate script is not present (the
+project predates the plugin version that ships it), say so explicitly in the
+review — a silent skip is not one of the exits.
+
 To do this, follow these steps precisely:
 
 1. Use a Haiku agent to check the current git state:

package/plugins/lisa/.codex-plugin/skills/lisa-tdd-implementation/SKILL.md

@@ -71,6 +71,7 @@ TDD Cycle:
 
 - Write the minimum production code to make the test pass
 - Do not optimize, do not add features beyond what the test requires
+- For any UI surface the implementation adds or changes, the `design-source-of-truth` rule requires its design-source declaration to land in the same commit as the surface it describes — `DESIGN-SOURCE: <figma-url>` when the surface is backed by a Figma node (sync it back first if Figma access exists), or the exception marker `DESIGN-SOURCE: none — not in Figma` when it genuinely is not captured at the source. `scripts/design-source-gate.mjs` fails closed on an undeclared surface. Cite the rule; do not restate its marker grammar here.
 - The goal is the simplest code that makes the test green
 
 ### REFACTOR Phase

package/plugins/lisa/.codex-plugin/skills/lisa-tracker-source-artifacts/SKILL.md

@@ -93,6 +93,8 @@ Mocks define visual *intent*, not implementation shortcut. Every UI-touching tic
 
 If no existing component fits, building a new one is an explicit decision that must be recorded in the ticket (with rationale) before implementation. Lovable-generated components are never the reuse target — always use the project's own components.
 
+The divergence note above covers the **ticket** side of this event. The **code** side is governed by the `design-source-of-truth` rule: a UI surface built with no Figma source behind it is either synced back to Figma and annotated `DESIGN-SOURCE: <figma-url>`, or explicitly marked `DESIGN-SOURCE: none — not in Figma`, and review fails closed if neither happened. Cite the rule for the code obligation rather than restating it here — a ticket comment closes with the ticket, the annotation stays with the surface.
+
 ## 8. Preservation gate (run after creating tickets)
 
 Before declaring done, verify every extracted artifact is reachable from the created tickets.

package/plugins/lisa/rules/eager/design-source-of-truth.md

@@ -0,0 +1,38 @@
+# Design Source of Truth (load-bearing)
+
+**Figma is the design source of truth, and every UI surface a change touches declares where its design came from.** A changed UI surface that neither cites a Figma node nor carries the designated marker is a contract violation — and so is a surface whose declaration the gate cannot resolve.
+
+**One vendor-neutral contract, cited by** `lisa-implement`, `lisa-tdd-implementation`, `lisa-review-local`, `lisa-quality-review`, and `lisa-tracker-source-artifacts` (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never divergent per-skill prose).
+
+## Membership
+
+Membership is **surface, not repo name or file extension**: a file is in scope the moment a change makes it render something user-observable — a screen, component, layout, style token, visual state, or markup a user reads. Barrels, pure-logic modules, tests, stories, generated output, and vendored code are out. Projects narrow or widen the default detection through `designSource.include` / `designSource.exclude` in `.lisa.config.json`; they never turn the obligation off.
+
+## The two declarations
+
+Exactly one of these, written as an ordinary comment in whatever syntax the file uses:
+
+| Form | Means |
+|---|---|
+| `DESIGN-SOURCE: <figma-url>` | The surface is backed by a Figma node — it already existed there, or it was synced back. |
+| `DESIGN-SOURCE: none — not in Figma` | The surface is deliberately not captured at the design source. |
+
+The marker's spelling is fixed and load-bearing; a drifted spelling silently disarms the gate. An optional trailing ` — <reason>` records why. Only a `figma.com` URL seals a surface: a link to a screenshot, a Slack thread, or any other mock is **malformed**, not proof.
+
+## Sync-back is the default; the marker is the exception, not the default
+
+When the flow has proven Figma access (the `tool-access-gate` probe), reflecting the surface in Figma and citing the node is the expected outcome. Reach for the marker only when the surface genuinely does not belong in the design source — a debug affordance, a dev-only playground, a throwaway internal tool. The gate reports every marked exception so review can challenge it, and reports a reasonless exception separately when Figma access was available.
+
+## Host design-system rules stay authoritative
+
+Projects that carry their own design-system rules (`figma-design-system`, `design-system`, `use-the-design-library`, or an equivalent) keep them. This contract never restates component hierarchy, token vocabulary, or reuse policy, and never overrides them. It asks one orthogonal question the host rules do not: is the design source declared?
+
+## The gate fails closed
+
+`scripts/design-source-gate.mjs` decides the change deterministically. It fails on an undeclared surface, a malformed annotation, a file that both cites Figma and denies having a source, a changed file it could not read, and a diff it could not compute. **A design-source violation is a blocking review finding, never a warning** — it is not demoted to "optional", "if cheap", or a follow-up. A gate that passes on what it could not read proves nothing, so it never does.
+
+## Bootstrap and degradation
+
+Adoption never demands a retroactive backfill: the gate judges **only the surfaces this change touched**. Pre-existing unannotated UI is burndown, recorded and worked down, not this work item's blocker. If a project has no Figma at all, that is not an exemption — every changed surface carries the marker, and the resulting exception list is the honest record of how much of the product lives outside its design source. Behavior obligations for the same surfaces are unchanged and still governed by `bdd-e2e-coverage`.
+
+Full contract (marker grammar, gate semantics, host-rule precedence, bootstrap procedure): [reference/design-source-of-truth.md](../reference/design-source-of-truth.md).

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