@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-devin/rules/reference/dependency-decision-records.md

@@ -0,0 +1,177 @@
+# 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 [the rule index](../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
+blast radius it has, or what would fail if a bad update shipped. Dependency
+decision records close that gap: they turn dependency posture into decisions an
+operator can read, instead of package-manager trivia only an engineer can
+interpret.
+
+## Where the record lives
+
+The governed record is the markdown file `.lisa/DEPENDENCY_DECISIONS.md` in the
+host project.
+
+It is distributed through Lisa's `all/create-only` template surface, so:
+
+- Every project that runs `lisa apply` receives the scaffold, regardless of
+  stack — the record is stack-independent because dependency posture is.
+- The strategy is **create-only**: Lisa seeds the file once and never overwrites
+  it. Host projects own their content outright, and Lisa upstream never carries
+  a copy of any host project's private dependency inventory.
+- It lives in the cold `.lisa/` directory rather than an auto-loaded rules tree,
+  so a long record is never injected raw into every session. Agents read the
+  entry they need, when they need it.
+
+Markdown is deliberate. The record's primary audience is the product gate, where
+a non-technical operator has to make a keep/replace/escalate judgment. A machine
+format would serve tooling and fail that reader.
+
+## What an entry must name
+
+Each material-dependency entry names nine things, in this order. Every label
+leads with the operator's question and keeps the technical term in parentheses,
+because the record's primary reader is looking for an answer, not a term:
+
+- **Why we keep it** — plain-language reason, written for a non-technical
+  reader, leading with the outcome it protects. This is deliberately the FIRST
+  bullet: an entry that opens with a version range opens with exactly the
+  package-manager trivia this record exists to replace.
+- **What it is (dependency)** — package or service, plus the version range in
+  use.
+- **What it does for us (owned capability)** — the single capability the
+  dependency is responsible for. A dependency with no nameable capability is
+  either not material, or is doing too much and should be split in the record.
+- **Why we believe it's safe (trust basis)** — the evidence that it will still
+  be maintained and safe next quarter: maintainer, release cadence,
+  security-response history, breadth of adoption, whether the version is pinned.
+- **What breaks if this is compromised (exposure)** — what it can reach and what
+  breaks when it misbehaves: build-time versus runtime, and whether it touches
+  user data, secrets, the network, or CI credentials.
+- **What it would take to replace (replacement cost)** — the honest effort to
+  remove or swap it, what would need rewriting, and whether a viable alternative
+  exists today.
+- **What would catch a bad update (detection evidence)** — the named check that
+  would **fail** if an update broke the owned capability: a test, suite,
+  workflow, or monitor. "Nothing would catch it" is a legitimate and high-value
+  answer.
+- **Who owns this and how often we recheck (owner / review cadence)** — who is
+  accountable, and how often the entry gets re-read.
+- **Last reviewed** — ISO `YYYY-MM-DD` date of the most recent actual review.
+
+## When to escalate
+
+The record exists to produce decisions, so three states are escalations rather
+than to-dos. Raise them to an owner instead of leaving them recorded:
+
+- Detection evidence says "nothing would catch it" — the capability is trusted
+  blind.
+- `Last reviewed` predates the dependency's last major upgrade — the record
+  describes software no longer running.
+- The trust basis names no maintainer, owner, or release history.
+
+An entry full of `_Not yet decided_` is not an escalation; it is unstarted work.
+These three are escalations precisely because someone already looked and the
+answer was bad.
+
+## What counts as material
+
+Material means: if this dependency vanished, broke, or shipped a hostile update,
+a user would notice, or replacing it would cost real time. Test frameworks,
+linters, HTTP clients, ORMs, auth libraries, UI toolkits, and build tooling are
+usually material. Transitive packages and single-function utilities usually are
+not — record the direct dependency that owns the capability, not everything
+underneath it.
+
+Do not attempt to record the whole lockfile. An exhaustive record decays into
+noise and stops being read, which is worse than a short record that is true.
+
+## Maintenance
+
+Update the relevant entry in the same change that adds a material dependency,
+upgrades one across a major version, or removes one. Refresh `Last reviewed`
+whenever someone actually re-reads an entry, even when nothing else changes — a
+stale date is the signal that the record has drifted from reality.
+
+When detection evidence fails for a dependency, treat the entry as the first
+place to look and the first place to correct: either the evidence was wrong
+about what it protects, or the exposure was understated.
+
+## Entry format
+
+Entries are uniform and appendable by design, because a later seeding pass adds
+them mechanically rather than by rewriting the document:
+
+- An entry is a level-3 heading (`### <name>`) followed by the nine field
+  bullets in the fixed order above.
+- Entries live under `## Records`, the final section of the file, and new
+  entries are appended to its end. A `###` heading inside `## Records` is always
+  an entry, never guidance — that scoping is what makes the section safe to
+  parse and append to.
+- `_Not yet decided_` is the reserved marker for a field nobody has answered
+  yet. Never leave a field blank and never guess: a blank field is
+  indistinguishable from an overlooked one, and a guess is a wrong answer that
+  nobody re-checks.
+
+Note that `_Not yet decided_` and "nothing would catch it" are different
+statements. The first means nobody has looked. The second is a finding — a real
+capability with no detection evidence behind it.
+
+## Scaffold, not inventory
+
+The seeded file is a scaffold: field structure, guidance, and one clearly marked
+worked example so an operator can see the intended shape. The example is meant
+to be replaced or deleted once real entries exist. Lisa does not pre-populate a
+host project's dependency inventory — only the project knows which of its
+dependencies are material.
+
+## Agent parity
+
+The record is a governed markdown artifact, not a runtime behavior, so every
+supported coding agent — Claude Code, Codex, Cursor, OpenCode, Antigravity, and
+Copilot — reaches it identically through the shared rules mirror and the same
+`.lisa/DEPENDENCY_DECISIONS.md` path in the host project. There is no per-agent
+enforcement surface to diverge.
+
+The documented gap, uniform across all six runtimes: no agent runtime enforces
+that entries stay accurate or current. Nothing blocks a commit whose dependency
+change skips the record, and nothing fails when `Last reviewed` goes stale.
+Freshness is carried by this rule and by review, not by a hook or a lint gate.

