baldart 3.8.2 → 3.10.0

package/CHANGELOG.md

@@ -5,6 +5,67 @@ 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.10.0] - 2026-05-23
+
+BALDART grows an **LSP symbol-search layer**. When enabled, `codebase-architect` and the code-exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) prefer LSP `find-references` / `go-to-definition` over Grep for identifier-shaped queries. The filtering happens **before** Claude reads files — a function-name search that previously returned thousands of textual matches now resolves to the actual callsites of the same symbol. Grep remains the fallback for free-text queries and when the LSP layer is unavailable, so existing flows degrade gracefully.
+
+The layer is opt-in: at install / update / configure, BALDART asks "Enable LSP symbol-search layer?" and (on yes) detects the project's languages and installs the matching language servers — npm devDeps for TypeScript and Python, system commands printed for Go, Rust, Ruby.
+
+### Added
+
+- **`baldart.config.yml` → `features.has_lsp_layer`** — new boolean (default `false`). Gates the LSP retrieval tier in agents and skills. When `true`, also populates the new `lsp` section with the installed language servers.
+- **`baldart.config.yml` → `lsp.installed_servers` + `lsp.auto_verify`** — new top-level section tracking which language servers are recorded for the project and whether `baldart doctor` should re-verify them on every run.
+- **`framework/agents/code-search-protocol.md`** — new protocol module defining the retrieval hierarchy (RAG hybrid → LSP for symbols → Grep → Git), query-type discrimination, LSP budget (max 3 calls/task), and fallback rules. Referenced from `framework/agents/index.md`.
+- **`framework/.claude/skills/lsp-bootstrap/SKILL.md`** — new invokable skill (`/lsp-bootstrap`) that runs the install + verify flow as a standalone workflow. Refuses to run when `features.has_lsp_layer: false`. Idempotent.
+- **`src/utils/lsp-adapters/`** — new pluggable adapter registry (TypeScript, Python via Pyright, Go via gopls, Rust via rust-analyzer, Ruby via ruby-lsp). Each adapter exposes `detect(cwd)`, `installCommand()`, `verifyCommand()`, and `claudePluginId()`. Same pattern as `src/utils/tool-adapters/`. Add a new language by dropping in a `<lang>.js` file and registering it in `index.js`.
+- **`src/utils/lsp-installer.js`** — high-level installer used by `configure.js` and the `doctor` LSP step. `detectLanguages()` / `recommend()` / `installServers()` / `verifyServers()`. Pure detection has no side effects; install ops respect `--non-interactive`.
+- **`src/commands/configure.js` LSP block** — when the user opts in, autodetects languages, prompts per server, installs npm-mode adapters in-process, prints system-mode install commands, verifies binaries, and persists `lsp.installed_servers`. Re-running configure on an existing project re-detects and updates the list.
+- **`src/commands/doctor.js` LSP step** — new "LSP layer" line in the diagnostic table + a `lsp-fix` action that reinstalls broken servers. Surfaces missing binaries without breaking other doctor flows.
+- **`framework/templates/overlays/agents/codebase-architect.lsp-example.md`** — starter overlay demonstrating how to add project-specific LSP tuning (monorepo quirks, generated-code exclusions, callsite thresholds) on top of the shipped protocol.
+
+### Changed
+
+- **`framework/.claude/agents/codebase-architect.md`** — Investigation Protocol step 3 now points at `agents/code-search-protocol.md` for LSP escalation. Behavior under `features.has_lsp_layer: false` is unchanged.
+- **`framework/.claude/agents/REGISTRY.md`** — `codebase-architect` row gains "LSP symbol resolution (when `features.has_lsp_layer: true`)" as a specialization.
+- **`framework/.claude/skills/context-primer/SKILL.md`** — step 3 of the retrieval loop redirects to the code-search protocol for symbol-shaped queries when the flag is on.
+- **`framework/.claude/skills/bug/SKILL.md`** — Phase 0 step 3 references the protocol; `codebase-architect` now automatically uses LSP for symbol lookups during code-path mapping.
+- **`framework/.claude/skills/simplify/SKILL.md`** — deduplication step 3 uses LSP `find-references` to confirm callsites before recommending consolidation; eliminates false positives from textual name collisions and dead-code candidates.
+- **`framework/.claude/skills/prd/SKILL.md` / `new/SKILL.md`** — one-line note that LSP usage is transitive via `context-primer` / `codebase-architect` when the flag is on.
+- **`framework/templates/baldart.config.template.yml`** — adds `features.has_lsp_layer` and the new `lsp:` block with inline documentation.
+- **`framework/docs/PROJECT-CONFIGURATION.md`** — new § 4.5 row for `has_lsp_layer` and a new § 4.6 documenting the `lsp.*` keys, per-adapter install modes, and the fallback contract.
+
+### Notes
+
+- **Schema-change propagation** (matches the `v3.9.0` pattern): the new key is wired into the template, the configure prompt, the update-detector, the doctor table, the relevant skills, and the changelog.
+- **Backwards-compatible.** Pre-v3.10 consumers running `npx baldart update` see the standard "new config keys" warning (`has_lsp_layer`) and are offered `configure`. Agents and skills behave exactly as before when the flag is absent or `false`.
+- **Fallback contract.** When the layer is enabled but a server is missing, broken, or returns no references for a known symbol, agents silently fall back to Grep. Code search never fails because of LSP issues; `baldart doctor` surfaces the mismatch.
+- **Languages out of scope** (Java, C/C++, PHP, Elixir, …) can be added by dropping a new file under `src/utils/lsp-adapters/`. No core change required.
+
+## [3.9.0] - 2026-05-22
+
+`worktree-manager` (`/mw`) gains a configurable merge strategy. The previous flow forced every consumer through `gh pr create` + `gh pr merge`; in repos where `develop` is not protected on GitHub, that roundtrip is unnecessary and was observed to stall (PR opened, never merged). The new `git.merge_strategy` key lets each project pick its lane.
+
+### Added
+
+- **`baldart.config.yml` → `git.merge_strategy`** — new top-level config section with one key (default `pr`):
+  - `pr` (default, backwards-compatible) — push feature branch, open PR via `gh pr create`, merge via `gh pr merge`. Required if `develop` is protected on origin.
+  - `local-push` — after the rebase in `/mw` step 4b, fast-forward push the feature branch directly to `origin/develop` (`git push origin <feat>:develop`). No PR, no `gh` dependency. Fails hard with a clear hint if `develop` is protected on origin.
+- **`framework/.claude/skills/worktree-manager/SKILL.md` step 4c** — fully rewritten into two clearly labelled strategies (A: `pr`, B: `local-push`) plus a shared local-develop-sync block. Both strategies remain strictly worktree-isolated — neither runs `git checkout` / `git switch` / `git branch` on the main repo.
+- **Programmatic API output** — `/mw` now returns `strategy: "pr"|"local-push"`. `prNumber` is `null` in `local-push` mode.
+
+### Changed
+
+- **`framework/.claude/skills/new/SKILL.md`** — Phase 6 description and fail-safe rules reference the configured strategy instead of hard-coding `gh pr merge`.
+- **`worktree-manager` Project Context header** — added at the top of the skill, citing `git.merge_strategy` + `paths.backlog_dir` per the always-ask-never-assume contract in `framework/agents/project-context.md`.
+- **`src/commands/configure.js`** — gained autodetection + interactive prompt for `git.merge_strategy`. The probe runs `gh api repos/:o/:r/branches/develop/protection` to recommend `pr` (when develop is protected) or `local-push` (when not). Falls back to `pr` safely when `gh` is missing or the remote is unreachable. The detection reason is surfaced inline so the user knows *why* a strategy is recommended.
+- **`src/commands/update.js`** — schema-drift detection now also covers new top-level sections (currently `git.*`). When new keys are detected, `update` proactively offers to run `configure` instead of just warning. This means an existing consumer running `npx baldart update` will be **asked** about the new `git.merge_strategy` key, not silently defaulted.
+
+### Notes
+
+- No migration is required for existing consumers. `git.merge_strategy` defaults to `pr` when the key is absent, preserving the v3.4.0+ behaviour exactly.
+- On `npx baldart update`, existing consumers are **prompted** to run `configure`, where the merge-strategy autodetection probes their repo and recommends `pr` or `local-push` with a one-line reason. The user picks; nothing is auto-applied.
+- `develop` remains the only supported integration branch; configurable `base_branch` is out of scope for this release.
+
 ## [3.8.2] - 2026-05-22
 
 `baldart` (smart doctor) no longer double-confirms safe actions. Previously, running `baldart` with a remote-ahead state would ask *"Run: Pull N commit(s)?"* and then the `update` command would ask *"Proceed with update?"* immediately after — two prompts for the same intent.

