@codyswann/lisa 2.282.0 → 2.284.0

package/plugins/src/base/rules/reference/dependency-trust-classes.md

@@ -0,0 +1,243 @@
+# Dependency Trust Classes
+
+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/src/base/skills/lisa-task-decomposition/SKILL.md

@@ -74,6 +74,31 @@ Each task must have a verification method. Choose the most appropriate:
 - Prefer independent tasks that can run in parallel where possible
 - Flag external dependencies (other teams, services, permissions, data) that may block progress
 
+### 4.5. Classify Any New Material Dependency
+
+Step 4 maps dependencies *between tasks*. This step covers third-party
+dependencies a task proposes to **add**.
+
+A dependency is **material** if its failure, disappearance, or bad update would
+break something a user can see, or would cost real time to replace. If a work
+unit proposes adding one, the work unit must, before it is buildable:
+
+1. **Name its trust class** — exactly one of: mature ecosystem primitive,
+   fast-moving standard implementation, build/development tool, runtime-critical
+   service client, thin wrapper suitable for in-house ownership, or
+   temporary/experimental dependency. See the `dependency-trust-classes` rule
+   for what each class means and why it is trusted.
+2. **State the class's required evidence** — the detection evidence that class
+   demands, and whether product/human ratification is required before the work
+   starts. Runtime-critical service clients and expiry extensions on temporary
+   dependencies always require ratification; a work unit that needs it and does
+   not say so is not ready.
+3. **Include updating `.lisa/DEPENDENCY_DECISIONS.md`** in its acceptance
+   criteria, so the record entry lands in the same change as the dependency.
+
+If nobody can pick a class, that is the finding — resolve it before accepting
+the work unit, not after the package is installed.
+
 ### 5. Determine Execution Order
 
 - Place foundational tasks first (types, schemas, interfaces, shared utilities)
@@ -121,6 +146,7 @@ Map each task to the skills needed to complete it. This enables delegation to sp
 - Every task must have at least one acceptance criterion that can be empirically verified
 - Do not create tasks that cannot be verified -- if you cannot define how to prove it is done, the task is not well-scoped
 - Every Task / Bug / Sub-task / Improvement is scoped to exactly one repo -- if the work spans repos, split into per-repo work units under a shared parent Story (see step 1.5)
+- Any task proposing a new material dependency names its trust class, states that class's required evidence and whether human ratification is needed, and updates `.lisa/DEPENDENCY_DECISIONS.md` in the same change (see step 4.5) -- a proposed material dependency with no named class is not ready to build
 - Keep tasks ordered so that no task references work that has not been completed by a prior task
 - Flag any task that requires access, permissions, or external input not yet available
 - Prefer more small tasks over fewer large tasks -- smaller tasks are easier to verify and less risky to fail

package/ui/index.html

