@codyswann/lisa 4.49.0 → 4.50.1

package/plugins/src/base/rules/reference/control-reachability.md

@@ -1,5 +1,49 @@
 # Control Reachability — 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`.
+
+## Control Reachability — A Prescribed Control Must Reach the Changed Path (load-bearing)
+
+A work item may hand the implementer a falsifiable stopping rule: *"make the change; `<named existing test>` must go red. If it still passes, the fix did nothing."* That is good practice — it replaces eyeballing with an observation. It is also **only valid if that test's fixture exercises the path the change touches.**
+
+When it does not, the test stays green **for a reason unrelated to the change**: execution never reached the changed code. The stopping rule then instructs the implementer to revert a correct fix, and the more faithfully the implementer follows the item, the more reliably it happens. Measured once in the portfolio: a pinned test's fixture omitted the field the fix read, execution fell through to a default branch, the test stayed green, and the fix had worked.
+
+This is the specification-side sibling of `falsifiable-checks`, which governs a check *you authored*. Here the check is **prescribed by the work item** and the defect is in the prose, not the code.
+
+## Authoring obligation — checkable, not advisory
+
+**A work item that names an existing test as a red-before-green control must say what makes that test reach the code the change touches.** Naming the code is not enough; the item names the *input*.
+
+Declare it in `## Validation Journey`, one marker per named control:
+
+```text
+[CONTROL: <test-identifier> | reaches: <input-or-field>]
+```
+
+- `<test-identifier>` — non-empty: the test file path, the test name, or both.
+- `reaches:` — the literal key, then the **input, field, fixture key, argument, or state** that carries execution into the changed code. `reaches: the fix` and `reaches: the changed code` restate the assertion and do not satisfy it.
+
+Enforced by gate **S20** in `lisa-jira-validate-ticket`, `lisa-github-validate-issue`, and `lisa-linear-validate-issue`; rendered by `lisa-jira-write-ticket`, `lisa-github-write-issue`, and `lisa-linear-write-issue`; read at claim time by `lisa-ticket-triage` and `lisa-implement`.
+
+**An item that prescribes no existing-test control is exempt.** Introducing a *new* test carries no reachability obligation — the gate is `N/A` and the item is never reported as incomplete on this basis.
+
+## Implementer obligation — a green control is two facts, not one
+
+`lisa-tdd-implementation` and `lisa-reproduce-bug` bind this arm: **when a prescribed control does not change state as the item predicted, stop. Establish which cause holds before acting on the stopping rule.**
+
+| Cause | Correct action |
+|---|---|
+| The change had no effect on behaviour | Revisit the change |
+| The fixture never reaches the changed code path | Fix or extend the control — do **not** revert |
+
+They demand opposite actions, and the cheaper reading ("the fix did nothing") wins by default when nothing forces the distinction. So force it: **prove reachability by execution, never by reading the fixture.** Put a temporary throw, log line, or counter in the changed code and run that one test; or run coverage scoped to it and read whether the changed lines were hit. Reasoning that the fixture *looks like* it reaches the path is the same move `falsifiable-checks` rejects as "mentally reverting".
+
+**Never revert on an unexplained green.** An unexplained control is a blocked observation, not a verdict — and a reachable-but-still-green control is the only form of it that licenses revisiting the change.
+
+---
+
 The full body behind the `control-reachability` eager head. It defines one vendor-neutral contract consumed by the three tracker writers (`lisa-jira-write-ticket`, `lisa-github-write-issue`, `lisa-linear-write-issue`), the three validators (`lisa-jira-validate-ticket`, `lisa-github-validate-issue`, `lisa-linear-validate-issue`) via gate **S20**, and the implementer surfaces `lisa-ticket-triage`, `lisa-tdd-implementation`, `lisa-reproduce-bug` and `lisa-implement`. Each surface cites this slug rather than growing its own prose, exactly as the vendor arms cite `leaf-only-lifecycle`, `repo-scope-split` and `derived-branch-plan`. One slug is what keeps a control rejected on JIRA from being accepted on Linear.
 
 ## The measured instance

package/plugins/src/base/rules/reference/convergent-review.md