package/README.md

@@ -183,18 +183,22 @@ Skills always-ask when required keys are missing — never silently default.
 never overwrites your file. Full guide:
 [`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md).
 
-### Skills (new in v2.0.0 — 22 portable skills)
+### Skills (23 portable skills)
 
 Skills live under `.claude/skills/` and are auto-discovered by Claude Code.
 Bundled skills:
 
 - **Workflow**: `new`, `prd`, `prd-add`, `bug`, `simplify`, `worktree-manager`, `issue-review`, `context-primer`
-- **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`
+- **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`, `lsp-bootstrap` (v3.10.0)
 - **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`
 - **Product**: `seo-audit`, `copywriting`, `api-design-principles`
 - **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay)
 - **Integration**: `kie-ai`, `remotion-best-practices`
 
+### LSP Symbol Search Layer (new in v3.10.0)
+
+When `features.has_lsp_layer: true`, `codebase-architect` and the code-exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) prefer LSP `find-references` / `go-to-definition` over Grep for identifier-shaped queries — the filtering happens **before** Claude reads files, so a common function name no longer dumps thousands of textual matches into context. Opt-in at `baldart configure`; BALDART installs the matching language servers (npm devDeps for TypeScript/Python, system commands printed for Go/Rust/Ruby). Grep remains the fallback for free-text queries and degraded states. See [`framework/agents/code-search-protocol.md`](framework/agents/code-search-protocol.md).
+
 ### Commands
 
 - **/new**: Batch orchestrator with QA validation, production readiness checklist, and context recovery (also available as a skill)

package/VERSION

@@ -1 +1 @@
-3.8.2
+3.10.0

package/framework/.claude/agents/REGISTRY.md

@@ -8,7 +8,7 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 
 | Agent | Category | When to Use | Specialization | Can Edit Code | Key Tools |
 |-------|----------|-------------|----------------|---------------|-----------|