@@ -1522,68 +1522,65 @@
             card: "Required",
             items: [
               {
+                id: "setup.install",
                 label: "Install Lisa and apply templates",
                 desc: "Detects the project’s stacks, applies project-owned templates, agent surfaces, and git hooks. External plugin/runtime installation is reported separately and never inferred from project files.",
                 command: "bun add -d @codyswann/lisa && bunx lisa",
-                done: true,
               },
               {
+                id: "setup.sync",
                 label: "Populate configuration",
                 desc: "Fills every missing .lisa.config.json setting (absorbing existing artifact values first) and syncs mirrored files. No unset configs.",
                 command: "lisa sync",
-                done: true,
               },
               {
+                id: "setup.agent-ready",
                 label: "Make the project agent-ready (brownfield)",
                 desc: "Builds the knowledge wiki through read-only, redacted ingestion; records every source as complete, partial, or unavailable; and writes wiki/gaps.md. Answer inline, re-run in a new session, repeat until every source is complete and zero gaps remain. Greenfield projects are ready by construction.",
                 command: "/lisa:agent-ready",
-                done: false,
-                why: "wiki/gaps.md has 2 open gaps",
               },
               {
+                id: "setup.standards",
                 label: "Adopt the standards (conformance refactor)",
                 desc: "Apply Lisa's full lint rules, guardrails, and thresholds — the project goes red by design — then agents refactor to automated conformance without changing business logic. Empirical product verification remains a separate Verify-factory gate.",
                 command:
                   "/lisa:improve:* · /lisa:fix:linter-error · lisa standards-proof",
-                done: false,
-                why: "blocked by agent-ready",
               },
               {
+                id: "setup.tracker",
                 label: "Connect the work tracker",
                 desc: "Verifies the workflow status names and writes the tracker section. This project: JIRA, project ACME.",
                 command: "/lisa:setup:jira | github | linear",
-                done: true,
               },
               {
+                id: "setup.prd-source",
                 label: "Connect the PRD source",
                 desc: "Wires the product-requirements queue and its lifecycle vocabulary. This project: Notion.",
                 command: "/lisa:setup:notion | confluence | linear | github",
-                done: true,
               },
               {
+                id: "setup.github-governance",
                 label: "Apply GitHub repository governance",
                 desc: "Repo settings (merge-only), rulesets with required checks, write deploy key, deployment environments with approval gates.",
                 command: "/lisa:setup:github-repo",
-                done: true,
               },
               {
+                id: "setup.secrets",
                 label: "Provision CI secrets",
                 desc: "CLAUDE_CODE_OAUTH_TOKEN, GITGUARDIAN_API_KEY, SONAR_TOKEN, per-environment AWS accounts, and the optional scanners.",
                 command: "gh secret set …",
-                done: false,
-                why: "2 missing: SNYK_TOKEN, FOSSA_API_KEY",
               },
               {
+                id: "setup.automations",
                 label: "Schedule the automations",
                 desc: "Creates the six-automation fleet — intake, repair, and the QA / Product Planning / Monitoring loops — on the harness’s native scheduler.",
                 command: "/lisa:setup-automations",
-                done: false,
               },
               {
+                id: "setup.exploration",
                 label: "Configure exploration environments",
                 desc: "Per-environment mutation policy and test identity so agents can use the product safely (production defaults to forbidden).",
                 command: ".lisa.config.json exploration.*",
-                done: false,
               },
             ],
           },
@@ -1592,17 +1589,17 @@
             card: "Optional",
             items: [
               {
+                id: "setup.wiki",
                 label: "Install the LLM wiki",
                 desc: "In-repo knowledge base agents read and maintain.",
                 command: "/lisa:wiki:install",
-                done: false,
                 optional: true,
               },
               {
+                id: "setup.starter-provenance",
                 label: "Record starter provenance",
                 desc: "Which starter repo(s) this project descends from, enabling starter sync (planned).",
                 command: ".lisa.config.json starter.*",
-                done: false,
                 optional: true,
               },
             ],
@@ -5085,6 +5082,30 @@
       let healthChipState = { state: "idle" };
       /* Durable Health view model projected by every whole-page render. */
       let healthViewState = { state: "idle" };
