@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-devin/rules/reference/dependency-trust-classes.md

@@ -0,0 +1,291 @@
+# 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 [the rule index](../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
+conversation to re-argue trust from first principles.
+
+Trust classes fix that. Each class states, in plain language, **why we can trust
+that kind of dependency**, and names **the one event that would trigger human
+review**. A dependency's class is the answer to the
+"Why we believe it's safe (trust basis)" field in
+`.lisa/DEPENDENCY_DECISIONS.md` — the record says what
+this dependency is and what would catch a bad update; the class says what bar it
+had to clear to be here at all.
+
+Exactly one class per dependency. If two seem to fit, take the lower-trust one —
+the requirements are strictly stronger, and being over-careful about a formatter
+costs a review cycle while being under-careful about an auth client costs users.
+
+## The five review inputs
+
+Every class fixes the same five inputs. What changes between classes is how
+demanding each one is:
+
+- **Capability owner** — who is accountable when this breaks. A role for
+  high-trust classes; a named person for low-trust ones, because "the platform
+  team" cannot be paged at 2am.
+- **Update cadence** — how often the entry is re-read and the version re-judged.
+- **Detection evidence** — the named check that fails if an update breaks the
+  owned capability. Stronger classes demand evidence *we* own, not upstream's
+  test suite.
+- **Replacement-cost threshold** — the point past which the cost itself is the
+  finding. High replacement cost is acceptable in a high-trust class and is an
+  escalation in a low-trust one.
+- **Product/human ratification** — whether a human has to say yes before the
+  dependency is added, upgraded, or kept. This is the gate, and it is deliberate
+  that the lower-trust and higher-exposure classes carry it.
+
+## The six classes
+
+### 1. Mature ecosystem primitive
+
+**Why we can trust it:** so many other projects depend on it that a bad release
+is usually found, reported, and fixed by someone else before it reaches us. It
+has an identifiable maintaining organization, a published release cadence, and a
+documented process for handling security reports. Trust here comes from the size
+of the crowd standing in front of us, not from us having read the code.
+
+Examples in kind: a language's canonical test runner, a foundation-maintained
+linter, a mainstream UI framework.
+
+- **Capability owner:** a role or team is sufficient.
+- **Update cadence:** re-read at each major upgrade, and at least every 12
+  months.
+- **Detection evidence:** an existing CI check must fail if the owned capability
+  breaks. Naming an upstream test suite is acceptable here and only here.
+- **Replacement-cost threshold:** high replacement cost is accepted. That is the
+  bargain — we take deep coupling in exchange for the crowd's scrutiny.
+- **Ratification:** not required to add or to take a minor/patch upgrade.
+
+**Human review is triggered when:** maintainership changes hands or the project
+is archived, or a security advisory goes unfixed past the project's own
+published response window. Either event removes the crowd, which was the whole
+basis for the trust — reclassify rather than re-trust.
+
+### 2. Fast-moving standard implementation
+
+**Why we can trust it:** it is the standard implementation of a protocol, spec,
+or platform we have deliberately decided not to own — a cloud SDK, an API
+client, a framework tracking a moving platform. We trust the *standard*; we do
+not trust the release we happen to be on, because the project moves faster than
+our review cycle does. Trust here is conditional on us keeping up.
+
+- **Capability owner:** a named team that owns staying current.
+- **Update cadence:** re-read at every minor upgrade, and no less than
+  quarterly. A dependency in this class going quiet for a year is itself a
+  finding.
+- **Detection evidence:** an automated test **we** own that exercises the owned
+  capability. Upstream's suite does not count — it tests their contract, not our
+  use of it.
+- **Replacement-cost threshold:** replacement cost must stay moderate. Keep the
+  coupling behind our own boundary so a forced migration is a rewrite of the
+  boundary, not of the application.
+- **Ratification:** required for any major upgrade that changes user-visible
+  behavior.
+
+**Human review is triggered when:** two consecutive major versions ship that we
+did not adopt inside the cadence window. At that point we are pinned to
+unsupported software and the decision — catch up, replace, or accept the
+exposure — belongs to a human.
+
+### 3. Build/development tool
+
+**Why we can trust it:** it never runs in production and never touches customer
+data. If it ships a bad update, developers notice within one build, and the
+worst case is lost engineering time rather than a user-visible failure. The
+blast radius is what earns the trust, not the maintainer.
+
+- **Capability owner:** a role or team is sufficient.
+- **Update cadence:** re-read at each major upgrade, and at least every 12
+  months.
+- **Detection evidence:** the build, lint, or test job the tool powers. It fails
+  loudly and immediately, which is the point.
+- **Replacement-cost threshold:** high cost is accepted — swapping a build tool
+  is disruptive but never urgent.
+- **Ratification:** not required.
+
+**Human review is triggered when:** the tool gains reach it did not have —
+running in production, reading secrets, or reading CI credentials. The moment
+that happens the blast-radius argument is void: reclassify it as a
+runtime-critical service client and apply that class's requirements immediately.
+
+### 4. Runtime-critical service client
+
+**Why we can trust it:** honestly, we mostly don't. This class covers anything
+that reaches users, their data, or money in production — payment SDKs, auth
+libraries, database drivers, service clients on the request path. Even a mature,
+well-run project lands in this class if a bad update reaches production, because
+maturity does not shrink blast radius. Trust here is bought with our own
+evidence and a human's signature, not the vendor's reputation.
+
+- **Capability owner:** a named accountable person, not a team.
+- **Update cadence:** re-judged at every version change. Versions are pinned
+  exactly, so upgrades are always deliberate.
+- **Detection evidence:** an integration or end-to-end test that exercises the
+  real capability, **plus** a production monitor that would notice failure in
+  the wild. "Nothing would catch it" is not an acceptable answer in this class —
+  it is a blocker.
+- **Replacement-cost threshold:** replacement cost must be written down, never
+  `_Not yet decided_`. If nobody can estimate it, we do not know how trapped we
+  are, and that unknown is the finding.
+- **Ratification:** **product/human ratification is required** before adding the
+  dependency and before any major upgrade.
+
+**Human review is triggered when:** any version changes, any security advisory
+is published, or the vendor has a service incident. Every one of those is a
+human decision in this class — that is what makes it the strictest.
+
+### 5. Thin wrapper suitable for in-house ownership
+
+**Why we can trust it:** it is small enough that we could read all of it in an
+afternoon and own it outright. Safety is not really the question; whether it is
+earning its keep is. A dependency we could write in a day still costs us a
+supply-chain entry, a transitive tree, and an upgrade obligation forever.
+
+- **Capability owner:** the team that would inherit the code if we in-housed it.
+  If no team will claim it, do not add it.
+- **Update cadence:** re-read at every upgrade — there should be few.
+- **Detection evidence:** our own unit tests covering the wrapped behavior. They
+  are cheap here precisely because the surface is small, and they are what makes
+  in-housing a one-day job later instead of a rewrite.
+- **Replacement-cost threshold:** roughly one day. Under it, the default is to
+  in-house the code rather than take the dependency.
+- **Ratification:** **required to keep it** when replacement cost is under the
+  threshold. Note the inversion: the human signs off on the *exception* — taking
+  a dependency we could trivially own — not on the removal.
+
+**Human review is triggered when:** the package goes unmaintained, or its
+transitive dependency tree grows larger than the code it wraps. Either way we
+are now carrying more supply chain than capability, and in-housing should be
+reconsidered on purpose.
+
+### 6. Temporary/experimental dependency
+
+**Why we can trust it:** we don't, and we say so. This class exists so a spike,
+a prototype, or a stopgap can move fast without silently becoming permanent. It
+is admitted on a clock: a written expiry date and a named exit — replace,
+in-house, promote to another class, or remove.
+
+- **Capability owner:** the person who introduced it, by name. Ownership does
+  not transfer to a team while the dependency is in this class.
+- **Update cadence:** reviewed at the stated expiry date, which is at most one
+  quarter out. No expiry date means it does not belong in this class.
+- **Detection evidence:** "nothing would catch it" is tolerated **only** while
+  exposure stays out of production. The moment it reaches production, the
+  runtime-critical requirements apply.
+- **Replacement-cost threshold:** must be low by construction. Anything
+  expensive to remove is not temporary — it is a permanent dependency wearing a
+  temporary label, and it should be classified honestly on day one.
+- **Ratification:** **required to extend past the expiry date** or to promote it
+  into any other class. An expiry that slides without a human saying yes is how
+  a prototype becomes production.
+
+**Human review is triggered when:** the expiry date passes, or the dependency
+starts running in production or touching user data — whichever happens first.
+
+## Ratification, summarized
+
+Ratification is not a formality; it is the point where a human owns the residual
+risk. Required for:
+
+- **Runtime-critical service client** — to add, and for every major upgrade.
+- **Temporary/experimental dependency** — to extend past expiry or to promote.
+- **Thin wrapper suitable for in-house ownership** — to keep it rather than
+  in-house it.
+- **Fast-moving standard implementation** — for a major upgrade that changes
+  user-visible behavior.
+
+Not required for mature ecosystem primitives or build/development tools on
+routine adds and upgrades. Those two classes are where the crowd and the blast
+radius do the work a human would otherwise have to do.
+
+## Naming a class at planning time
+
+A work item that proposes adding a new material dependency must, before it is
+buildable, name the dependency's trust class and state that it will update the
+`.lisa/DEPENDENCY_DECISIONS.md` entry in the same change. This is enforced at
+decomposition time by the `lisa-task-decomposition` skill, which rejects a work
+unit proposing a material dependency with no named class.
+
+The class is what makes the rest of the ticket reviewable: it tells the reviewer
+which evidence to demand and whether a human has to ratify before the work
+starts, rather than discovering both at the end.
+
+Naming a class is not a formality either. If nobody can pick one, that is the
+finding — an unclassifiable dependency is usually one nobody has thought about,
+and it should be resolved before the work item is accepted rather than after the
+package is installed.
+
+## Reclassification
+
+Trust classes describe the dependency as it is used today, not as it was
+introduced. When exposure changes — a build tool starts running in production, a
+prototype ships to users, a thin wrapper grows a large transitive tree — move it
+to the correct class and apply the new requirements immediately. Update the
+`Last reviewed` date on the record entry when you do.
+
+Reclassifying downward (to a lower-trust class) is never a demotion of the
+dependency. It is an admission that its blast radius grew, which is a fact about
+us, not about the maintainers.
+
+## Agent parity
+
+Trust classes are a governed markdown rule and a decomposition-time expectation,
+not a runtime behavior, so Claude Code, Codex, Cursor, OpenCode, Antigravity,
+and Copilot all reach them identically through the shared rules mirror and the
+same `lisa-task-decomposition` skill.
+
+The documented gap, uniform across all six runtimes: no agent runtime enforces
+that a dependency carries a correct class. Nothing fails a build when a package
+is installed with no class named, and nothing detects that a build tool quietly
+started running in production. Classification is carried by this rule, the
+decomposition skill, and review — not by a hook or a lint gate.