-| **codebase-architect** | Architecture | **MANDATORY** before planning/implementing changes | Platform analysis, system design, canonical-source resolution via Linking Protocol v1 | No | Code navigation, pattern tracing |
+| **codebase-architect** | Architecture | **MANDATORY** before planning/implementing changes | Platform analysis, system design, canonical-source resolution via Linking Protocol v1, LSP symbol resolution (when `features.has_lsp_layer: true`) | No | Code navigation, pattern tracing, LSP find-references / go-to-definition |
 | **plan-auditor** | Architecture | Review implementation plans before coding begins | Risk assessment, gap detection | Yes | Multi-persona review (eng/security/SRE) |
 | **doc-reviewer** | Architecture | Audit/write docs after feature implementation | Macro feature identification, SSOT sync, linking-protocol resolution, doc debt tracking, gap analysis | Yes | Doc writing, TaskCreate (doc debt), token optimization |
 | **wiki-curator** | Documentation | Maintain the derived LLM wiki overlay under `docs/wiki/` (concept pages, syntheses, dashboards, reading guides) without creating new canonicals. See `agents/llm-wiki-methodology.md`. | Synthesis pages, provenance hygiene, freshness, derived-link checks, auto-learning loop | Yes | `docs/wiki/`, wiki lint, reindex follow-up |

package/framework/.claude/agents/codebase-architect.md

@@ -163,6 +163,14 @@ Before providing any architectural guidance or implementation advice, follow thi
 3. **Targeted grep** (only if RAG was weak/empty): grep for 2-3 specific identifiers
    (function names, file patterns), NOT broad keyword sweeps across the entire codebase.
 
+   **LSP escalation (since v3.10.0):** when `features.has_lsp_layer: true` in
+   `baldart.config.yml` AND the query is a symbol/identifier (function, type, class,
+   variable name), prefer LSP `find-references` / `go-to-definition` over Grep — it
+   filters textual collisions before you read anything. Cap at 3 LSP calls per task,
+   then escalate to direct file reads. Falls back to Grep silently when the LSP tool
+   isn't loaded or returns nothing. See `framework/agents/code-search-protocol.md`
+   for the full hierarchy and query-type discrimination.
+
 4. **Targeted verification** — DO NOT read entire files. Instead:
    - For files **<200 lines**: read in full.
    - For files **200-500 lines**: read the first 50 lines (imports + exports) + the

package/framework/.claude/skills/bug/SKILL.md

@@ -38,7 +38,11 @@ Argument: optional bug description (e.g., `/bug feature X is not saving`).
    - **Data/Firestore** → MCP Firestore tools + transaction tracing
    - **Auth** → authMiddleware.ts + auth error codes
    - **Build/Deploy** → Vercel logs + build output
-3. Launch `codebase-architect` agent to map the affected code paths — do NOT start debugging blind
+3. Launch `codebase-architect` agent to map the affected code paths — do NOT start debugging blind.
+   When `features.has_lsp_layer: true` and the symptom names a concrete symbol
+   (function/type/handler), `codebase-architect` will use LSP find-references /
+   go-to-definition to locate the exact callsites instead of grepping. See
+   `framework/agents/code-search-protocol.md`.
 4. Search doc-rag for related patterns: `mcp__doc-rag__search_docs` with bug keywords
    - always use `mode="hybrid"` (vector + knowledge graph) for richer context retrieval
    - if results come from Obsidian, treat them as context only and verify runtime behavior against repo docs/code before fixing

package/framework/.claude/skills/context-primer/SKILL.md

@@ -78,6 +78,10 @@ SEARCH STRATEGY — RAG-first, verify-only-if-needed:
 
 3. ONLY IF RAG was empty — broader search:
    a. Grep the project's source root for 2-3 specific identifiers from steps 1-2.
+      When `features.has_lsp_layer: true` AND the identifier is a symbol (function /
+      type / class name, not a free-text phrase), prefer LSP `find-references` /
+      `go-to-definition` over Grep — it filters textual collisions before any file
+      read. Cap at 3 LSP calls, then fall back. See `framework/agents/code-search-protocol.md`.
    b. Read key file headers (first 50 lines) to identify structure.
    DO NOT read `${paths.prd_dir}/` or `${paths.references_dir}/` files in full —
    RAG already indexes them. Only read a specific doc section if RAG

