baldart 3.12.0 → 3.14.0

package/CHANGELOG.md

@@ -5,6 +5,74 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.14.0] - 2026-05-23
+
+BALDART closes the **LSP install completeness gap** AND adds a long-overdue **`.framework/` gitignore self-heal** so install / update / push never trip over a stale or pre-existing ignore rule.
+
+### LSP install completeness
+
+Since v3.10.0, opting into `features.has_lsp_layer: true` installed the language-server binary (typescript-language-server, pyright, gopls, rust-analyzer, ruby-lsp) into the consumer repo — but the matching native Claude Code plugin (`<lang>-lsp@claude-plugins-official`) was left for the user to install manually via `/plugin install`. Almost nobody did, so Claude itself never invoked the LSP and code-exploration silently fell back to Grep. The "opt-in to LSP" UX was effectively broken: users thought they had it, agents behaved as if they didn't. v3.14.0 wires the two layers together — when the user opts into LSP, BALDART now installs the binary AND enables the native plugin in the same `configure` step, idempotently and gated on `claude` being in `tools.enabled`.
+
+### Added
+
+- **`claudePluginId()` returns real plugin ids** in every LSP adapter (`src/utils/lsp-adapters/{typescript,python,go,rust,ruby}.js`). Previously a `null` placeholder; now resolves to `typescript-lsp@claude-plugins-official`, `pyright-lsp@claude-plugins-official`, `gopls-lsp@claude-plugins-official`, `rust-analyzer-lsp@claude-plugins-official`, `ruby-lsp@claude-plugins-official` respectively. All plugins live in the Anthropic-published [`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official) marketplace.
+- **`LspInstaller.installClaudePlugins(serverNames, opts)`** in `src/utils/lsp-installer.js` — high-level installer that (1) verifies the `claude` CLI is on PATH, (2) idempotently registers the `claude-plugins-official` marketplace via `claude plugin marketplace add anthropics/claude-plugins-official --scope user` (no-op when already registered — list is parsed first), (3) reads `claude plugin list --json` to skip plugins already installed at any scope, (4) runs `claude plugin install <id> --scope user` per missing plugin. Defaults to `--scope user` so a single install is reused across every project on the machine (LSP plugins are machine-wide useful — project scope would create N copies). Always returns `{ installed, skipped, manual, marketplace }`; never throws.
+- **`LspInstaller.ensureClaudeMarketplace()`, `isClaudeCliAvailable()`, `listInstalledClaudePlugins()`, `verifyClaudePlugins(serverNames)`** — supporting primitives, all idempotent and degrade-open (parsing failure returns empty set → next install is attempted rather than incorrectly skipped).
+- **`baldart configure` companion-plugin step** — after installing the language servers, the configure flow now calls `installClaudePlugins(merged.lsp.installed_servers)`. Surfaces clear messaging for each branch: success (✓ Installed plugin ids), idempotent skip ("Already installed"), Claude CLI missing (manual install commands printed verbatim per plugin), or `claude` opted out of `tools.enabled` (silent skip — Codex-only users don't want Claude marketplace mutation).
+- **`baldart doctor` companion-plugin diagnostic** — `detectState` now calls `verifyClaudePlugins` when LSP is enabled and the `claude` CLI is available, populating `state.lspMissingClaudePlugins`. The `LSP layer` row in the diagnostic table reports `N server(s) verified, M Claude plugin(s) missing (…)` when the layer is half-installed. Severity `warn`.
+- **`lsp-install-claude-plugins` action** in the doctor planner — `autoOk: true` (user-scope plugin install is idempotent and fully reversible via `claude plugin uninstall`). Backfills missing plugins for installs predating v3.14.0 and recovers from manual plugin uninstalls. Pairs with other actions; never short-circuits.
+
+### Changed
+
+- **LSP opt-in is now end-to-end.** Pre-v3.14.0: `features.has_lsp_layer: true` installed the binary but the integration was dormant until the user manually enabled the plugin. Post-v3.14.0: opting in installs both layers in the same step. The framework's "always-ask, never-assume" contract still applies — when `claude` is not in `tools.enabled` OR the `claude` CLI is missing, the install gracefully degrades (no error, clear hint, deferred until the prerequisites are in place). `baldart doctor` then surfaces the half-install state on every subsequent invocation.
+
+### Notes
+
+- **No new `baldart.config.yml` keys.** The plugin install reuses `features.has_lsp_layer`, `lsp.installed_servers`, and `tools.enabled` already in place — so the [schema-change propagation rule](../.claude/projects/-Users-antoniobaldassarre-BALDART/memory/feedback_schema_change_propagation.md) does not require a new template / configure prompt / update detector for this release. Scope is hard-coded to `user` (machine-wide LSP plugins) rather than exposed as `lsp.claude_plugin_scope` — the decision is opinionated and consistent with how the official marketplace tracks its own installs. If a future release needs per-project plugin scope, *that* would trigger the propagation rule (template + prompt + update detector + this changelog).
+- **Marketplace and plugins live at `--scope user`, not project.** Three reasons: (1) LSP plugins are machine-wide useful — typescript-lsp installed once at user scope is reused by every TS project on the machine, not duplicated N times; (2) marketplace install at user scope means subsequent `baldart configure` runs in sibling projects skip the marketplace add entirely (idempotent); (3) project-scope plugins live under `.claude/` in the consumer repo, which would either need committing (noisy diffs) or `.gitignore` adjustments (extra protocol burden). User scope avoids all three.
+- **Idempotency is checked twice.** Marketplace add reads `claude plugin marketplace list --json` first; plugin install reads `claude plugin list --json` first. Re-running `baldart configure` (or `baldart doctor` with the action accepted) is a no-op when everything is in place — no spurious install commands, no error noise.
+- **Gate on `claude` in `tools.enabled`.** When the consumer has `tools.enabled: [codex]` (Codex-only), the plugin install is a silent no-op — Codex has no equivalent plugin model and Claude marketplace mutation would be off-target. Doctor diagnostics for missing plugins are similarly gated.
+- **No framework payload changes.** All work is inside `src/` — adapters, installer, configure command, doctor command. No framework agent/skill/command/protocol module touched, so existing consumers see the new behavior the next time they run `baldart configure` or `baldart doctor` after upgrading the CLI (`npm i -g baldart@latest`).
+
+### `.framework/` gitignore self-heal
+
+`.framework/` is a git subtree — it MUST be tracked. If anything in the gitignore chain (project `.gitignore`, `.git/info/exclude`, global `core.excludesFile`) matches `.framework`, every subsequent `git add` on files under that directory fails with `paths are ignored by one of your .gitignore files` — and `git subtree pull` itself errors out. Pre-v3.14.0 we relied on the user noticing and removing the rule manually; v3.14.0 detects and self-heals.
+
+### Added
+
+- **`GitUtils.checkFrameworkIgnored()` and `ensureFrameworkNotIgnored()`** in `src/utils/git.js` — `check-ignore -v --no-index .framework` to detect the offending source / line / pattern, then idempotently strip standalone `.framework` rules from the project `.gitignore` and append a one-time `!.framework` + `!.framework/**` negation block marked with `# BALDART: .framework/ is a git subtree — never ignore (auto-managed)`. Re-checks after writing — if the rule lives in a location we cannot rewrite from here (parent-dir `.gitignore` outside the repo, non-standard `core.excludesFile`), surfaces the leftover state via `{ stillIgnored: true, recheck }` so the caller can hard-fail with actionable output.
+- **Self-heal call in `baldart add`** (before `git subtree add`), **`baldart update`** (before `git subtree pull`), **`baldart push`** (before any `git add`). All three flows degrade gracefully — if `check-ignore` itself fails, the heal step prints a warning and continues; if the rule persists after heal, the command exits 1 with the resolution path printed.
+
+### Notes (gitignore)
+
+- **Idempotent across re-runs.** The negation marker is checked before appending; the strip step is a `filter` over current lines. Running `add` / `update` / `push` repeatedly on a healthy repo is a no-op.
+- **No false positives on .framework-related paths.** The strip filter matches only the six exact forms (`.framework`, `.framework/`, `/.framework`, `/.framework/`, `.framework/*`, `/.framework/*`) — `.frameworks/` or `framework/something.bak` patterns are preserved untouched.
+
+## [3.13.0] - 2026-05-23
+
+BALDART closes **two drift visibility gaps in one release**. (1) The CLI binary (installed globally via `npm i -g baldart`) and the framework payload (`.framework/` inside each consumer repo, updated by `baldart update`) drifted silently — users on an old CLI never learned that new flags, new doctor checks, or new adapters had shipped. (2) The framework payload on disk and the `.baldart/state.json` ledger could drift silently when the ledger write failed (the catch in `update.js` was silent until now), when an update flow exited mid-way, or when a manual commit excluded `.baldart/state.json` — `baldart doctor` had no way to detect or fix this. Both gaps are now closed: a **non-invasive CLI self-update notifier** for the first, and **ledger drift detection + self-heal** in the doctor for the second. The unifying theme is "no silent drift" — every layer that can fall out of sync now reports it and offers a one-step fix.
+
+### Added
+
+- **`src/utils/update-notifier.js`** — best-effort CLI self-update check. HTTPS GET to `https://registry.npmjs.org/baldart/latest` with a 1.5s timeout, cached at `~/.baldart/cli-update-check.json` (TTL 24h). Banner is printed from the cache on subsequent invocations (the very first run shows nothing — that is intentional; the check never blocks the command). The background refresh fire-and-forget: its timer is `unref()`'d and the underlying socket dies with the process, so the check can never hold the event loop open. Suppression: `BALDART_NO_UPDATE_CHECK=1`, `CI=true`, `NODE_ENV=test`, non-TTY stdout, or `--offline` on `baldart` / `baldart doctor` / `baldart version`.
+- **Top-of-run banner in `bin/baldart.js`** — when a newer baldart npm package has been detected on a previous run, every command prints a 3-line hint at startup (yellow arrow + bold version, then two gray lines): `↑ baldart X.Y.Z available (you have A.B.C)` + `Update with: npm i -g baldart@latest` + `Suppress with: BALDART_NO_UPDATE_CHECK=1`. Zero-latency (reads cache only); no banner if cache is missing or up-to-date.
+- **`CLI` row in `baldart doctor` diagnostic table** — always shown (independent of git/framework state), surfaces drift inline alongside framework version / config / overlays / hooks so the doctor remains the single pane of glass. Severity `warn` when an update is available, `ok` otherwise.
+- **CLI drift in `baldart version` box** — the existing `CLI: vX.Y.Z` line now appends `→ vA.B.C available (npm i -g baldart@latest)` when a newer version was detected.
+- **`State.reconcileInstalledVersion({ to, reason })` in `src/utils/state.js`** — new ledger reconciliation helper. Idempotent (no-op when `from === to`), audit-trailed (writes a `ledger-reconcile` history entry distinct from real `update` events), and reversible (pure local file write). Used by the doctor's new `reconcile-state-ledger` action and available for direct call from future recovery flows.
+- **Ledger drift detection in `baldart doctor`** — `detectState` now compares `.framework/VERSION` against `.baldart/state.json:installed_version` and surfaces a `stateLedgerDrift` state field when they diverge. The action planner inserts a `reconcile-state-ledger` action (`autoOk: true`, idempotent, no remote effects) that one-shot fixes the drift via `State.reconcileInstalledVersion()`. Drift is non-blocking — it pairs with other proposed actions instead of short-circuiting them.
+
+### Changed
+
+- **`src/commands/update.js`** — replaced the silent `try { State.recordUpdate(...) } catch (_) {}` on the ledger write with a visible warning + actionable next step. When the write fails or returns an unexpected `installed_version`, the user now sees a yellow warning explaining the drift (framework on disk is at vNEW but ledger still records vOLD) and is told to run `baldart doctor` to reconcile. This is the root cause of most "my doctor says I'm on the wrong version" reports — silent catches were hiding write failures (permissions, EBUSY) for weeks. New behavior makes the failure immediately visible and self-healable.
+
+### Notes
+
+- **CLI vs framework — two independent layers.** `npm i -g baldart@latest` updates the binary on disk (this package); `baldart update` updates the *framework payload* inside the consumer repo (the `.framework/` subtree). They are *independent* by design — a consumer may want to update the framework without touching the global CLI (or vice versa). The notifier surfaces drift on the *CLI* layer; the existing `Remote` row in doctor (and the `Remote:` line in `version`) surfaces drift on the *framework* layer. Both layers are now visible at a glance from the same diagnostic surface.
+- **Why not auto-install.** Three reasons we deliberately reject `npx baldart` auto-running `npm i -g`: (1) blast radius — global install impacts *every* project on the user's machine, not just the one they invoked from; (2) permissions — `npm i -g` often needs sudo (without nvm/volta), and a no-args `baldart` cannot trigger sudo prompts silently; (3) reproducibility — `--auto` runs in CI must be deterministic, so auto-updating the CLI mid-run would change behavior unpredictably. The notifier is the right level: visible, dismissible, never invasive.
+- **No new `baldart.config.yml` keys.** The notifier cache lives in `~/.baldart/cli-update-check.json` (per-user, not per-project), so the schema-change propagation rule (per `feedback_schema_change_propagation`) does not apply to this release. Suppression is via environment variable (`BALDART_NO_UPDATE_CHECK=1`) which is intentionally global — disabling the notifier in one project but enabling it in another is not a use case worth modeling.
+- **Backwards-compatible.** Pre-3.13 consumers see the new banner on their next `baldart` run after the npm package upgrades. Consumers that never want the check set `BALDART_NO_UPDATE_CHECK=1` in their shell rc; CI runs are auto-suppressed.
+- **No framework payload changes.** All work is inside `src/` and `bin/` — the framework agents/skills/commands/protocols are unchanged. This is purely a CLI-layer improvement; no consumer files are touched by `baldart update`.
+
 ## [3.12.0] - 2026-05-23
 
 BALDART completes the **UI excellence loop**: the `ui-expert` agent is upgraded from a "good but generic" baseline to a world-class UI/UX reviewer/designer, and — crucially — the registry-first discipline gains a **post-intervention coherence gate** so visual coherence is enforced not only when work begins (BLOCKING reads) but also when work ends (BLOCKING completion check). The asymmetry of v3.11.0 (registry read before, no verification after) is closed: every UI change introduced by `ui-expert`, the `ui-design` skill, the `frontend-design` skill, or caught by `code-reviewer` must now reconcile the registry (INDEX + per-component specs + tokens-reference) in the **same change**, never deferring drift to the weekly `ds-drift` routine. This release contains zero schema changes — the cascade reuses `features.has_design_system` + `paths.*` already in place.

package/README.md

@@ -156,6 +156,30 @@ last-push info. Use `--offline` to skip the upstream fetch.
 
 State updates happen automatically — no manual bookkeeping required.
 
+### CLI self-update notifier (new in v3.13.0)
+
+The CLI binary (`baldart`, installed globally via `npm i -g baldart`) and the
+framework payload (`.framework/` inside each repo, updated by `baldart update`)
+are two independent layers. Until now the CLI drifted silently — users on an
+old CLI never learned about new flags or new doctor checks.
+
+Now every `baldart` run does a best-effort check against `registry.npmjs.org`
+(cached at `~/.baldart/cli-update-check.json` with a 24h TTL, 1.5s network
+timeout, fire-and-forget). When a newer version is available, a one-shot
+banner appears at the top of the run:
+
+```
+↑ baldart 3.13.0 available (you have 3.12.0)
+  Update with: npm i -g baldart@latest
+  Suppress with: BALDART_NO_UPDATE_CHECK=1
+```
+
+The notifier never installs anything automatically — global installs can
+require sudo and affect every other project on your machine, so the choice
+stays with you. CLI drift also appears inline in `baldart doctor` (new `CLI`
+row) and in `baldart version`. Auto-suppressed in CI, in non-TTY runs, with
+`--offline`, with `NODE_ENV=test`, or via `BALDART_NO_UPDATE_CHECK=1`.
+
 ### Project Configuration (new in v3.0.0)
 
 BALDART skills are **portable across projects**. Instead of hard-coding paths

package/VERSION

@@ -1 +1 @@
-3.12.0
+3.14.0

package/bin/baldart.js

@@ -3,6 +3,20 @@
 const { Command } = require('commander');
 const chalk = require('chalk');
 const packageJson = require('../package.json');
+const updateNotifier = require('../src/utils/update-notifier');
+
+// CLI self-update notifier (v3.13.0+). Best-effort; non-blocking; suppressed
+// in CI / non-TTY / via BALDART_NO_UPDATE_CHECK=1 / when --offline is passed.
+// Prints a one-shot hint at the top of the run if a newer npm version was
+// detected on a previous invocation, then kicks off a background refresh.
+// First-ever run shows nothing — that is intentional; we never block the
+// command on a network call.
+const rawArgsForNotifier = process.argv.slice(2);
+const offlineForNotifier = rawArgsForNotifier.includes('--offline');
+updateNotifier.announceAndRefresh({
+  currentVersion: packageJson.version,
+  offline: offlineForNotifier,
+});
 
 const program = new Command();
 

package/framework/docs/LSP-LAYER.md

@@ -45,7 +45,7 @@ so existing behavior is preserved).
 
 ---
 
-## 2. The four moving parts
+## 2. The five moving parts
 
 ```
 ┌─────────────────────────────────────────────────────────────────────┐
@@ -53,17 +53,30 @@ so existing behavior is preserved).
 │    features.has_lsp_layer: true                                     │
 │    lsp.installed_servers: [typescript, python]                      │
 │    lsp.auto_verify: true                                            │
+│    tools.enabled: [claude]   ← gates native plugin install          │
 └──────────────┬──────────────────────────────────────────────────────┘
                │ read by
                ▼
 ┌─────────────────────────────────────────────────────────────────────┐
 │  Plumbing layer (CLI, this repo)                                    │
 │    src/utils/lsp-adapters/<lang>.js     ← per-language recipes      │
-│    src/utils/lsp-installer.js           ← high-level install+verify │
+│    src/utils/lsp-installer.js           ← server + plugin installer │
 │    src/commands/configure.js  (prompt + install on opt-in)          │
-│    src/commands/doctor.js     (verify + lsp-fix action)             │
+│    src/commands/doctor.js     (verify + lsp-fix + plugin-fix)       │
 └──────────────┬──────────────────────────────────────────────────────┘
-               │ writes installed_servers; surfaces broken servers
+               │ writes installed_servers; runs `claude plugin install`
+               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  Native Claude Code integration (since v3.14.0)                     │
+│    Marketplace: anthropics/claude-plugins-official  (user scope)    │
+│    Plugins:                                                         │
+│      typescript-lsp@claude-plugins-official                         │
+│      pyright-lsp@claude-plugins-official                            │
+│      gopls-lsp@claude-plugins-official                              │
+│      rust-analyzer-lsp@claude-plugins-official                      │
+│      ruby-lsp@claude-plugins-official                               │
+└──────────────┬──────────────────────────────────────────────────────┘
+               │ surfaces LSP to Claude Code at runtime
                ▼
 ┌─────────────────────────────────────────────────────────────────────┐
 │  Protocol layer (framework/)                                        │
@@ -85,9 +98,13 @@ so existing behavior is preserved).
 ```
 
 Each layer is independently testable and individually replaceable. The
-adapters never speak LSP themselves — they just describe *how to install*
-the language server. Actual symbol resolution at runtime happens through
-whatever Claude Code plugin / MCP server the consumer has loaded.
+adapters describe *how to install* the language server AND *which native
+plugin* surfaces it to Claude. Pre-v3.14.0 the second half was a manual
+step the user almost always skipped — opting into LSP put a binary on
+disk that Claude never invoked. v3.14.0 closes that gap: the configure
+flow installs both halves in one step, gated on `claude` being in
+`tools.enabled` (Codex-only consumers are unaffected — the gate degrades
+to a silent no-op).
 
 ---
 
@@ -123,6 +140,23 @@ When the user confirms, for each detected language:
   `baldart doctor` re-verifies on the next run and flags the mismatch if the
   user hasn't run the printed command yet.
 
+**Then (v3.14.0+) the native plugin install runs.** For every server in
+`installed_servers` whose adapter declares a `claudePluginId()`, configure:
+
+1. Verifies the `claude` CLI is on PATH (skipped silently if not — manual
+   install commands are printed instead).
+2. Idempotently registers the `claude-plugins-official` marketplace at user
+   scope (`claude plugin marketplace add anthropics/claude-plugins-official
+   --scope user` — no-op when already registered).
+3. Reads `claude plugin list --json` to skip plugins already installed at
+   any scope.
+4. Runs `claude plugin install <id> --scope user` for each missing plugin
+   (e.g. `typescript-lsp@claude-plugins-official`). User scope = a single
+   install is reused by every project on the machine.
+
+Gated on `claude` being in `tools.enabled` — Codex-only consumers see a
+silent skip, not a failure.
+
 ### 3.2 Update from pre-v3.10
 
 ```bash
@@ -238,7 +272,7 @@ Every adapter is a class exporting:
 | `npmPackage`         | string (npm-dev only) | What goes after `npm install --save-dev`                 |
 | `installCommand()`   | string              | The exact shell command (printed or executed)              |
 | `verifyCommand()`    | string              | A no-side-effect probe (e.g. `--version`)                  |
-| `claudePluginId()`   | string \| null      | Reserved: id of a Claude Code code-intelligence plugin     |
+| `claudePluginId()`   | string \| null      | Native Claude Code plugin id (e.g. `typescript-lsp@claude-plugins-official`) — installed by the configure flow alongside the language server (v3.14.0+). `null` = no companion plugin |
 | `static detect(cwd)` | boolean             | Pure: does the language live in this repo?                 |
 
 The contract is enforced by convention, not by an interface check. When you
@@ -249,14 +283,37 @@ to the REGISTRY in `lsp-adapters/index.js`.
 
 `LspInstaller` exposes:
 
+**Language-server layer (since v3.10.0):**
+
 - `detectLanguages()` → string[] — pure, no I/O beyond filesystem reads
 - `recommend(langs?)` → entries with install metadata for UI consumption
 - `installServers(names, { interactive=true, dryRun=false })` →
   `{ installed, skipped, manual }` — returns rather than throws
 - `verifyServers(names)` → `[{ name, ok, output|error }]` — never throws
 
+**Native Claude Code plugin layer (since v3.14.0):**
+
+- `isClaudeCliAvailable()` → boolean — `claude --version` probe with 5s timeout
+- `ensureClaudeMarketplace()` → `{ ok, alreadyPresent, error? }` — idempotently
+  registers `anthropics/claude-plugins-official` at user scope; reads the
+  existing marketplace list first so re-runs are no-ops
+- `listInstalledClaudePlugins()` → `Set<string>` of `<name>@<marketplace>` ids
+  pulled from `claude plugin list --json`; empty set on any failure (degrade
+  open — we'd rather attempt a redundant install than incorrectly skip)
+- `installClaudePlugins(names, { toolsEnabled=['claude'], scope='user', interactive=false })`
+  → `{ installed, skipped, manual, marketplace, reason? }` — gated on
+  `claude` being in `toolsEnabled` AND the CLI being available; per-plugin
+  idempotency check; defaults to `--scope user` so a single install is reused
+  across every project on the machine
+- `verifyClaudePlugins(names)` → `[{ name, pluginId, installed }]` —
+  consumed by `baldart doctor` to surface the half-installed state where the
+  language-server binary is on PATH but the matching plugin is missing
+
 All side-effecting methods are gated by `interactive` and a per-server
-confirm; doctor passes `interactive: true` so the user retains veto power.
+confirm; doctor passes `interactive: true` for the server layer and
+`interactive: false` for the plugin layer (the plugin install is idempotent
+and user-scope, so the outer doctor prompt + per-action `autoOk: true` is
+sufficient).
 
 ---
 

package/package.json

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

package/src/commands/add.js

@@ -79,6 +79,30 @@ async function add(repo, options) {
     // Step 4: Download framework
     UI.header('STEP 4/5: Download Framework');
 
+    // `.framework/` MUST be trackable — `git subtree add` itself fails if a
+    // pre-existing `.gitignore` rule matches the path. Heal proactively.
+    // (since v3.14.0)
+    try {
+      const heal = await git.ensureFrameworkNotIgnored();
+      if (heal.wasFixed) {
+        UI.warning(`.framework/ was ignored by ${heal.source || 'a gitignore'} — auto-healed before subtree add.`);
+        if (heal.removedLines > 0) {
+          UI.info(`  Removed ${heal.removedLines} stale .framework line(s) from .gitignore.`);
+        }
+        if (heal.appendedNegation) {
+          UI.info('  Appended `!.framework` negation block to .gitignore (idempotent).');
+        }
+        if (heal.stillIgnored) {
+          UI.error('.framework/ is STILL ignored after auto-heal — install would fail.');
+          UI.info(`Source: ${heal.recheck.source}:${heal.recheck.line} (${heal.recheck.pattern})`);
+          UI.info('Resolve by removing that rule, then re-run `baldart add`.');
+          process.exit(1);
+        }
+      }
+    } catch (err) {
+      UI.warning(`Could not check .gitignore for .framework: ${err.message}`);
+    }
+
     const downloadSpinner = UI.spinner(`Downloading from ${repo}...`).start();
 
     try {

package/src/commands/configure.js

@@ -607,6 +607,50 @@ async function interactivePrompts(merged, detected) {
           UI.warning(`Skipped: ${skipped.map(s => `${s.name} (${s.reason})`).join(', ')}`);
         }
       }
+
+      // ---- Native Claude Code companion plugins (since v3.14.0) ----------
+      // Install the official LSP plugin alongside each language server. Without
+      // this step, opting into the LSP layer only puts the binary on disk —
+      // Claude itself never sees it and agents fall back to Grep silently.
+      // Gated on `claude` being in `tools.enabled` and the `claude` CLI being
+      // on PATH; degrades gracefully otherwise.
+      const allLspServers = Array.from(new Set([
+        ...(merged.lsp.installed_servers || [])
+      ]));
+      if (allLspServers.length) {
+        const pluginResult = await installer.installClaudePlugins(allLspServers, {
+          toolsEnabled: merged.tools.enabled,
+          interactive: false,
+          scope: 'user'
+        });
+        if (pluginResult.reason === 'claude not in tools.enabled') {
+          UI.info('Skipping native Claude plugin install (claude not in tools.enabled).');
+        } else if (pluginResult.reason === 'claude CLI not on PATH') {
+          UI.warning('`claude` CLI not on PATH — native LSP plugins not installed.');
+          UI.info('Install them manually after adding the CLI:');
+          for (const m of pluginResult.skipped) {
+            // We don't have manual[] entries here (no targets resolved past the
+            // gate), so synthesize the command from the adapter directly.
+            try {
+              const a = lspAdapters.getAdapter(m.name, process.cwd());
+              const pid = a.claudePluginId();
+              if (pid) UI.code(`claude plugin install ${pid} --scope user`, m.name);
+            } catch { /* unknown adapter */ }
+          }
+        } else {
+          if (pluginResult.installed.length) {
+            UI.success(`Installed Claude LSP plugin(s): ${pluginResult.installed.map(i => i.pluginId).join(', ')}`);
+          }
+          const alreadyOnes = pluginResult.skipped.filter(s => s.reason === 'plugin already installed');
+          if (alreadyOnes.length) {
+            UI.info(`Already installed: ${alreadyOnes.map(s => s.name).join(', ')}`);
+          }
+          for (const m of pluginResult.manual) {
+            UI.warning(`Could not auto-install ${m.label} plugin — run manually:`);
+            UI.code(m.command, '');
+          }
+        }
+      }
     }
   } else {
     // Feature disabled — wipe the state so `installed_servers` doesn't lie.

package/src/commands/doctor.js

@@ -31,6 +31,8 @@ const UI = require('../utils/ui');
 const State = require('../utils/state');
 const Hooks = require('../utils/hooks');
 const LspInstaller = require('../utils/lsp-installer');
+const UpdateNotifier = require('../utils/update-notifier');
+const cliPackageJson = require('../../package.json');
 
 const FRAMEWORK_DIR = '.framework';
 const REPO_DEFAULT = 'antbald/BALDART';
@@ -146,6 +148,8 @@ async function detectState(cwd, opts = {}) {
   const git = new GitUtils(cwd);
   const state = {
     cwd,
+    cliVersion: cliPackageJson.version,
+    cliUpdate: UpdateNotifier.hint({ currentVersion: cliPackageJson.version }),
     isGitRepo: await git.isGitRepo(),
     frameworkPresent: await git.frameworkExists(),
     legacyLayout: false,
@@ -188,6 +192,19 @@ async function detectState(cwd, opts = {}) {
       ? `v${ledger.last_pushed_version} (${(ledger.last_push_date || '').slice(0, 10) || '—'})`
       : null;
 
+    // Ledger drift detection (v3.13.0+): the framework on disk says one thing,
+    // the ledger says another. Caused by interrupted updates, manual commits
+    // that excluded state.json, or filesystem write failures the old silent
+    // catch in update.js used to hide. Self-healable via `reconcile-state-ledger`.
+    state.stateLedgerDrift = null;
+    if (state.frameworkVersion && ledger.installed_version &&
+        state.frameworkVersion !== ledger.installed_version) {
+      state.stateLedgerDrift = {
+        payload: state.frameworkVersion,
+        ledger: ledger.installed_version
+      };
+    }
+
     state.remote = await describeRemote(git, ledger.framework_repo || REPO_DEFAULT, !!opts.offline);
     state.commitsAhead = await commitsAheadOfRemote(git);
     state.workingTreeDirty = await localFrameworkChanges(git);
@@ -198,10 +215,18 @@ async function detectState(cwd, opts = {}) {
     state.editGateRegistered = false;
     try { state.editGateRegistered = Hooks.isRegistered(cwd); } catch (_) {}
 
+    // `.framework/` is a git subtree — gitignore matching it breaks every
+    // future `git add` under that path (the failure mode that hit v3.13.0
+    // consumers during push). Detect any gitignore rule that catches the
+    // path so the planner can heal it before any flow needs to stage files.
+    state.frameworkIgnored = { ignored: false };
+    try { state.frameworkIgnored = await git.checkFrameworkIgnored(); } catch (_) {}
+
     // ---- LSP layer (since v3.10.0) -------------------------------------
     state.lspEnabled = false;
     state.lspInstalled = [];
     state.lspBroken = [];
+    state.lspMissingClaudePlugins = []; // [{ name, pluginId }] — since v3.14.0
     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) {
@@ -213,6 +238,20 @@ async function detectState(cwd, opts = {}) {
           const installer = new LspInstaller(cwd);
           const results = installer.verifyServers(installed);
           state.lspBroken = results.filter(r => !r.ok).map(r => r.name);
+
+          // Companion Claude plugin check (v3.14.0+). Gated on `claude` being
+          // in tools.enabled AND the `claude` CLI being available; otherwise
+          // we don't report missing plugins (manual install hint would be
+          // misleading without the CLI).
+          const toolsEnabled = (config.tools && Array.isArray(config.tools.enabled))
+            ? config.tools.enabled
+            : ['claude'];
+          if (toolsEnabled.includes('claude') && installer.isClaudeCliAvailable()) {
+            const checks = installer.verifyClaudePlugins(installed);
+            state.lspMissingClaudePlugins = checks
+              .filter(c => c.installed === false)
+              .map(c => ({ name: c.name, pluginId: c.pluginId }));
+          }
         }
       }
     } catch (_) { /* never block doctor on LSP probe */ }
@@ -313,6 +352,64 @@ function planActions(state) {
     // Drift is non-blocking — keep checking for other actions after.
   }
 
+  if (state.stateLedgerDrift) {
+    actions.push({
+      key: 'reconcile-state-ledger',
+      label: `Reconcile state ledger (${state.stateLedgerDrift.ledger} → ${state.stateLedgerDrift.payload})`,
+      why: `.framework/VERSION is v${state.stateLedgerDrift.payload} but .baldart/state.json records installed_version=${state.stateLedgerDrift.ledger}. Typical causes: an update flow that exited mid-way (configure declined, stash conflict), a manual commit that excluded .baldart/state.json, or a write failure that the old silent catch in update.js used to hide (fixed in v3.13.0).`,
+      autoOk: true, // pure local file write, idempotent, fully reversible
+      run: () => {
+        const res = State.reconcileInstalledVersion({
+          to: state.stateLedgerDrift.payload,
+          reason: 'doctor reconcile — payload/ledger drift'
+        });
+        if (res.changed) {
+          UI.success(`Ledger updated: installed_version ${res.from} → ${res.to}`);
+          UI.info('History entry "ledger-reconcile" recorded for audit. Commit .baldart/state.json when ready.');
+        } else {
+          UI.info('No change needed — ledger already matches payload.');
+        }
+      },
+    });
+    // Drift is non-blocking — keep checking for other actions after.
+  }
+
+  // Heal `.gitignore` BEFORE any other action that may stage files under
+  // `.framework/`. Without this, every downstream `git add` (push, auto-commit
+  // during update, lsp-install commits, …) would fail with "paths are ignored
+  // by one of your .gitignore files". (since v3.14.0)
+  if (state.frameworkIgnored && state.frameworkIgnored.ignored) {
+    actions.push({
+      key: 'unignore-framework',
+      label: 'Heal .gitignore so .framework/ is trackable',
+      why: `.framework/ is a git subtree managed by BALDART — it MUST be tracked. Currently ignored by ${state.frameworkIgnored.source}:${state.frameworkIgnored.line} (pattern: ${state.frameworkIgnored.pattern}). Any subsequent \`git add\` under that path would fail.`,
+      autoOk: true, // pure local file rewrite, idempotent, fully reversible
+      run: async () => {
+        const git = new GitUtils(state.cwd);
+        const heal = await git.ensureFrameworkNotIgnored();
+        if (!heal.wasFixed) {
+          UI.info('.gitignore already healthy — nothing to do.');
+          return;
+        }
+        UI.success('.gitignore healed:');
+        if (heal.removedLines > 0) {
+          UI.info(`  Removed ${heal.removedLines} stale .framework line(s).`);
+        }
+        if (heal.appendedNegation) {
+          UI.info('  Appended `!.framework` negation block (idempotent).');
+        }
+        if (heal.stillIgnored) {
+          UI.warning('  .framework/ is STILL ignored — likely a parent-dir .gitignore outside this repo.');
+          UI.info(`  Source: ${heal.recheck.source}:${heal.recheck.line} (${heal.recheck.pattern})`);
+          UI.info('  Resolve by removing that rule manually.');
+        } else {
+          UI.info('  Commit the .gitignore change when you next push.');
+        }
+      },
+    });
+    // Non-blocking — keep looking for other actions to run in the same pass.
+  }
+
   if (state.editGateRegistered === false) {
     actions.push({
       key: 'register-edit-gate',
@@ -347,6 +444,40 @@ function planActions(state) {
     });
   }
 
+  // Native Claude LSP plugins (v3.14.0+). The server binary alone is not
+  // enough — without the matching `<lang>-lsp@claude-plugins-official` plugin
+  // installed, Claude Code never invokes the LSP and agents silently fall back
+  // to Grep. This action backfills the plugins for installs predating v3.14.0
+  // and recovers from manual plugin uninstalls.
+  if (state.lspEnabled && state.lspMissingClaudePlugins && state.lspMissingClaudePlugins.length > 0) {
+    const missing = state.lspMissingClaudePlugins;
+    actions.push({
+      key: 'lsp-install-claude-plugins',
+      label: `Install ${missing.length} native Claude LSP plugin(s)`,
+      why: `LSP layer is enabled and the language server(s) are present, but the matching Claude Code plugin(s) are not installed: ${missing.map(m => m.pluginId).join(', ')}. Without them Claude never sees the LSP and the layer is effectively dead. Standard since v3.14.0; missing on installs predating that version.`,
+      autoOk: true, // user-scope plugin install, idempotent, fully reversible via `claude plugin uninstall`
+      run: async () => {
+        const installer = new LspInstaller(state.cwd);
+        const res = await installer.installClaudePlugins(missing.map(m => m.name), {
+          toolsEnabled: ['claude'], // we already checked tools.enabled in detectState
+          interactive: false,
+          scope: 'user',
+        });
+        if (res.installed.length) {
+          UI.success(`Installed: ${res.installed.map(i => i.pluginId).join(', ')}`);
+        }
+        for (const m of res.manual || []) {
+          UI.warning(`Could not auto-install ${m.label}:`);
+          console.log(`    ${m.command}`);
+        }
+        if (res.skipped.length) {
+          const real = res.skipped.filter(s => s.reason !== 'plugin already installed');
+          if (real.length) UI.warning(`Skipped: ${real.map(s => `${s.name} (${s.reason})`).join(', ')}`);
+        }
+      },
+    });
+  }
+
   const remoteAhead = state.remote.fetched && state.remote.behind > 0;
   const hasLocalWork = state.workingTreeDirty > 0 || state.commitsAhead > 0;
 
@@ -394,6 +525,17 @@ function renderDiagnostic(state) {
   console.log(`Repository:    ${state.cwd}`);
   console.log();
 
+  // CLI version line — always shown (independent of git repo state). When a
+  // newer baldart npm package was detected on a previous run, surface it here
+  // so the doctor table is the single pane of glass for "what's stale".
+  console.log(statusLine(
+    'CLI',
+    state.cliUpdate
+      ? `v${state.cliVersion} → v${state.cliUpdate.latest} available (npm i -g baldart@latest)`
+      : `v${state.cliVersion}`,
+    state.cliUpdate ? 'warn' : 'ok'
+  ));
+
   console.log(statusLine('Git repo', state.isGitRepo ? 'yes' : 'no', state.isGitRepo ? 'ok' : 'err'));
 
   if (!state.isGitRepo) return;
@@ -429,9 +571,11 @@ function renderDiagnostic(state) {
   console.log(statusLine(
     'State ledger',
     state.statePresent
-      ? `installed v${state.stateInstalled} (${fmtDate(state.stateInstallDate)})`
+      ? (state.stateLedgerDrift
+          ? `drift: ledger=v${state.stateLedgerDrift.ledger}, payload=v${state.stateLedgerDrift.payload}`
+          : `installed v${state.stateInstalled} (${fmtDate(state.stateInstallDate)})`)
       : 'not seeded',
-    state.statePresent ? 'ok' : 'warn'
+    state.stateLedgerDrift ? 'warn' : (state.statePresent ? 'ok' : 'warn')
   ));
 
   if (state.stateLastUpdate) {
@@ -478,15 +622,29 @@ function renderDiagnostic(state) {
     state.editGateRegistered ? 'ok' : 'warn'
   ));
 
+  if (state.frameworkIgnored && state.frameworkIgnored.ignored) {
+    console.log(statusLine(
+      '.gitignore',
+      `IGNORES .framework/ (${state.frameworkIgnored.source}:${state.frameworkIgnored.line}) — will be auto-healed`,
+      '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';
+    const missingPlugins = (state.lspMissingClaudePlugins || []).length;
+    let value;
+    if (total === 0) {
+      value = 'enabled but no servers installed';
+    } else if (broken > 0) {
+      value = `${broken}/${total} broken (${state.lspBroken.join(', ')})`;
+    } else if (missingPlugins > 0) {
+      value = `${total} server(s) verified, ${missingPlugins} Claude plugin(s) missing (${state.lspMissingClaudePlugins.map(m => m.pluginId).join(', ')})`;
+    } else {
+      value = `${total} server(s) verified (${state.lspInstalled.join(', ')})`;
+    }
+    const severity = total === 0 || broken > 0 || missingPlugins > 0 ? 'warn' : 'ok';
     console.log(statusLine('LSP layer', value, severity));
   } else {
     console.log(statusLine('LSP layer', 'disabled', 'ok'));