@codyswann/lisa 4.49.0 → 4.50.0

package/plugins/lisa/rules/reference/config-resolution.md

@@ -2,6 +2,103 @@
 
 Lisa is vendor-agnostic. PRDs can be sourced from Notion, Confluence, Linear, GitHub Issues, or JIRA. Tickets can be written to JIRA, GitHub Issues, or Linear. Per-project configuration lives in `.lisa.config.json` at the repo root, with optional `.lisa.config.local.json` overriding on a per-key basis.
 
+
+> The sections between here and the horizontal rule were demoted out of the
+> always-on eager head by CodySwannGT/lisa#3992, verbatim. They are tracker-write
+> and provider mechanics: needed when a flow writes to a tracker or resolves a
+> deploy target, not on every session. The eager head keeps the resolution
+> pointer, the Atlassian identity switch, tracker selection, and repo identity.
+
+## Tracker status vocabulary
+
+**A status transition may target only a status named in the project's configured workflow map** (`jira.workflow.*` for JIRA; the equivalent label/state map for GitHub and Linear). The configured map is the COMPLETE authorized vocabulary — not a starting point.
+
+- **Never adopt statuses discovered from the tracker's live workflow metadata** — transition lists (`getTransitionsForJiraIssue` targets), board columns, status descriptions, or statuses seen on other tickets. A tracker workflow usually contains more statuses than the config names; those extra statuses are not lisa's to use. The live workflow is consulted only to find the transition *id* that reaches a config-named status.
+- **A lifecycle stage with no configured status gets no transition.** If the flow reaches a stage the map does not name (e.g. "PR open awaiting review" when `jira.workflow.review` is unset, or a QA-ready stage with no `qa` mapping), leave the status where it is and record the stage in a comment. Do not pick the nearest-sounding tracker status.
+- **This binds every actor that writes to the tracker** — the lead as much as any subagent. In runtimes where interactively-authenticated MCPs are lead-only, the lead performs the tracker writes for the whole flow; loading an implement/sync skill without the agent definition does not relax this rule.
+
+This is the shared slug for the config-bound-transitions policy (the `leaf-only-lifecycle` precedent: one slug, never divergent per-surface prose). Skills and agent definitions cite it rather than restating it.
+
+## Project rules and learnings
+
+Host-authored project rules live in the fixed, agent-neutral directory
+`.agents/rules/` — not a configurable file. Every agent reaches it through the
+Lisa-managed pointer block in `AGENTS.md`, so it is read once, on demand. A
+project that still carries the retired `.claude/rules/PROJECT_RULES.md` keeps
+it, untouched and authoritative; the pointer names it too. Automated
+learnings never append to host rules: they use the separate machine-managed
+ledger resolved from `.lisa.config.json` — the optional `learnings.file`
+override, else the default `.lisa/PROJECT_LEARNINGS.md`. The ledger lives in the
+cold `.lisa/` tree (never an auto-loaded rules directory) and is consumed only
+through the contract's bounded projection, never read raw wholesale. Both
+writers and budget checks import the executable contract from
+`@codyswann/lisa/learnings`; they must not copy its numeric limits.
+
+## Optional Kane browser provider
+
+Kane is selected only through `verification.browser.kane`: require `enabled: true`, exact version
+`0.6.3`, `cloudUploadApproved: true`, an explicit non-production `allowedEnvironments` entry, a
+Test Manager `projectId`, and a resolved `exploration` mutation policy of `full`. Credentials never
+live in Lisa config. Run `lisa kane probe` before use and invoke only through `lisa-kane-browser`;
+provider/auth/upload/schema failures are tooling failures, not product failures. Kane supplies
+empirical evidence only—native Playwright/Cypress/Maestro remains the regression authority.
+
+## Env → base branch
+
+The `## Target Backend Environment` grammar is durable: human-confirmed values
+are a bare configured key or `Confirmed: <env>`; automation writes either
+`Inferred: <env> — evidence: <title|body|reproduction|hostname>` or
+`Assumption: <env> — remote default branch <branch>`. When no unique environment
+maps to the default branch, use `Assumption: remote default branch <branch>`.
+Human confirmation replaces an automated 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 with
+conflicting evidence stops for confirmation.
+
+Resolution order is human-confirmed value; validated `Inferred:` evidence; then
+one unambiguous signal from the human-authored title, body, and reproduction
+steps or a URL hostname. Exclude the complete `Target Backend Environment`
+section and other machine-authored metadata/draft blocks from the scan so an
+annotation cannot validate or conflict with itself. Evidence supersedes only an
+`Assumption:`. A signal must be an exact
+`deploy.branches` key as a complete token/hostname label. The sole normalization
+is `prod` ↔ `production` when exactly one is configured; no other aliases exist.
+Conflicting signals stop. Never infer from arbitrary branch text, URL paths or
+query strings, or substrings. With no signals, use the remote default branch and
+record an assumption: include `<env>` only for a unique reverse-map, otherwise
+use the branch-only form without inventing an environment or blocking. Require
+any selected environment mapping and its remote branch to exist.
+A non-integration environment bug is fixed, merged, and verified on that
+environment branch first, then
+forward cherry-picked down to the integration branch via a linked follow-up.
+
+## Env-keyed `done` — promotion completeness
+
+A merged PR's base branch names the environment a change **entered**, never the environments it has
+**reached**. Before writing an env-keyed `done`, walk `deploy.order` from its lowest rung and write
+the highest **contiguously reached** rung at or below the resolved env. A rung is reached only when
+the merge commit is an ancestor of its `deploy.branches` branch
+(`git merge-base --is-ancestor <merge-sha> origin/<branch>`, asserted for **every** env branch at or
+below the resolved one, not only the PR's base) **and** that branch's most recent deploy
+**concluded `success`** — read the `conclusion`, never the `status`, because an in-flight deploy has
+a null conclusion and looks identical to a pass. Only a concluded `success` promotes: a null
+conclusion and every other conclusion (`failure`, `cancelled`, `timed_out`, `neutral`, `skipped`,
+`stale`, `action_required`) leave the rung unreached. Where `deploy.order` is absent the ladder is
+the single resolved env; where a branch exposes no deploy surface at all, ancestry alone decides
+that rung.
+
+A hotfix straight to `main` that skipped `staging` therefore resolves to the rung below the gap and
+stays open; the terminal value, and provider-native closure with it, is earned only by a
+promotion-complete merge. The recorded reason always carries all three fields —
+`<first unreached env> (<its branch>) — <condition>`, where the condition is `missing ancestry`,
+`deploy unknown: <run URL or "no concluded run">`, or `deploy concluded <conclusion>: <run URL>`. A
+failing run named without its environment and branch is an incomplete reason. An open back-fill PR
+against a skipped environment branch is outstanding delivery, not branch hygiene.
+
+
+---
+
 This rule is the single source of truth for the `.lisa.config.json` schema, the resolution algorithm, and the dispatch tables every vendor-neutral skill follows.
 
 ## File location and precedence

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