package/framework/.claude/skills/lsp-bootstrap/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: lsp-bootstrap
+description: >
+  Install, verify, and document the LSP symbol-search layer for this project.
+  Detects languages (TypeScript, Python, Go, Rust, Ruby), installs the matching
+  language servers (npm devDep where possible, system command otherwise),
+  verifies binaries are reachable, and writes lsp.installed_servers to
+  baldart.config.yml. Use when the user says /lsp-bootstrap, "install LSP",
+  "set up symbol search", or after enabling features.has_lsp_layer for the
+  first time. Idempotent — re-running on an already-configured project
+  re-verifies and reports drift.
+---
+
+# LSP Bootstrap
+
+Set up the LSP (Language Server Protocol) layer that lets agents and skills
+search by symbol instead of by string. Without this layer, code search burns
+context on textual collisions; with it, references resolve to the same symbol
+**before** Claude reads any file.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `features.has_lsp_layer`, `lsp.installed_servers`, `lsp.auto_verify`.
+**Gated by features:** `features.has_lsp_layer` — this skill refuses to run when the flag is `false`, prompting the user to flip it via `npx baldart configure` first.
+**Overlay:** loads `.baldart/overlays/lsp-bootstrap.md` if present — project-specific install commands (e.g. a system-managed pyright via uv, a non-standard gopls path).
+**On missing keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+## What This Skill Does
+
+1. Reads `baldart.config.yml` and confirms `features.has_lsp_layer: true`.
+2. Probes the cwd via `src/utils/lsp-adapters/` to detect which languages are
+   present (markers: `tsconfig.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`,
+   `Gemfile`, plus heuristic fallbacks).
+3. For each detected language:
+   - **npm-dev** adapters (TypeScript, Python via pyright): runs `npm install
+     --save-dev <pkg>` with user confirmation.
+   - **system** adapters (Go gopls, Rust rust-analyzer, Ruby ruby-lsp): prints
+     the install command for the user to run in a separate terminal. Does NOT
+     execute system-level installs automatically.
+4. Verifies each binary is reachable (`<binary> --version`).
+5. Updates `lsp.installed_servers` in `baldart.config.yml` with the verified
+   set. System-mode servers are recorded even if not yet reachable (the user
+   may have a pending install) — `baldart doctor` will flag the mismatch.
+6. Prints a summary table and points the user to
+   `framework/agents/code-search-protocol.md` for runtime behavior.
+
+## Workflow
+
+1. **Refusal check.** If `features.has_lsp_layer: false` (or missing):
+   ```
+   This project hasn't opted in to the LSP layer yet.
+   Run `npx baldart configure` and answer YES to "Enable LSP symbol-search layer?"
+   then re-run /lsp-bootstrap.
+   ```
+   Stop here. Do not proceed.
+
+2. **Probe.** Call the BALDART installer (internally `src/utils/lsp-installer.js`):
+   ```
+   node -e 'const L=require("./.framework/src/utils/lsp-installer"); console.log(JSON.stringify(new L().recommend(),null,2))'
+   ```
+   Show the detected languages with their `installMode`.
+
+3. **Confirm per server.** For each recommended server, ask the user. Skip the
+   ones already in `lsp.installed_servers` unless they fail verify.
+
+4. **Install.** Run the appropriate `installCommand()`. Capture failures into a
+   "Skipped" bucket — never abort the whole skill on one failure.
+
+5. **Verify.** For each installed server, call its `verifyCommand()`. Mark the
+   results.
+
+6. **Persist.** Update `baldart.config.yml`:
+   ```yaml
+   lsp:
+     installed_servers: [typescript, python]
+     auto_verify: true
+   ```
+
+7. **Output.** A compact one-line status, in the project's `identity.language`
+   from `baldart.config.yml` (English default). Matches the brevity of
+   `/cont` rather than its specific Italian phrasing.
+
+## Output Contract
+
+A single short status block — never a multi-page report. Format:
+
+```
+LSP bootstrap:
+  ✓ typescript-language-server (npm devDep, verified)
+  ✓ pyright (npm devDep, verified)
+  ⚠ gopls — run `go install golang.org/x/tools/gopls@latest`, then `baldart doctor`
+  · ruby — not detected (no Gemfile)
+Config updated: baldart.config.yml lsp.installed_servers = [typescript, python, go]
+Next: codebase-architect will now prefer LSP find-references over Grep for symbols.
+```
+
+## Notes
+
+- This skill never edits source code or installs binaries that aren't language
+  servers — its only side effect is `npm install --save-dev <lsp-package>` and a
+  YAML write to `baldart.config.yml`.
+- For Claude Code users: in addition to the binaries, you may need to load a
+  code-intelligence plugin (`/plugin` in Claude Code). That step is documented
+  in the printed output when applicable, but the skill does NOT manage Claude
+  Code plugins directly.
+- Re-run safely. The skill diffs the current `lsp.installed_servers` against
+  recommended + verified, so additions / removals / repairs are all idempotent.
+
+## See Also
+
+- `framework/agents/code-search-protocol.md` — runtime fallback rules
+- `src/utils/lsp-adapters/` — per-language install/verify recipes
+- `src/commands/configure.js` — same install flow when first enabling the flag

package/framework/.claude/skills/new/SKILL.md

@@ -236,7 +236,7 @@ For each card, execute these phases in order:
    - If NOT `DONE` → HALT: log in `## Issues & Flags` and ask the user: "Card <CARD-ID> depends on <DEP-ID> which is `<status>`. Proceed anyway, or wait?" Do not start implementation until the user responds explicitly.
    - If `DONE` → continue.
 3. Update `${paths.references_dir}/project-status.md` Active Code Context (skip when the file does not exist in the project).