package/plugins/lisa-devin/rules/reference/dependency-internalization-kit.md

@@ -0,0 +1,244 @@
+# 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 [the rule index](../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
+disappear at the moment the package is uninstalled; it **changes shape**, from
+"is upstream trustworthy?" to "did we actually rebuild what upstream did?"
+
+The confidence-rebuild kit is the standing answer to that second question. It is
+a reusable set of acceptance criteria that any removal, replacement, or
+internalization work item inherits, so the evidence bar is decided once instead
+of guessed at per ticket by whoever happens to write the tests.
+
+The kit pairs with the other two dependency surfaces:
+`.lisa/DEPENDENCY_DECISIONS.md` records *what we decided*, the
+[dependency-trust-classes](dependency-trust-classes.md) rule says *what bar the
+dependency had to clear to be there*, and this kit says *what proof we owe when
+we take the capability back*.
+
+## The seven required evidence types
+
+Each is stated as the plain question it answers, because the person deciding
+whether a removal is safe to ship is often not the person who wrote the code.
+
+### 1. Real corpus — did we test it on real inputs, not toy examples?
+
+The replacement must be exercised against **representative real inputs** drawn
+from actual usage: production samples, recorded fixtures, historical files, real
+config, the actual shapes the old dependency saw. Hand-written happy-path
+examples are not a corpus. They are written by the same person who wrote the
+implementation, from the same mental model, so they agree with the bug.
+
+The acceptance criterion names where the corpus came from and roughly how big it
+is. "We ran it on the 400 config files already in the repo" is a corpus. "We
+tested it with `{a: 1}`" is not.
+
+If real inputs cannot be obtained — because they are sensitive, or the capability
+is new-shaped — say so explicitly and name what stands in for them. An unstated
+absence reads as coverage that does not exist.
+
+### 2. Conformance fixtures — does the new code do what the dependency did?
+
+The replacement must be shown to **match the old dependency's behavior** on the
+behavior we actually rely on. The strongest form is a differential test: run both
+implementations over the corpus and assert the outputs agree, while the
+dependency is still installed. That is why the kit belongs on the *removal*
+ticket and not a follow-up — once the dependency is gone, the oracle is gone too.
+
+Where a differential run is impossible, conformance fixtures are captured from
+the old dependency's output *before* removal and asserted against afterwards.
+
+Deliberate divergences are allowed and must be **written down** as divergences.
+An intentional behavior change that nobody recorded is indistinguishable from a
+regression six months later.
+
+### 3. Negative fixtures — does it still reject what it should reject?
+
+Most dependencies do half their work by **refusing** things: rejecting malformed
+input, erroring on out-of-range values, failing closed on bad credentials.
+Conformance fixtures over valid input never test that half, and a replacement
+that accepts everything passes them all.
+
+Negative fixtures assert the replacement still fails on what the dependency
+failed on — and fails the same *way* where callers depend on the error type or
+message. This is the criterion most often dropped, and its absence is how a
+validation library gets internalized into a function that returns `true`.
+
+### 4. Coverage as a gap detector — what behavior is still untested?
+
+Coverage on internalization work is used to **find untested behavior**, not to
+report a number. The criterion is a review of the uncovered lines and branches
+with a stated disposition for each: tested, deliberately untested with a reason,
+or a gap to close before shipping.
+
+A coverage percentage on its own proves nothing here — new code written
+alongside its own tests reaches a high number trivially while the branch that
+matters is the one nobody thought of. The evidence is the *gap list*, and it is
+acceptable for that list to end with "none".
+
+### 5. Provenance and license review — where did this code come from, and are we allowed to use it?
+
+Internalized code has a source: written from scratch against a spec, adapted
+from the dependency's implementation, vendored wholesale, or copied from docs or
+an answer online. The work item must **say which**, because that is what
+determines our license obligation.
+
+Adapting or vendoring carries the upstream license with it — attribution,
+notice files, and copyleft terms follow the code even when the package does not.
+A permissive license is not "no obligation"; it is usually an attribution
+obligation.
+
+The criterion states the origin, the license, and what we have to do about it. If
+the answer is "written from scratch without reading their source," say that too —
+it is the cleanest provenance available and worth recording.
+
+### 6. Migration and update plan — how do existing call sites move, and how does the new code stay current?
+
+Two halves, both required:
+
+- **Migration**: every existing call site is enumerated and moved, in this change
+  or on a named schedule. A replacement nobody calls is not an internalization —
+  it is a second implementation, and the dependency is still installed.
+- **Staying current**: the capability the dependency tracked usually keeps
+  moving — a spec revises, a format gains a version, a platform changes. Name
+  who watches for that and what triggers an update. "Upstream did this for us"
+  was a real service, and dropping the dependency dropped it.
+
+### 7. Rollback or replacement criteria — what would make us go back, and to what?
+
+Written **before** the removal ships, while it is still a technical judgment
+rather than an argument during an incident. The criterion names:
+
+- the observable conditions that mean the internalization failed — defect rate,
+  a class of input we cannot handle, maintenance cost we are not paying;
+- what we do when they are met — reinstall the dependency, or pick a different
+  one, named;
+- how long the rollback stays cheap, and what makes it expensive.
+
+"We will fix forward" is a valid answer only if someone wrote it down on purpose.
+
+## Applying the kit — and not over-applying it
+
+The distinction the kit turns on is **whether ownership moves in-house**.
+
+**Inherits the kit** — ownership moves:
+
+- removing a material dependency and doing the work ourselves;
+- replacing it with our own implementation;
+- vendoring its source into the repo;
+- forking it and maintaining the fork.
+
+Each of those lands the capability in the
+`thin wrapper suitable for in-house ownership` trust class or removes it from
+the dependency set entirely, and either way we now own the behavior.
+
+**Does not inherit the kit** — ownership does not move:
+
+- a routine version bump of a trusted dependency **within its existing trust
+  class**, major or minor. The version-bump bar is the trust class's own
+  detection evidence and cadence, which already exist;
+- swapping one third-party dependency for another third-party dependency, where
+  trust simply moves to a different upstream. That is a trust-class decision and
+  a decision-record update, not an internalization;
+- adding a new dependency, which is covered by the trust-class rule.
+
+Over-applying the kit is a real failure, not a harmless excess of caution. A
+version bump forced to produce a corpus, conformance fixtures, and rollback
+criteria costs days for evidence that proves nothing — nobody rebuilt anything —
+and it teaches planners that the kit is boilerplate to be dispensed with, which
+is exactly how it stops being applied when it matters.
+
+The one exception: a version bump that **reclassifies** the dependency into
+in-house ownership — a bump taken as a fork, or an upgrade we decline in favor of
+owning the code — is an internalization wearing a bump's clothing, and it
+inherits the kit.
+
+## The non-material escape hatch
+
+A work item that removes a dependency inherits the kit **unless it explicitly
+justifies why the dependency is non-material**. A dependency is non-material when
+its failure or disappearance would not break anything a user can see and would
+not cost real time to replace — a one-line utility, a dev-only convenience, a
+package nothing imports anymore.
+
+The justification is written in the work item, in one sentence, and it is
+reviewable. What is not acceptable is silence: a removal ticket with no kit and
+no stated reason is not ready to build. That is the whole enforcement mechanism —
+the planner must either carry the criteria or say on the record why they do not
+apply.
+
+## For the operator at the gate
+
+The kit exists so that a removal ticket **explains how confidence will be rebuilt
+before the dependency is dropped**, in language that does not require reading the
+code. The seven questions are the readable form: did we test it on real inputs,
+does it do what the old one did, does it still reject bad input, what is still
+untested, where did the code come from and may we use it, how do callers move and
+how does it stay current, and what would make us go back.
+
+An operator who can read answers to those seven can judge the removal without
+being an engineer. A removal ticket that cannot answer them is not a plan — it is
+an intention.
+
+## Agent parity
+
+The kit is a governed markdown rule plus a decomposition-time expectation, not a
+runtime behavior, so Claude Code, Codex, Cursor, OpenCode, Antigravity, and
+Copilot all reach it identically through the shared rules mirror and the same
+`lisa-task-decomposition` skill. Cursor receives the pair flattened into two
+`.mdc` rules; Antigravity has no separate rules tree of its own and inherits the
+same content through the shared mirror — no runtime is missing the kit.
+
+The documented gap, uniform across all six runtimes: nothing enforces that a
+removal ticket actually carries the kit. No hook or lint gate fails a build when
+a dependency is deleted from a manifest with no corpus, no conformance fixtures,
+and no rollback criteria. Inheritance is carried by this rule, the decomposition
+skill, and review — the same posture as the trust-class rule it extends.