@codyswann/lisa 2.282.0 → 2.283.0

package/all/create-only/.lisa/DEPENDENCY_DECISIONS.md

@@ -0,0 +1,175 @@
+# Dependency Decisions
+
+<!-- lisa-dependency-decisions:v1 -->
+
+This file is the project's record of **why we keep each material dependency**.
+
+A *material* dependency is one whose failure, disappearance, or bad update would
+break something a user can see, or would cost real time to replace. Not every
+package in the lockfile belongs here — only the ones that own a capability.
+
+You do not need to be an engineer to read this file. Every entry starts with a
+plain-language explanation of what the dependency does for us, and every entry
+names what evidence would catch a bad update. If an entry does not answer those
+two questions in words a non-engineer understands, the entry is wrong — fix the
+words, not the reader.
+
+Lisa seeds this file once and never overwrites it. It is yours to maintain.
+
+## How to use this file
+
+1. Copy the **Entry template** below for each material dependency.
+2. Add the filled-in entry to the end of the **Records** section.
+3. Fill in every field. If you do not know the answer yet, write
+   `_Not yet decided_` — never leave a field blank and never guess. An
+   unanswered field is an honest question for the next review; a guess is a
+   wrong answer that nobody will re-check.
+4. Re-read an entry whenever that dependency is upgraded across a major version,
+   changes maintainers, or its detection evidence fails.
+5. Update `Last reviewed` every time someone actually re-reads the entry, even
+   if nothing else changed.
+
+### Entry format (stable, appendable)
+
+Entries are deliberately uniform so they can be added by hand or appended by a
+script without rewriting the rest of the file:
+
+- Every entry is a level-3 heading (`### <name>`) followed by the nine field
+  bullets, always in the order shown in the **Entry template**.
+- Entries live under `## Records`, which is the last section of this file, and
+  new entries are appended to the end. A `###` heading inside `## Records` is
+  always an entry and never guidance — that is what makes the section safe to
+  parse and append to.
+- Nothing after `## Records` is guidance, so appending to the end of the file is
+  always safe.
+- `_Not yet decided_` is the reserved marker for an unanswered field, so
+  unfilled entries are visibly honest rather than silently empty.
+
+## When to escalate
+
+Reading an entry should end in a decision. Raise these to an owner rather than
+letting them sit — each one means the project is carrying a risk nobody has
+accepted on purpose:
+
+- **Nothing would catch a bad update.** The detection-evidence field says
+  "nothing would catch it". We are trusting the dependency blind.
+- **The review is older than the dependency.** `Last reviewed` predates the last
+  major upgrade of that dependency, so the record describes software we are no
+  longer running.
+- **Nobody is behind it.** The trust basis names no maintainer, no owner, or no
+  release history — on our side or theirs.
+
+An entry full of `_Not yet decided_` is not itself an escalation; it is a
+to-do. The three items above are escalations because someone already looked and
+the answer was bad.
+
+## What each field means
+
+- **Why we keep it** — the plain-language reason, written for a non-technical
+  reader. Lead with the outcome it protects, not the mechanism.
+- **What it is (dependency)** — the package or service name, and the version
+  range in use.
+- **What it does for us (owned capability)** — the single capability this
+  dependency is responsible for. If you cannot name one capability, the
+  dependency is either not material or is doing too much.
+- **Why we believe it's safe (trust basis)** — why we believe this dependency
+  will still be maintained and safe next quarter. Evidence, not vibes: who
+  maintains it, release cadence, security-response history, how widely it is
+  used, whether it is pinned.
+- **What breaks if this is compromised (exposure)** — what it can reach and what
+  breaks if it misbehaves. Does it run at build time only, or in production?
+  Does it touch user data, secrets, the network, or CI credentials?
+- **What it would take to replace (replacement cost)** — what it would actually
+  take to remove or swap it: rough effort, what would have to be rewritten, and
+  whether a viable alternative exists today.
+- **What would catch a bad update (detection evidence)** — the specific check
+  that would **fail** if an update broke the owned capability. Name the test,
+  suite, workflow, or monitor. If the honest answer is "nothing would catch it",
+  write that down — it is the most valuable line in the entry. Use
+  `_Not yet decided_` only when nobody has looked yet, which is a different
+  statement from "we looked, and nothing covers this".
+- **Who owns this and how often we recheck (owner / review cadence)** — who is
+  accountable for this entry and how often it gets re-read.
+- **Last reviewed** — ISO date (`YYYY-MM-DD`) of the most recent review.
+
+## Entry template
+
+Copy this block, fill it in, and append it to the end of **Records** below. Keep
+the nine bullets in this order. Any field you cannot answer yet gets
+`_Not yet decided_`.
+
+### <dependency name>
+
+- **Why we keep it:** <plain-language reason a non-technical reader can follow>
+- **What it is (dependency):** <package or service name> `<version range>`
+- **What it does for us (owned capability):** <the one capability it owns>
+- **Why we believe it's safe (trust basis):** <maintainer, cadence, adoption,
+  security history, pinning>
+- **What breaks if this is compromised (exposure):** <build-time vs runtime;
+  data, secrets, network, CI reach>
+- **What it would take to replace (replacement cost):** <effort to remove or
+  swap, and the alternative>
+- **What would catch a bad update (detection evidence):** <the named check that
+  fails if an update breaks it>
+- **Who owns this and how often we recheck (owner / review cadence):**
+  <accountable owner> / <cadence>
+- **Last reviewed:** <YYYY-MM-DD>
+
+## Records
+
+> **The two entries below are EXAMPLES.** They are here so you can see the shape
+> of a good record — the first complete, the second still being filled in.
+> Replace them with your own material dependencies, or delete them once you have
+> written real entries.
+
+### ESLint (EXAMPLE — a complete entry)
+
+- **Why we keep it:** It is the automatic reviewer that reads every change
+  before a human does and refuses the ones that break our agreed coding rules.
+  Without it, those rules become suggestions and the codebase drifts a little
+  with every change until nobody can predict how anything is written.
+- **What it is (dependency):** `eslint` `^9`
+- **What it does for us (owned capability):** Automated enforcement of
+  code-quality and style rules on every commit and every pull request.
+- **Why we believe it's safe (trust basis):** Maintained by the OpenJS
+  Foundation with a published release cadence and a documented
+  security-disclosure process; used by a very large share of the JavaScript
+  ecosystem, so breakage is found by other people before it reaches us. The
+  major version is pinned, so an upgrade is a deliberate decision rather than
+  something that arrives on its own.
+- **What breaks if this is compromised (exposure):** Build-time and CI only. It
+  never runs in production and never touches customer data. It does run inside
+  CI, so a compromised release could in principle read CI environment variables
+  — which is why the version is pinned and upgrades are reviewed.
+- **What it would take to replace (replacement cost):** High. Every rule
+  configuration and every custom rule would have to be re-expressed in another
+  linter, and the pre-commit and CI wiring rebuilt. Alternatives exist (for
+  example Biome or oxlint) but none is a drop-in match for the current rule set
+  today.
+- **What would catch a bad update (detection evidence):** The `lint` check in
+  CI. Warning sign: if lint passes a change we know breaks a rule, the checking
+  has silently stopped working — the rule tests exist to catch exactly that.
+- **Who owns this and how often we recheck (owner / review cadence):** Platform
+  / engineering owner — reviewed each major version upgrade, and at least once
+  every 6 months.
+- **Last reviewed:** _Not yet decided_ (example entry — never reviewed)
+
+### sharp (EXAMPLE — an entry still being filled in)
+
+- **Why we keep it:** It resizes and re-encodes every image users upload, so
+  photos load quickly instead of being served at full camera resolution.
+- **What it is (dependency):** `sharp` `^0.33`
+- **What it does for us (owned capability):** Server-side image resizing and
+  format conversion on upload.
+- **Why we believe it's safe (trust basis):** _Not yet decided_ — nobody has
+  checked who maintains it or how quickly security issues get fixed.
+- **What breaks if this is compromised (exposure):** Runs in production and
+  processes files uploaded by users. It ships native code, so its reach is
+  wider than a pure-JavaScript package.
+- **What it would take to replace (replacement cost):** _Not yet decided_
+- **What would catch a bad update (detection evidence):** _Not yet decided_ —
+  this is the gap to close first, because nothing currently proves an upgrade
+  did not silently corrupt uploaded images.
+- **Who owns this and how often we recheck (owner / review cadence):**
+  _Not yet decided_
+- **Last reviewed:** _Not yet decided_