-4. Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation.
+4. Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation. When `features.has_lsp_layer: true`, the architect uses LSP find-references for any identifier-shaped lookups inside the card (transitive via `agents/code-search-protocol.md`).
 4b. **Plan-auditor grounding check** — invoke the **plan-auditor** agent in QUICK mode with this prompt:
    ```
    Quick grounding check only (not a full audit). Verify this backlog card's requirements are grounded in the actual codebase.
@@ -1176,7 +1176,7 @@ After the final review passes AND all cards are committed in the worktree, deleg
    - The worktree path and branch from the tracker
    - `checksAlreadyPassed: true` (final review + QA already validated the build)
    - All card IDs for the commit message
-3. The skill handles: safety commit of any remaining uncommitted files (step 3), rebasing onto latest develop (step 4b — auto-resolves doc conflicts, stops on code conflicts), remote merge to develop via `gh pr merge` (step 4c — NEVER `git checkout develop` on the main repo; this respects the absolute terminal-isolation rule that many consumer projects declare in CLAUDE.md), post-merge verification, worktree removal, registry cleanup, and remote branch deletion.
+3. The skill handles: safety commit of any remaining uncommitted files (step 3), rebasing onto latest develop (step 4b — auto-resolves doc conflicts, stops on code conflicts), merging into develop via the configured `git.merge_strategy` (step 4c — `pr` uses `gh pr merge`, `local-push` does a direct FF push to `origin/develop`; NEITHER runs `git checkout develop` on the main repo, respecting the absolute terminal-isolation rule), post-merge verification, worktree removal, registry cleanup, and remote branch deletion.
 4. **If code merge conflicts** → the skill STOPs and reports. Doc-only conflicts (ssot-registry.md, project-status.md, etc.) are auto-resolved by keeping both sides.
 5. **If post-merge build fails** → the skill STOPs and keeps the worktree intact for investigation.
 6. Record the merge commit hash and result in the tracker.
@@ -1245,8 +1245,8 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
 **Why this exists**: Agents frequently skip the DONE marking in Phase 4 (step 27) due to context compaction, commit failures that interrupt the flow, or team mode where Step D.6 gets lost. This gate is the safety net that catches ALL of these cases.
 
 ### Fail-safe rules (enforced by worktree-manager skill)
-- **Never `git checkout`, `git switch`, `git checkout -b`, or `git branch` on the main repo** from inside this orchestrator. The main repo is shared across parallel terminals. Use `gh pr merge` for develop merges and `git -C <main> pull --ff-only` (only when `HEAD = develop` already) for sync. See `/mw` step 4c.
-- Never merge to `main` — only to `develop`, and only via `gh pr merge` (NOT local checkout).
+- **Never `git checkout`, `git switch`, `git checkout -b`, or `git branch` on the main repo** from inside this orchestrator. The main repo is shared across parallel terminals. Use the configured `git.merge_strategy` for develop merges and `git -C <main> pull --ff-only` (only when `HEAD = develop` already) for sync. See `/mw` step 4c.
+- Never merge to `main` — only to `develop`, via the configured `git.merge_strategy` (NOT local checkout).
 - Never force push to `main` or `develop`. `--force-with-lease` on feature branches after rebase is allowed.
 - Never delete a branch before successful merge verification.
 - Never remove a worktree before confirming develop is stable post-merge.

package/framework/.claude/skills/prd/SKILL.md

@@ -148,7 +148,9 @@ Before entering the discovery loop, load codebase context using the **context-pr
 2. Invoke the `Skill` tool with `skill: "context-primer"` passing the keywords
    (e.g., `args: "prize scanning scratch card wheel"`).
 3. The context-primer launches `codebase-architect` which searches RAG, docs,
-   backlog, source code, and git history — returning a compact summary.
+   backlog, source code, and git history — returning a compact summary. When
+   `features.has_lsp_layer: true`, the symbol-lookup tier is automatically used
+   for identifier-shaped queries (transitive via `agents/code-search-protocol.md`).
 4. Additionally, use `search_docs` MCP tool (if available) with `mode: "hybrid"` for the feature domain
    to surface related PRDs, ADRs, and specs not covered by context-primer. The
    active retrieval layer is Obsidian-first LightRAG; use Obsidian hits for

package/framework/.claude/skills/simplify/SKILL.md

@@ -39,6 +39,12 @@ For each new piece of code in the diff:
 1. **Start with `${paths.references_dir}/component-registry.md`** — the authoritative inventory of all UI primitives, shared components, hooks, and utility modules. Scan the relevant tables before grepping. Then search for existing utilities and helpers that could replace newly written code in the project's utility roots (e.g. `${paths.components_root}/shared/`, `${paths.components_primitives}/`, and `src/lib/`, `src/hooks/` if they exist), and files adjacent to the changed ones.
 2. **For each new component**, Grep the codebase for components with similar names, similar prop signatures, or similar JSX structure. Check for copy-pasted layout components (`layout.tsx` files with near-identical structure).
 3. **For each new function/hook**, search for functions with similar signatures or logic patterns elsewhere. Check for duplicated page-level patterns (similar data fetching, similar error boundaries, similar loading states).
+   When `features.has_lsp_layer: true`, run LSP `find-references` on each new exported
+   symbol before grepping — it tells you exactly which callsites would need to migrate
+   if you replaced the new code with an existing utility (textual grep over identifier
+   names overcounts because of collisions). See `framework/agents/code-search-protocol.md`.
+   Also use LSP `find-references` on candidate "existing" utilities to confirm they're
+   really in use and not abandoned dead code before recommending them as the canonical version.
 4. **Flag components that wrap the same underlying element** with minor style/prop differences.
 
 Classify each finding as:

package/framework/.claude/skills/worktree-manager/SKILL.md

@@ -14,6 +14,11 @@ description: >
 
 # Worktree Manager
 
+**Project Context (resolved from `baldart.config.yml`)**:
+- `git.merge_strategy` — `pr` (default, GitHub PR via `gh`) or `local-push` (direct fast-forward to `origin/develop`). Drives `/mw` step 4c.
+- `paths.backlog_dir` — used for syncing untracked backlog cards (`/nw` step 3b).
+- Protocol reference: `framework/agents/project-context.md`. Skills must ASK when a needed key is missing — never assume.
+
 **IMMEDIATE EXECUTION**: When invoked via `/nw`, `/mw`, `/lw`, or `/cw`, do NOT explain the process. Start executing the matching command flow immediately:
 
 - `/nw` → Ask for **slug** (required) and optionally a **card ID**, then execute all steps (pre-flight → create → install → build → report). If the user provided args, skip questions and use them directly. Supports three forms:
@@ -38,9 +43,13 @@ Output: `{ path: string, branch: string, port: number }`
 ### /mw programmatic
 
 Input: `{ worktreePath: string, checksAlreadyPassed?: boolean }`
-Output: `{ merged: boolean, developVerified: boolean, prNumber: number, mergeCommit: string }`
+Output: `{ merged: boolean, developVerified: boolean, prNumber: number|null, mergeCommit: string, strategy: "pr"|"local-push" }`
+
+The merge path depends on `git.merge_strategy` in `baldart.config.yml`:
+- `pr` (default, since v3.4.0): merge via `gh pr create` + `gh pr merge`. `prNumber` is the PR number, `mergeCommit` is the SHA returned by the GitHub merge API.
+- `local-push` (since v3.9.0): direct fast-forward push of the rebased feature branch to `origin/develop` — no PR, no `gh`. `prNumber` is `null`, `mergeCommit` is the local SHA of the feature branch tip.
 
-Note: since v3.4.0 the merge happens via `gh pr merge` against GitHub (NOT a local `git checkout develop` + `git merge`). `mergeCommit` is the SHA returned by the GitHub merge API. The orchestrator can use `prNumber` for follow-up (linking, deploy webhooks, etc.).
+Neither path runs `git checkout` / `git switch` / `git branch` on the main repo. The orchestrator can branch on `strategy` if it needs PR linking (only meaningful in `pr` mode).
 
 ### /cw programmatic
 
@@ -435,16 +444,32 @@ npm run build
 
 If build fails after rebase → STOP and report. The rebase introduced incompatibilities.
 
-### 4c. Remote merge via GitHub PR (NO main-repo checkout)
+### 4c. Land the feature branch onto develop (strategy-branched)
 
-**IMPORTANT — Remote merge only, NO local checkout/switch/branch on the main repo.** Consumer projects often share the main repo as a parallel resource across multiple terminals; running `git checkout develop` on it preempts whatever the other terminals are doing and breaks worktree-driven workflows. We therefore do the merge via the GitHub API (`gh pr create` + `gh pr merge`) — the main repo's `HEAD` is never touched.
+**IMPORTANT — NO local checkout/switch/branch on the main repo, regardless of strategy.** Consumer projects share the main repo as a parallel resource across multiple terminals; running `git checkout develop` on it preempts whatever the other terminals are doing and breaks worktree-driven workflows. Both strategies below operate from the worktree and the main repo's `HEAD` is never touched.
 
-The previous local-merge flow caused: (a) classifier-blocked `git checkout develop` in projects with terminal-isolation rules in CLAUDE.md, (b) silent failure of the orchestrator's merge phase.
+Read `git.merge_strategy` from `baldart.config.yml` (default: `pr`):
 
 ```bash
 MAIN=$(git -C "$WORKTREE_PATH" rev-parse --git-common-dir)/..
 MAIN=$(cd "$MAIN" && pwd)
 