@@ -1,5 +1,36 @@
 # Convergent Review
 
+> 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`.
+
+## Convergent Review
+
+Review exists to get correct work merged, not to keep a PR in review orbit.
+
+- Block only concrete correctness, security, data-loss, or contract-violation
+  failures. Lint-owned style, formatting, taste, and speculative improvements
+  are non-blocking unless the work item or repository rules make them release
+  criteria.
+- Every finding must state severity, blocking yes/no, a concrete failure
+  scenario, evidence, and the smallest actionable fix — plus
+  `invariant_violated` (the property at risk) and `machinery_to_remove` (what
+  becomes deletable, or `none`), required for `readiness-rubric` findings and
+  recommended elsewhere.
+- Present findings highest-consequence first, by severity and blast radius, not
+  by discovery order. Report section order stays stable.
+- A blocking finding without a concrete failure scenario is malformed by
+  contract; downgrade it to non-blocking and ask for evidence.
+- Resolve each finding as `fixed`, `deferred`, or `pushed-back`. If the reviewer
+  cannot refute a pushback with fresh evidence, the author's disposition stands.
+- After suggestion implementation completes and gates pass, review does not
+  reopen absent new evidence: a relevant new commit, a failed gate, a newly cited
+  failure scenario, or a scope change.
+- Irreconcilable blocking disagreement becomes a blocked work item with both
+  positions summarized for the operator, not an endless loop.
+
+---
+
 Review exists to get correct work merged, not to keep a PR in review orbit.
 Apply this contract to every product, quality, local, bot-parity, and suggestion
 implementation pass.

package/plugins/src/base/rules/reference/credential-substrate-precedence.md

@@ -1,5 +1,62 @@
 # Credential-Substrate Precedence
 
+> 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`.
+
+## Credential-Substrate Precedence (load-bearing)
+
+**When more than one substrate can reach an external system, the configured credentials
+provider's token/CLI path goes first and the interactive MCP is the fallback — and
+identity-match verification is mandatory on every substrate, at every tier.**
+
+**One shared, vendor-neutral contract cited by every `*-access` skill** (the
+`leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never divergent
+per-skill prose). An access skill states its per-vendor mechanics — which token, which
+CLI, which identity anchor — and cites this rule for the ordering. It never restates,
+narrows, or locally overrides that ordering.
+
+Settled by decision record `2026-08-12-credential-substrate-precedence` (D6), and
+settled in the `settled-decisions` sense: re-arguing MCP-first inside a skill is out of
+scope for that skill's work.
+
+## The ladder
+
+1. **Tier 1 — configured-provider substrate.** The token or CLI path fed by
+   `lisa-secrets-access`, chosen whenever its bootstrap credential is available **and**
+   the resolved substrate identity-matches the configured tenant/workspace/site.
+   `lisa-secrets-access` is the single chokepoint — never read an OS keychain a second
+   time. The two legacy OS-keychain rungs that remain (`lisa-atlassian-access`,
+   `lisa-notion-access`) are a dated migration ramp with a **removal date of
+   2026-11-01**, not a standing exemption; no new access skill may add one.
+2. **Tier 2 — interactive MCP**, used only when tier 1 is *genuinely* unavailable:
+   no bootstrap, no adapter for the operation (per-operation, not per-session), or a
+   provider outage. "The MCP happens to be authenticated" and "tier 1 is slower" are
+   **not** qualifying reasons.
+3. **Tier 3 — loud, actionable failure** naming the exact credential to set and the exact
+   remediation. Never silently no-op, never blind-retry a failed or absent substrate,
+   never fall through to one that failed identity-match.
+
+## Identity-match is mandatory on every substrate
+
+Verified **in both directions** before any operation: the substrate must claim the
+configured tenant, and the configured tenant must be one the substrate can reach. A
+substrate authenticated as a different account is **skipped, never used — including at
+tier 1**. A credential is not an identity claim; the identity claim is what the provider
+says when asked. Skipping the check because "the user obviously meant this workspace" is
+forbidden.
+
+## Mutating operations: fallback is guarded, never routine
+
+Falling back to an ambient-bound substrate for a **write** requires: switch profile and
+assert identity immediately before the write → write → re-read the affected objects →
+assert the tenant **from the response** (self URL host, cloudId in the path, response
+metadata), not from the pre-flight check → on mismatch, stop, report a cross-tenant
+hazard, and best-effort roll back. A successful pre-flight switch is not sufficient:
+another process can mutate global state between the check and the write.
+
+---
+
 **When more than one substrate can reach an external system, the configured credentials
 provider's token/CLI path goes first and the interactive MCP is the fallback — and
 identity-match verification is mandatory on every substrate, at every tier.**

package/plugins/src/base/rules/reference/dependency-decision-records.md

@@ -1,5 +1,42 @@
 # Dependency Decisions
 
+> 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`.
+
+## Dependency Decisions (load-bearing)
+
+Material dependencies are recorded as decisions, not lockfile trivia. The
+governed record is `.lisa/DEPENDENCY_DECISIONS.md`, seeded once by `lisa apply`
+from the `all/create-only` template surface and never overwritten afterward.
+
+A *material* dependency is one that owns a user-visible capability or would cost
+real time to replace. Each record entry must name, in this order: why we keep it
+in plain language, what it is, its owned capability, trust basis, exposure,
+replacement cost, detection evidence, owner/review cadence, and last-reviewed
+date. Field labels lead with the operator's question and keep the technical term
+in parentheses. "Why we keep it" comes first on purpose — an entry that opens
+with a version range opens with the trivia the record exists to replace.
+
+When you add, upgrade across a major version, or remove a material dependency,
+update its entry in the same change. When you cannot name the detection evidence
+that would fail if an update broke the owned capability, write "nothing would
+catch it" rather than inventing a check — the gap is the finding.
+
+Write every entry so a non-technical operator can tell why the dependency is
+kept and what evidence would detect a bad update. Lead with the outcome it
+protects, not the mechanism.
+
+Entries are repeatable blocks appended under `## Records`, so a seeding script
+can add one without rewriting the file. An honest gap is written as
+`_Not yet decided_` — never left blank.
+
+Escalate, rather than just recording, when detection evidence says "nothing
+would catch it", when `Last reviewed` predates the dependency's last major
+upgrade, or when the trust basis names no maintainer or owner.
+
+---
+
 Lisa already governs dependency *mechanics* — pinning, audit gates, override
 resolution, duplicate detection. What those mechanics cannot tell anyone is
 **why** a dependency is in the project at all, what capability it owns, how much

package/plugins/src/base/rules/reference/dependency-internalization-kit.md

@@ -1,5 +1,52 @@
 # Dependency Internalization Kit
 
+> 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`.
+
+## Dependency Internalization Kit (load-bearing)
+
+When a work item **removes, replaces, or internalizes** a material dependency,
+ownership of that capability moves in-house. The risk moves with it: we stop
+trusting an upstream project and start having to **prove we rebuilt the
+capability correctly**. The confidence-rebuild kit is the standing acceptance
+bar for that proof, so internalization work never has to guess at its own tests.
+
+The kit is seven required evidence types. Each leads with the plain question it
+answers:
+
+1. **Real corpus** — did we test it on real inputs, not toy examples?
+2. **Conformance fixtures** — does the new code do what the dependency did?
+3. **Negative fixtures** — does it still reject what it should reject?
+4. **Coverage as a gap detector** — what behavior is still untested?
+5. **Provenance and license review** — where did this code come from, and are we
+   allowed to use it?
+6. **Migration and update plan** — how do existing call sites move, and how does
+   the new code stay current?
+7. **Rollback or replacement criteria** — what would make us go back, and to
+   what?
+
+All seven are required. A partial kit is the finding: dropping the corpus leaves
+a toy-example pass, dropping negative fixtures leaves code that accepts garbage,
+and dropping rollback criteria leaves nobody able to say the internalization
+failed.
+
+**When the kit applies:** ownership moves in-house — the dependency is removed,
+replaced with our own code, vendored, or forked and maintained by us. That is
+usually a move into the `thin wrapper suitable for in-house ownership` trust
+class, or out of the dependency set entirely.
+
+**When the kit does NOT apply:** a routine version bump of a trusted dependency
+**within its existing trust class**. Ownership does not move, so there is no
+rebuilt capability to prove. Applying the kit there is over-application — it
+buys no confidence and makes ordinary upkeep expensive.
+
+A work item that removes, replaces, or internalizes a material dependency
+inherits all seven criteria unless it explicitly justifies why the dependency is
+**non-material**. Silence is not a justification.
+
+---
+
 Taking a dependency is a decision about trust: we believe someone else's code
 works. Dropping one reverses that decision without reversing the obligation —
 the capability still has to work, and now it is ours. The risk does not

package/plugins/src/base/rules/reference/dependency-trust-classes.md

@@ -1,5 +1,53 @@
 # Dependency Trust Classes
 
+> 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`.
+
+## Dependency Trust Classes (load-bearing)
+
+Every material dependency belongs to exactly one **trust class**. The class is
+the answer to the decision record's "Why we believe it's safe (trust basis)"
+field in `.lisa/DEPENDENCY_DECISIONS.md` — it says why we can trust a *kind* of
+dependency, so each entry does not re-argue trust from scratch.
+
+The six classes, from most to least self-evidently trustworthy:
+
+1. **Mature ecosystem primitive** — so widely used that other people hit the
+   breakage first.
+2. **Fast-moving standard implementation** — the standard implementation of
+   something we refuse to own, but it changes faster than we do.
+3. **Build/development tool** — never runs in production; a bad update costs
+   developer time, not users.
+4. **Runtime-critical service client** — reaches users, data, or money directly,
+   so it is the least trusted regardless of how mature it is.
+5. **Thin wrapper suitable for in-house ownership** — small enough that we could
+   own the code, so the question is whether it earns its keep, not whether it is
+   safe.
+6. **Temporary/experimental dependency** — not trusted at all; admitted on a
+   clock with a written expiry date and a named exit.
+
+Each class fixes five review inputs: capability owner, update cadence, detection
+evidence, replacement-cost threshold, and whether product/human ratification is
+required. Higher exposure and lower trust buy stronger evidence and mandatory
+ratification, not weaker: runtime-critical service clients always need human
+ratification to add or major-upgrade; temporary dependencies need it to live
+past their expiry date; thin wrappers need it to be kept rather than in-housed.
+
+Every class also names one **human-review trigger** — the observable event that
+takes the decision away from the agent. A class definition that cannot say what
+would trigger human review is not finished.
+
+A work item that proposes adding a new material dependency must name the
+dependency's trust class and update its `.lisa/DEPENDENCY_DECISIONS.md` entry in
+the same change. A proposal with no named class is not ready to build.
+
+Reclassify — do not quietly re-trust — when a dependency's exposure changes: a
+build tool that gains runtime reach or reads CI credentials becomes a
+runtime-critical service client, and its stronger requirements apply immediately.
+
+---
+
 Without named classes, every third-party package sits in one implicit bucket:
 "we installed it, so presumably it's fine." That bucket makes a payment SDK and
 a code formatter look identical at review time, and it forces every dependency

package/plugins/src/base/rules/reference/deployed-state-readback.md

@@ -1,5 +1,57 @@
 # Deployed-State Readback
 
+> 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`.
+
+## Deployed-State Readback (load-bearing)
+
+**A build ticket asserts that something is missing from a running system. That assertion must come from reading the running system, never from reading the source.** Source tells you what the code says; only the environment tells you what is deployed. A ticket authored from source alone specifies work against a system it has not observed.
+
+**One vendor-neutral contract, cited by** the Phase 2 research step of `lisa-notion-to-tracker`, `lisa-github-to-tracker`, `lisa-linear-to-tracker`, and `lisa-confluence-to-tracker` (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never four divergent forks).
+
+## The waiver this replaces was scoped to the wrong axis
+
+Phase 2 has two halves — codebase research and a live product walkthrough — and the walkthrough was waived for work that is *"purely backend with no user-visible surface."*
+
+"Is it user-facing?" is a question about the **observation method**: browser, API client, or resource readback. It was being used to answer a different question — **"should we observe live state at all?"** Backend, infrastructure, CI, and dependency work all have live state. It simply is not visible through a browser. Waiving the browser step correctly, and live grounding along with it, is what let tickets be authored for work that had already shipped.
+
+So the skip is **not** "no live check". It is **a different probe**.
+
+## Routing
+
+| The work | Probe |
+|---|---|
+| User-facing surface | `lisa-product-walkthrough` against the running app |
+| HTTP / API backend | Call the deployed endpoint and read the response |
+| Infrastructure / IaC | **Describe the deployed resource in the account** |
+| CI / workflow config | Read the config the running pipeline actually used |
+| Dependency / package pin | Read the **installed** artifact, and the registry |
+| Screen that does not exist yet | No probe; record why |
+
+## What is never accepted as evidence of deployment
+
+**Git ancestry, a merge check, and `cdk synth` are not deployment evidence.** A commit can be an ancestor of the default branch and never have shipped: a pipeline running `executionMode: SUPERSEDED` discards queued executions, so an intermediate commit's deploy is silently dropped. `git log`, a merge check, and a synth all report "present" while the environment does not have it.
+
+Read the deployed thing back. Do not infer it from anything upstream of the deploy.
+
+**This does not conflict with `blocker-containment`, which requires exactly the ancestry test this rule rejects.** The two answer different questions and both are right:
+
+- `blocker-containment` asks a **development** question — *is the blocker's code on the branch I will build from?* Ancestry is the correct and sufficient test.
+- This rule asks a **deployment** question — *is this live?* Ancestry is provably insufficient, per the discarded-execution case above.
+
+Neither may be used to answer the other's question.
+
+## An unanswerable probe is not a "no"
+
+If the deployed state cannot be read back — no credentials, no such environment, the resource is not addressable — **record that the check could not be performed**. Absence of evidence is not evidence of absence, and defaulting an unreadable probe to "not deployed" reintroduces the whole defect while appearing to satisfy the rule.
+
+## Record the readback on the ticket
+
+Write what was probed, how, and what came back. Claim-time triage then inherits evidence instead of re-deriving it from source — which is the same mistake one stage later.
+
+---
+
 A build ticket is a claim about a running system: *this is missing, build it.* The claim is only as good as the observation behind it, and until this rule the observation was optional for everything that did not render in a browser.
 
 It is a **single vendor-neutral contract** consumed by the Phase 2 research step of `lisa-notion-to-tracker`, `lisa-github-to-tracker`, `lisa-linear-to-tracker`, and `lisa-confluence-to-tracker`. Each cites this slug rather than restating the routing, exactly as they would cite `leaf-only-lifecycle` or `repo-scope-split`. Phase 2 had already forked into four near-identical copies; this is what stops them drifting further.

package/plugins/src/base/rules/reference/derived-branch-plan.md

@@ -1,5 +1,57 @@
 # Derived Branch Plan — 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`.
+
+## Derived Branch Plan (load-bearing)
+
+**Every applicable leaf work item shows the branch it will be built from and the branch its PR lands in, as a generated `Branch Plan` section — and that section is derived data, not a second authority.** The authority is `## Target Backend Environment` resolved forward through `.lisa.config.json` `deploy.branches`. A work item that displays branches nobody can trace back to that mapping, or a flow that reads the displayed branches instead of recomputing them, is a contract violation.
+
+**One vendor-neutral contract, cited by** `lisa-jira-write-ticket`, `lisa-github-write-issue`, `lisa-linear-write-issue`, `lisa-jira-validate-ticket`, `lisa-github-validate-issue`, `lisa-linear-validate-issue`, and `lisa-implement` (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never divergent per-vendor prose).
+
+## Why derived, and not two branch fields
+
+The operator need is real: reading a ticket should not require resolving a config file to learn where the work starts and where it lands. But Lisa already owns that fact. Adding independent literal branch fields would create **a second source of truth that can drift** — and the failure mode of that drift is not a cosmetic mismatch, it is code silently shipped to the wrong environment. So the branches are rendered for humans and recomputed for machines. The rendered branches are **never read as input** by any flow, at any phase — a surface that needs the base branch derives it again from the environment.
+
+## The rendered section
+
+Exactly three lines, identical across vendors (`h2. Branch Plan` in JIRA wiki markup, `## Branch Plan` in GitHub/Linear markdown):
+
+```
+Branch from: <branch>
+PR into: <branch>
+Derived from: Target Backend Environment <env> via .lisa.config.json deploy.branches
+```
+
+The third line is the **derivation provenance line**. It is what marks the section machine-authored: a `Branch Plan` without it is treated as hand-authored, and hand-authored branches are never obeyed.
+
+`Branch from` and `PR into` name the **same branch by construction** — implementation checks the feature branch out of `origin/<base>` and targets the PR back into `<base>`. A plan naming two different branches is malformed and fails validation. (A fix that genuinely lands on one branch and must reach another travels as a linked follow-up work item with its own branch plan, never as a divergence inside one plan.)
+
+## Derivation
+
+1. Resolve the environment under the existing `Target Backend Environment` grammar (`config-resolution`, `pre-flight-autofill`) — human-confirmed wins, then validated `Inferred:`, then `Assumption:`.
+2. Map that exact configured key forward through `deploy.branches`. The key must map uniquely and the mapped branch must exist on the remote.
+3. Render both fields to that branch plus the provenance line.
+
+A missing or **ambiguous** mapping, a key that is **not unique**, or a branch absent from the remote **stops** the flow — exactly as `lisa-implement` already stops. **Never default independently to `main`, to the remote default branch, or to any other branch** to keep a write from failing. The remote default is a legitimate input only through the `Assumption:` fallback the environment grammar already defines, and it must be recorded as such.
+
+## Exemption
+
+Work that declares no runtime behavior change — `runtime_behavior_change = false`, i.e. doc-only, config-only, and type-only items — has nothing to derive from and **requires no branch plan**. Its **absence is correct**, not a missing section, and no gate may demand one. Containers (an Epic, or a Story/Spike still holding child work) are exempt for the same reason: they are not built directly.
+
+But the exemption is **declared, never inferred from an absent section**. `Target Backend Environment` is rendered on every leaf, because it is where `runtime_behavior_change` is persisted: an exact configured environment key means `true`, `None — no runtime behavior change: doc-only` (or `config-only` / `type-only`) means `false`, `None — container: state rolls up from children` marks a container, and an **absent section is underivable — never `false`**. On a live item the stored declaration beats any caller assertion, and a contradicting assertion fails S8 rather than being believed. Absence used to be the only signal, which meant the flag every one of S8, S11, S14, and S19 turns on could not be checked against the item at all.
+
+The exemption is one-way. Exempt work that *carries* a branch plan fails validation — branches asserted for work that declared it has no runtime target are hand-authored by definition, which is the second-authority failure this rule exists to prevent.
+
+## Conflict, legacy, and drift
+
+- **Conflict** — a present plan that disagrees with the recomputed plan **fails**; the flow never silently picks a side. The remediation is always to correct the environment, never to edit the branches.
+- **Legacy** — an item written before this rule has no plan. At claim time the implementing agent derives it, **writes the assumption onto the item as a comment**, and proceeds. Never a silent guess.
+- **Drift** — config changed after the plan was rendered. Current config wins; the stale plan is re-rendered and never followed.
+
+---
+
 The full body behind the `derived-branch-plan` eager head. It defines one vendor-neutral contract consumed by the three tracker writers (`lisa-jira-write-ticket`, `lisa-github-write-issue`, `lisa-linear-write-issue`), the three validators (`lisa-jira-validate-ticket`, `lisa-github-validate-issue`, `lisa-linear-validate-issue`) via gate **S19**, and `lisa-implement` at claim time. Each surface cites this slug rather than growing its own prose, exactly as the vendor arms cite `leaf-only-lifecycle` and `repo-scope-split`. One slug is what keeps a branch plan rejected on JIRA from being accepted on Linear.
 
 ## The problem this solves, and the one it must not create

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

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

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