baldart 3.9.0 → 3.12.0

package/framework/docs/UPGRADE-3.12-UI-COHERENCE.md

@@ -0,0 +1,268 @@
+# Upgrade to v3.12.0 — UI Excellence & Registry Coherence
+
+> **Audience**: Claude (or a human operator) working inside a **consumer
+> repo** (any project that installed BALDART via `npx baldart add` and just
+> ran `npx baldart update` to v3.12.0). This document is the alignment
+> walkthrough — it does not replace the CHANGELOG (which describes *what*
+> changed in the framework); it tells you *what to do* in this specific
+> project to align an existing graphic organization with the new discipline.
+>
+> Run this once per project after updating to v3.12.0. It is idempotent —
+> re-running on an already-aligned project produces an empty backlog.
+
+## What changed in one paragraph
+
+The `ui-expert` agent received a major upgrade (UI states taxonomy,
+Performance Gates, modern CSS, AI-era patterns, 60+ categorized red flags),
+and the registry-first discipline gained a **post-intervention coherence
+gate**: every UI task that introduces, modifies, or surfaces a primitive or
+token must reconcile the registry (`INDEX.md` + `components/<Name>.md` +
+`tokens-reference.md`) **in the same change**. Drift can no longer wait for
+Monday's `ds-drift` routine — it must be resolved at introduction. Three
+layers now enforce coherence: per-task (in `ui-expert` / `ui-design` /
+`frontend-design`) → per-merge (`code-reviewer`) → weekly safety net
+(`ds-drift`). The full text-of-record lives in
+`.framework/framework/agents/design-system-protocol.md` § "Post-Intervention
+Coherence Check".
+
+## Step 0 — Should you even run this walkthrough?
+
+Run only if all three are true. Otherwise, exit cleanly.
+
+```
+[ ] baldart.config.yml has features.has_design_system: true
+[ ] paths.design_system points to an existing directory
+[ ] That directory contains at least an INDEX.md
+```
+
+If `has_design_system: false` → there is nothing to align. The new gates
+short-circuit. Optionally consider bootstrapping a registry via
+`/design-system-init` (skill ships with v3.11.0+).
+
+If `has_design_system: true` but `paths.design_system` does not exist or is
+empty → run `/design-system-init` first; come back to this walkthrough
+after.
+
+## Step 1 — Surface the current state (no edits yet)
+
+Before touching anything, build a snapshot. Do the four scans below and
+emit one finding per item. **Do not fix anything yet** — fixing without a
+baseline produces churn and hides the size of the gap.
+
+### 1.1 — Silent primitives (`DS_INDEX_DRIFT` baseline)
+
+Goal: find components that exist in the source tree but are NOT documented
+in `INDEX.md`.
+
+```bash
+# List candidate primitives in the project (adjust glob to match the project)
+find $(yq '.paths.components_primitives' baldart.config.yml) \
+  -maxdepth 2 -type f \( -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" \)
+```
+
+For each filename `<Name>.tsx`, grep `INDEX.md` for `<Name>` (case-sensitive).
+Anything not found is a silent primitive. Record name + path + estimated
+broadness (broadly-useful vs. surface-specific). Output:
+
+```
+SILENT_PRIMITIVES:
+  - Badge        | components/ui/Badge.tsx       | broadly-useful
+  - PriceTag     | components/marketing/Price.tsx | surface-specific
+  ...
+```
+
+### 1.2 — Stale specs (`DS_COMPONENT_STALE` baseline)
+
+For each `${paths.design_system}/components/<Name>.md`:
+
+1. Locate the source file for `<Name>`.
+2. Compare the spec's documented props/variants against the source's actual
+   exported types/props. Use `codebase-architect` if the project has LSP
+   enabled — it does this cheaply via go-to-definition.
+3. Spec older than the source's last edit in git AND with mismatch on
+   props/variants → `DS_COMPONENT_STALE`.
+
+```
+STALE_SPECS:
+  - Button.md   | source mtime 2026-04-12, spec mtime 2026-01-05
+                | spec missing variants: "danger-outline", "icon-only"
+                | spec missing prop: leftIcon
+  ...
+```
+
+### 1.3 — Hardcoded tokens (`DS_TOKENS_DRIFT` baseline)
+
+Scan the codebase for values that bypass `tokens-reference.md`:
+
+```bash
+# Hardcoded hex/rgb in styled code (adjust path to actual sources)
+grep -RInE '#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)' \
+  $(yq '.paths.components_root' baldart.config.yml) \
+  --include='*.tsx' --include='*.css' --include='*.scss'
+
+# Hardcoded box-shadow tuples
+grep -RInE 'box-shadow:\s*[^v;]+;' \
+  $(yq '.paths.components_root' baldart.config.yml)
+
+# Spacing values outside the scale (heuristic: any odd or > 64 px literal)
+grep -RInE '(padding|margin|gap|inset)[^:]*:\s*[0-9]+px' \
+  $(yq '.paths.components_root' baldart.config.yml)
+```
+
+For each hit, classify:
+- **Tokenizable** — exact value matches an existing token → trivial replace
+- **Missing token** — value would belong to the system but no token exists →
+  propose adding to `tokens-reference.md`
+- **Justified one-off** — surface-specific value with a documented reason →
+  leave + add a code comment citing the exception
+
+```
+HARDCODED_TOKENS:
+  - tokenizable:      37 hits across 12 files
+  - missing-token:    8 hits (suggest 3 new tokens)
+  - justified-one-off: 2 hits
+```
+
+### 1.4 — Overlay drift (only if `.baldart/overlays/ui-expert.md` exists)
+
+The v3.12.0 base `ui-expert.md` now defines authoritatively things the
+overlay may have previously codified. Likely conflict points:
+
+| Overlay section likely to conflict | Why |
+|---|---|
+| Custom "Red Flags" list | Base now has 60+ categorized red flags — overlay items may be duplicates or contradictions |
+| Custom workflow steps | Base now has step 10 (Review) and step 12 (Design) as BLOCKING completion gates — overlay must not skip them |
+| Custom token rules | Base now references the Reference Tables in `design-system-protocol.md` — overlay numeric scales should defer to the protocol |
+| Custom motion guidance | Base now delegates to `motion-design` skill — overlay should point there, not redefine durations/easings |
+
+Read `.baldart/overlays/ui-expert.md` and report each section that:
+- Uses `## [OVERRIDE]` marker on a section the base now owns
+  authoritatively (red flags, workflow steps, expertise enumeration).
+- Uses `## [APPEND]` to add red flags that are now in the base set
+  (duplicates).
+- Hardcodes scales / thresholds / durations the new protocol tables now
+  declare canonically.
+
+Output:
+
+```
+OVERLAY_DRIFT:
+  - [OVERRIDE] Your Expertise — conflicts with expanded base (consider [APPEND] instead)
+  - [APPEND]   Red Flags — 4 of 6 items now in base list (deduplicate)
+  - hardcoded  motion duration 250ms — defer to motion-design timing tables
+```
+
+### 1.5 — Emit the baseline report
+
+Save the four sections above as:
+
+```
+${paths.references_dir:-docs/references}/ds-coherence-baseline-YYYYMMDD.md
+```
+
+Present a short summary to the user (totals per finding type + estimated
+size of the reconciliation work). **Stop here for user confirmation** before
+proceeding to Step 2.
+
+## Step 2 — Prioritize reconciliation
+
+Not all findings are equal. Rank them so the user gets quick wins first.
+
+| Priority | Criteria | Action |
+|---|---|---|
+| **P0** | Silent primitive used in ≥ 3 places AND broadly-useful | Add INDEX entry + scaffold full `components/<Name>.md` spec |
+| **P0** | Hardcoded token (tokenizable) in the design-system entry-point file or in a primitive | Replace with the existing token reference inline |
+| **P1** | Silent primitive used in 1–2 places, broadly-useful | Add INDEX entry + stub spec (`status: needs-review`) |
+| **P1** | Stale spec on a primitive used by ≥ 3 features | Update spec to match source |
+| **P1** | Missing-token (hardcoded value that should be a token) used > 5 times | Propose new token + update `tokens-reference.md` + replace inline |
+| **P2** | Surface-specific silent primitive | Add INDEX entry with `scope: local` + 2-line note |
+| **P2** | Stale spec on a rarely-used primitive | Update spec OR open follow-up card |
+| **P3** | Justified one-off hardcoded value | Add inline code comment citing the exception |
+| **P3** | Overlay-base conflict that does not break the new gates | Refactor overlay to use `[APPEND]` instead of `[OVERRIDE]` |
+
+Convert the prioritized findings into the project's backlog format. If
+`features.has_backlog: true`:
+
+- One card per P0 item.
+- One card per **group** of P1 items (e.g. "Reconcile 8 stale specs in
+  `components/forms/`").
+- One catch-all card for P2/P3 batched cleanup.
+
+If no backlog feature → emit a markdown checklist under
+`${paths.references_dir}/ds-coherence-followups-YYYYMMDD.md` and present it
+to the user.
+
+## Step 3 — Quick wins (apply now, with user approval)
+
+Apply only the items that are **truly trivial and reversible**:
+
+- Inline replacement of `tokenizable` hardcoded values (the token already
+  exists; the change is a pure substitution).
+- Adding INDEX entries for surface-specific silent primitives (no spec
+  needed beyond the scope: local note).
+- Removing overlay `[APPEND]` items that exactly duplicate the new base
+  red flags.
+
+Group them in **one commit per category** (`chore(ds): replace hardcoded
+tokens with existing references`, `docs(ds): index surface-specific
+primitives`, etc.) so the diff is reviewable.
+
+Anything more substantial (new specs, new tokens, overlay refactors, stale
+spec updates) → backlog cards, not inline edits. Resist the urge to "just
+clean it up while you're there" — that turns the alignment into a
+multi-day refactor.
+
+## Step 4 — Verify the new gates fire correctly
+
+After the quick wins land, pick **one** small UI task that touches a
+primitive (e.g. add a variant to an existing Button) and run it end-to-end:
+
+1. Invoke `ui-expert` or the relevant skill.
+2. Make the code change.
+3. Observe that the agent's final output explicitly reports the
+   Post-Intervention Coherence Check result — either "no findings" or one
+   of the `DS_*_DRIFT` codes.
+
+If the agent silently skips this step → the upgrade didn't propagate to
+this project. Check:
+
+- `npx baldart status` confirms v3.12.0 installed.
+- `.framework/framework/agents/design-system-protocol.md` contains the
+  "Post-Intervention Coherence Check" section.
+- `.framework/framework/.claude/agents/ui-expert.md` has step 10 (Review)
+  and step 12 (Design).
+
+If any of those is stale → `npx baldart update` again, then re-test.
+
+## Step 5 — Establish the rhythm
+
+Going forward, the operator (you, or future Claude instances on this
+project):
+
+- Treats the coherence check at end-of-task as **non-negotiable**, same
+  category as "tests pass". A UI task without the coherence-check report
+  is incomplete.
+- Treats `DS_*_DRIFT` findings surfaced by `code-reviewer` as merge
+  blockers — they indicate the upstream check was skipped.
+- Reads the weekly `ds-drift` routine report when it lands and treats any
+  finding there as a **process bug** (somewhere the upstream gates were
+  bypassed), not just a content fix.
+
+## Reference points (resolved by `npx baldart update`)
+
+After update, these files exist locally and are authoritative:
+
+| Concern | File |
+|---|---|
+| What "coherence check" means + decision matrix | `.framework/framework/agents/design-system-protocol.md` § "Post-Intervention Coherence Check" |
+| Numeric reference tables (type / contrast / spacing / density) | `.framework/framework/agents/design-system-protocol.md` § "Reference Tables (embed)" |
+| Token cascade primitive → semantic → component | `.framework/framework/agents/design-system-protocol.md` § "Token Cascade" |
+| Upgraded `ui-expert` (states taxonomy, red flags, gates) | `.framework/framework/.claude/agents/ui-expert.md` |
+| Code-reviewer rule 8 (merge gate) | `.framework/framework/.claude/agents/code-reviewer.md` § "Design System Compliance" rule 8 |
+| `ui-design` Step H (design-time gate) | `.framework/framework/.claude/skills/ui-design/SKILL.md` |
+| Performance Gates (CWV 2026, LCP/INP/CLS) | `.framework/framework/.claude/skills/frontend-design/SKILL.md` § "Performance Gates" |
+| Motion + reduced-motion + View Transitions | `.framework/framework/.claude/skills/motion-design/reference/accessibility-and-modern-apis.md` |
+| Weekly safety net | `.framework/framework/routines/ds-drift.routine.yml` |
+
+The framework files are symlinked, so reading them via the paths above
+gets the live, current version.

package/framework/templates/baldart.config.template.yml

@@ -112,6 +112,28 @@ features:
   # LLM-wiki overlay (paths.wiki_dir + capture/wiki-curator loop).
   has_wiki_overlay: false
 
+  # LSP symbol-search layer. When true, agents and skills that explore code
+  # (codebase-architect, context-primer, bug, prd, new, simplify) prefer
+  # language-server "find references / go to definition" over Grep for
+  # identifier queries, falling back to Grep only when LSP is unavailable
+  # or the query isn't a symbol. See framework/agents/code-search-protocol.md.
+  # `baldart configure` installs the relevant language servers when enabled.
+  has_lsp_layer: false
+
+# ─── LSP ─────────────────────────────────────────────────────────────────
+# State of the LSP layer for this project. Populated by `baldart configure`
+# (and by `npx baldart lsp install` / the `/lsp-bootstrap` skill). Leave
+# empty if `features.has_lsp_layer: false`.
+lsp:
+  # Languages whose language server BALDART has installed/verified locally.
+  # Identifiers map to adapters under src/utils/lsp-adapters/
+  # (typescript, python, go, rust, ruby — extend as needed).
+  installed_servers: []
+
+  # When true, `baldart doctor` re-verifies the binaries are reachable on
+  # every run. Disable on CI if the verify step is too noisy.
+  auto_verify: true
+
 # ─── GIT ─────────────────────────────────────────────────────────────────
 # Controls how worktree-manager (`/mw`) integrates a worktree's feature
 # branch back into `develop`.

package/framework/templates/overlays/agents/codebase-architect.lsp-example.md

@@ -0,0 +1,53 @@
+---
+base_agent: codebase-architect
+base_agent_version: 3.10.0
+mode: extend
+---
+
+> **How to use this example**
+>
+> Copy this file to `.baldart/overlays/agents/codebase-architect.md` (drop the
+> `.lsp-example`) when you want to add project-specific LSP guidance on top of
+> the shipped `agents/code-search-protocol.md`. The framework regenerates
+> `.claude/agents/codebase-architect.md` from base + overlay on every
+> `npx baldart update`.
+>
+> Section markers (see `framework/templates/overlays/README.md`):
+> - `## [OVERRIDE] <heading>` — replace the entire matching H2 from the base.
+> - `## [APPEND] <heading>`  — add content after the base section.
+> - `## [PREPEND] <heading>` — add content before the base section.
+> - `## <heading>` with no marker — appended at the end as a new custom section.
+>
+> Skip this overlay entirely if the shipped protocol is enough — the base
+> agent already wires LSP correctly when `features.has_lsp_layer: true`.
+
+## [APPEND] LSP Symbol Search
+
+Project-specific tuning on top of `framework/agents/code-search-protocol.md`:
+
+- **Preferred entry points.** For identifier-shaped lookups in this repo,
+  start with `find-references` on the symbol exported from
+  `src/<your-canonical-module>/index.ts` (or your equivalent). The export
+  surface is small enough that the references list converges in 1–2 calls.
+- **Per-language quirks.**
+  - TypeScript: monorepo packages under `packages/<name>` need
+    `tsserver` workspaces enabled. If LSP returns zero references for a
+    symbol you know is used cross-package, fall back to Grep scoped to
+    `packages/*/src/`.
+  - Python: pyright honors `extraPaths` from `pyrightconfig.json` — if
+    you re-rooted sources, double-check the config before reporting "no
+    references found".
+- **Don't chase generated code.** Skip LSP results pointing into `dist/`,
+  `.next/`, `coverage/`, or any path matching the project's `.gitignore` —
+  treat them as noise.
+
+## Project-only conventions
+
+Custom rules with no equivalent in the base — appended as a new H2:
+
+- All `find-references` outputs over 50 callsites trigger a refactor
+  conversation with the maintainer before any rename / signature change
+  proceeds.
+- When LSP is unavailable, write the reason (binary missing / plugin not
+  loaded / language not yet adopted) into the analysis output so reviewers
+  understand why Grep was used instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.9.0",
+  "version": "3.12.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/configure.js

@@ -3,6 +3,8 @@ const path = require('path');
 const yaml = require('js-yaml');
 const UI = require('../utils/ui');
 const toolAdapters = require('../utils/tool-adapters');
+const LspInstaller = require('../utils/lsp-installer');
+const lspAdapters = require('../utils/lsp-adapters');
 
 const CONFIG_FILE = 'baldart.config.yml';
 // The subtree pull copies the entire BALDART repo (which itself has a
@@ -342,6 +344,9 @@ function detect(cwd = process.cwd()) {
       has_adrs: countMatches('docs/decisions', /^ADR-.*\.md$/) > 0,
       has_prd_workflow: exists('docs/prd'),
       has_wiki_overlay: exists('docs/wiki'),
+      // LSP recommended when any supported language server adapter would
+      // detect this project. Drives the default for the configure prompt.
+      has_lsp_layer: lspAdapters.detectAll(cwd).length > 0,
     },
     tools: {
       enabled: toolAdapters.defaultEnabled(cwd)
@@ -506,6 +511,7 @@ async function interactivePrompts(merged, detected) {
     ['has_adrs', 'Project uses ADR workflow?'],
     ['has_prd_workflow', 'Project uses PRD workflow (docs/prd/)?'],
     ['has_wiki_overlay', 'Project has LLM-wiki overlay (docs/wiki/)?'],
+    ['has_lsp_layer', 'Enable LSP symbol-search layer? (recommended for large codebases)'],
   ]) {
     const [key, question] = flag;
     const currentVal = merged.features[key];
@@ -516,6 +522,27 @@ async function interactivePrompts(merged, detected) {
     merged.features[key] = await promptForKey(question, proposedDefault, 'confirm');
   }
 
+  // ---- Design-system bootstrap hint (since v3.11.0) ---------------------
+  // If the user said YES to has_design_system but autodetect found no path
+  // (i.e. they WANT a registry but it doesn't exist yet), surface the
+  // bootstrap skill so they don't end up with a flag that points at nothing.
+  // If they said NO, plant a soft pointer for the future.
+  if (merged.features.has_design_system === true && !detected.paths.design_system) {
+    UI.info(
+      'No design-system path was detected on disk. After configure, run\n' +
+      '  /design-system-init  (or invoke the skill)\n' +
+      'to scaffold INDEX.md + tokens-reference.md + per-component specs at\n' +
+      'docs/design-system/. The registry-first protocol (ui-expert, ui-design,\n' +
+      'frontend-design, /design-review) needs these files to enforce coherence.'
+    );
+  } else if (merged.features.has_design_system === false) {
+    UI.info(
+      'has_design_system=false — UI work will rely only on ui_guidelines.md.\n' +
+      'When you want visual coherence + component reuse enforced project-wide,\n' +
+      'run /design-system-init to scaffold a registry from your existing code.'
+    );
+  }
+
   // Path prompts — only ask for paths whose feature is enabled and value missing
   UI.section('Paths (autodetected — confirm or override)');
   const pathPrompts = [
@@ -544,6 +571,48 @@ async function interactivePrompts(merged, detected) {
     merged.paths[key] = await promptForKey(`${label}`, proposed);
   }
 
+  // ---- LSP layer (since v3.10.0) ----------------------------------------
+  // Only runs when the user opted in above. Idempotent: re-running configure
+  // on an already-installed project re-detects, asks which servers to keep,
+  // and updates lsp.installed_servers accordingly.
+  merged.lsp = merged.lsp || { installed_servers: [], auto_verify: true };
+  if (merged.features.has_lsp_layer === true) {
+    UI.section('LSP layer (install language servers for symbol search)');
+    const installer = new LspInstaller(process.cwd());
+    const detectedLangs = installer.detectLanguages();
+    if (detectedLangs.length === 0) {
+      UI.warning('No supported languages detected (tsconfig.json, pyproject.toml, go.mod, Cargo.toml, Gemfile).');
+      UI.info('Skipping LSP install. You can run `/lsp-bootstrap` or `npx baldart configure` later.');
+    } else {
+      const recs = installer.recommend(detectedLangs);
+      const already = new Set(merged.lsp.installed_servers || []);
+      const toInstall = [];
+      for (const r of recs) {
+        const note = already.has(r.name) ? ' (already recorded)' : '';
+        UI.info(`${r.label} → ${r.binary} (${r.installMode})${note}`);
+        const want = await UI.confirm(`Install ${r.label}?`, true);
+        if (want) toInstall.push(r.name);
+      }
+      if (toInstall.length) {
+        const { installed, skipped, manual } = await installer.installServers(toInstall, { interactive: false });
+        for (const m of manual) {
+          UI.warning(`System-level install required for ${m.label}:`);
+          UI.code(m.command, `Recorded as pending — run \`baldart doctor\` after installing to verify.`);
+        }
+        const verify = installer.verifyServers(installed.map(i => i.name));
+        const verified = verify.filter(v => v.ok).map(v => v.name);
+        const newSet = new Set([...(merged.lsp.installed_servers || []), ...verified, ...manual.map(m => m.name)]);
+        merged.lsp.installed_servers = Array.from(newSet);
+        if (skipped.length) {
+          UI.warning(`Skipped: ${skipped.map(s => `${s.name} (${s.reason})`).join(', ')}`);
+        }
+      }
+    }
+  } else {
+    // Feature disabled — wipe the state so `installed_servers` doesn't lie.
+    merged.lsp.installed_servers = [];
+  }
+
   UI.section('Stack (autodetected from package.json — confirm or override)');
   const charting = merged.stack.charting;
   const chartingCanonical = await promptForKey(

package/src/commands/doctor.js

@@ -30,6 +30,7 @@ const GitUtils = require('../utils/git');
 const UI = require('../utils/ui');
 const State = require('../utils/state');
 const Hooks = require('../utils/hooks');
+const LspInstaller = require('../utils/lsp-installer');
 
 const FRAMEWORK_DIR = '.framework';
 const REPO_DEFAULT = 'antbald/BALDART';
@@ -196,6 +197,25 @@ async function detectState(cwd, opts = {}) {
 
     state.editGateRegistered = false;
     try { state.editGateRegistered = Hooks.isRegistered(cwd); } catch (_) {}
+
+    // ---- LSP layer (since v3.10.0) -------------------------------------
+    state.lspEnabled = false;
+    state.lspInstalled = [];
+    state.lspBroken = [];
+    try {
+      // Reuse the `config` already parsed above instead of re-reading the file.
+      if (config && !config.__malformed && config.features && config.features.has_lsp_layer === true) {
+        state.lspEnabled = true;
+        const installed = (config.lsp && config.lsp.installed_servers) || [];
+        state.lspInstalled = installed;
+        const autoVerify = !(config.lsp && config.lsp.auto_verify === false);
+        if (autoVerify && installed.length) {
+          const installer = new LspInstaller(cwd);
+          const results = installer.verifyServers(installed);
+          state.lspBroken = results.filter(r => !r.ok).map(r => r.name);
+        }
+      }
+    } catch (_) { /* never block doctor on LSP probe */ }
   }
 
   return state;
@@ -306,6 +326,27 @@ function planActions(state) {
     });
   }
 
+  if (state.lspEnabled && state.lspBroken && state.lspBroken.length > 0) {
+    actions.push({
+      key: 'lsp-fix',
+      label: `Reinstall ${state.lspBroken.length} broken LSP server(s)`,
+      why: `LSP layer is enabled but these language servers are not reachable: ${state.lspBroken.join(', ')}. Symbol search will silently fall back to Grep until they are reinstalled.`,
+      autoOk: false, // touches dev-deps and is the kind of action a user may
+      // have made deliberate (switching from npm pyright to system pyright);
+      // keep the outer prompt + the per-server confirm both alive.
+      run: async () => {
+        const installer = new LspInstaller(state.cwd);
+        const { installed, manual, skipped } = await installer.installServers(state.lspBroken);
+        if (installed.length) UI.success(`Reinstalled: ${installed.map(i => i.name).join(', ')}`);
+        for (const m of manual) {
+          UI.warning(`System-level reinstall required for ${m.label}:`);
+          console.log(`    ${m.command}`);
+        }
+        if (skipped.length) UI.warning(`Skipped: ${skipped.map(s => `${s.name} (${s.reason})`).join(', ')}`);
+      },
+    });
+  }
+
   const remoteAhead = state.remote.fetched && state.remote.behind > 0;
   const hasLocalWork = state.workingTreeDirty > 0 || state.commitsAhead > 0;
 
@@ -437,6 +478,20 @@ function renderDiagnostic(state) {
     state.editGateRegistered ? 'ok' : 'warn'
   ));
 
+  if (state.lspEnabled) {
+    const total = state.lspInstalled.length;
+    const broken = state.lspBroken.length;
+    const value = total === 0
+      ? 'enabled but no servers installed'
+      : broken === 0
+        ? `${total} server(s) verified (${state.lspInstalled.join(', ')})`
+        : `${broken}/${total} broken (${state.lspBroken.join(', ')})`;
+    const severity = total === 0 || broken > 0 ? 'warn' : 'ok';
+    console.log(statusLine('LSP layer', value, severity));
+  } else {
+    console.log(statusLine('LSP layer', 'disabled', 'ok'));
+  }
+
   console.log();
 }
 