+# Resolve strategy from baldart.config.yml (default: pr)
+STRATEGY=$(grep -A1 '^git:' "$MAIN/baldart.config.yml" 2>/dev/null \
+  | grep 'merge_strategy:' | head -1 \
+  | sed -E 's/.*merge_strategy:[[:space:]]*([a-z-]+).*/\1/' || echo "pr")
+STRATEGY=${STRATEGY:-pr}
+```
+
+If neither `pr` nor `local-push` resolves, ASK the user once which to use and suggest persisting the choice (per the always-ask, never-assume contract in `framework/agents/project-context.md`).
+
+---
+
+#### Strategy A — `pr` (default, GitHub PR via `gh`)
+
+Use this when `develop` is protected on origin (required status checks, reviews, merge queue) — a direct push would be rejected.
+
+```bash
 # 1. Push the feature branch to origin (force-with-lease in case of rebase in 4b).
 git -C "$WORKTREE_PATH" push --force-with-lease origin "$BRANCH"
 
@@ -464,10 +489,6 @@ fi
 echo "PR #$PR_NUMBER ready to merge."
 
 # 3. Merge via gh CLI. --delete-branch removes the remote branch on success.
-#    The CLI may print a non-fatal warning if the LOCAL branch can't be deleted
-#    (e.g. "fatal: 'develop' is already used by worktree at ..." when develop is
-#    checked out in another worktree). The REMOTE merge happens regardless — we
-#    swallow the local-cleanup warning.
 MERGE_OUTPUT=$(gh pr merge "$PR_NUMBER" --merge --delete-branch 2>&1) || MERGE_RC=$?
 echo "$MERGE_OUTPUT"
 
@@ -488,11 +509,63 @@ if [ "$PR_STATE" != "MERGED" ]; then
   exit 1
 fi
 echo "✅ PR #$PR_NUMBER merged to develop."
