@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-devin/rules/reference/leaf-only-lifecycle.md

@@ -0,0 +1,227 @@
+# Leaf-Only Build-Ready Invariant, Parent Status Rollup & Terminal Native Closure
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## Leaf-Only Build-Ready Invariant (load-bearing)
+
+**Build-ready means a directly implementable leaf work unit.** Containers never carry build-ready.
+
+A leaf is structurally defined: **no open children** AND not an Epic — the by-design leaf types (Bug, Task, Sub-task, Improvement) plus a childless Story or Spike. A container is an **Epic**, or any item of any type that has acquired open child work.
+
+## Invariant
+
+- **At decomposition/write time** — only leaves receive the `ready` role. Parent containers are created in their non-ready state.
+- **At validate time** — `*-validate-*` FAILs any container carrying the build-ready role. The parent-declared gate (S7) does **not** FAIL a build-ready leaf with no parent (flat Task/Improvement or childless Story/Spike); a Sub-task is the one exception and always needs a parent.
+- **At claim time** — build-intake claims leaves only. A container with a stale build-ready role is rolled up or safe-blocked, NEVER implemented.
+
+## Childless-parent exception
+
+A childless item is structurally a leaf — and may be build-ready **unless its type is Epic**:
+
+- **Task, Bug, Story, Spike, or Improvement with no children** → leaf → may be build-ready. A Story ships directly as one increment and a Spike *is* the investigation unit; neither needs sub-items to be implementable, so a childless one must not be stranded.
+- **Epic with no children** → still NOT build-ready. An Epic is a pure rollup container by design — its body is a high-level summary, never directly implementable — so a childless build-ready Epic is an incomplete decomposition or a mis-applied role. Repair: decompose into leaves, or reclassify to a leaf type.
+
+## Parent state rollup (priority order, first match wins)
+
+Evaluate over the env ladder `in-progress < dev < staging < production` (the ordered keys of the project's env-keyed `done` map; single-env projects have only the production rung):
+
+1. Any leaf is **blocked** → parent rolls up to **blocked / attention-needed**.
+2. Else **every** required leaf has shipped to some env → parent rolls up to the **least-advanced** env among them (all `On Stg` → `On Stg`; mixed `On Dev`+`On Stg` → `On Dev`; all production → terminal `done`).
+3. Else any leaf has **started** (claimed/in review, or shipped while a sibling has not) → parent is **in-progress** (`claimed`).
+4. Else (leaves exist but none started) → parent unchanged.
+
+**Blocked dominates — but it must say which leaf and which kind.** A parent that rolls up to `blocked` names the blocking leaf (with the path to it) and the **class** of the hold, derived by `rollup-blocker-classification` from recorded signals only:
+
+| Class | Recorded signal on the leaf | Who must act |
+|---|---|---|
+| `spec-defect` | the `spec_defect` marker (human-applied only) | a person rewrites the acceptance criteria — nothing external will ever clear it |
+| `human-input` | the `human_needed` marker | a person supplies the input (access, credential, product decision) |
+| `hard-blocker` | an open `is blocked by` link | nobody — it clears when that work closes |
+| `unknown` | none of the above | a person says which kind it is, and records it |
+
+Never infer a class from prose, and never auto-apply `spec_defect`: judging a criterion unbuildable is a human call, and `unknown` is the honest answer. A rollup that examined nothing — unreadable tracker, no children, no readable child — **fails**; it never reports not-blocked.
+
+**Blocked dominates.** A parent reaches an env only once all required leaves have reached at least that env. Intermediate-env rollup (`On Dev`/`On Stg`) happens, but native closure fires only at production `done`. Optional/won't-do children do not hold a parent open. Rollup is recursive — bottom-up. The parent never carries `ready`; a container found in `ready` is reconciled by rolling it up from its children.
+
+## Terminal native closure
+
+When a leaf reaches the true terminal `done` (the production / final-env value), also finalize via the tracker's native completion mechanism:
+
+- **GitHub** — `gh issue close <n> --reason completed` after the terminal label.
+- **Linear** — move workflow `state` to the team's Done.
+- **JIRA** — transition to terminal Done/Resolved/Closed; verify `statusCategory = Done`.
+
+Intermediate env-keyed states (`status:on-dev`, `On Stg`, etc.) remain open. Idempotent — if already closed, report and continue.
+
+### Exactly one lifecycle role survives closure
+
+The terminal transition retires **every** other lifecycle role the item carries, not only the one it was last known to hold. Resolve the complete configured set — `ready`, `claimed`, `review` where bound, `blocked`, and every env-keyed `done` value — and remove each one that is present, except the terminal role being applied. Type, component, priority, and provenance labels are untouched.
+
+Retiring only the claimed role assumes the item travelled the happy path, and items skip stages: one reaches completion straight from `ready` having never been claimed, another is unblocked and closed still carrying `blocked`. Measured on a live tracker: 34 closed issues carried an active lifecycle role, six of them carrying `ready` and the terminal role at once.
+
+**This is not cosmetic.** A queue scan filters on the synthesized role, not the native closed state, so a closed item still reading `ready` is handed back out — one already-shipped fix was independently rebuilt end to end before a push-time gate caught it.
+
+Three constraints on how it is done:
+
+- **Remove only roles the item actually carries.** Naming an absent label is a 404, which fails a clean closure and makes a repeat run fail where the first one succeeded.
+- **Verify by re-reading.** Confirm the final closed state and the unique terminal role from a **fresh read of the item**, never from the write's own response. A write that reports success is not evidence of the state it intended to produce — asserting otherwise is the same defect as the drift being repaired, one layer up.
+- **Never re-complete an abandoned item.** Refuse to apply a terminal `done` role to work closed as not-planned. Duplicate closeout below remains allowed, but removes lifecycle labels without adding a done label; verify that no lifecycle role remains.
+
+Trackers with a native lifecycle field (JIRA, Linear) get exclusivity for free: the field that closes the item is the field a queue scan filters on, so the two cannot disagree. GitHub Issues has no lifecycle beyond open/closed, so Lisa synthesizes one in labels and inherits a reconciliation duty the others do not have. That asymmetry is tracked separately in `CodySwannGT/lisa#3479`; this section is the obligation, not the redesign.
+
+Duplicate closeout is a narrow terminal exception: build intake may close a claimed item without a PR only when `ticket-triage` returns `DUPLICATE_ALREADY_FIXED` with a canonical item reference and empirical base-branch proof. Close it through provider duplicate semantics, not as completed build work. `BLOCKED`, ambiguous, duplicate-of-open, and other human-owned dispositions are not auto-closed.
+
+---
+
+This is the single vendor-neutral source of truth for three coupled lifecycle rules. Every `*-to-tracker`, `*-write-*`, `*-validate-*`, and `*-build-intake` skill cites this rule rather than restating it, so per-vendor logic does not drift.
+
+1. **Leaf-only invariant** — only an independently implementable **leaf work unit** may carry the build-ready role. A parent/container with child work is never directly build-ready.
+2. **Parent status rollup** — a parent/container's lifecycle state is *derived* from its children, never set independently.
+3. **Terminal native closure** — when a leaf work unit reaches the configured terminal `done` role, Lisa also closes / resolves / completes it using the provider's native mechanism where one exists. Intermediate done-like environment states stay open.
+
+The first two are the same idea seen from opposite ends: a parent never enters the build queue as work; it only ever *reflects* the state of the leaves underneath it. The third keeps the provider's native open/closed signal aligned with Lisa's terminal lifecycle state so finished work does not linger as open.
+
+## Why this exists
+
+Build intake processes whatever carries the build-ready role (the `ready` role — see `config-resolution`). A parent container (an Epic, a Story, a Linear Project, any issue with child work) is not a unit of implementation; it organizes work. If a parent is marked build-ready, an agent may try to implement the container itself unless intake gates it first — the wrong permission and lifecycle boundary. This surfaced in real PRD intake: a PRD decomposed into an Epic, Stories, and Sub-tasks, and *every* item received the build-ready label, so a subsequent build pass would have tried to "implement" the Epic.
+
+The fix is not vendor-specific. It belongs here, in a cross-vendor rule, and every writer / validator / intake path enforces it.
+
+## Container vs. leaf taxonomy
+
+A **leaf work unit** is an individually implementable item with **no open child work**. Structurally, that is *any work item with no open children except an Epic*: the by-design leaf types **Bug, Task, Sub-task, Improvement**, plus a **childless Story or Spike** (a Story is a directly shippable increment and a Spike is itself the investigation unit — neither needs sub-items to be implementable). These are what an agent claims and implements. A leaf work unit is also single-repo (the `repo-scope-split` rule).
+
+A **container** organizes other work and is never directly implemented:
+
+| Class | Examples by type | May carry build-ready? |
+|---|---|---|
+| **Leaf work unit** | Bug, Task, Sub-task, Improvement, or a childless Story / Spike — anything with no open children **except an Epic** | **Yes** |
+| **Container** | An **Epic**, or *any* item (of any type) that has open child work | **No** — state rolls up from children |
+
+The classification is **structural, not nominal**: an item is a container if it has open child work, regardless of its declared type. A "Task" that has acquired sub-tasks is a container for rollup purposes. The single nominal exception is the **Epic**, which is a pure rollup container by design and is treated as a container even when childless; for every other type the presence of children is decisive. See the childless-parent exception below for the converse case.
+
+### How each vendor encodes hierarchy
+
+The invariant is vendor-neutral; the mechanics of "has child work" differ. A skill resolves child membership using the native hierarchy first, falling back to text/metadata links where the vendor has no native parent/child:
+
+- **GitHub Issues** — native **sub-issues** (parent ↔ child issue graph), plus task-list checkboxes and `Blocked by #<n>` / parent references in the body. Epic and Story are modeled as parent issues; their Sub-tasks are sub-issues.
+- **JIRA** — native **Epic → Story → Sub-task** hierarchy: Epic link / parent field for Stories under an Epic, and the subtask relationship for Sub-tasks under a Story/Task. Issue links (`blocks` / `is blocked by`) express cross-item dependencies but are not parentage.
+- **Linear** — **Project** (the Epic equivalent) groups **Issues** via `projectId`; an Issue groups **sub-issues** via `parentId`. Project state and Issue state are native. Relations (`save_issue_relation`) express dependencies, not parentage. (Initiatives are not used — see `config-resolution`.)
+
+Where a vendor lacks native hierarchy for a given pair, a text link or metadata marker establishes the relationship (per PRD #522 non-goals: vendors need not expose identical native hierarchy features).
+
+## Leaf-only invariant (the rule)
+
+**Build-ready means a directly implementable leaf work unit.** Therefore:
+
+- **At decomposition / write time** — when a PRD decomposes into a hierarchy, only the leaf work units receive the `ready` role (status/label). Parent containers (Epic, Story, Project, and any parent issue that has child work) are created in their normal non-ready state and never receive the build-ready role directly. The leaves are what downstream build intake will claim.
+- **At validate time** — the `*-validate-*` gate FAILs any container carrying the build-ready role. This is the symmetric write-side guard: a stale or hand-applied build-ready role on a parent is a lifecycle error. Conversely, the parent-declared gate (S7) does **not** FAIL a build-ready leaf that has no parent: a flat Task/Improvement or a childless Story/Spike may stand alone, so a missing parent on such a leaf is `N/A`. Stranding a parentless build-ready leaf would directly violate the "must not be stranded" guarantee below. (A Sub-task is the one exception — it always requires a parent.)
+- **At claim time** — build intake scans for the `ready` role but dispatches **only leaf work units**. A container that still carries a stale build-ready role (e.g. applied before this rule existed) is **not dispatched**: intake either moves it into the vendor's parent/container progress state or safely blocks it with a clear lifecycle-repair message. Intake never silently implements a container.
+
+The permission boundary is the maintainer-applied build-ready role, not authorship — do not add author-based guards (PRD #522 non-goal). This rule narrows *what* may carry that role, not *who* may apply it.
+
+## Childless-parent exception
+
+A childless item is, structurally, a leaf — and may be build-ready **unless its issue type is Epic**.
+
+- A **Task, Bug, Story, Spike,** or **Improvement** with no children → leaf → may be build-ready. Many real tickets are flat Tasks with no sub-tasks; just as common, a **Story** is implemented directly as a single shippable increment and a **Spike** *is* the investigation work unit. None of these need to be decomposed to be claimable, and this rule must not strand them. (A childless Story/Spike promoted to a leaf this way is single-repo like any other leaf — see `repo-scope-split`.)
+- An **Epic** with no children → still **not** build-ready. An Epic is a pure rollup container by design: its body is a high-level summary, never a directly implementable unit, so a childless Epic carrying the build-ready role is an incomplete decomposition or a mis-applied role — not work. The correct repair is to decompose it (add leaf children) or reclassify it to a leaf type — not to claim it.
+
+So the exception is narrow only at the top: childlessness promotes every type **except Epic** to a build-ready leaf. A childless Epic is never directly implementable; everything else, when childless, is.
+
+## Parent status rollup (the state machine)
+
+A parent/container never sets its own lifecycle state; it **derives** it from the roll-up of its children's states. Rollup is evaluated whenever a child transitions — the **forward** arm runs in each `*-build-intake` done step the moment a leaf reaches `done`, walking the leaf's ancestor chain (see Citation → Rollup) — or when intake observes the child set, with `repair-intake` as the **recovery** net for parents left un-rolled. Using the canonical build-lifecycle roles from `config-resolution` (`ready`, `claimed`, `review`, `blocked`, `done`):
+
+Evaluate over the **env ladder** `in-progress < dev < staging < production` — the ordered keys of the project's env-keyed `done` map, with `claimed`/`review` as the rung below the first env (a single-environment project has only the `production` rung). Take the **first** match:
+
+| If among the required leaves… | …the parent rolls up to | Role |
+|---|---|---|
+| any leaf is **blocked** | blocked / attention-needed | `blocked` |
+| else **every** required leaf has shipped to some env (each is at a `done`-map value) | the **least-advanced** env among them on the ladder | env-keyed `done[min-env]` (terminal `done` when that env is production) |
+| else any leaf has **started** (claimed / in review, or shipped to some env while a sibling has not) | active / in-progress | `claimed` (or `review` where supported — see below) |
+| else (leaves exist but none started) | unchanged (parent stays in its non-ready container state) | — |
+
+The middle two rungs are the same idea seen at two resolutions: a parent reaches an env only once **all** its required leaves have reached **at least** that env. So all leaves at `On Stg` → parent `On Stg`; a mix of `On Dev` and `On Stg` → parent `On Dev` (the set as a whole has only fully reached dev); any leaf still `claimed`/`review` (not yet shipped anywhere) holds the parent at `claimed`. In a single-environment project the only env rung is production, so this collapses to the familiar "all leaves `done` → parent `done`, else `claimed`."
+
+Notes:
+
+- **Blocked dominates.** A single blocked leaf surfaces blocked/attention on the parent even if other leaves are progressing, so a human sees the parent needs attention.
+- **Blocked must name its leaf and its class.** "Blocked" alone is a single bit, and it is lossy in the one dimension that decides what the operator does next. Two holds that render identically are not the same problem: one waits on an external event and may clear with nobody touching it; the other waits on a person rewriting an acceptance criterion and will never clear on its own. Rendered the same, the second class accumulates silently — measured on one Epic at two occurrences, 32 identical hold comments and six weeks, while the initiative was two-thirds complete both times (#3045). See **Classifying a hold** below.
+- **"Required" leaves.** Optional or won't-do children do not hold a parent open; only the leaves that must ship for the parent to be complete are counted toward the env-rollup check.
+- **Least-advanced env wins.** The parent reflects the env the whole required set has collectively reached — never an env ahead of its laggard leaf. Native closure (below) fires only when the resolved env is the production/terminal value, never at an intermediate env (`On Dev`/`On Stg`).
+- **Rollup is recursive.** An Epic rolls up from its Stories, each of which rolls up from its own leaves. Evaluate bottom-up: a Story reaches an env only when its leaves have all reached at least that env; an Epic reaches it only when its Stories have.
+- **Vendor support varies.** Apply the rollup state the vendor can express. Where a vendor has no native intermediate state, use the nearest configured role or a metadata/comment signal rather than forcing a non-existent status (PRD #522 non-goal: vendors need not expose identical states).
+- **The parent never carries `ready`.** `ready` is a *human* "this is buildable, claim it" signal and only ever lives on leaves. Rollup moves a parent between non-ready container states (in-progress / per-env / blocked / terminal); it never sets the parent to `ready`. A container found carrying `ready` is a leaf-only-invariant violation — recompute its rolled state from its children and apply that (see `repair-intake`).
+
+### Classifying a hold
+
+`rollup-blocker-classification` (`scripts/rollup-blocker-classification.mjs` under the active Lisa plugin root) is the single installed implementation. It takes the child graph the vendor reader already produced and returns, per held leaf, a class and the actor who must clear it:
+
+| Class | Recorded signal on the leaf | Who must act | Clears on its own? |
+|---|---|---|---|
+| `spec-defect` | the `spec_defect` marker (`config-resolution` → Build markers) | a person rewrites the acceptance criteria | never |
+| `human-input` | the `human_needed` marker | a person supplies the input — access, a credential, a product decision | no |
+| `hard-blocker` | at least one **open** `is blocked by` link | nobody | yes, when that work closes |
+| `unknown` | none of the above | a person says which kind it is, then records it | no |
+
+Four properties are load-bearing:
+
+1. **Recorded signals only.** A class comes from a marker or a link somebody wrote, never from reading the item's prose. There is no heuristic to drift.
+2. **It never reclassifies.** Deciding an acceptance criterion is unbuildable is a human product call. The tool makes the distinction *recordable and visible*; it does not make it. `unknown` is the honest answer, and it names the person who must resolve it rather than guessing.
+3. **A transparent parent is not the blocker.** A held item whose own children include a held one is reported *through*: the rollup names the leaf at the bottom of the chain and the path to it (`#1495 -> #1515 -> #1547`), which is what turns a five-level descent into one read.
+4. **It fails rather than reporting all-clear.** An unreadable tracker, a container with no children, and children none of which could be read each return a refusal, not `not-blocked`. A rollup that examined nothing and reported clean would be the same defect one level up.
+
+The report is **composed per class**: a class with nothing in it produces no text, so the summary and the per-item lines cannot disagree (the `#3101` shape). It also carries a fingerprint of `container + held refs + classes`, so a cycle whose verdict is unchanged has nothing new to post and stays quiet — the 32 identical hold comments were one verdict restated on a schedule.
+
+### The rollup env states are the configured "done" map — multi-env capable
+
+The env rungs are whatever the project configures for `done` — which is **env-keyed** (`config-resolution` "Env-keyed `done`"): a `done` map keyed by environment (`dev`, `staging`, `production`), each leaf's env resolved from its merged PR's base branch. This rule does **not** hardcode a `dev → staging → prod` promotion chain as required — that is a project-specific deploy topology; the ladder is simply the ordered keys of the project's `done` map. A downstream project with dev/staging/prod environments rolls a parent up to the least-advanced env value its required leaves have collectively reached (an intermediate-env parent state, e.g. `On Stg`), and only to the production `done` value once every required leaf is at production. The rule stays generic and multi-env capable.
+
+Intermediate-env rollup and terminal native closure are distinct: a parent **rolls up to** an intermediate env (`On Dev`/`On Stg`) as its required leaves reach it, but native closure (next section) fires **only** at the production/terminal `done` value. A parent sitting at `On Stg` is correctly rolled up *and* still open.
+
+**Single-environment collapse (this repo).** The collapse is a property of the **resolution**, not of the declaration. `.lisa.config.json` declares `github.labels.build.done` as the generic **env-keyed map** — `dev: status:on-dev`, `staging: status:on-stg`, `production: status:done` — which is exactly the shape `lisa-setup-github` creates by default. What this repo lacks is deploy *branches*: `deploy.branches` maps only `production → main`, so `production` is the sole reachable rung and every merge this repo can make resolves to `status:done`. For GitHub the build lifecycle therefore runs one chain in practice: `ready → claimed (in-progress) → done`, and the rollup terminal state is `status:done`. Do not read the collapse as an absent map: code that reads the `done` role must still resolve the merged PR's base branch through `deploy.branches` and take that env's rung, in this repo as in any other — assuming a scalar here would read the wrong rung the moment a deploy branch is added. Projects with more deploy branches differ only in how many rungs are reachable, not in the declared shape.
+
+## Terminal native closure
+
+The configured terminal `done` role is not just another label or status. Once a **leaf work unit** reaches the true terminal `done` value, Lisa must also finalize the item through the tracker's native completion mechanism when the tracker supports one:
+
+| Tracker | Terminal native action |
+|---|---|
+| GitHub Issues | `gh issue close <number> --reason completed` after applying the terminal `done` label |
+| Linear | move the Issue's native workflow `state` to the team's configured Done / Completed state after applying the terminal `done` label |
+| JIRA | transition to the configured terminal Done / Resolved / Closed status and verify the resulting issue is in `statusCategory = Done` with a resolution when the workflow requires one |
+| Provider without a close / archive concept | no-op; the terminal lifecycle role is sufficient |
+
+This action is **terminal-only**:
+
+- Intermediate env-keyed states such as `status:on-dev`, `status:on-stg`, `On Dev`, or `On Stg` remain open / unresolved / active. They are deployment waypoints, not terminal completion.
+- A single-environment project whose `done` resolves to one value treats that value as terminal. In this repo, `production: main` means `status:done` / `Done` is terminal.
+- A multi-environment project treats only the production / final environment's `done` value as terminal unless the project explicitly configures `done` as a single string. Do not close native work items at lower environments.
+- Duplicate closeout is a narrow terminal exception: build intake may close a claimed item without a PR only when `ticket-triage` returns `DUPLICATE_ALREADY_FIXED` with a canonical item reference and empirical proof that the canonical fix is present on the relevant base branch. That closeout uses the provider's duplicate semantics (`Duplicate` resolution, duplicate/canceled state, or GitHub not-planned close with a duplicate link/comment), not the normal "completed build" reason. `BLOCKED`, ambiguous, duplicate-of-open, and other human-owned dispositions are not auto-closed.
+- The native finalization must be idempotent. If the item is already closed / completed / resolved, report that and continue.
+- If a provider exposes no native close / archive operation, or a project has not configured the native Done state, record a capability-aware no-op or setup error according to the vendor skill. Do not invent a state name.
+
+## Citation
+
+Skills that enforce this invariant or perform rollup cite this rule by slug (the `leaf-only-lifecycle` rule) instead of restating it:
+
+- **Decomposition / write** (`*-to-tracker`, `*-write-*`) — apply the `ready` role to leaves only; never to containers.
+- **Validate** (`*-validate-*`) — FAIL a container carrying the build-ready role; FAIL a childless **Epic** marked build-ready (a childless Story/Spike is a valid leaf and passes).
+- **Build intake** (`*-build-intake`, `tracker-build-intake`) — dispatch leaves only; move or safe-block containers with stale build-ready roles according to vendor lifecycle semantics.
+- **Rollup** — derive parent state from children per the state machine above. The **forward**
+  rollup fires the moment a leaf transitions to `done`: each `*-build-intake` done step (`3d.1`)
+  walks the leaf's ancestor chain and invokes `*-sync --rollup`, so a parent advances/closes as
+  soon as its last required child ships rather than waiting on a cron. `*-sync --rollup` is the
+  single rollup implementation; `repair-intake` calls the same path as the **recovery** net,
+  closing out parent/container rollups that were left open after every required child became
+  terminal — e.g. children closed outside the Lisa flow (external automation), or completed while
+  no forward `*-build-intake` cycle ran.
+- **Terminal native closure** (`*-build-intake`, `repair-intake`, terminal helpers) — after a leaf
+  or all-terminal rollup parent reaches the true terminal `done` role, finalize it through the
+  provider's native close / complete / resolve mechanism where available; never do this for
+  intermediate env states.
+
+This is the inverse-direction companion to `repo-scope-split` (which governs a leaf's *repo* scope); together they define what a build-ready leaf work unit is: directly implementable, single-repo, childless-or-leaf-typed.

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

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

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

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

package/plugins/lisa-devin/rules/reference/measurement-integrity.md

@@ -0,0 +1,119 @@
+# Measurement Integrity
+
+How an audit, sweep, or population count arrives at a confident wrong number, and the mechanical steps that catch each way.
+
+## The unifying property
+
+**Every failure here produces output that looks exactly like an answer.** None throws, none warns, none reports partial. The wrong number is indistinguishable from the right one by inspecting the result, which is why it survives review and gets cited.
+
+That has a direct consequence for remedies: **a step that requires the auditor to notice something has already failed.** Every recommendation below is shaped as an action that is either performed or not — validate the detector against known-true items, assert the end-of-pages signal, pair a negative with a positive control. "Be careful about scope" is not one of these.
+
+## The membership test
+
+This is a method, not a bestiary. A failure belongs here when **all three** hold:
+
+1. **The output is well formed.** No exception, no warning, no truncation marker, no partial flag.
+2. **The error is invisible from the artifact alone.** Reading the result — the number, the list, the report — cannot distinguish it from a correct one.
+3. **A mechanical step would have caught it.** Something performed-or-not, not a judgement. If no such step exists, it is a hazard worth documenting but it is not a mode here, because the entry earns its place by supplying the check.
+
+**The list is open.** It is currently six modes in two families plus one adjacent family. An earlier four-item version of a related list felt complete at four and was not; a taxonomy is the artifact most likely to be believed finished, and its own characteristic failure is a reader who stops looking once their case appears covered. Condition 3 is what lets you add to it rather than merely consult it.
+
+## Family A — the instrument mis-measures
+
+Six modes fall out of two axes: **direction** (does it under- or over-report?) and **stage** (does it fail while *enumerating* candidates, or while *matching* them?). All four cells are occupied, which is a reason to believe the family is close to complete and not a reason to stop looking.
+
+| | under-reports | over-reports |
+|---|---|---|
+| **enumeration** | class exclusion · truncation | scope inflation |
+| **matching** | pattern blindness | tokenization · alternation order |
+
+### A1. Class exclusion — under, enumeration
+
+An entire corpus sits outside the query's scope and nothing says so. `gh search issues` does not return pull requests; run alone against a mostly-PR population it reported **10 items where the answer was 45**, and omitted the two items already known to be members. A list that misses the examples you started from still reads as authoritative.
+
+**Catch it:** validate the detector against known-true items before believing any count.
+
+#### A second domain, which is what makes this a category rather than a quirk
+
+The same mode, on a filesystem rather than a tracker. A survey of agent worktrees enumerating `.claude/worktrees/` and `.worktrees/` returns a well-formed list — and omits every worktree created outside the repository tree, under the per-user temporary directory. Four such worktrees existed, three of them with uncommitted changes; none appeared.
+
+Run it through the membership test and it qualifies on all three counts: the list is **well formed** (no error, no warning, no partial marker); the omission is **invisible from the list itself**, which looks exactly like a complete survey of a machine with fewer worktrees on it; and **a mechanical step would have caught it** — the same one A1 already prescribes, validating the enumeration against a worktree you know exists.
+
+This example is here rather than folded into the paragraph above because **a second domain tests whether the category is real or just a description of one tool's behaviour.** A mode observed only through `gh search` could be a fact about GitHub's search semantics; the same shape in a `find` over directories says the failure belongs to *enumeration with an unstated boundary*, whichever substrate is enumerating. When extending this document, a new domain for an existing mode is worth as much as a new mode.
+
+**The consequence in that instance was not academic.** Uncommitted work outside the repository tree is invisible to every query anyone would run before deciding what to clean up, and looks identical to abandoned scratch — so a survey feeding a deletion decision under-reports precisely the thing that must not be deleted. See the worktree-and-binding hazards for the separate question of a mitigation whose cost is invisibility; the measurement half is this mode.
+
+### A2. Truncation — under, enumeration
+
+Real members past the first page are dropped with no truncation signal. `gh issue list` and `gh pr list` default to 30 and cap silently at whatever `--limit` is passed: one audit reported **37 items where the answer was 513**, a 14× undercount. A paging API returning **249 of 845 rows with `hasNextPage: false`** is the same mode on another substrate.
+
+**Catch it:** paginate to exhaustion and assert the end-of-pages signal rather than trusting it.
+
+### A3. Pattern blindness — under, matching
+
+Members the pattern cannot express are never matched. A prose form of an organisation's name appeared in three bodies and was matched by no pattern in the audit that was looking for exactly that; it was caught only because a person added the spelling by hand.
+
+**Catch it:** nothing automatic. Report every pattern-derived total as a **floor**, never a total — saying so is the honest form, and it is a step that is either performed or not.
+
+### A4. Scope inflation — over, enumeration
+
+Candidates are enumerated from a root that reaches beyond the population. A tree walk asserting a repository ships exactly one copy of a script found **21 additional copies**, one per agent worktree nested inside the checkout, and failed. The walk was correct; its root was wrong.
+
+Note the trap this mode sets for A1's remedy: **path reachability is not membership.** "The search reached it" and "it belongs to the population" are different claims, and conflating them is how an over-report is defended as thoroughness.
+
+**Catch it:** state the population boundary before enumerating, and assert that a known non-member is excluded — the positive control's mirror.
+
+### A5. Tokenization — over, matching
+
+The query is split into terms, so unrelated items match. Searching for a URL-shaped needle matched issues containing only its bare final word in ordinary prose — one read *"There is no account, token, or session."* Two of 47 candidates were phantoms.
+
+**Catch it:** treat search results as **candidates, never members**; read each one directly and confirm the literal.
+
+### A6. Alternation order — over, matching, and it fabricates
+
+A regex alternative matches early and produces a value with no referent. Extracting paths with `\.(mjs|js|sh|json)` matched `js` inside `package.json` before reaching `json`, producing a phantom `package.js` and reporting a live exposure that did not exist.
+
+This is the most expensive mode. A4 and A5 return a *real item for a wrong reason* and die on a direct read; this returns an **artifact that does not exist**, so a direct read cannot disconfirm it — there is nothing to read — and it sends someone chasing a break that was never there.
+
+**Catch it:** order alternations longest-first, or anchor the match end. Control it with an input crafted to trip the partial match; asserting the regex matches what it should is satisfied by the broken version.
+
+## Family B — the instrument is right and the report is wrong
+
+### B1. Unit error
+
+The measurement is correct and the **reported unit** is not. "Three separate branches" versus *three events across two branches* is not a count error — the count was three either way. It inflates the **independence** of the sample, which is the property the argument rested on: repeated observations on one branch are weaker evidence of a general flake than the same number spread across branches.
+
+No amount of instrument validation catches this. The detector was never involved.
+
+**Catch it:** state the unit next to the number, and ask whether the claim rests on *how many* or on *how many independent*. Where it rests on independence, report both.
+
+## Family C — adjacent, and deliberately not a mode here
+
+### C1. Filter blindness
+
+**A filter built from the failure shapes you already expect cannot show you a shape you did not.** An agent grep-filtered push output for failure markers and discarded the gate's own line naming the cause; the gate had diagnosed itself perfectly and the filter threw the diagnosis away.
+
+This is listed and **excluded from the taxonomy on purpose.** It fails condition 2 in a different place: the artifact was complete and correct, and the loss happened while *reading* it. Forcing it into Family A would dilute the membership test, which is the part of this document that does work. It is here because it is the same shape one layer out, and because the remedy is one line: **read gate and tool output unfiltered on a refusal.**
+
+## Composition: no single check catches all of them
+
+This is the payload. Each check is blind to modes the others catch.
+
+| check | catches | blind to |
+|---|---|---|
+| validate the detector against known-true items | A1, A3 | A2 when the knowns sit on page one · A4 · A5 · A6 · B1 |
+| read every candidate directly | A5, A6 | A1 · A2 · A3 — it only ever sees what enumeration handed it |
+| paginate and assert end-of-pages | A2 | everything else |
+| assert a known non-member is excluded | A4 | A1 · A2 · A3 |
+| state the unit beside the number | B1 | all of Family A |
+
+**Validating against known-true items** loses to truncation, because your known examples are usually recent and therefore on the first page. **Reading every candidate** kills both over-reports and cannot see what was never enumerated. They are complements, not alternatives.
+
+## The procedure
+
+1. **State the population boundary** before enumerating — what is in, what is adjacent and out.
+2. **Enumerate candidates and prove the enumeration complete** — paginate, assert the end-of-pages signal, and check the query's scope covers every corpus (issues *and* pull requests, open *and* closed, bodies *and* comments).
+3. **Validate the detector against known-true items.** If it cannot find the examples you already have, its total means nothing.
+4. **Read every candidate directly** and confirm the literal. Search results are candidates, never members.
+5. **Control the instrument in both directions** — it must report a real absence, and must not invent one.
+6. **Report pattern-derived totals as floors**, and **state the unit** beside any count whose argument rests on independence.

package/plugins/lisa-devin/rules/reference/never-name-a-downstream-project.md

@@ -0,0 +1,37 @@
+# Never Name a Downstream Project
+
+## The rule
+
+A downstream project's identity — its organization, product, or repository name — does not belong in anything that outlives the session it was written in: tracker items (titles, descriptions, comments), pull request titles and bodies, commit messages, wiki and ingested sources, and the text of rules and skills.
+
+## Why the identity is never the point
+
+An observation earns its place by being reproducible, not by its provenance. "A caller repo pinned all 64 of its call sites" and the same sentence with a name carry exactly the same engineering weight — the second just adds an obligation for whoever reads it later.
+
+Where an argument appears to need the name, that is a signal the argument is under-specified. The fix is to state the condition that made it true — the version, the config, the shape of the tree — not to identify the place it was observed.
+
+## How to write it instead
+
+| situation | write |
+|---|---|
+| one project | "a caller repo", "a downstream project", "the reference repository" |
+| two contrasted | "repo A" / "repo B" |
+| several that must stay distinct in one sentence | `<project-1>`, `<project-2>` |
+| a real identifier | `<ticket>` |
+
+Rewrite the prose rather than substituting tokens wherever a placeholder reads badly: "follow `<name>`'s serverless pattern" becomes "follow the reference serverless pattern", not "follow `<project-1>`'s serverless pattern".
+
+## Enforcement is partial, and must not be relied on
+
+`block-host-name-leak` compares against a **curated denylist** and inspects **Bash tool calls only**. If the detector cannot be loaded, the hook warns and permits the write without inspecting the text. These limits follow:
+
+- a name nobody has added to the list is invisible to it;
+- a write issued by a script that reads its own body — rather than by a CLI given a `--body-file` — never reaches it at all.
+
+When the detector is available, a clean run means "no listed name appeared", never "this text is safe". When it is unavailable, no inspection occurred. This rule is default-deny and holds independently of whether the guard fires.
+
+Note also that the denylist cannot be the primary control: this repository is public and `dist/` ships to npm, so the entries most worth catching are the ones least safe to enumerate there.
+
+## Prior reference is not licence
+
+An existing ticket, brief, or ingested source that already carries a name does not authorise repeating it, and inherited text is the most common way such names spread — ingestion carries them forward, and each new document that quotes the last one multiplies them. When you meet one, replace it in what you are writing; do not propagate it because it was already there.

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