@codyswann/lisa 2.281.0 → 2.283.0

package/plugins/lisa-agy/scripts/doctor-report.mjs

@@ -6,7 +6,7 @@
  * repo adds real readiness probes. Keep this file dependency-free so future
  * doctor scripts can reuse it from plugin distributions and downstream repos.
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 
@@ -121,9 +121,12 @@ export function createPluginSyncDoctorGroup(root = process.cwd()) {
 /**
  * The eight repository-readiness ownership dimensions, in fixed render order,
  * defined once by the `readiness-rubric` rule. This group consumes that rubric;
- * it does not redefine the vocabulary. Evidence gathering for each dimension is
- * wired by later PRD #1739 tickets, so every dimension renders `SKIP` with a
- * reason here — reported, never silently omitted, per the shipped contract.
+ * it does not redefine the vocabulary. Evidence gathering lives in the
+ * TypeScript CLI producers, which persist the authoritative per-dimension
+ * result to `.lisa/readiness.json`; this surface projects that result. When no
+ * usable report is on disk, each dimension renders `SKIP` carrying the reason
+ * it was not assessed — reported, never silently omitted, per the shipped
+ * contract.
  * @type {readonly { id: string, question: string, skipReason: string }[]}
  */
 const REPOSITORY_READINESS_DIMENSIONS = [
@@ -132,81 +135,322 @@ const REPOSITORY_READINESS_DIMENSIONS = [
     question:
       "Can an agent recover the real job from what is written down (integration-access-layer, wiki-knowledge-source, config-resolution)?",
     skipReason:
-      "Context/routing evidence is assessed by the agent-ready wiring (RRR-4, #1856); no readiness probe is wired in this Lisa version.",
+      "Context/routing evidence is assessed by the agent-ready wiring (RRR-4, #1856); no usable `.lisa/readiness.json` was found, so this dimension was not assessed here. Run `lisa doctor --offline --readiness` to produce the report, then re-run doctor.",
   },
   {
     id: "capabilities-tools",
     question:
       "Is every tool the work needs provably reachable, not merely installed (tool-access-gate)?",
     skipReason:
-      "Capabilities/tools evidence is gathered by the journey-execution wiring (RRR-6, #1858); no readiness probe is wired in this Lisa version.",
+      "Tool reachability needs a live read-only probe and can never be established from an offline read: the `tool-access-gate` rule names presence — a binary on `PATH`, a dependency in a manifest, a configured MCP server — as the anti-pattern, because it proves a tool was declared, never that a request through it succeeded. This dimension is therefore a deliberate, permanent reasoned SKIP on an offline pass rather than a not-yet-wired one; only a run that actually exercises the tools can answer it.",
   },
   {
     id: "domain-ownership",
     question:
       "Are the business rules, glossary, and danger zones owned and written down (agent-ready domain phase wiki pages)?",
     skipReason:
-      "Domain-ownership evidence sources from agent-ready's danger-zone wiki pages, read by RRR-4 (#1856); no readiness probe is wired in this Lisa version.",
+      "Domain-ownership evidence sources from agent-ready's danger-zone wiki pages, read by RRR-4 (#1856); no usable `.lisa/readiness.json` was found, so this dimension was not assessed here. Run `lisa doctor --offline --readiness` to produce the report, then re-run doctor.",
   },
   {
     id: "execution-proof",
     question:
       "Can the claimed user-visible outcome be proved by running the system (verification, empirical-inquiry, claim-evidence-mapping)?",
     skipReason:
-      "Execution/proof consumes qualification evidence and representative journeys wired by RRR-6 (#1858); no readiness probe is wired in this Lisa version.",
+      "Execution/proof consumes qualification evidence and representative journeys wired by RRR-6 (#1858); no usable `.lisa/readiness.json` was found, so this dimension was not assessed here. Run `lisa doctor --offline --readiness` to produce the report, then re-run doctor.",
   },
   {
     id: "feedback-guardrails",
     question:
       "Does a failing loop produce a named outcome and a runbook (automation-runbook-contract, observability-audit)?",
     skipReason:
-      "Feedback/guardrails evidence is assessed by RRR-4 (#1856); no readiness probe is wired in this Lisa version.",
+      "Feedback/guardrails evidence is assessed by RRR-4 (#1856); no usable `.lisa/readiness.json` was found, so this dimension was not assessed here. Run `lisa doctor --offline --readiness` to produce the report, then re-run doctor.",
   },
   {
     id: "dependencies-supply-chain",
     question:
       "Is there a confidence model for what the repo depends on (security-audit-handling)?",
     skipReason:
-      "Dependencies/supply-chain evidence is assessed by RRR-4 (#1856); no readiness probe is wired in this Lisa version.",
+      "Dependencies/supply-chain evidence is assessed by RRR-4 (#1856); no usable `.lisa/readiness.json` was found, so this dimension was not assessed here. Run `lisa doctor --offline --readiness` to produce the report, then re-run doctor.",
   },
   {
     id: "delivery-authority",
     question:
       "Does the thing that ships equal the thing that was validated, and does the shipping credential carry only the authority it needs (claim-archaeology, security-audit-handling)?",
     skipReason:
-      "Delivery/authority blockers are populated by the blocker gate in RRR-5 (#1857); no readiness probe is wired in this Lisa version.",
+      "Delivery/authority blockers are populated by the blocker gate in RRR-5 (#1857); no usable `.lisa/readiness.json` was found, so this dimension was not assessed here. Run `lisa doctor --offline --readiness` to produce the report, then re-run doctor.",
   },
   {
     id: "proportionality",
     question:
       "Is the machinery proportional to the job, or is there scaffolding to subtract (repo-scope-split, #1742 subtraction candidates)?",
     skipReason:
-      "Proportionality reuses the scaffolding-subtraction candidates surfaced by the journey work (RRR-6, #1858); no readiness probe is wired in this Lisa version.",
+      "Proportionality reuses the scaffolding-subtraction candidates surfaced by the journey work (RRR-6, #1858); no usable `.lisa/readiness.json` was found, so this dimension was not assessed here. Run `lisa doctor --offline --readiness` to produce the report, then re-run doctor.",
   },
 ];
 
+/**
+ * `schema_version` this surface knows how to project. A report stamped with any
+ * other version is treated as unreadable rather than guessed at: the whole point
+ * of the version stamp is that a reader may not invent a mapping it was never
+ * told about.
+ */
+const READINESS_REPORT_SCHEMA_VERSION = 1;
+
+/**
+ * Longest operator-facing summary projected out of a CLI finding. Findings can
+ * carry kilobytes of concatenated evidence (every offending workflow job, for
+ * example); the doctor line is a headline, and the full text stays available in
+ * `.lisa/readiness.json`.
+ */
+const READINESS_SUMMARY_MAX_LENGTH = 320;
+
+/**
+ * Resolve the single location the CLI writes the readiness report to. This
+ * mirrors the CLI's `resolveReadinessReportPath` so relocating the artifact
+ * stays a two-line change across both scorers.
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+function resolveReadinessReportPath(repoRoot) {
+  return path.join(repoRoot, ".lisa", "readiness.json");
+}
+
+/**
+ * Read the CLI-authored readiness report, or `null` when there is nothing
+ * trustworthy to project. Absence, unparseable JSON, an unknown
+ * `schema_version`, and a missing `dimensions` array are all the same answer —
+ * "the CLI readiness pass has not produced a result this surface can read" —
+ * and none of them is evidence about the repository itself.
+ * @param {string} repoRoot
+ * @returns {{ dimensions: readonly Record<string, unknown>[], blockers: readonly Record<string, unknown>[], narrowedClaim: string, provenance: string } | null}
+ */
+function readReadinessReport(repoRoot) {
+  const reportPath = resolveReadinessReportPath(repoRoot);
+  if (!existsSync(reportPath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(reportPath, "utf8"));
+    if (
+      parsed === null ||
+      typeof parsed !== "object" ||
+      parsed.schema_version !== READINESS_REPORT_SCHEMA_VERSION ||
+      !Array.isArray(parsed.dimensions)
+    ) {
+      return null;
+    }
+    return {
+      dimensions: parsed.dimensions,
+      blockers: Array.isArray(parsed.blockers) ? parsed.blockers : [],
+      // The narrowed claim is the sentence `readiness-rubric` requires whenever
+      // a blocker stands ("...IS ready for supervised, single-ticket agent
+      // work..."). Dropping it would hand the agent operator a bare NOT_READY
+      // where the CLI hands them the fallback they can actually act on.
+      narrowedClaim:
+        typeof parsed.narrowed_claim === "string" ? parsed.narrowed_claim : "",
+      // Stamped into every projected check so a months-old report cannot read
+      // as current truth: this surface reflects a file, not a live assessment.
+      provenance: describeReportProvenance(parsed),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Describe when the projected report was produced and by which Lisa version.
+ * @param {Record<string, unknown>} parsed
+ * @returns {string}
+ */
+function describeReportProvenance(parsed) {
+  const generatedAt =
+    typeof parsed.generated_at === "string" && parsed.generated_at.length > 0
+      ? parsed.generated_at
+      : "an unrecorded time";
+  const version =
+    typeof parsed.lisa_version === "string" && parsed.lisa_version.length > 0
+      ? ` by Lisa ${parsed.lisa_version}`
+      : "";
+  return `generated ${generatedAt}${version}`;
+}
+
+/**
+ * Pull the operator-facing sentence out of a dimension's findings. The CLI
+ * producers write human text under `evidence` (an assessed dimension),
+ * `reason` (a deliberately-unassessed one), or `observation` (a neutral note);
+ * the rest of the finding is machine bookkeeping the blocker engine owns.
+ * Reading only two of the three would print the dimension's question under a
+ * FAIL, which reads as "nothing to report" exactly when there is most to say.
+ * @param {readonly unknown[]} findings
+ * @returns {string}
+ */
+function summarizeReadinessFindings(findings) {
+  const sentences = findings
+    .filter(finding => finding !== null && typeof finding === "object")
+    .flatMap(finding => [finding.evidence, finding.reason, finding.observation])
+    .filter(text => typeof text === "string" && text.trim().length > 0)
+    .map(text => text.trim());
+  if (sentences.length === 0) {
+    return "";
+  }
+  const joined = sentences.join(" ");
+  return joined.length > READINESS_SUMMARY_MAX_LENGTH
+    ? `${joined.slice(0, READINESS_SUMMARY_MAX_LENGTH - 1).trimEnd()}…`
+    : joined;
+}
+
+/**
+ * Carry the CLI's not-established caveat onto every unassessed dimension. The
+ * CLI headline says it out loud — "N of 8 dimensions were never assessed, so
+ * this cannot say whether an unattended fleet may operate here" — and a reader
+ * who sees a lone `SKIP` line without it can mistake silence for a clean bill
+ * of health on that dimension.
+ * @param {DoctorCheck} check
+ * @param {readonly DoctorCheck[]} checks
+ * @returns {DoctorCheck}
+ */
+function applyNotEstablishedCaveat(check, checks) {
+  const unassessed = checks.filter(entry => entry.status === "SKIP").length;
+  if (check.status !== "SKIP" || unassessed === 0) {
+    return check;
+  }
+  return {
+    ...check,
+    observed: `${check.observed} NOT ESTABLISHED: ${unassessed} of ${checks.length} dimensions were never assessed, so this cannot say whether an unattended fleet may operate here.`,
+  };
+}
+
+/**
+ * Decide whether a standing blocker was evidenced in this dimension.
+ *
+ * `dimension_id` is the authority: the CLI's `buildDetectedBlocker` documents it
+ * as "the dimension the evidencing finding was found in". `owning_dimensions` is
+ * the blocker's static spec and can name dimensions that did NOT evidence it —
+ * B4 is specced as `[domain-ownership, feedback-guardrails]` while only the
+ * guardrails producer ever emits the B4 finding. Escalating on the spec would
+ * stamp `FAIL` on a dimension whose own recorded evidence says it found nothing,
+ * contradicting both that evidence and the CLI's per-dimension result. The spec
+ * is used only as a fallback, for a blocker record carrying no attribution.
+ * @param {Record<string, unknown>} blocker
+ * @param {{ id: string }} dimension
+ * @returns {boolean}
+ */
+function blockerEvidencedIn(blocker, dimension) {
+  if (
+    typeof blocker.dimension_id === "string" &&
+    blocker.dimension_id.length > 0
+  ) {
+    return blocker.dimension_id === dimension.id;
+  }
+  return (
+    Array.isArray(blocker.owning_dimensions) &&
+    blocker.owning_dimensions.includes(dimension.id)
+  );
+}
+
+/**
+ * Collect the ids of the standing ship blockers evidenced in a dimension.
+ * Blockers with no usable id are dropped rather than stringified, so a malformed
+ * record can never render "Standing ship blocker(s): undefined" at an operator.
+ * @param {{ id: string }} dimension
+ * @param {{ blockers: readonly Record<string, unknown>[] }} report
+ * @returns {readonly string[]}
+ */
+function standingBlockerIds(dimension, report) {
+  return report.blockers
+    .filter(
+      blocker =>
+        blocker !== null &&
+        typeof blocker === "object" &&
+        blockerEvidencedIn(blocker, dimension)
+    )
+    .map(blocker => blocker.id)
+    .filter(id => typeof id === "string" && id.length > 0)
+    .filter((id, index, ids) => ids.indexOf(id) === index);
+}
+
+/**
+ * Project one CLI dimension record into this surface's check shape, or `null`
+ * when the record is absent or carries a status outside the shipped vocabulary
+ * (the caller then falls back to the reasoned SKIP).
+ * @param {{ id: string, question: string, skipReason: string }} dimension
+ * @param {{ dimensions: readonly Record<string, unknown>[], blockers: readonly Record<string, unknown>[], narrowedClaim: string, provenance: string }} report
+ * @returns {DoctorCheck | null}
+ */
+function projectReadinessDimension(dimension, report) {
+  const record = report.dimensions.find(
+    entry =>
+      entry !== null && typeof entry === "object" && entry.id === dimension.id
+  );
+  if (!record || !DOCTOR_STATUSES.includes(record.status)) {
+    return null;
+  }
+  const findings = Array.isArray(record.findings) ? record.findings : [];
+  const summary = summarizeReadinessFindings(findings);
+  const blockerIds = standingBlockerIds(dimension, report);
+
+  return {
+    id: dimension.id,
+    // A standing blocker outranks the recorded label. Three CLI producers (B1
+    // domain-ownership, B4 feedback-guardrails, B6 context-routing) record
+    // `WARN` while standing a blocker, each stating in-line that "the blocker
+    // engine never reads this status, so the finding flips the repository to
+    // NOT_READY exactly as a FAIL would". Projecting that `WARN` verbatim would
+    // score READY_WITH_WARNINGS on a repository the CLI calls NOT_READY — the
+    // precise disagreement this bridge exists to eliminate. This still reflects
+    // the CLI's decision rather than re-scoring: the CLI decided the blocker
+    // stands and wrote it into `blockers[]`.
+    status: blockerIds.length > 0 ? "FAIL" : record.status,
+    summary: summary.length > 0 ? summary : dimension.question,
+    observed: `${dimension.question} Projected from \`.lisa/readiness.json\` (schema_version ${READINESS_REPORT_SCHEMA_VERSION}, ${report.provenance}), the report the Lisa CLI readiness pass wrote.`,
+    ...(blockerIds.length > 0
+      ? {
+          remediation:
+            `Standing ship blocker(s): ${blockerIds.join(", ")}. See \`.lisa/readiness.json\` for the full evidence and the \`readiness-rubric\` rule for the blocker definitions.` +
+            (report.narrowedClaim.length > 0 ? ` ${report.narrowedClaim}` : ""),
+        }
+      : {}),
+  };
+}
+
 /**
  * Build the orthogonal "Repository readiness" doctor group ("may an agent fleet
  * operate here unattended?"), scored against the eight `readiness-rubric`
  * ownership dimensions. It is separate from the installation-readiness groups
  * and is appended in a fixed position by the readiness-mode caller; the eight
- * dimension checks render in fixed order. In this Lisa version every dimension
- * is `SKIP` with a stated reason because the evidence-gathering surfaces ship
- * with later PRD #1739 tickets — reported, never silently omitted.
+ * dimension checks render in fixed order.
+ *
+ * The blocker engine and the evidence producers live in the TypeScript CLI,
+ * which is the single source of truth; this surface is a bridge, not a second
+ * implementation (#1902). It projects whatever the CLI persisted to
+ * `.lisa/readiness.json` so an operator running `/lisa:doctor` through any
+ * coding agent gets the same readiness answer the CLI gives. When no usable
+ * report exists, every unmatched dimension renders `SKIP` with its reason:
+ * absence means the readiness pass has not run, never that the repository is
+ * clean, so a pass or fail is never manufactured from it.
  * @param {string} root
  * @returns {DoctorGroup}
  */
 export function createRepositoryReadinessDoctorGroup(root = process.cwd()) {
-  void path.resolve(root);
+  const report = readReadinessReport(path.resolve(root));
+  const checks = REPOSITORY_READINESS_DIMENSIONS.map(
+    dimension =>
+      (report === null
+        ? null
+        : projectReadinessDimension(dimension, report)) ?? {
+        id: dimension.id,
+        status: "SKIP",
+        summary: dimension.question,
+        observed:
+          report === null
+            ? dimension.skipReason
+            : `${dimension.question} \`.lisa/readiness.json\` carries no usable record for this dimension, so it was not assessed here. Re-run \`lisa doctor --offline --readiness\` to regenerate the report.`,
+      }
+  );
   return {
     id: "repository-readiness",
     title: "Repository readiness",
-    checks: REPOSITORY_READINESS_DIMENSIONS.map(dimension => ({
-      id: dimension.id,
-      status: "SKIP",
-      summary: dimension.question,
-      observed: dimension.skipReason,
-    })),
+    checks: checks.map(check => applyNotEstablishedCaveat(check, checks)),
   };
 }
 

package/plugins/lisa-agy/skills/lisa-doctor/SKILL.md

@@ -319,9 +319,27 @@ default doctor path never renders it and stays byte-identical.
    contract; do not restate or fork that vocabulary here.
 3. **`SKIP` carries a reason and is never blank.** A dimension with no applicable evidence renders
    `SKIP` with a stated reason ("no deployment target configured, so delivery/authority was not
-   assessed"). An unassessed dimension is a known unknown, and the report says so. In Lisa versions
-   where the evidence-gathering surfaces (RRR-4/5/6) are not yet wired, every dimension renders `SKIP`
-   with that reason.
+   assessed"). An unassessed dimension is a known unknown, and the report says so.
+
+   **This surface reflects the CLI; it does not re-score.** The evidence producers and the blocker
+   engine live in the Lisa CLI, which is the single source of truth. When `.lisa/readiness.json` is
+   present and readable (parses, matching `schema_version`, carries a `dimensions` array), this group
+   **projects** each recorded dimension's status and its operator-facing evidence/reason text, so an
+   operator running `/lisa:doctor` through any coding agent sees the same readiness answer the CLI
+   gives. When the report is absent, unparseable, or stamped with an unknown `schema_version` — or
+   records nothing for a given dimension — that dimension falls back to `SKIP` with the reason it was
+   not assessed. Absence means the readiness pass has not run, never that the repository is clean: a
+   pass or a fail is never manufactured from a missing report. Run
+   `lisa doctor --offline --readiness` to produce the report first.
+
+   **A standing blocker outranks the recorded status.** Some CLI producers record `WARN` while
+   standing a ship blocker — the blocker engine never reads the per-dimension status, so the finding
+   flips the repository to `NOT_READY` exactly as a `FAIL` would. A dimension that owns an entry in
+   the report's `blockers[]` therefore projects as `FAIL` regardless of its recorded label, and its
+   remediation names the blocker ids and repeats the report's `narrowed_claim` (the "IS ready for
+   supervised, single-ticket agent work" fallback `readiness-rubric` requires whenever a blocker
+   stands). Projected checks also carry the report's `generated_at`/`lisa_version` so a stale report
+   cannot read as current truth, and unassessed dimensions carry the CLI's not-established caveat.
 4. **Reuse the shipped verdict ladder and consequence ordering.** No new verdict value and no new
    severity: reuse `READY` / `READY_WITH_WARNINGS` / `NOT_READY`. `READY` requires *positive*
    evidence — every readiness dimension assessed and clean, with no blocker standing. An unassessed

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.281.0",
+  "version": "2.283.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.281.0",
+  "version": "2.283.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.281.0",
+  "version": "2.283.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.281.0",
+  "version": "2.283.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.281.0",
+  "version": "2.283.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.281.0",
+  "version": "2.283.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/rules/eager/dependency-decision-records.md

@@ -0,0 +1,32 @@
+# 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.
+
+Full prose: [reference/dependency-decision-records.md](../reference/dependency-decision-records.md).

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

@@ -0,0 +1,140 @@
+# Dependency Decisions
+
+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.