+```
+
+If `gh` is not installed in the project, STOP and ask the user to install GitHub CLI (`brew install gh` or equivalent) and run `gh auth login`. Do NOT fall back to a local checkout — it violates terminal isolation.
+
+If both gh CLI and REST API merge fail → STOP and report. Suggest switching to `merge_strategy: local-push` only if `develop` is NOT protected on origin.
+
+---
+
+#### Strategy B — `local-push` (direct FF push, no PR)
+
+Use this when `develop` is NOT protected on origin and the user wants to skip the GitHub PR roundtrip. After step 4b the feature branch is rebased onto `origin/develop`, so it can fast-forward `develop` on origin in a single push.
+
+```bash
+# 1. Sanity: confirm the feature branch is strictly ahead of origin/develop
+#    (i.e. the rebase in step 4b succeeded and we can FF develop on origin).
+git -C "$WORKTREE_PATH" fetch origin develop --quiet
+AHEAD=$(git -C "$WORKTREE_PATH" rev-list --count "origin/develop..$BRANCH")
+BEHIND=$(git -C "$WORKTREE_PATH" rev-list --count "$BRANCH..origin/develop")
+if [ "$BEHIND" -ne 0 ]; then
+  echo "❌ local-push aborted: $BRANCH is $BEHIND commit(s) behind origin/develop." >&2
+  echo "   Re-run step 4b (rebase onto origin/develop), then retry." >&2
+  exit 1
+fi
+if [ "$AHEAD" -eq 0 ]; then
+  echo "ℹ️ Nothing to push — $BRANCH is identical to origin/develop. Skipping."
+else
+  echo "Fast-forwarding origin/develop by $AHEAD commit(s) via local-push…"
+fi
+
+# 2. Direct fast-forward push to develop on origin. No PR.
+#    If develop is protected on origin, this fails — surface the hint and stop.
+if ! PUSH_OUTPUT=$(git -C "$WORKTREE_PATH" push origin "$BRANCH:develop" 2>&1); then
+  echo "$PUSH_OUTPUT"
+  if echo "$PUSH_OUTPUT" | grep -qiE "protected branch|required status|review required"; then
+    echo "❌ local-push rejected: 'develop' is protected on origin." >&2
+    echo "   Switch baldart.config.yml → git.merge_strategy: pr, or remove the protection." >&2
+  fi
+  exit 1
+fi
+echo "✅ $BRANCH merged into develop on origin (fast-forward, no PR)."
 