+      const SETUP_READINESS_CHECKS = [
+        "setup.install",
+        "setup.sync",
+        "setup.agent-ready",
+        "setup.standards",
+        "setup.tracker",
+        "setup.prd-source",
+        "setup.github-governance",
+        "setup.secrets",
+        "setup.automations",
+        "setup.exploration",
+        "setup.wiki",
+        "setup.starter-provenance",
+      ];
+      const SETUP_READINESS_UNAVAILABLE =
+        "Setup readiness is unavailable. Re-open the console after checking the local Lisa service.";
+      /* Durable Setup state survives every whole-page live-status re-render. */
+      let setupReadinessState = {
+        state: "loading",
+        findings: new Map(),
+        message: "Checking current setup readiness.",
+      };
+      let setupReadinessGeneration = 0;
+      let setupReadinessInFlight = null;
 
       function el(tag, cls, html) {
         const node = document.createElement(tag);
@@ -5711,6 +5732,7 @@
 
       function buildChecklist(block) {
         const card = el("div", "card");
+        card.dataset.setupChecklist = block.card;
         const head = el("div", "card-head");
         const note = el("span", "note");
         const countDone = () =>
@@ -5724,35 +5746,38 @@
         card.appendChild(head);
         const body = el("div", "card-body");
         block.items.forEach(item => {
-          const row = el("div", "check-item" + (item.done ? " done" : ""));
+          const finding = setupReadinessState.findings.get(item.id);
+          const isDone = finding && finding.status === "pass";
+          const reason =
+            setupReadinessState.state === "result" && finding
+              ? finding.reason
+              : setupReadinessState.message;
+          const row = el("div", "check-item" + (isDone ? " done" : ""));
+          row.dataset.setupCheck = item.id;
           const right = el("div", "check-right");
-          const refreshRight = () => {
-            const isDone = row.classList.contains("done");
-            right.innerHTML = "";
-            right.appendChild(
-              el(
-                "span",
-                "badge " +
-                  (isDone ? "pass" : item.optional ? "default" : "warn"),
-                isDone ? "done" : item.optional ? "not set up" : "pending"
-              )
-            );
-            if (!isDone && item.why) {
-              right.appendChild(el("span", "status-why", esc(item.why)));
-            }
-            right.appendChild(
-              el(
-                "span",
-                "status-why",
-                "read-only: setup checklist state has not shipped yet"
-              )
-            );
-          };
+          right.appendChild(
+            el(
+              "span",
+              "badge " +
+                (isDone
+                  ? "pass"
+                  : finding?.status === "fail"
+                    ? "fail"
+                    : "warn"),
+              isDone ? "done" : "pending"
+            )
+          );
+          if (!isDone) {
+            right.appendChild(el("span", "status-why", esc(reason)));
+          }
           const ck = el("button", "ck");
           ck.type = "button";
           ck.disabled = true;
-          ck.title = "read-only: setup checklist state has not shipped yet";
-          ck.setAttribute("aria-label", item.label + " checklist status");
+          ck.title = reason;
+          ck.setAttribute(
+            "aria-label",
+            item.label + ": " + (isDone ? "done" : "pending") + ". " + reason
+          );
           row.appendChild(ck);
           const content = el("div", "check-content");
           const lab = el("div", "check-label", esc(item.label));
@@ -5765,7 +5790,6 @@
             content.appendChild(el("span", "keychip", esc(item.command)));
           }
           row.appendChild(content);
-          refreshRight();
           row.appendChild(right);
           body.appendChild(row);
         });
@@ -5947,6 +5971,7 @@
 
       let activeSection = "overview";
       function showSection(sid) {
+        const previousSection = activeSection;
         activeSection = sid;
         document
           .querySelectorAll(".section")
@@ -5962,6 +5987,11 @@
           history.replaceState(null, "", "#" + sid);
         applyFilter(document.getElementById("search").value);
         window.scrollTo({ top: 0 });
+        if (sid === "setup" && previousSection !== "setup") {
+          void hydrateSetupReadiness({
+            refresh: setupReadinessGeneration > 0,
+          });
+        }
       }
 
       function applyFilter(query) {
@@ -6677,6 +6707,128 @@
         }
       }
 
