baldart 3.8.2 → 3.10.0

package/framework/agents/index.md

@@ -14,6 +14,7 @@ Route agents to the right module with minimal reading.
 
 - **MANDATORY pre-read for any skill/agent that touches project-specific paths, identity, stack, or feature toggles** -> read `agents/project-context.md`. Skills consult `baldart.config.yml` + `.baldart/overlays/<skill>.md` instead of hard-coded paths; missing keys MUST be asked, never assumed.
 - If needing to understand codebase structure, existing patterns, or architecture before planning -> MUST invoke `codebase-architect` agent (via Task tool) first; do not proceed without architectural understanding.
+- If searching for a function/type/symbol (identifier-shaped query, not free text) and `features.has_lsp_layer: true` -> read `agents/code-search-protocol.md` and prefer LSP `find-references` / `go-to-definition` over Grep. Falls back to Grep when LSP is unavailable or the query is textual.
 - If touching API endpoints or request/response shape -> read `agents/api-contracts.md` and `${paths.references_dir}/api/index.md` (then specific API module for your domain).
 - If touching database schema or fields -> read `agents/data-model.md` and `${paths.references_dir}/data-model.md`.
 - If touching UI pages/routes or flows -> read `${paths.references_dir}/ui/index.md` (then specific UI module for your domain).