package/plugins/lisa-devin/rules/reference/deployed-state-readback.md

@@ -0,0 +1,142 @@
+# 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 [the rule index](../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.
+
+## The failure this replaces
+
+Phase 2 is titled "Codebase + Live Product Research" and has two halves:
+
+- **2a — codebase research.** Source only, by construction.
+- **2b — live product walkthrough.** The only live-state input anywhere in the PRD-to-ticket path, gated on *"If the PRD touches existing user-facing surfaces"* and then waived outright: *"Skip 2b only when the work is purely backend with no user-visible surface, or affects a screen that does not yet exist in dev/prod."*
+
+So user-facing work got one live check and everything else got none. Backend, infrastructure, CI-config and dependency-pin work reached the build queue with **zero deployed-state evidence**, and nothing downstream closed the gap at authoring time: the `*-validate-issue` skills treat "live" as the live *tracker item*; the write skills' only "already exists" concept is the tracker-to-tracker `duplicates` relation; and `lisa-use-the-product`'s IaC lane defaults to `cdk synth` / `cdk diff` — still derived from source — and Phase 2 never routed non-user-facing work into it anyway.
+
+### The waiver was scoped to the wrong axis
+
+This is the whole diagnosis, and the fix follows from it.
+
+*"Is it user-facing?"* is a question about the **observation method** — do you need a browser, an API client, or a resource description call? It was being used to answer *"should we observe live state at all?"*
+
+Those come apart precisely outside the browser case. An infrastructure change has live state; a dependency pin has live state; a CI workflow has live state. None of them are visible through a browser, all of them are readable. The waiver treated "not observable *this way*" as "not observable", and every measured failure sat in that gap: tickets aimed at the wrong repository, tickets specifying the defect rather than the fix, tickets whose target version matched none of the four live version numbers in play, tickets for work that needed verification rather than implementation, and a ticket for behavior that had been in production for a month with a code comment already stating its intent verbatim.
+
+This is the same shape as `blocker-containment`'s defect: a proxy that holds in the common case, used as though it held in general.
+
+## The doctrine this applies
+
+Lisa already says this, three times over, in eager load-bearing rules — none of which the authoring path cited:
+
+- **`empirical-inquiry`** — *"find out empirically before you act… Do not reason your way to a confident-sounding answer from documentation, prior assumption, or training knowledge when the real system is right there and a quick probe would tell you the truth."*
+- **`verification`** — *"Never claim success without runtime evidence. 'The code looks correct' is not evidence."*
+- **`stale-state-claims`** — on assertions of state that expire. A PRD's *"X doesn't exist yet"* is exactly such a claim, and that rule names this outcome in advance: work *"re-planned as undone when it already shipped."*
+
+This rule is not new doctrine. It is those three, wired into the one path that was authoring claims about running systems without consulting any of them.
+
+## Routing — the skip is a different probe, never no probe
+
+Phase 2 selects a probe for each thing the candidate tickets would create or change:
+
+| The work | Probe | Reads |
+|---|---|---|
+| User-facing surface | `lisa-product-walkthrough` against `E2E_BASE_URL` | The running app |
+| HTTP / API backend | Call the deployed endpoint as the test identity | The running service |
+| Infrastructure / IaC | Describe the deployed resource in the account (`aws … describe-*`, provider read API) | The account |
+| CI / workflow config | Read the configuration the most recent pipeline run actually used | The pipeline |
+| Dependency / package pin | Read the **installed** artifact in the deployed tree, plus the registry | The artifact |
+| CLI / library | Invoke the published build's `--version` / read-only command | The published build |
+| Screen or resource that does not exist yet | None — record why, per the unanswerable-probe rule below | — |
+
+The probe is chosen by **what kind of thing it is**, never by whether a human could have clicked it.
+
+## 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 deploy pipeline running `executionMode: SUPERSEDED` discards queued executions, so an intermediate commit's deploy is silently dropped. `git log` reports the commit present, a merge check reports it merged, and a synth reports the resource declared — while the environment does not have it. Every one of those signals is upstream of the deploy, and the deploy is the step that can fail silently.
+
+Read the deployed thing back. Do not infer it from anything upstream of the deploy.
+
+### This does not conflict with `blocker-containment`
+
+`blocker-containment` requires exactly the ancestry test this rule rejects. Both are correct, because they answer different questions:
+
+| Rule | Question | Ancestry |
+|---|---|---|
+| `blocker-containment` | **Development** — is the blocker's code on the branch I will build from? | Correct and sufficient |
+| this rule | **Deployment** — is this live? | Provably insufficient |
+
+An `is blocked by` link is satisfied when the code you need is on your base branch; whether it has reached production is irrelevant to whether you can build against it. A "this already exists" claim is satisfied only when the thing is running. **Neither test may be used to answer the other's question**, and a surface that needs both runs both.
+
+## An unanswerable probe is not a "no"
+
+If the deployed state cannot be read back — no credentials for the account, no such environment provisioned, the resource is not addressable from here — **record that the check could not be performed, and say which probe was attempted.**
+
+Defaulting an unreadable probe to "not deployed" reintroduces the entire defect while appearing to satisfy this rule, and it is the single most likely way to implement it wrongly. It is the same error `blocker-containment` guards with its fail-closed table and `lisa-repair-intake` guards with *"'No blocker found' is inconclusive, never clearance."* Absence of evidence is not evidence of absence.
+
+A ticket authored on an unanswerable probe is still allowed — some work genuinely cannot be grounded before it starts — but it carries the unanswered probe on its face, so the human at the gate and the agent at claim time both know the claim is ungrounded rather than confirmed.
+
+## Record the readback on the ticket
+
+Write what was probed, how, and what came back — the command or call, and the result. Two reasons:
+
+1. **Claim-time triage inherits evidence instead of re-deriving it.** `lisa-ticket-triage`'s `DUPLICATE_ALREADY_FIXED` verdict already demands empirical evidence; without a recorded readback it must reconstruct one from source, which is the same mistake one stage later.
+2. **An ungrounded ticket becomes visible as ungrounded.** A missing readback section is a signal, where a silently source-derived ticket looked identical to a grounded one.
+
+## What this rule does not do
+
+It does not decide whether the work is worth doing, size it, or govern anything after authoring. It governs one step: before a build ticket asserts that something is absent from a running system, that absence is observed rather than assumed.
+
+It also does not require a probe for work that creates something genuinely new — a resource with no deployed predecessor has nothing to read back, and that is the "does not exist yet" row above, recorded rather than skipped silently.