package/src/utils/lsp-adapters/go.js

@@ -0,0 +1,29 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Go LSP adapter — gopls.
+ *
+ * gopls is a Go binary; we can't install it into node_modules. installMode
+ * is 'system' which means the configure flow prints the canonical install
+ * command and the user runs it themselves. The verify step still checks
+ * that the binary is in PATH.
+ */
+class GoAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'go'; }
+  get label() { return 'Go (gopls)'; }
+  get binary() { return 'gopls'; }
+  get installMode() { return 'system'; }
+
+  installCommand() { return 'go install golang.org/x/tools/gopls@latest'; }
+  verifyCommand() { return 'gopls version'; }
+  claudePluginId() { return null; }
+
+  static detect(cwd = process.cwd()) {
+    return fs.existsSync(path.join(cwd, 'go.mod'));
+  }
+}
+
+module.exports = GoAdapter;

package/src/utils/lsp-adapters/index.js

@@ -0,0 +1,49 @@
+const TypeScriptAdapter = require('./typescript');
+const PythonAdapter     = require('./python');
+const GoAdapter         = require('./go');
+const RustAdapter       = require('./rust');
+const RubyAdapter       = require('./ruby');
+
+/**
+ * LSP adapter registry.
+ *
+ * Adding a new language (Java, C/C++, PHP, Elixir, …):
+ *   1. Create `src/utils/lsp-adapters/<lang>.js` exporting a class with the
+ *      same shape as TypeScriptAdapter (name, label, binary, installMode,
+ *      installCommand, verifyCommand, claudePluginId, static detect).
+ *   2. Add it to the REGISTRY below.
+ *   3. (Optional) Wire a Claude Code plugin id if one exists.
+ *
+ * Adapters describe *how* to install/verify a language server; they do NOT
+ * speak LSP themselves. The actual symbol search at runtime happens through
+ * whatever Claude Code plugin or MCP server the user has loaded.
+ */
+const REGISTRY = {
+  typescript: TypeScriptAdapter,
+  python:     PythonAdapter,
+  go:         GoAdapter,
+  rust:       RustAdapter,
+  ruby:       RubyAdapter
+};
+
+function listAdapters() { return Object.keys(REGISTRY); }
+
+function getAdapter(name, cwd) {
+  const Cls = REGISTRY[name];
+  if (!Cls) throw new Error(`Unknown LSP adapter: ${name}. Available: ${listAdapters().join(', ')}`);
+  return new Cls(cwd);
+}
+
+/**
+ * Probe the cwd for every known language and return the names of adapters
+ * whose static detect() fires. Pure: no install side effects.
+ */
+function detectAll(cwd = process.cwd()) {
+  return Object.entries(REGISTRY)
+    .filter(([, Cls]) => {
+      try { return Cls.detect(cwd); } catch { return false; }
+    })
+    .map(([name]) => name);
+}
+
+module.exports = { REGISTRY, listAdapters, getAdapter, detectAll };