@@ -57,6 +58,7 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/skills-mapping.md`
 - `agents/llm-wiki-methodology.md` — LLM wiki overlay methodology + auto-learning loop (since v2.0.0)
 - `agents/project-context.md` — Project context protocol: `baldart.config.yml` + overlays + missing-key handling (since v3.0.0)
+- `agents/code-search-protocol.md` — Retrieval hierarchy for code search: RAG → LSP → Grep → Git (since v3.10.0, gated on `features.has_lsp_layer`)
 
 ## Where to Document (Decision Tree)
 

package/framework/docs/LSP-LAYER.md

@@ -0,0 +1,405 @@
+<!-- contamination-scan: skip
+     This guide uses literal example paths (tsconfig.json, pyproject.toml,
+     `src/components/...`, etc.) as pedagogical examples of what
+     `baldart configure` autodetects. They are not project leak. -->
+# LSP Symbol-Search Layer
+
+A complete operator + agent reference for the LSP retrieval tier introduced in
+**v3.10.0**. Read this when:
+
+- you are upgrading a consumer repo from pre-v3.10 and want to know what
+  changed and how to roll the new feature out,
+- you are an AI agent asked to extend, debug, or modify the layer,
+- a contributor wants to add a new language adapter or change the fallback
+  rules.
+
+For the *runtime* protocol (RAG → LSP → Grep → Git, query-type
+discrimination, budget) read [`framework/agents/code-search-protocol.md`](../agents/code-search-protocol.md).
+This document covers the *plumbing*: how the layer is installed, configured,
+verified, and wired into agents/skills.
+
+---
+
+## 1. Why this exists
+
+Pre-v3.10, every BALDART code-exploration flow ran:
+
+> RAG hybrid → `git log` → **Grep** → read files.
+
+Grep collapses semantically distinct symbols that share a name. A search for
+`handleSubmit` in a medium repo dumps every form handler, every CLI utility,
+every test helper into the model's context — Claude then burns turns opening
+files to figure out which one is relevant. The signal is buried in the
+textual noise.
+
+LSP — Language Server Protocol — answers "give me every reference to *this*
+symbol" by walking the type graph the compiler/interpreter already has. A
+function named `handleSubmit` declared in `src/forms/Login.tsx` returns
+exactly the callsites that resolve to *that* declaration; the CLI utility's
+unrelated `handleSubmit` is filtered out before any file is read.
+
+The layer is **opt-in** (some consumers don't want devDep churn, some target
+languages we don't have an adapter for yet) and **degrades gracefully** (when
+LSP is unavailable, agents silently fall back to the legacy RAG → Grep flow,
+so existing behavior is preserved).
+
+---
+
+## 2. The four moving parts
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  baldart.config.yml                                                 │
+│    features.has_lsp_layer: true                                     │
+│    lsp.installed_servers: [typescript, python]                      │
+│    lsp.auto_verify: true                                            │
+└──────────────┬──────────────────────────────────────────────────────┘
+               │ 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/commands/configure.js  (prompt + install on opt-in)          │
+│    src/commands/doctor.js     (verify + lsp-fix action)             │
+└──────────────┬──────────────────────────────────────────────────────┘
+               │ writes installed_servers; surfaces broken servers
+               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  Protocol layer (framework/)                                        │
+│    framework/agents/code-search-protocol.md                         │
+│    framework/agents/index.md                       (routing line)   │
+└──────────────┬──────────────────────────────────────────────────────┘
+               │ referenced by
+               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  Consumers (framework/.claude/)                                     │
+│    agents/codebase-architect.md          (Investigation Protocol)   │
+│    agents/REGISTRY.md                    (capability declaration)   │
+│    skills/context-primer/SKILL.md        (retrieval step 3)         │
+│    skills/bug/SKILL.md                   (Phase 0 step 3)           │
+│    skills/simplify/SKILL.md              (deduplication step 3)     │
+│    skills/prd/SKILL.md, skills/new/SKILL.md  (transitive note)      │
+│    skills/lsp-bootstrap/SKILL.md         (/lsp-bootstrap)           │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+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.
+
+---
+
+## 3. End-to-end lifecycle
+
+### 3.1 First install in a brand-new repo
+
+```bash
+npx baldart add                # subtree pull + symlink reconcile
+                               # → triggers configure interactively
+```
+
+`configure` autodetects supported languages by probing for marker files:
+
+| Language   | Marker(s)                                                | Adapter                          |
+|------------|----------------------------------------------------------|----------------------------------|
+| TypeScript | `tsconfig.json`, `jsconfig.json`, `package.json` w/ typescript | `lsp-adapters/typescript.js` |
+| Python     | `pyproject.toml`, `setup.py`, `setup.cfg`, `requirements.txt`, `Pipfile`, top-level `*.py` | `lsp-adapters/python.js` |
+| Go         | `go.mod`                                                 | `lsp-adapters/go.js`             |
+| Rust       | `Cargo.toml`                                             | `lsp-adapters/rust.js`           |
+| Ruby       | `Gemfile`, `.ruby-version`, `config.ru`                  | `lsp-adapters/ruby.js`           |
+
+If any adapter fires, `features.has_lsp_layer` defaults to `true` in the
+configure prompt (the user can still say no). The prompt copy is
+*"Enable LSP symbol-search layer? (recommended for large codebases)"*.
+
+When the user confirms, for each detected language:
+
+- **npm-dev mode** (TS, Python via pyright): `npm install --save-dev <pkg>`
+  runs in-process. Success → added to `lsp.installed_servers`.
+- **system mode** (Go, Rust, Ruby): the install command is *printed*, never
+  executed. The server name is recorded as pending in `installed_servers`;
+  `baldart doctor` re-verifies on the next run and flags the mismatch if the
+  user hasn't run the printed command yet.
+
+### 3.2 Update from pre-v3.10
+
+```bash
+npx baldart update             # subtree pull
+                               # → schema-drift detector runs
+```
+
+`update.js:407–435` diffs `template.features` vs `cur.features`. It finds
+`has_lsp_layer` missing and prints:
+
+> ⚠ New config keys in this version: has_lsp_layer.
+> Run `baldart configure` now to populate them? (y/N)
+
+The user re-enters the configure flow above. **No silent default** — the
+always-ask contract from `framework/agents/project-context.md` § 3 owns this.
+
+### 3.3 Routine doctor run
+
+```bash
+npx baldart                    # smart doctor (no-arg, default since v3.2.0)
+```
+
+`doctor.js` reads `config.lsp.installed_servers`. When
+`lsp.auto_verify !== false`, it executes each adapter's `verifyCommand()`
+(e.g. `npx --no-install typescript-language-server --version`). Output:
+
+```
+·  LSP layer        2 server(s) verified (typescript, python)
+```
+
+If any server fails verify, the planner emits an `lsp-fix` action with
+`autoOk: false` (so it asks before touching anything) and reinstalls only
+the broken ones — with per-server confirmation, preserving any deliberate
+uninstall the user may have done.
+
+### 3.4 Standalone bootstrap
+
+```
+/lsp-bootstrap                 # inside Claude Code, when the layer is enabled
+```
+
+The same install + verify flow exposed as a skill, useful when the user has
+toggled `has_lsp_layer: true` manually in `baldart.config.yml` and now wants
+to populate the layer without re-running the full configure prompt. The
+skill refuses to run when the flag is `false` — opt-in is owned by configure.
+
+### 3.5 Runtime behavior in a Claude Code session
+
+When `codebase-architect` or one of the code-exploration skills (`bug`,
+`prd`, `new`, `simplify`, `context-primer`) is invoked:
+
+1. Read `baldart.config.yml`. If `features.has_lsp_layer !== true`, behave
+   exactly as v3.9.x (RAG → Grep → Git).
+2. Otherwise: classify the query.
+   - Identifier-shaped (function name, type name, class, exported symbol) →
+     **LSP first** (`ToolSearch("LSP")` → `find-references` / `definition`).
+   - Free text / phrase / comment / path / regex → **Grep first**, LSP is
+     useless here.
+   - Mixed (e.g. "refactor function X used in 5 places") → RAG hybrid for
+     conceptual context, then LSP for the structural part.
+3. Budget: max **3 LSP calls per task**. After 3 calls without convergence,
+   escalate to direct file reads — don't ping-pong references.
+4. If LSP tool isn't loaded / plugin missing / timeout > 8s / zero
+   references for a symbol you know exists → **silent fallback to Grep**.
+   The user does not see an error mid-task; `baldart doctor` is the
+   self-heal channel.
+
+The protocol document
+[`framework/agents/code-search-protocol.md`](../agents/code-search-protocol.md)
+is the authoritative runtime spec — this doc points at it rather than
+duplicating its content.
+
+---
+
+## 4. Field reference
+
+### 4.1 `baldart.config.yml`
+
+```yaml
+features:
+  has_lsp_layer: true            # gate
+
+lsp:
+  installed_servers:             # list of adapter names
+    - typescript
+    - python
+  auto_verify: true              # doctor re-runs verifyCommand on each call
+```
+
+Constraints:
+
+- `has_lsp_layer` MUST be present and explicitly `true | false` once
+  configure has run (always-ask contract).
+- `installed_servers` is **only meaningful when the flag is `true`**.
+  Configure resets it to `[]` if the flag flips to `false` (so the file
+  doesn't lie about pending installs).
+- `auto_verify: false` is intended for noisy CI — agents still respect the
+  layer at runtime; only the doctor's verify probe is suppressed.
+- Adapter names map 1:1 to filenames under `src/utils/lsp-adapters/`. An
+  unknown name in `installed_servers` produces a soft warning, never a hard
+  failure.
+
+### 4.2 Adapter contract (`src/utils/lsp-adapters/<lang>.js`)
+
+Every adapter is a class exporting:
+
+| Member               | Type                | Purpose                                                    |
+|----------------------|---------------------|------------------------------------------------------------|
+| `name`               | string getter       | Stable id used in `installed_servers` (e.g. `"typescript"`)|
+| `label`              | string getter       | Human-readable for prompts/diagnostics                     |
+| `binary`             | string getter       | Executable name expected on PATH or in node_modules        |
+| `installMode`        | `"npm-dev"` / `"system"` | How the installer treats this language               |
+| `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     |
+| `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
+add a new adapter, mirror the shape of `typescript.js` exactly, then add it
+to the REGISTRY in `lsp-adapters/index.js`.
+
+### 4.3 Installer contract (`src/utils/lsp-installer.js`)
+
+`LspInstaller` exposes:
+
+- `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
+
+All side-effecting methods are gated by `interactive` and a per-server
+confirm; doctor passes `interactive: true` so the user retains veto power.
+
+---
+
+## 5. Adding a new language
+
+Worked example: adding **Java** support.
+
+1. Pick the language server. For Java the de-facto choice is `jdtls`
+   (Eclipse JDT Language Server), installed via system means.
+2. Create `src/utils/lsp-adapters/java.js`:
+   ```js
+   const fs = require('fs');
+   const path = require('path');
+
+   class JavaAdapter {
+     constructor(cwd = process.cwd()) { this.cwd = cwd; }
+     get name() { return 'java'; }
+     get label() { return 'Java (jdtls)'; }
+     get binary() { return 'jdtls'; }
+     get installMode() { return 'system'; }
+     installCommand() { return 'brew install jdtls'; }
+     verifyCommand() { return 'jdtls --version'; }
+     claudePluginId() { return null; }
+     static detect(cwd = process.cwd()) {
+       return ['pom.xml', 'build.gradle', 'build.gradle.kts']
+         .some(m => fs.existsSync(path.join(cwd, m)));
+     }
+   }
+
+   module.exports = JavaAdapter;
+   ```
+3. Register in `src/utils/lsp-adapters/index.js`:
+   ```js
+   const JavaAdapter = require('./java');
+   // ...
+   const REGISTRY = {
+     // ...
+     java: JavaAdapter,
+   };
+   ```
+4. Smoke test:
+   ```bash
+   node -e 'const r = require("./src/utils/lsp-adapters"); console.log(r.listAdapters())'
+   ```
+   Should now include `java`.
+5. No change required in `configure.js`, `doctor.js`, the protocol module,
+   or any agent/skill — they all iterate over the REGISTRY.
+6. Update `CHANGELOG.md`, bump VERSION (PATCH if pure addition), document the
+   adapter in this file's § 3.1 marker table.
+7. Optional: add a per-language quirk paragraph to
+   `framework/templates/overlays/agents/codebase-architect.lsp-example.md`
+   if Java has gotchas worth flagging to consumers (e.g. classpath setup,
+   multi-module Maven projects).
+
+---
+
+## 6. Troubleshooting
+
+### 6.1 "Agents are still using Grep even though LSP is enabled"
+
+Likely causes, in order of likelihood:
+
+1. The query is free text, not a symbol. Re-read § 3.5 — Grep is correct
+   here, not a regression.
+2. The Claude Code LSP plugin isn't loaded in this session. Check inside
+   Claude Code with `/plugin list`. Reload if necessary.
+3. The language server binary isn't on PATH. Run `baldart doctor` — the
+   LSP line will say `n/m broken (typescript, ...)` and propose `lsp-fix`.
+4. `features.has_lsp_layer` is `false` or missing in `baldart.config.yml`.
+   Run `baldart configure`.
+
+### 6.2 "configure prompted me but didn't install anything"
+
+The autodetector found no supported language markers. Either:
+
+- You're in a polyglot repo where the supported language lives in a
+  subdirectory configure didn't probe. Add the marker file at the repo root
+  (e.g. a stub `tsconfig.json`) or extend the adapter's `detect()`.
+- You're using a language we don't ship an adapter for. See § 5.
+
+### 6.3 "doctor says my server is broken but it works in my editor"
+
+`verifyCommand()` executes from the consumer cwd with a hard 8s timeout. If
+the language server takes longer than that to print `--version` (rare, but
+seen on first-run cold caches), the verify fails. Re-run `baldart doctor`
+once warm. If still failing, run the exact `verifyCommand()` string in your
+shell — the actual error will surface.
+
+### 6.4 "I want to enable the layer but not have devDeps in package.json"
+
+For TypeScript / Python you can override the adapter's `installMode` by
+writing an overlay at `.baldart/overlays/agents/codebase-architect.md`
+documenting your alternative install path (e.g. system pyright via uv), and
+then manually setting `lsp.installed_servers: [python]` in the config. The
+runtime layer doesn't care *how* the binary got there, only that it's
+reachable. `baldart doctor` will continue to verify it.
+
+---
+
+## 7. Mental model for agents extending this layer
+
+When you (an AI agent) are asked to modify the LSP layer, internalize these
+invariants — they are the rules the existing code obeys, and breaking them
+silently corrupts consumer installs:
+
+1. **Opt-in is owned by configure.** No code path may flip
+   `features.has_lsp_layer` from `false` to `true` (or vice versa) without
+   going through `configure.js` or an explicit user-typed YAML edit. The
+   `lsp-bootstrap` skill and the doctor `lsp-fix` action both *refuse* to
+   change the gate; they only act when it's already on.
+2. **`installed_servers` is descriptive, not normative.** It records what
+   BALDART knows about; it does not enforce. Removing a name from the list
+   doesn't uninstall the binary, and adding a name doesn't install one. The
+   single source of truth for "is it usable" is the verify probe.
+3. **Fallback to Grep is silent.** Never abort an agent's task because LSP
+   failed. The user finds out about broken LSP through `baldart doctor`,
+   not by getting an error mid-bug-investigation.
+4. **The adapter REGISTRY is the only place to enumerate languages.**
+   `configure.js`, `doctor.js`, the bootstrap skill, and the docs all
+   iterate the registry. Hard-coding a language anywhere else is a bug.
+5. **Schema-change propagation rule** (from memory
+   `feedback_schema_change_propagation.md`): any new key under `lsp.*` or
+   `features.has_lsp_*` must land in the template, the configure prompt,
+   the update detector, the doctor diagnostic, the relevant skill(s), AND
+   the CHANGELOG. If you only add the template, you have introduced silent
+   drift between layers — the v3.9.0 pattern is the worked example to copy.
+6. **No MCP server lives in this repo.** BALDART does not ship its own LSP
+   bridge. The runtime tools come from Claude Code's plugin ecosystem (or
+   a third-party MCP the user installs); BALDART's job is to make sure the
+   binaries are present and to instruct agents how to use them.
+
+If a feature request seems to break one of these invariants, push back and
+propose an alternative that preserves them — they were chosen deliberately
+in the design review (see the approved plan in
+`/Users/antoniobaldassarre/.claude/plans/` from 2026-05-23).
+
+---
+
+## 8. See also
+
+- [`framework/agents/code-search-protocol.md`](../agents/code-search-protocol.md) — runtime protocol
+- [`framework/agents/project-context.md`](../agents/project-context.md) — always-ask contract
+- [`framework/docs/PROJECT-CONFIGURATION.md`](PROJECT-CONFIGURATION.md) § 4.5 + § 4.6 — config schema
+- [`framework/.claude/skills/lsp-bootstrap/SKILL.md`](../.claude/skills/lsp-bootstrap/SKILL.md) — invokable skill
+- [`framework/templates/overlays/agents/codebase-architect.lsp-example.md`](../templates/overlays/agents/codebase-architect.lsp-example.md) — starter overlay
+- [`CHANGELOG.md`](../../CHANGELOG.md) — v3.10.0 entry

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -148,6 +148,23 @@ Every flag MUST be present as `true` or `false` once `baldart configure` has run
 | `has_adrs` | ADR workflow. Architectural decisions get logged in `paths.adrs_dir`. |
 | `has_prd_workflow` | PRD workflow (`paths.prd_dir`). `/prd` and `/prd-add` skills refuse to run without it. |
 | `has_wiki_overlay` | LLM-wiki overlay (`paths.wiki_dir`). `/capture` skill refuses to run without it. |