+      /** Validate the strict three-field Setup readiness transport contract. */
+      function requireSetupReadinessResult(candidate) {
+        const isObject = value =>
+          value !== null && typeof value === "object" && !Array.isArray(value);
+        const hasExactKeys = (value, keys) =>
+          isObject(value) &&
+          Object.keys(value).sort().join(",") === [...keys].sort().join(",");
+        const canonicalUtc = value => {
+          if (
+            typeof value !== "string" ||
+            !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(value)
+          ) {
+            return false;
+          }
+          const instant = new Date(value);
+          return (
+            !Number.isNaN(instant.valueOf()) && instant.toISOString() === value
+          );
+        };
+        const readableReason = value =>
+          typeof value === "string" &&
+          value.trim() === value &&
+          value.length > 0 &&
+          new TextEncoder().encode(value).length <= 2000 &&
+          !Array.from(value).some(character => {
+            const codePoint = character.codePointAt(0) ?? 0;
+            return (
+              codePoint <= 0x1f ||
+              (codePoint >= 0x7f && codePoint <= 0x9f) ||
+              (codePoint >= 0x202a && codePoint <= 0x202e) ||
+              (codePoint >= 0x2066 && codePoint <= 0x2069)
+            );
+          });
+        if (
+          !hasExactKeys(candidate, [
+            "schemaVersion",
+            "observedAt",
+            "findings",
+          ]) ||
+          candidate.schemaVersion !== 1 ||
+          !canonicalUtc(candidate.observedAt) ||
+          !Array.isArray(candidate.findings) ||
+          candidate.findings.length !== SETUP_READINESS_CHECKS.length
+        ) {
+          throw new TypeError(
+            "Setup readiness response is not valid schema v1 JSON"
+          );
+        }
+        const findings = new Map();
+        candidate.findings.forEach((finding, index) => {
+          if (
+            !hasExactKeys(finding, ["check", "layer", "status", "reason"]) ||
+            finding.check !== SETUP_READINESS_CHECKS[index] ||
+            finding.layer !== "deterministic" ||
+            !["pass", "warn", "fail"].includes(finding.status) ||
+            !readableReason(finding.reason)
+          ) {
+            throw new TypeError(
+              "Setup readiness response contains an invalid finding"
+            );
+          }
+          findings.set(finding.check, finding);
+        });
+        return findings;
+      }
+
+      /** Rebuild only the two Setup checklist cards from durable readiness state. */
+      function repaintSetupChecklist() {
+        const section = document.getElementById("section-setup");
+        if (!section) return;
+        const blocks = DATA.sections.setup.blocks.filter(
+          block => block.type === "checklist"
+        );
+        const cards = section.querySelectorAll("[data-setup-checklist]");
+        blocks.forEach((block, index) => {
+          if (cards[index]) cards[index].replaceWith(buildChecklist(block));
+        });
+      }
+
+      /** Read current Setup readiness with same-entry dedupe and stale-response protection. */
+      function hydrateSetupReadiness({ refresh = false } = {}) {
+        if (!refresh && setupReadinessInFlight) {
+          return setupReadinessInFlight;
+        }
+        setupReadinessState = {
+          state: "loading",
+          findings: new Map(),
+          message: "Checking current setup readiness.",
+        };
+        repaintSetupChecklist();
+        const generation = ++setupReadinessGeneration;
+        const request = (async () => {
+          let nextState;
+          try {
+            const response = await fetch("/api/setup-readiness", {
+              cache: "no-store",
+            });
+            if (!response.ok) throw new Error(SETUP_READINESS_UNAVAILABLE);
+            nextState = {
+              state: "result",
+              findings: requireSetupReadinessResult(await response.json()),
+              message: "",
+            };
+          } catch {
+            nextState = {
+              state: "error",
+              findings: new Map(),
+              message: SETUP_READINESS_UNAVAILABLE,
+            };
+          }
+          if (generation === setupReadinessGeneration) {
+            setupReadinessState = nextState;
+            repaintSetupChecklist();
+          }
+          if (setupReadinessInFlight === request) {
+            setupReadinessInFlight = null;
+          }
+        })();
+        setupReadinessInFlight = request;
+        return request;
+      }
+
       /** Run exactly one deterministic Health v1 check through the local server. */
       async function runHealthCheck() {
         const button = document.getElementById("runHealthCheckButton");
@@ -7224,11 +7376,11 @@
       function boot() {
         hydrateFromLiveConfig();
         renderAll();
-        void hydrateLiveStatuses();
-        void hydrateHealth();
         showSection(location.hash ? location.hash.slice(1) : "overview");
         if (!document.getElementById("section-" + activeSection))
           showSection("overview");
+        void hydrateLiveStatuses();
+        void hydrateHealth();
       }
       if (document.readyState === "loading") {
         document.addEventListener("DOMContentLoaded", boot);