package/src/utils/lsp-adapters/python.js

@@ -0,0 +1,42 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Python LSP adapter — Pyright.
+ *
+ * Pyright ships as both an npm package and a pip package. We default to the
+ * npm devDep route so installs stay project-local and version-pinned without
+ * touching the user's Python env. Users who already drive Python via pip/uv
+ * can override by removing pyright from devDeps and installing system-wide.
+ *
+ * Detection signal: pyproject.toml, setup.py, setup.cfg, requirements.txt,
+ * Pipfile, or a top-level .py source tree.
+ */
+class PythonAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'python'; }
+  get label() { return 'Python (Pyright)'; }
+  get binary() { return 'pyright'; }
+  get installMode() { return 'npm-dev'; }
+  get npmPackage() { return 'pyright'; }
+
+  installCommand() { return 'npm install --save-dev pyright'; }
+  verifyCommand() { return 'npx --no-install pyright --version'; }
+  claudePluginId() { return null; }
+
+  static detect(cwd = process.cwd()) {
+    const markers = ['pyproject.toml', 'setup.py', 'setup.cfg', 'requirements.txt', 'Pipfile'];
+    for (const m of markers) {
+      if (fs.existsSync(path.join(cwd, m))) return true;
+    }
+    // Fallback: a `src/` or top-level *.py file is a strong enough signal.
+    try {
+      const entries = fs.readdirSync(cwd);
+      if (entries.some(e => e.endsWith('.py'))) return true;
+    } catch { /* ignore */ }
+    return false;
+  }
+}
+
+module.exports = PythonAdapter;