package/dist/core/upstream-evidence-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upstream-evidence-manifest.d.ts","sourceRoot":"","sources":["../../src/core/upstream-evidence-manifest.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwgEpE,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAupMjE,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAk6I/D,CAAC"}
+{"version":3,"file":"upstream-evidence-manifest.d.ts","sourceRoot":"","sources":["../../src/core/upstream-evidence-manifest.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4gEpE,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAiqMjE,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAk6I/D,CAAC"}

package/dist/core/upstream-evidence-manifest.js

@@ -310,6 +310,7 @@ export const UPSTREAM_EVIDENCE_MANIFEST = Object.freeze({
     "plugins/src/base/rules/eager/coding-philosophy.md": "cf2c52032e0368d81f17f002fed5c957ab350d01fc4a43f66b5f366516bac54a",
     "plugins/src/base/rules/eager/config-resolution.md": "2689c1f47903a5f6c84677fbfd2f1f148096faf122b7498b21d3b0f2345c6c87",
     "plugins/src/base/rules/eager/convergent-review.md": "ba4ba53863ef99be353c07c01195fa4ae2923ef2b2a5ad4427072802c260d208",
+    "plugins/src/base/rules/eager/dependency-decision-records.md": "e22888f107906992e863fca50f26c2c4b124da7132535cacfac71e4f3085728f",
     "plugins/src/base/rules/eager/documentation-source-paths.md": "3a7c2a6264654a3cc44dd326441ba211a39c1c267033cc189c1c635adb84b52b",
     "plugins/src/base/rules/eager/empirical-inquiry.md": "60d77a67cc0d3b6a0aad0ab8fe6de5dff0127b2a6c63fa46b021b7a711eb07d6",
     "plugins/src/base/rules/eager/factory-model.md": "dee39b4276926ee27a2614bf26b985fd33bb3d115313fa6e2893de12da13ed7c",
@@ -339,6 +340,7 @@ export const UPSTREAM_EVIDENCE_MANIFEST = Object.freeze({
     "plugins/src/base/rules/reference/coding-philosophy.md": "fed8381f16a5d6793a49d84d5813d62125808cb2f4981a558b119cf63e2586d9",
     "plugins/src/base/rules/reference/config-resolution.md": "071b2c91f3b661ee493ea6f37d78f0fdea8004b4e4e7b5e94dcf232df7eceda7",
     "plugins/src/base/rules/reference/convergent-review.md": "788a9d4dc2af7a928c3ccbb4d53a92856bb3544941ce512cfe38068d6b35850d",
+    "plugins/src/base/rules/reference/dependency-decision-records.md": "84f9fb8fa0a606307e828ec355ccbf2258beeeb88795dd113abe9bb2c37db39f",
     "plugins/src/base/rules/reference/documentation-source-paths.md": "555155889c9cf279865b9d8fc554bdd461c96a3ec76a5001dfeb361a71056999",
     "plugins/src/base/rules/reference/empirical-inquiry.md": "85f4552aa4c561677de40fd01bc6cccf5dbcf13865647db9df819d11f3cc3389",
     "plugins/src/base/rules/reference/factory-model.md": "b28a2ea4df7c33390111667a2807d9003cf8c9a14829f6fb0dbc929b05bfed3a",
@@ -2262,6 +2264,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "plugins/lisa-copilot/rules/eager/coding-philosophy.md": true,
     "plugins/lisa-copilot/rules/eager/config-resolution.md": true,
     "plugins/lisa-copilot/rules/eager/convergent-review.md": true,
+    "plugins/lisa-copilot/rules/eager/dependency-decision-records.md": true,
     "plugins/lisa-copilot/rules/eager/documentation-source-paths.md": true,
     "plugins/lisa-copilot/rules/eager/empirical-inquiry.md": true,
     "plugins/lisa-copilot/rules/eager/factory-model.md": true,
@@ -2291,6 +2294,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "plugins/lisa-copilot/rules/reference/coding-philosophy.md": true,
     "plugins/lisa-copilot/rules/reference/config-resolution.md": true,
     "plugins/lisa-copilot/rules/reference/convergent-review.md": true,
+    "plugins/lisa-copilot/rules/reference/dependency-decision-records.md": true,
     "plugins/lisa-copilot/rules/reference/documentation-source-paths.md": true,
     "plugins/lisa-copilot/rules/reference/empirical-inquiry.md": true,
     "plugins/lisa-copilot/rules/reference/factory-model.md": true,
@@ -2626,6 +2630,8 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "plugins/lisa-cursor/rules/config-resolution.mdc": true,
     "plugins/lisa-cursor/rules/convergent-review-reference.mdc": true,
     "plugins/lisa-cursor/rules/convergent-review.mdc": true,
+    "plugins/lisa-cursor/rules/dependency-decision-records-reference.mdc": true,
+    "plugins/lisa-cursor/rules/dependency-decision-records.mdc": true,
     "plugins/lisa-cursor/rules/documentation-source-paths-reference.mdc": true,
     "plugins/lisa-cursor/rules/documentation-source-paths.mdc": true,
     "plugins/lisa-cursor/rules/empirical-inquiry-reference.mdc": true,
@@ -4999,6 +5005,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "plugins/lisa/rules/eager/coding-philosophy.md": true,
     "plugins/lisa/rules/eager/config-resolution.md": true,
     "plugins/lisa/rules/eager/convergent-review.md": true,
+    "plugins/lisa/rules/eager/dependency-decision-records.md": true,
     "plugins/lisa/rules/eager/documentation-source-paths.md": true,
     "plugins/lisa/rules/eager/empirical-inquiry.md": true,
     "plugins/lisa/rules/eager/factory-model.md": true,
@@ -5028,6 +5035,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "plugins/lisa/rules/reference/coding-philosophy.md": true,
     "plugins/lisa/rules/reference/config-resolution.md": true,
     "plugins/lisa/rules/reference/convergent-review.md": true,
+    "plugins/lisa/rules/reference/dependency-decision-records.md": true,
     "plugins/lisa/rules/reference/documentation-source-paths.md": true,
     "plugins/lisa/rules/reference/empirical-inquiry.md": true,
     "plugins/lisa/rules/reference/factory-model.md": true,
@@ -5525,6 +5533,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "plugins/src/base/rules/eager/coding-philosophy.md": true,
     "plugins/src/base/rules/eager/config-resolution.md": true,
     "plugins/src/base/rules/eager/convergent-review.md": true,
+    "plugins/src/base/rules/eager/dependency-decision-records.md": true,
     "plugins/src/base/rules/eager/documentation-source-paths.md": true,
     "plugins/src/base/rules/eager/empirical-inquiry.md": true,
     "plugins/src/base/rules/eager/factory-model.md": true,
@@ -5554,6 +5563,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "plugins/src/base/rules/reference/coding-philosophy.md": true,
     "plugins/src/base/rules/reference/config-resolution.md": true,
     "plugins/src/base/rules/reference/convergent-review.md": true,
+    "plugins/src/base/rules/reference/dependency-decision-records.md": true,
     "plugins/src/base/rules/reference/documentation-source-paths.md": true,
     "plugins/src/base/rules/reference/empirical-inquiry.md": true,
     "plugins/src/base/rules/reference/factory-model.md": true,
@@ -6869,6 +6879,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/strategies/copy-overwrite.test.ts": true,
     "tests/unit/strategies/create-only.test.ts": true,
     "tests/unit/strategies/debrief-reroute-contract.test.ts": true,
+    "tests/unit/strategies/dependency-decision-records-rule-pair.test.ts": true,
     "tests/unit/strategies/distributed-content-round2-contract.test.ts": true,
     "tests/unit/strategies/doctor-automation-readiness.test.ts": true,
     "tests/unit/strategies/doctor-config-readiness.test.ts": true,
@@ -6992,6 +7003,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/sync/config-sync.test.ts": true,
     "tests/unit/sync/health-schedule.test.ts": true,
     "tests/unit/sync/legacy-monitor-thresholds.test.ts": true,
+    "tests/unit/templates/dependency-decisions-template.test.ts": true,
     "tests/unit/templates/project-learnings-template.test.ts": true,
     "tests/unit/templates/stack-tsconfig-shadowing.test.ts": true,
     "tests/unit/transaction/backup.test.ts": true,