+| `has_lsp_layer` | LSP symbol-search layer (since v3.10.0). When `true`, `codebase-architect`, `context-primer`, `bug`, `prd`, `new`, and `simplify` prefer LSP `find-references` / `go-to-definition` over Grep for identifier queries. Wired by `framework/agents/code-search-protocol.md`. The flag also triggers `baldart configure` (and the `/lsp-bootstrap` skill) to install the matching language servers. |
+
+### 4.6 `lsp` — installed language servers (since v3.10.0)
+
+Populated by `baldart configure` and the `/lsp-bootstrap` skill when `features.has_lsp_layer: true`. Leave empty otherwise.
+
+| Key | Meaning |
+|---|---|
+| `lsp.installed_servers` | List of language IDs (`typescript`, `python`, `go`, `rust`, `ruby`, …) whose server BALDART has recorded for this project. Identifiers map 1:1 to adapter files under `src/utils/lsp-adapters/`. |
+| `lsp.auto_verify` | When `true` (default), `baldart doctor` re-verifies the binaries are reachable on every run. Disable on CI if the verify step is too noisy. |
+
+**Install modes per adapter:**
+
+- `typescript`, `python` — installed as npm devDeps (`npm install --save-dev typescript-language-server typescript` / `pyright`). Project-local, version-pinned.
+- `go`, `rust`, `ruby` — installed via system tools (`go install …`, `rustup component add …`, `gem install …`). BALDART prints the command; the user runs it.
+
+**Fallback contract.** When the LSP layer is enabled but a server is missing or broken, agents silently fall back to Grep — code search never fails because of LSP issues. `baldart doctor` surfaces the mismatch and offers reinstall.
 
 ## 5. The overlay system
 

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

@@ -112,6 +112,48 @@ 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`.
+git:
+  # How `/mw` lands the feature branch onto develop:
+  #
+  #   pr          (default) — push feature branch, open a PR via `gh pr create`,
+  #                 merge via `gh pr merge`. Required if `develop` is protected
+  #                 on origin (status checks, required reviews, merge queue).
+  #
+  #   local-push  — after rebasing the feature branch onto `origin/develop`,
+  #                 fast-forward push the feature branch directly to
+  #                 `origin/develop` (`git push origin <feat>:develop`).
+  #                 No PR, no `gh` dependency. FAILS hard if `develop` is
+  #                 protected on origin — switch back to `pr` in that case.
+  #
+  # Neither strategy ever touches the main repo's HEAD — both flows are
+  # worktree-isolated and respect the terminal-isolation rule.
+  merge_strategy: pr
+
 # ─── TOOLS ───────────────────────────────────────────────────────────────
 # Which AI CLI tools should the framework target on this machine?
 # Each enabled tool gets its own per-item skill symlinks pointing at the

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.8.2",
+  "version": "3.10.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"