-# 4. Sync local develop ONLY if the main repo's HEAD is already develop.
-#    NEVER `git checkout develop` here — that's the regression we're fixing.
-#    If the user (or another terminal) had develop checked out, ff-only updates
-#    it cleanly. Otherwise we leave their HEAD alone and they'll pull next time.
+# 3. Delete the remote feature branch (best-effort — never fatal).
+git -C "$WORKTREE_PATH" push origin --delete "$BRANCH" 2>/dev/null || true
+
+MERGE_SHA=$(git -C "$WORKTREE_PATH" rev-parse HEAD)
+PR_NUMBER=""
+```
+
+---
+
+#### Common — sync local develop ref (both strategies)
+
+```bash
+# Sync local develop ONLY if the main repo's HEAD is already develop.
+# NEVER `git checkout develop` here. If the user (or another terminal) had
+# develop checked out, ff-only updates it cleanly. Otherwise we leave their
+# HEAD alone and they'll pull next time.
 CURRENT_BRANCH=$(git -C "$MAIN" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
 if [ "$CURRENT_BRANCH" = "develop" ]; then
   git -C "$MAIN" pull --ff-only origin develop || \
@@ -503,10 +576,6 @@ else
 fi
 ```
 
-If `gh` is not installed in the project, STOP and ask the user to install GitHub CLI (`brew install gh` or equivalent) and run `gh auth login`. Do NOT fall back to the legacy local-checkout flow — it violates terminal isolation in worktree-driven projects.
-
-If both gh CLI and REST API merge fail → STOP and report. Do NOT attempt a local checkout as fallback.
-
 ### 5. Post-merge verification
 
 ```bash
@@ -554,7 +623,9 @@ Remove the entry from `.worktrees/registry.json`.
 Merge complete:
   Card:     <CARD-ID>
   Branch:   <BRANCH> (deleted on remote; local-cleanup may have skipped if checked out elsewhere)
-  PR:       #<PR_NUMBER> merged via `gh pr merge`
+  Strategy: <pr | local-push>
+  PR:       #<PR_NUMBER> merged via `gh pr merge`    ← only in `pr` strategy
+  Push:     fast-forward to origin/develop           ← only in `local-push` strategy
   Worktree: <WORKTREE_PATH> (removed)
   develop:  remote up to date; local main-repo synced only if HEAD was already develop
 ```
@@ -665,8 +736,8 @@ Cleanup complete:
 
 ## Safety Rules
 
-- **NEVER `git checkout`, `git switch`, `git checkout -b`, or `git branch` on the main repo from inside `/mw` / `/nw` / `/cw`.** The main repo is a shared resource across parallel terminals; touching its `HEAD` preempts other agents and breaks worktree-driven workflows. Many consumer projects (e.g. mayo) declare this as an absolute rule in CLAUDE.md and Claude Code's classifier will pattern-match and block these commands preemptively. Use `gh pr create` + `gh pr merge` for develop merges and `git -C <main> pull --ff-only` (only when `HEAD = develop` already) for sync. See `/mw` step 4c.
-- NEVER merge to `main` — only to `develop`, and only via `gh pr merge` (NOT local checkout).
+- **NEVER `git checkout`, `git switch`, `git checkout -b`, or `git branch` on the main repo from inside `/mw` / `/nw` / `/cw`.** The main repo is a shared resource across parallel terminals; touching its `HEAD` preempts other agents and breaks worktree-driven workflows. Many consumer projects declare this as an absolute rule in CLAUDE.md and Claude Code's classifier will pattern-match and block these commands preemptively. Use the configured `git.merge_strategy` for develop merges and `git -C <main> pull --ff-only` (only when `HEAD = develop` already) for sync. See `/mw` step 4c.
+- NEVER merge to `main` — only to `develop`, via the configured `git.merge_strategy` (`pr` → `gh pr merge`; `local-push` → `git push origin <feat>:develop`). NEVER via local checkout.
 - NEVER force push from a worktree (`--force-with-lease` on the feature branch after rebase is the only allowed force variant).
 - NEVER `git add .` or `git add -A` — always explicit file names.
 - NEVER remove a worktree with uncommitted changes without explicit user confirmation.

package/framework/agents/code-search-protocol.md

@@ -0,0 +1,126 @@
+# Code Search Protocol
+
+## Purpose
+
+Define a deterministic retrieval hierarchy for agents and skills that need to
+find code (identifiers, references, definitions, similar patterns) inside the
+consumer repo. The goal is to filter noise **before** Claude reads files, not
+after — Grep on a common function name returns thousands of textual matches and
+burns context; LSP returns only the references that point to the same symbol.
+
+## Scope
+
+**In**: How agents/skills should choose between RAG, LSP, Grep, and Git when
+searching for code. Fallback rules when a tier is unavailable.
+**Out**: Documentation search (see `agents/llm-wiki-methodology.md`), test
+discovery (see `agents/testing.md`).
+
+## Gating
+
+This protocol is **conditional** on `features.has_lsp_layer: true` in
+`baldart.config.yml`. When the flag is `false` or missing, agents fall back to
+the legacy RAG → Grep → Git flow and skip the LSP tier entirely.
+
+Adapters for installed servers live under `src/utils/lsp-adapters/`; the
+current set of servers BALDART has wired in this project is recorded at
+`lsp.installed_servers` in `baldart.config.yml`.
+
+## Retrieval Hierarchy (in order)
+
+1. **RAG hybrid** — `search_docs(query, mode: "hybrid")` via the doc-rag MCP if
+   available. Best for free-text and conceptual queries ("how does session
+   token storage work").
+2. **LSP symbol search** — when the query is an identifier (function, type,
+   class, variable name) and `features.has_lsp_layer: true`. Use the LSP tool
+   (`ToolSearch("LSP")` in Claude Code) for:
+   - **find references**: every callsite of a symbol across the project.
+   - **go to definition**: the single authoritative declaration.
+   - **type info / hover**: signature, parameters, return type.
+   - **document/workspace symbols**: enumerate top-level symbols.
+3. **Grep** — for textual patterns that aren't symbols (a comment, a magic
+   string, a regex match, a config key, a TODO marker). Also the fallback when
+   LSP is unavailable or returns nothing for a symbol that clearly exists.
+4. **Git log** — `git log --oneline -20 --grep="keyword"` to find when and why
+   code changed. Last resort, but cheap when you suspect a regression.
+
+## Query-type discrimination
+
+Before picking a tier, classify the query:
+
+| Query shape                            | Start with |
+|----------------------------------------|------------|
+| `handleSubmit`, `UserSchema`, `useAuth`| LSP        |
+| `"TODO: encrypt tokens"`               | Grep       |
+| `/api/v1/users` route handler          | Grep then LSP on the handler name |
+| "how is auth wired"                    | RAG hybrid |
+| "when did we change session storage"   | Git log    |
+| Mixed (refactor a function used in 5 places) | RAG → LSP find-references |
+
+## Budget
+
+- **LSP**: up to **3 calls per task** for symbol resolution. If after 3 calls
+  the picture is still unclear, escalate to RAG or read the file directly —
+  don't keep ping-ponging through references.
+- **Grep**: existing project budget (typically 15–25 calls per agent).
+- **RAG / Git**: no hard budget, but verify the verdict (`rag_telemetry.verdict`
+  for RAG) before relying on it.
+
+## Fallback rules
+
+- LSP tool not loaded / plugin missing → silently fall back to Grep with the
+  symbol name. Do **not** prompt the user mid-task — the missing tool is a
+  setup concern surfaced by `baldart doctor`.
+- LSP returns zero references for a symbol you know exists → fall back to
+  Grep; the symbol may live in a file the LSP server hasn't indexed yet (e.g.
+  a path excluded by `tsconfig.json`).
+- LSP times out (>8s) → fall back to Grep for this query, log the symptom in
+  the agent's reasoning so the user can re-run doctor.
+
+## Examples
+
+### Refactor: rename a function used across the repo
+
+1. RAG hybrid: confirm the function is the right one and not a name collision.
+2. LSP find-references on the symbol → exact callsite list (file + line +
+   column).
+3. Read each callsite, propose the rename, apply edits.
+
+Why this beats Grep: a project with both `handleSubmit` in a form component
+and `handleSubmit` in a CLI utility gets two semantically distinct sets from
+LSP, but a single conflated list from Grep.
+
+### Bug: trace where a value originates
+
+1. RAG hybrid on the symptom (free text).
+2. LSP go-to-definition on the suspect variable → authoritative source.
+3. LSP find-references back from the definition → call graph upstream.
+4. Grep only if LSP cannot resolve (e.g. the value passes through a
+   dynamically-typed boundary).
+
+### Cleanup: remove a deprecated helper
+
+1. LSP find-references on the helper. Zero hits → safe to delete.
+2. Non-zero hits → migrate callsites first, then delete.
+
+Skip Grep here: textual matches inside string literals or comments are not
+true callsites and would falsely block the deletion.
+
+## When to skip LSP entirely
+
+- Query is a phrase or comment, not a symbol.
+- The project's `lsp.installed_servers` is empty for the relevant language.
+- You are reading a single small file (under 200 lines) — direct Read is
+  cheaper than a tool call.
+
+## Maintenance
+
+When adding a new language to `src/utils/lsp-adapters/`, no change is required
+here unless the new language has special tooling caveats (e.g. multi-root
+workspaces, monorepos). In that case, append a subsection below.
+
+## See also
+
+- `framework/.claude/skills/lsp-bootstrap/SKILL.md` — install + verify flow.
+- `framework/agents/project-context.md` — always-ask / never-assume contract.
+- `framework/.claude/agents/codebase-architect.md` — primary consumer of this
+  protocol.