@codyswann/lisa 4.49.0 → 4.50.1

package/plugins/lisa/rules/reference/design-value-binding.md

@@ -1,5 +1,108 @@
 # Design Value Binding — full contract
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Design Value Binding (load-bearing)
+
+**Values come from design variables where a variable system exists.** Visual measurement is supplemental there, and it is the legitimate primary source where no variable system exists. Missing design information blocks the work item; it is never worked around.
+
+**One vendor-neutral contract, cited by** `lisa-design-intake`, `lisa-implement`, `lisa-tdd-implementation`, `lisa-review-local`, and `lisa-quality-review` (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never divergent per-skill prose).
+
+This is **not** `design-source-of-truth`. That contract asks whether a changed surface *declares where its design came from*. This one asks whether the *values on it are bound*. A surface can cite a perfectly valid design node and still paint a literal that no variable backs — the design looks finished and has nothing to extract. Both apply; neither substitutes for the other.
+
+## Regime is per-dimension, not per-project
+
+Resolve the source of truth **per-axis** — colour, spacing, typography, radius, elevation, motion — from what the design source **actually publishes**. **Never by asking a human**, and never once per project.
+
+The axis vocabulary is fixed, and the identifiers are what the config and the lint rule use: `color`, `spacing`, `typography`, `radius`, `elevation`, `motion`. Projects declare which of them are typed; they never invent a seventh.
+
+| axis has a published variable collection | source of truth | an unbound value means |
+|---|---|---|
+| yes (**typed**) | the variable | **block** |
+| no (**untyped**) | visual measurement | measure it, and record what you derived |
+
+A library with a mature colour system and no spacing scale is the common case and must work: colour blocks while spacing gets measured, in the same work item, without contradiction.
+
+**Asking the design tool "which collections are published?" does not work headlessly, and that is measured.** The Variables REST endpoint returns names but is Enterprise-plan only; the design-tool MCP returns names on every plan but authenticates by browser OAuth, which cron, CI, and a subagent cannot perform. A gate built on either runs interactively and silently no-ops everywhere else. So the regime is derived from a **committed variable-id map**: `/v1/files/:key/nodes` reports every binding as an opaque `VariableID`, that id→name mapping is static, and `design-variable-ids.mjs` resolves it once interactively so `design-bindings-probe.mjs` runs headlessly on a plain access token forever after. An axis is typed when the committed map names at least one variable in its namespace.
+
+**Staleness is self-detecting, and that is what makes a committed map safe to trust.** An id the map has never seen fails loudly telling you to regenerate; it never silently resolves to the wrong variable.
+
+**Measure the subtree you are implementing, not the enclosing screen.** A frame-level read counts the chrome behind a modal and over-reports — one measured work item scored 14 bound values at frame level and zero inside the modal subtree it actually had to build. **That distinction is decision-changing, not a refinement**: applying it moved 5 of 11 real work items between build and block.
+
+## Block on *unbound*, never on *unsure*
+
+This distinction is the whole contract. "I cannot tell what they meant" is a judgment call, and an agent asked to make it blocks on everything or nothing. "The design does not bind a value I need" is objective and decides the same way twice.
+
+**Block conditions — five, all objectively checkable:**
+
+1. **A named token does not exist.** The work item or frame references a variable the library does not have.
+2. **A value is hardcoded in the design file itself, in a typed axis.** The most important and easiest to miss: the frame paints a literal instead of binding a variable, so the design looks finished and there is nothing to extract.
+3. **The component is not published.** Local to a draft file, so there is no stable reference.
+4. **A required state has no design.** The work item specifies disabled/error/loading and the component set has no such variant.
+5. **Two sources disagree.** The bound token says one value, the frame renders another. Never guess which is right.
+
+**Explicit non-block list — equally load-bearing, or the gate fires constantly:**
+
+- Anything in an **untyped** axis. Measure it.
+- One-off values that are not semantic (an illustration's exact offset).
+- Anything where a token exists and is bound — the happy path.
+- **Aesthetic uncertainty.** If every value needed is bound and the agent merely finds the design ambiguous or ugly, that is an opinion, not a block.
+
+## Why this is a block and not a warning — the measured case
+
+An agent that had read this contract, and cited it in the briefing it wrote for its own build agents, instructed them in that same briefing to **"snap unbound dimensions via the snap tables (ties round down) and flag the rest."** A block downgraded to a warning, by the agent enforcing it, inside the document enforcing it — not from ignorance, but from reasoning around it under delivery pressure with eleven work items queued and blocking feeling like not-shipping. It took a human restating the rule as an absolute for the instruction to be withdrawn.
+
+Coverage measured afterwards, on the subtrees actually being implemented:
+
+| frames | colour | spacing | radius | reality |
+|---|---|---|---|---|
+| compliance screens | 96-100% | 82-97% | 88-93% | design-system composed |
+| edit-KPI / target dialogs | **100%** | **0%** | **0%** | colours bound, geometry never bound |
+| planning mockups | **1-4%** | **0-2%** | **0-3%** | hand-drawn, effectively unbound |
+
+**Five of the eleven items blocked back to design; six proceeded.** One modal's subtree contained **zero variable references** — under snap-and-flag an agent would have produced a complete, lint-clean, tested component **in which every style value was invented**, and shipped it with a note. Five view files were written before it was stopped.
+
+Blocking cost far less than it appeared it would: the non-visual half of the blocked work — domain types, adapters, CRUD, formatters — was completed and preserved. That is the answer to the delivery-pressure reasoning that produced the softening. And the contract holds once it is absolute rather than advisory: one agent withdrew a radius class it had already applied on finding `radius/none` was the only radius bound in its subtree; another refused to build an icon disc whose diameter and radius were both unbound rather than pick a size.
+
+**A gate that depends on an agent choosing to honour it under delivery pressure is not a gate.** That is why this contract has an executable, headless rung at all — the judgment-based version demonstrably failed in the hands of an agent that had read the rule and agreed with it.
+
+## What visual matching is for, precisely
+
+In a **typed** axis it is *verification*: build from the variable, screenshot, confirm agreement — and a disagreement is condition 5, not a licence to trust the pixels. In an **untyped** axis it is *derivation*, and legitimate. The rule is never "do not look at pixels"; it is **"do not derive a value from pixels when a binding exists."**
+
+## Derived values are recorded, not just used
+
+When measuring in an untyped axis, record the derived values on the work item. Over time that accumulates a free inventory of what the token system is missing, ranked by what people actually needed.
+
+## Escalation is configured, never hardcoded
+
+The escalation target, label, and authoritative design source are host configuration — `design.escalation.assignee`, `design.escalation.label`, `design.tokens.source`. **An unset `assignee` is itself a block condition**: a blocked item assigned to nobody is an item nobody sees. Escalation routes through the vendor-neutral tracker abstraction per `config-resolution` — Linear lifecycle is native state, GitHub uses labels, JIRA uses status — never a hardcoded label call.
+
+The blocked comment is written for the non-technical operator standing at the gate: plain language, no engineering vocabulary, naming the specific missing artifact and what to do about it.
+
+## A design source is OPTIONAL; a configured one fails closed
+
+**Most projects have no designs, and this contract must not break them.** No configured design source, no access token, or no committed id map is **SKIPPED** — loudly, exit 0. A mandatory gate on an absent integration breaks every non-design project on upgrade, which is a worse outcome than any drift it would have caught.
+
+Where a design source *is* configured, the gate fails closed: `scripts/design-bindings-probe.mjs` gathers the facts, `scripts/design-intake-gate.mjs` decides deterministically, and `/lisa:design:intake` carries the judgment between them. Facts it could not gather are a block with a named reason, never a quiet pass. The threshold is **100% by default** — the rule as written — with a `--min` flag so any relaxation is an explicit reviewable decision on the command line rather than a quiet softening in code.
+
+The lint rung (`ui-standards/no-unbound-design-value`) catches the same defect at authoring time, and is silent on any axis the project has not declared typed.
+
+## Every failure names an OWNER
+
+Conflating these sends the wrong person the wrong work.
+
+| Owner | Failure | What happens |
+|---|---|---|
+| **design** | Values are unbound. | Block the work item with the exact bind-list. |
+| **us** | The committed id map is stale or ambiguous. | The values ARE bound; regenerate the map. Not the designer's problem. |
+
+An ambiguous id is still a failure even though nothing is wrong in the design: two variables share a value, our map cannot say which one is meant, and guessing is exactly what this contract forbids.
+
+---
+
 The eager head is [eager/design-value-binding.md](../eager/design-value-binding.md). This body carries the axis vocabulary, the five block conditions in detail, the configuration schema, the comment grammar, and the escalation routing.
 
 ## Why this exists separately from `design-source-of-truth`

package/plugins/lisa/rules/reference/documentation-source-paths.md

@@ -1,5 +1,23 @@
 # Documentation Source Paths
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Documentation Source Paths (load-bearing)
+
+Do not treat `docs/`, `research/`, `transcripts/`, or other source-material directories as disposable duplicates just because a project also has a `wiki/`. They may be ingestion inputs, executable fixtures, runtime inputs, or historical evidence.
+
+Before moving, absorbing, or deleting documentation-like paths:
+
+1. Classify each path: durable wiki content, reader-safe source note, executable test fixture, runtime scratch/input, generated output, or obsolete.
+2. Use `rg` to find every code, test, script, config, README, rule, skill, agent, and wiki reference to the path.
+3. Preserve executable fixtures and runtime inputs OUTSIDE the wiki — they are project behavior, not documentation.
+4. When absorbing into `wiki/`, update source notes, indexes, logs, README links, rule references, and runtime defaults that pointed at the old path.
+5. Delete a path only AFTER references are updated and verification proves the project no longer reads it.
+
+---
+
 Do not treat `docs/`, `research/`, `transcripts/`, or other source-material directories as disposable duplicates just because a project also has a `wiki/`.
 
 Before moving, absorbing, or deleting documentation-like paths:

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

@@ -1,5 +1,80 @@
 # 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 `rules/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.** Applying a terminal `done` role to an item someone already closed as not-planned rewrites their decision that the work would not be done, and afterwards the two are indistinguishable. Refuse and say so. This does not restrict the duplicate closeout below, which is a flow deliberately closing an open item as not-planned rather than overwriting a closure that already exists.
+
+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.

package/plugins/lisa/rules/reference/observability-audit.md

@@ -1,5 +1,25 @@
 # Observability Audit (load-bearing)
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Observability Audit (load-bearing)
+
+The **audit + file** arm of `lisa-monitor`. On top of its existing live-signal sweep, `monitor` audits how well the **current repo** is instrumented and files build-ready tickets for what it finds. `monitor` is **manual** (no cron) and **files only** — it never fixes; the `intake` / `tracker-build-intake` cron implements what it files.
+
+## Invariants
+
+- **Repo-scoped two ways.** Audit only the rubric dimensions in scope for the repo's detected profile (`frontend` / `backend` / `infra` — a frontend repo never evaluates backend tracing), and stamp every filed ticket `repo:<CURRENT_REPO>` as a single-repo leaf (resolve the repo via the `config-resolution` ladder; cannot resolve → report, do not file).
+- **Two finding types → build-ready leaves.** A live signal over the conservative bar → a `Bug` leaf; an in-scope MISSING instrumentation dimension (gap, e.g. "no DB/query analytics") → a `Task`/`Improvement` leaf. Always via `lisa-tracker-write` with `build_ready: true` (never a vendor write skill directly); never an Epic/container (gate S15).
+- **Conservative by default.** Only high-signal anomalies (over the documented thresholds) and `core` missing dimensions are filed. `--all-gaps` widens gap filing to `recommended` tiers; nothing lowers the anomaly bar.
+- **Idempotent.** Every ticket carries a `<!-- lisa:monitor-finding: <fingerprint> -->` sentinel; search-before-create (including closed tickets) means a re-run never duplicates a live or just-resolved finding.
+- **Capped.** At most `monitor.maxCandidates` tickets per run (default 20), highest-severity first; report filed-vs-dropped (and list the dropped) — never silently truncate.
+- **Gate-passing.** Each ticket is a real authored artifact: three-audience description, Gherkin AC, single-repo, Target Backend Environment, and a Validation Journey with a typed `[EVIDENCE: <artifact-type>: <name>]` marker (unique kebab-case name) — so `tracker-validate` (S1–S15) accepts it. A finding that cannot be made into a credible ticket is reported, not filed.
+- **Verify guard.** When `monitor` is the post-deploy step of `lisa-verify` it runs **report-only** — Verify invokes it as `lisa-monitor <env> --report-only`, so it never files there. Filing is a standalone-only action.
+
+---
+
 This rule is the single source of truth for the **audit + file** arm of the `lisa-monitor` skill. The `monitor` skill collects live signals (errors, logs, performance, health) via the stack `ops-specialist` exactly as before; this rule adds two things on top, both **repo-scoped**:
 
 1. **Audit** — score the repo against an observability-completeness rubric for its detected type, so a frontend repo is never dinged for missing backend tracing.

package/plugins/lisa/rules/reference/prd-definition-of-ready.md

@@ -1,5 +1,42 @@
 # PRD Definition of Ready — Reference
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## PRD Definition of Ready (requirement atoms)
+
+**A requirements document is ready when a planner can decompose it mechanically and a verifier can check the result against it.** Both properties come from the shape of the requirements, not the prose around them. Modeled on ISO/IEC/IEEE 29148's requirement quality characteristics and the EARS sentence patterns; the fit criterion is Volere's.
+
+## The atom
+
+Every requirement is an **identified atom**:
+
+- **Identified** — carries an id (`R1`, `R2`, …). Ids are per-generation; the verbatim text is the durable anchor (same convention as the `*-to-tracker` Requirement Register).
+- **Singular** — one behavior per atom. "The system shall X and Y when Z" is two atoms.
+- **Unambiguous** — no vagueness lexicon: *as appropriate, user-friendly, fast, robust, handle gracefully, etc., and/or, optimize, seamless, intuitive, support* (unbounded). Each is a word no test can check.
+- **Verifiable** — carries a **fit criterion**: the measurable test of satisfaction ("p95 upload completes < 4s for files ≤ 25 MB"). A requirement no test could check is a wish.
+- **Pattern-shaped (SHOULD)** — one of the EARS patterns, which decompose into Gherkin mechanically:
+  - Ubiquitous: *The `<system>` shall `<response>`*
+  - Event-driven: *When `<trigger>`, the `<system>` shall `<response>`*
+  - State-driven: *While `<state>`, the `<system>` shall `<response>`*
+  - Unwanted behavior: *If `<condition>`, then the `<system>` shall `<response>`*
+  - Optional feature: *Where `<feature>` is present, the `<system>` shall `<response>`*
+
+## The document
+
+Beyond the atoms, a ready PRD carries: problem statement · solution outline · user stories grouping their atoms · an explicit **non-functional checklist** (walk the ISO 25010 axes — performance, security, reliability, usability, compatibility, maintainability — and either state the requirement as an atom or state "no requirement"; silence is not a decision) · out of scope · open questions (the honest home for what is NOT ready).
+
+## Enforcement points
+
+- **Write time** — `lisa-research` authors to this shape; `*-write-prd` skills carry it as a body rule.
+- **Intake time (the universal gate)** — `*-to-tracker` Phase 1.45 validates every register atom, because human-authored PRDs never pass through the write path. Failures are product clarifications quoting the atom verbatim with candidate rewrites.
+- **Verify time** — `verify-prd` / spec-conformance consume the atoms; fit criteria become the conformance checks.
+
+Downstream, ticket gate S16 quotes these atoms verbatim and `prd-ticket-coverage` audits atom→ticket coverage — both degrade when "one requirement" is secretly three welded together.
+
+---
+
 The eager head carries the atom definition and enforcement points; this
 reference carries the rationale, the full vagueness lexicon, and worked
 rewrites. The companion rule `work-item-definition-of-ready` governs the next

package/plugins/lisa/rules/reference/prd-lifecycle-rollup.md

@@ -1,5 +1,41 @@
 # PRD Lifecycle Rollup & Generated-Top-Level-Work Contract
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## PRD Lifecycle Rollup & Generated-Top-Level-Work Contract (load-bearing)
+
+The vendor-neutral source of truth for how a PRD owns the work it generated and how its lifecycle rolls up to `shipped`. Companion to `leaf-only-lifecycle` (which governs build-lifecycle of leaves); this rule governs PRD lifecycle and rollup from generated top-level children.
+
+## Generated top-level work (the contract)
+
+A PRD owns the work units it created **at the top of the hierarchy** — the Epic(s) and any top-level Story it created directly. It does NOT own descendants (Sub-tasks, Stories under an Epic, leaves under a top-level unit) — those are owned by their top-level parent and roll up via `leaf-only-lifecycle`.
+
+Leaf Sub-tasks are **never** direct children of a PRD when a top-level Epic/Story hierarchy exists.
+
+## How each vendor records the PRD→child link
+
+**Native hierarchy first**, machine-readable fallback section always written:
+
+- **GitHub Issues** — native sub-issues when source and tracker are the same repo + supports sub-issues.
+- **Linear** — `parentId` or generated Project grouping where the PRD also lives in Linear.
+- **JIRA** — Epic link / parent field, or documented issue-link type.
+- **Confluence / Notion** — no native issue hierarchy; the documented `## Tickets` / `## Generated Work` section IS the source of truth.
+- **Cross-vendor** (e.g. Notion PRD → JIRA tracker) — always documented section in the PRD source.
+
+The documented `## Tickets` section is ALWAYS written (additive to native links) so the generated set is readable without parsing comments.
+
+## Rollup transition
+
+PRD rolls from `ticketed` to `shipped` when every required generated top-level child is terminal. The PRD remains open for `/lisa:verify-prd` after `shipped` — verified PASS performs native closure (archive/close/transition), verified FAIL re-opens to `ticketed` with build-ready fix tickets (never `blocked`).
+
+## Idempotency dedupe key
+
+Re-runs of intake/backlink must dedupe by child-ref identity (e.g. `owner/repo#number` for GitHub, Linear issue UUID, JIRA key) — never by URL string, which varies by formatting.
+
+---
+
 This is the single vendor-neutral source of truth for how a PRD owns the work it generates and how its lifecycle rolls up to `shipped` from that work. Every PRD-source and PRD-intake skill (`prd-backlink`, `prd-ticket-coverage`, `*-prd-intake`, `*-to-tracker`) cites this rule by slug rather than restating it, so PRD→child linking and PRD closure rollup behave identically across GitHub, Linear, JIRA/Atlassian, Confluence, and Notion instead of drifting per vendor.
 
 It defines four coupled things:

package/plugins/lisa/rules/reference/pre-flight-autofill.md

@@ -1,5 +1,93 @@
 # Pre-Flight Spec Autofill (Draft-Then-Block)
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Pre-Flight Spec Autofill — Draft-Then-Block (load-bearing)
+
+When the pre-flight gate (`*-agent` Step 2) returns `FAIL` on **ticket-quality**
+gaps, do **not** bounce a raw checklist back to the reporter. Most "missing
+required spec content" gaps are **authorable** from material already on the work
+item (title, description, screenshots, design links, repro steps) plus the
+codebase. **Draft** a best-effort version of every authorable gap, write it into
+the item as clearly-labeled **assumptions/recommendations**, and only **then**
+block — turning the human ask from *"author all this"* into *"confirm or correct
+my draft, then flip back to Ready."* Same shape as `repo-scope-split`: the agent
+does the work it can; the human decides only what only a human can.
+
+This does **not** widen the gate — every required section must still exist
+before build. It replaces an empty demand with a defensible first draft, and it
+breaks the `Ready ↔ Blocked` ping-pong loop that a raw checklist causes (the
+information was already on the ticket; only the structure was missing).
+
+## Two tiers
+
+- **Tier A — authorable (always draft):** Technical Approach, Out of Scope,
+  Gherkin Acceptance Criteria (one scenario per fix), expected-vs-actual +
+  environment, Repository, Relationship Search (actually run the git+tracker
+  search — don't fabricate "none found"), Validation Journey **draft** (via the
+  vendor `*-add-journey` skill), Target Backend Environment. Preserve a bare
+  configured key or `Confirmed: <env>` as human-confirmed. Automation writes
+  `Inferred: <env> — evidence: <title|body|reproduction|hostname>` or
+  `Assumption: <env> — remote default branch <branch>`. Without a unique
+  reverse-map use `Assumption: remote default branch <branch>`; human confirmation
+  replaces the annotation with a bare key or `Confirmed: <env>`. For legacy bare
+  values, use managed draft markers and current ticket content only; provider
+  edit history is not required. A marker proves automation and requires
+  re-annotation; otherwise unknown provenance plus conflicting evidence stops.
+  Human-confirmed wins, then validated `Inferred:`
+  evidence. Otherwise use one unambiguous exact `deploy.branches` key from the
+  title, body, and reproduction steps or a URL hostname, excluding the complete
+  `Target Backend Environment` section and other machine-authored metadata/draft
+  blocks so annotations cannot become evidence. Evidence supersedes only
+  `Assumption:`. Normalize only built-in
+  `prod` ↔ `production` when exactly one is configured; no other aliases exist.
+  Never infer from arbitrary branch text, URL paths/query strings, or substrings.
+  Conflicting signals **stop** autofill. With no environment signal, use the
+  remote default and record the applicable `Assumption:` form; a non-unique
+  reverse-map alone never blocks. Require any selected mapping and remote branch.
+  Never overwrite human prose.
+- **Tier B — irreducibly human:** real credentials/access that exist nowhere on
+  the item or in repo test-user docs; a genuine product/scoping decision with no
+  defensible default. Still propose a recommended default where one exists; ask
+  a specific question only where none does.
+
+## Procedure
+
+1. Enumerate FAIL categories from `*-verify`. If S10 failed, run
+   `repo-scope-split` first (split, not autofill).
+2. Draft each Tier-A gap grounded in item material + codebase; tag every
+   inference as an assumption. **Never overwrite human prose** — add/augment
+   sections only.
+3. Write the draft via the vendor write skill (`jira-write-ticket` /
+   `github-write-issue` / `linear-write-issue`); draft the Validation Journey
+   via `*-add-journey`.
+4. Re-run `*-verify`. Structural gates should now PASS; anything still failing
+   is Tier B — name it in the comment.
+5. Block as usual (`blocked` status + `human_needed` marker + reassign to
+   Reporter) but post the **confirmation comment**, not a checklist: disclose
+   it's a Claude draft, one line per drafted section + its key assumption,
+   Tier-B items as specific questions with defaults, and close with *"correct
+   anything wrong, then flip back to Ready and it builds — or reply with
+   corrections."*
+6. **Loop-safety:** if the item already carries the agent's draft, refine only
+   the still-failing gaps; don't redraft. Re-readying after review is the
+   human's approval — the next claim's `*-verify` PASSes and build proceeds.
+
+## When you genuinely cannot autofill
+
+If drafting would be fabrication (no fix/expected behavior described, no usable
+design ref, uninformative title, no codebase anchor), block as before — but
+phrase each gap as a specific question with a default where defensible. Never a
+bare checklist when a defensible draft is possible.
+
+The agent writes **spec/criteria, never code**, at this gate — authoring AC and
+a validation journey is explicitly permitted here (this supersedes the older
+"the build agent does not author the missing spec content" stance).
+
+---
+
 When the pre-flight gate (`*-agent` Step 2) returns `FAIL` on **ticket-quality**
 gaps, the agent does **not** bounce a raw "here is everything you must write"
 checklist back to the reporter. Most "missing required spec content" gaps are

package/plugins/lisa/rules/reference/promotion-contract.md

@@ -1,5 +1,26 @@
 # Promotion Contract
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Promotion Contract (load-bearing)
+
+When implementing a learnings-ladder **promotion ticket** — turning prose
+knowledge into an executable control (lint / ast-grep / type / test / hook /
+`package.lisa.json` force) — the change must be **atomic**: one PR that
+**enables the control**, **fixes the existing violation population**, **ships a
+remediation-teaching diagnostic** (violated invariant + why + concrete fix),
+and **deletes the superseded prose**. A PR missing any of the four is
+**rejected by rule** — promote-without-remove double-pays forever;
+remove-without-diagnostic strands agents.
+
+Eager-tier admission is **demotion-biased** and earned only by repeated-miss
+evidence; the gardener audits the eager tier every run, including Lisa's own
+shipped eager rules.
+
+---
+
 When a learnings-ladder promotion ticket (PRD #1729) is implemented — turning a
 prose learning, rule section, or ledger entry into an **executable control**
 (lint, ast-grep, type constraint, test, hook, or `package.lisa.json` force) —

package/plugins/lisa/rules/reference/readiness-rubric.md

@@ -1,5 +1,68 @@
 # Repository Readiness Rubric
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Repository Readiness Rubric (load-bearing)
+
+**"Lisa is installed correctly" and "an agent fleet may run here unattended" are two different
+questions.** Doctor's shipped grouped checks answer the first — *installation readiness*. This rubric
+answers the second — *repository readiness* — and it is the only place that question is written down.
+A green test suite is not an answer to it.
+
+## Eight ownership dimensions
+
+Repository readiness is assessed across exactly eight dimensions, never fewer, and a dimension with
+no applicable evidence renders `SKIP` **with a reason** rather than a blank:
+
+1. **context/routing** — can an agent recover the real job from what is written down?
+2. **capabilities/tools** — is every tool the work needs *provably* reachable, not merely installed?
+3. **domain ownership** — are the business rules, glossary, and danger zones owned and written down?
+4. **execution/proof** — can the claimed user-visible outcome be proved by running the system?
+5. **feedback/guardrails** — does a failing loop produce a named outcome and a runbook?
+6. **dependencies/supply chain** — is there a confidence model for what the repo depends on?
+7. **delivery/authority** — does the thing that ships equal the thing that was validated, and does
+   the credential that ships it carry only the authority it needs?
+8. **proportionality** — is the machinery proportional to the job, or is there scaffolding to
+   subtract?
+
+## Seven ship blockers (closed set, v1)
+
+A **ship blocker** is a condition that, standing alone, means the answer to "may an unattended fleet
+run here?" is no. The set is closed in v1 — seven, no more — and extended only by editing this rule:
+
+- **B1** a realistic path causes **silent data loss**
+- **B2** a **release path bypasses the validated artifact**
+- **B3** **credentials carry material unintended authority**
+- **B4** a **consequential operation has no gate and no recovery**
+- **B5** an **owned compatibility or security surface has no confidence model**
+- **B6** **documentation overstates enforced guarantees**
+- **B7** there is **no way to prove the claimed user-visible outcome**
+
+## Verdict and narrowed claim
+
+The verdict reuses the shipped `READY` / `READY_WITH_WARNINGS` / `NOT_READY` ladder — cite doctor's
+ladder, never fork a parallel enum. **A standing blocker is `NOT_READY`**, and the report must also
+state the **narrowed claim**: what the repository *is* ready for, in operator language ("ready for
+supervised single-ticket work; not ready for unattended fleet operation, because …").
+
+## Ordering
+
+**Report section order stays stable and never silently omits a section; findings are ordered by
+consequence** — highest-consequence first — within and across sections. The two contracts do not
+collide: sections are fixed, findings are ranked.
+
+## Warn-only
+
+This rubric **gates a claim, not a process**. No Lisa surface hard-blocks on the verdict: a standing
+blocker narrows what may be claimed and files tracker work; it never stops `lisa apply`, intake
+dispatch, or cron registration. Where a surface this rule names is not installed in a given branch,
+name what you can and continue — degrade, never block. Written to be read by someone who does not
+code (`factory-model` rule 5).
+
+---
+
 Lisa can already tell you whether it is *installed* correctly. It cannot tell you whether a
 repository is somewhere an agent fleet can safely operate **unattended**. Those are two different
 questions, and conflating them is how a brownfield onboarding ends in "we built a wiki, looks good"

package/plugins/lisa/rules/reference/ready-role-filing.md

@@ -1,5 +1,39 @@
 # Ready-Role Filing
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Ready-Role Filing (load-bearing)
+
+Filing a work item without the ready role is an **incomplete handoff** — build-intake scans the ready lane and nothing else, so the item is never picked up. A correct write plus a missing role still loses the work.
+
+## Omitted means NOT ready — on every tracker
+
+**An omitted `build_ready` is NOT build-ready on JIRA, GitHub, and Linear alike.** Ready is an explicit claim, never an accident of which tracker a project configured. This is a **breaking change** for GitHub and Linear callers, which previously treated omission as ready; `lisa-github-validate-issue` F4's compensating omitted → `true` normalization is removed with it.
+
+## Every filing declares one of three things
+
+- **`build_ready: true`** — complete enough to build; enters the ready lane for auto-pickup. Required for any complete defect found during other work, so it is claimable next cycle with no human flipping status.
+- **`human_gate: "<why a human must judge this first>"`** — deliberately held outside the queue. The writer stamps a visible line plus `<!-- [lisa-human-gate] reason=<short-slug> -->` so the hold is auditable.
+- **The container declaration** — `None — container: state rolls up from children`, the canonical line `derived-branch-plan` defines and every writer stamps in place of a Target Backend Environment. A container is never build-ready (`leaf-only-lifecycle`) and needs no gate, so it declares the third thing instead. Deliberately **not** keyed on `--label type:Epic`: a declared type is a claim that costs a leaf nothing and leaves it looking buildable, where the container line costs the item the environment and Branch Plan a leaf needs to be built. It is refused alongside a by-design leaf type (`type:Bug` / `type:Task` / `type:Sub-task` / `type:Improvement`) — an item cannot be a container and a leaf at once.
+
+Filed, not ready, and no `human_gate` is the **incomplete handoff** case — writers reject it and name both ways to resolve it. `build_ready: false` with no reason is the same omission with a value attached. `build_ready` stays subordinate to `leaf-only-lifecycle`: a container is never build-ready and needs no gate.
+
+## The named exception
+
+`lisa-exploratory-qa` files findings not-ready **by design** — its findings are candidate defects whose product significance a human should judge. It is the named human-gate exception, not drift: it pairs `ready=false` with an explicit `human_gate` reason. The sibling `e2e-coverage-gaps` skills are the contrast (a missing test is not a product question, so they file build-ready).
+
+`lisa-repair-intake` sweeps for open items that are neither in the ready role nor marked `[lisa-human-gate]`, and surfaces them rather than promoting them.
+
+## This rule is enforced
+
+The PreToolUse guard `block-direct-issue-create.sh` refuses a direct tracker-creation command (`gh issue create`, `gh api` POST to an issues endpoint, `linear`/`jira`/`acli` creates, equivalent `curl` posts) that carries **none of the three declarations** — no configured build-ready role, no `[lisa-human-gate]` marker, and no container declaration. It shipped because this rule as prose did not bind: 13 of 13 issues filed during the session that merged it bypassed it, several by the agent that wrote it, while the one obligation backed by a git hook was honored 50 of 50 times. It stands down where no tracker is configured, and for an operator who set `LISA_ALLOW_DIRECT_ISSUE_CREATE` **in the ambient environment** — never from an inline assignment on the refused command.
+
+**The role is the TARGET repository's, not the caller's.** A creation addressed at another repository — `--repo` / `-R`, or a `repos/<org>/<repo>/issues` endpoint — is judged against that repository's build-ready role: `hardening.upstreamReadyRole` (default `status:ready`) when the target is `hardening.upstreamRepo`, and the stock `status:ready` otherwise. A creation naming no repository, or naming the project's own `github.org`/`github.repo`, is judged against the project's own role exactly as before. A declaration is required either way; only its vocabulary changes.
+
+---
+
 A work item that is filed but never given the ready role is an **incomplete handoff**. No other agent will ever pick it up: build-intake scans the ready lane and nothing else. The originating failure is small and entirely typical — an agent closed a ticket it could not reproduce, filed the real defect it found beside it, and left the new ticket sitting. The defect was correct, the write succeeded, and the work still died.
 
 This rule makes the ready role an **explicit claim** at every filing site, and makes omission mean the same thing on every tracker.