feat: add plans

openspec/changes/assess-clice-production-readiness/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-03

openspec/changes/assess-clice-production-readiness/design.md

@@ -0,0 +1,145 @@
+## Context
+
+`clice` already has the rough shape of a language server: a master process, stateful/stateless workers, compile scheduling, module/PCH support, an emerging index, and a set of AST-backed editor features. The current gap is not "missing framework", but a mismatch between the current implementation shape and the invariants required for real editor use.
+
+The highest-risk issues are all cross-cutting:
+
+- opened editor buffers are not yet the consistently authoritative source across compile, AST queries, and index-backed navigation
+- stateful feature reads can race with rebuilds and stale generations
+- header files and multi-context files do not yet have a sound compilation-context selection model
+- several features are either missing, stubbed, or substantially shallower than `clangd`
+- worker ownership, eviction, diagnostics, logging, and background work scheduling are not yet production-grade
+
+This design therefore treats production readiness as four coordinated workstreams with explicit boundaries: document model, compilation context, AST-only feature baseline, and runtime hardening.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- make opened-buffer semantics explicit and enforceable across compile and query paths
+- define how `clice` selects and persists compilation contexts for sources and headers
+- set a concrete AST-only feature baseline that can be implemented independently from global index work
+- define runtime invariants for worker lifecycle, resource control, logging, and stale-result handling
+- produce a task breakdown that allows server/core work and feature work to proceed in parallel with minimal overlap
+
+**Non-Goals:**
+
+- full global-index parity with `clangd`
+- final implementation details for every indexed feature such as workspace-wide rename or workspace symbols
+- performance tuning beyond the invariants needed to avoid obviously wrong scheduling and stale results
+- introducing compatibility layers or temporary abstractions whose only purpose is to avoid refactoring existing wrong-shape code
+
+## Decisions
+
+### 1. Treat the opened document as the primary source of truth
+
+Open documents with unsaved changes must override disk content for compile and AST-backed queries. This applies to on-demand compiles, stateful feature reads, and the local side of navigation requests.
+
+Why this over disk-first fallback:
+
+- it matches editor expectations
+- it removes offset mismatches between the text used to compute positions and the AST used to answer them
+- it gives a single invariant that can be tested across hover, completion, semantic tokens, and local navigation
+
+Alternative considered:
+
+- continue using disk-backed index and best-effort stale tolerance
+  Rejected because it produces silently wrong answers in the most common editing flow.
+
+### 2. Gate AST-backed feature reads on a versioned build generation
+
+Every opened document needs a version/generation model that ties together text, build scheduling, worker state, AST readiness, diagnostics publication, and feature requests. AST-backed reads must either use a generation known to match the current document or fail/retry cleanly; they must not run on a stale or fatal unit by default.
+
+Why this over the current dirty-flag shape:
+
+- `dirty` alone records staleness but does not protect the read path
+- version/generation checks let master and worker reject stale compile completions and stale feature answers deterministically
+
+Alternative considered:
+
+- optimistic reads while a rebuild is in flight
+  Rejected because it preserves responsiveness at the cost of correctness and makes debugging behavior impossible.
+
+### 3. Separate compilation-context resolution from feature implementation
+
+Header context, compilation context, and multi-command source handling must be solved in the compile layer, not feature-by-feature. Feature handlers should receive a coherent AST/index view and not carry their own header fallback logic.
+
+Why this over ad hoc per-feature fallback:
+
+- it prevents each feature from inventing a different answer for the same file
+- it keeps AST-only feature work independently assignable
+- it matches the way `clangd` centralizes command transfer and TU scheduling
+
+Alternative considered:
+
+- keeping generic fallback compile commands for headers until later
+  Rejected because it creates misleading "working" behavior with the wrong language mode and include environment.
+
+### 4. Keep AST-only feature work independent from index work
+
+The feature baseline for this change covers capabilities that can work from the current AST or local parse context. Missing index-backed features may be tracked, but they are not on the critical path for this change.
+
+Why this split:
+
+- it allows server/core work to proceed without blocking feature contributors
+- it matches the current repository structure, where most AST features already live under `src/feature`
+- it gives a realistic route to internal dogfooding before full index maturity
+
+Alternative considered:
+
+- waiting for index parity before improving features
+  Rejected because it serializes unrelated work and delays useful editor quality improvements.
+
+### 5. Remove or finish wrong-shape/stub behavior instead of hiding it
+
+Capabilities that are currently advertised but stubbed, or data structures that exist without a correct runtime selection model, should either be finished or explicitly de-scoped. Production readiness must reduce misleading behavior, not preserve it.
+
+Why this over compatibility shims:
+
+- stubs make clients believe a feature exists when it does not
+- partial lifecycle plumbing causes leaks and stale ownership even if the server appears responsive
+- cleaning up wrong-shape code reduces the long-term cost of later index and context work
+
+Alternative considered:
+
+- preserve current surface and patch around it incrementally
+  Rejected because it accumulates technical debt exactly in the areas that most need stable invariants.
+
+### 6. Use one research document as the coordination artifact, then execute by small work packages
+
+This change produces a detailed markdown report under `temp/` that groups findings into server/core and feature workstreams, then translates them into small, independently assignable tasks. The report is not the contract itself; the specs are. The report exists to preserve comparison context and justify prioritization.
+
+Why this over burying all detail in tasks:
+
+- the comparison against local `clangd` sources is too detailed to keep only in task bullets
+- the report gives future implementation agents a single place to understand gaps and evidence
+
+## Risks / Trade-offs
+
+- [Stricter generation gating may temporarily increase null/error responses] -> Mitigation: prefer explicit stale-result rejection over silently wrong data, and add targeted tests for retry behavior.
+- [Header-context design can expand into full index work] -> Mitigation: keep this change focused on command/context selection and defer cross-project index heuristics that are not needed for production dogfooding.
+- [Feature parity work may accidentally duplicate already-completed behavior] -> Mitigation: each feature task must confirm current implementation state before coding, using the gap-analysis report and local source references.
+- [Cleaning up wrong-shape code may require deleting partially integrated paths] -> Mitigation: treat deletion as part of completion criteria rather than as optional follow-up.
+- [Parallel execution can produce merge conflicts around `master_server.cpp` and protocol definitions] -> Mitigation: split tasks by ownership boundary, with server/core work owning protocol and lifecycle changes, and feature work owning only their feature modules plus the minimal routing needed for exposure.
+
+## Migration Plan
+
+1. Land the planning artifacts and the gap-analysis document.
+2. Implement server/core invariants first where feature correctness depends on them:
+   open-buffer source of truth, generation-safe AST reads, header/context selection, lifecycle cleanup.
+3. In parallel, implement AST-only feature tasks that do not depend on index maturity.
+4. Remove or hide stubbed feature advertisements that remain incomplete.
+5. Expand test coverage around document lifecycle, stale-result rejection, header handling, and feature-level golden cases.
+6. Start internal dogfooding only after the server/core acceptance criteria and the minimum AST-only baseline are both satisfied.
+
+Rollback strategy:
+
+- because this change is primarily a planning and refactoring contract, rollback means disabling newly advertised features or reverting individual implementation tasks rather than reverting the entire capability set at once
+
+## Open Questions
+
+- How should `clice` choose among multiple valid compilation contexts for the same source file before the full index is mature?
+- For headers without a direct compile command, what ranking rule should choose the preferred includer or proxy translation unit?
+- Should AST-backed requests block until a matching generation is ready, or return an explicit retriable error after a short timeout?
+- Which AST-only code actions are mandatory for first internal rollout, and which can remain behind capability flags?
+- How should dynamic, unsaved-document symbol data be combined with disk-backed merged index results without reintroducing offset drift?

openspec/changes/assess-clice-production-readiness/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+`clice` has reached the stage where the core server loop starts, responds, and already exposes a meaningful set of AST-backed language features. However, it is not yet safe to treat the server as production-usable or even stable for internal dogfooding, because open-buffer semantics, compilation-context handling, stale AST/index reads, worker lifecycle, and several AST-only editor features still diverge from the behavior expected from a real C++ language server.
+
+The project also lacks a single implementation contract that separates core server/compiler work from independently assignable feature work. A focused production-readiness change is needed now so server refactoring, feature parity work, and documentation updates can proceed in parallel without mixing concerns.
+
+## What Changes
+
+- Define a production-readiness plan for `clice` that separates core server/compiler obligations from AST-only feature work.
+- Specify correct open-buffer versus on-disk behavior for compile, query, and navigation flows.
+- Specify compilation-context and header-context behavior required for headers and multi-context source files.
+- Specify the minimum AST-only feature baseline needed before internal rollout, including feature parity gaps against `clangd` where global index is not required.
+- Specify server hardening requirements for worker lifecycle, stale-result rejection, observability, resource control, and error handling.
+- Produce a detailed gap-analysis document under `./temp` that compares current `clice` behavior against local `clangd` sources and turns the findings into implementation workstreams.
+
+## Capabilities
+
+### New Capabilities
+- `buffer-aware-document-model`: Define the source-of-truth rules for opened documents, unsaved edits, build generations, and request consistency.
+- `compilation-context-management`: Define how `clice` chooses and applies compilation contexts for source files and headers, including header context and compilation context behavior.
+- `ast-feature-baseline`: Define the AST-only feature set and quality baseline required before production dogfooding, including missing or incomplete `clangd`-style features.
+- `server-production-hardening`: Define the runtime, worker, indexing, logging, and lifecycle guarantees required for reliable day-to-day use.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+- Affected code spans `src/server`, `src/command`, `src/compile`, `src/index`, `src/feature`, and related tests under `tests/unit` and `tests/integration`.
+- The change establishes the implementation contract for upcoming refactors to document state, compile scheduling, header/context selection, worker ownership/eviction, and AST-only LSP handlers.
+- Documentation output will include OpenSpec artifacts under `openspec/changes/assess-clice-production-readiness/` and a detailed analysis document under `temp/`.

openspec/changes/assess-clice-production-readiness/specs/ast-feature-baseline/spec.md

@@ -0,0 +1,44 @@
+## ADDED Requirements
+
+### Requirement: Production rollout includes a minimum AST-only feature baseline
+Before internal production dogfooding, `clice` SHALL provide a stable AST-only feature baseline consisting of hover, completion, signature help, document symbols, document links, folding ranges, semantic tokens, inlay hints, formatting, diagnostics, document highlight, selection range, and AST-backed code actions that do not require a global index.
+
+#### Scenario: Missing AST-only feature is visible in capability surface
+- **WHEN** an AST-only feature is not implemented to the agreed baseline
+- **THEN** `clice` does not advertise it as available
+
+#### Scenario: Implemented AST-only feature is routed end-to-end
+- **WHEN** an AST-only feature reaches the agreed baseline
+- **THEN** `clice` exposes it through LSP capability advertisement, request routing, and worker execution
+
+### Requirement: Hover provides semantic detail beyond symbol name
+Hover responses SHALL include semantic information that is useful for real editing, such as declaration spelling, type information, or associated documentation when available.
+
+#### Scenario: Hover on function shows semantic information
+- **WHEN** a user hovers a function or method symbol
+- **THEN** the hover response includes more than a bare symbol kind and name
+
+### Requirement: Completion and signature help expose actionable assistance
+Completion and signature-help responses SHALL provide parameter-aware assistance that is suitable for day-to-day editing, including snippets or argument guidance when enabled by server options.
+
+#### Scenario: Completion inserts parameter-aware text
+- **WHEN** snippet-style completion support is enabled and a callable symbol is completed
+- **THEN** the completion response includes parameter-aware insertion behavior
+
+#### Scenario: Signature help identifies active parameter
+- **WHEN** a user requests signature help inside a callable argument list
+- **THEN** the response identifies the active parameter for the current cursor position
+
+### Requirement: Inlay hint computation respects requested scope
+Inlay hints SHALL be computed for the requested document scope rather than always forcing a full-document computation.
+
+#### Scenario: Range request limits inlay hint computation
+- **WHEN** a client requests inlay hints for a document range
+- **THEN** `clice` computes and returns hints for that range instead of scanning the entire file
+
+### Requirement: AST-only code actions are either implemented or hidden
+If an AST-only code action is advertised by `clice`, it SHALL produce a meaningful result instead of an unconditional empty placeholder response.
+
+#### Scenario: Advertised code action is not a stub
+- **WHEN** a client requests code actions for a context where an advertised AST-only code action applies
+- **THEN** `clice` returns a meaningful action or omits the capability from advertisement

openspec/changes/assess-clice-production-readiness/specs/buffer-aware-document-model/spec.md

@@ -0,0 +1,41 @@
+## ADDED Requirements
+
+### Requirement: Opened buffer content is authoritative
+When a document is opened in the editor, `clice` SHALL treat the opened buffer content as the source of truth for compile inputs and AST-backed queries until the document is closed.
+
+#### Scenario: Hover uses unsaved content
+- **WHEN** a user edits an opened file without saving and requests hover in that file
+- **THEN** `clice` uses the opened buffer content rather than the on-disk file content to answer the request
+
+#### Scenario: Completion uses unsaved content
+- **WHEN** a user edits an opened file without saving and requests completion in that file
+- **THEN** `clice` builds completion context from the opened buffer content rather than the on-disk file content
+
+### Requirement: AST-backed requests use a matching document generation
+`clice` SHALL answer AST-backed requests only from an AST generation that matches the current opened-document version, or otherwise reject/defer the request in a defined way.
+
+#### Scenario: Stale AST result is discarded
+- **WHEN** a rebuild completes for an older document version after a newer edit has already been accepted
+- **THEN** `clice` discards the stale AST result and does not publish it as the current answer state
+
+#### Scenario: Feature request does not read stale AST
+- **WHEN** a feature request arrives while the current document version has not yet produced a matching AST
+- **THEN** `clice` does not answer from an older AST generation
+
+### Requirement: Active-file navigation starts from live document state
+For an opened file, `clice` SHALL resolve the source-side symbol and position mapping for navigation requests from the current document state before using disk-backed index data for remote results.
+
+#### Scenario: Local definition lookup uses live offsets
+- **WHEN** a user makes unsaved edits that shift symbol offsets and requests definition from the opened file
+- **THEN** `clice` resolves the queried symbol from the current opened document state instead of interpreting the request against stale disk offsets
+
+### Requirement: Closing a document ends opened-buffer authority
+When an opened document is closed, `clice` SHALL stop treating the editor buffer as authoritative and SHALL release associated opened-document runtime state.
+
+#### Scenario: Closed document falls back to disk state
+- **WHEN** a document is closed and then queried again without reopening
+- **THEN** `clice` uses persisted project state rather than the former unsaved editor buffer
+
+#### Scenario: Close releases owned runtime state
+- **WHEN** a document is closed
+- **THEN** `clice` releases worker ownership and opened-document runtime state associated with that document

openspec/changes/assess-clice-production-readiness/specs/compilation-context-management/spec.md

@@ -0,0 +1,41 @@
+## ADDED Requirements
+
+### Requirement: Header files use a real compilation context
+When a header file lacks a direct compile command, `clice` SHALL derive its compilation context from a valid project context rather than falling back to a generic language-default command.
+
+#### Scenario: Opened header borrows project context
+- **WHEN** a user opens a header that is included by one or more project translation units but has no direct compile command entry
+- **THEN** `clice` selects a valid project-derived compilation context for that header
+
+#### Scenario: No generic fallback for project header
+- **WHEN** a project header has at least one valid project-derived compilation context
+- **THEN** `clice` does not prefer a generic fallback command over the project-derived context
+
+### Requirement: Header context and compilation context remain distinct runtime concepts
+`clice` SHALL distinguish header-context behavior from source-file compilation-context behavior in its runtime model and queries.
+
+#### Scenario: Header query selects header context
+- **WHEN** a file is analyzed as a header included through a source file context
+- **THEN** `clice` uses header-context selection rules instead of treating the file as an ordinary standalone translation unit
+
+#### Scenario: Source query selects compilation context
+- **WHEN** a file is analyzed as a directly compiled source file
+- **THEN** `clice` uses compilation-context selection rules appropriate to that source file
+
+### Requirement: Context-sensitive data is queried with an explicit active context
+If multiple valid contexts exist for the same path, `clice` SHALL retain enough context identity to select the active one during query execution.
+
+#### Scenario: Multi-context source file remains distinguishable
+- **WHEN** the same source file is compiled under multiple valid compile commands
+- **THEN** `clice` preserves distinguishable context identities instead of collapsing them into one ambiguous runtime state
+
+#### Scenario: Context-sensitive lookup does not union incompatible states
+- **WHEN** a query targets a file whose symbols differ by context
+- **THEN** `clice` does not answer by blindly unioning incompatible context-specific results
+
+### Requirement: Missing context is surfaced explicitly
+If `clice` cannot determine a valid compilation context for a file, it SHALL surface the degraded state explicitly through diagnostics or logs rather than silently pretending the file has a correct context.
+
+#### Scenario: Missing header context is observable
+- **WHEN** `clice` cannot derive a usable context for an opened header
+- **THEN** the failure is visible through diagnostics, logs, or both

openspec/changes/assess-clice-production-readiness/specs/server-production-hardening/spec.md

@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### Requirement: Worker lifecycle changes are reflected in runtime ownership
+`clice` SHALL keep worker ownership, opened-document tracking, and eviction state consistent across open, change, save, close, and worker-failure events.
+
+#### Scenario: Closing a document releases worker ownership
+- **WHEN** a document is closed
+- **THEN** `clice` removes the document from worker ownership tracking and allows its runtime state to be evicted
+
+#### Scenario: Worker failure is surfaced
+- **WHEN** a worker crashes, times out, or fails IPC
+- **THEN** `clice` records the failure and surfaces a defined error outcome instead of silently pretending the request succeeded
+
+### Requirement: Runtime resource controls are enforced rather than decorative
+Configured runtime limits for worker memory and background work SHALL affect actual scheduling or eviction behavior.
+
+#### Scenario: Memory limit influences eviction
+- **WHEN** worker memory pressure exceeds the configured limit
+- **THEN** `clice` uses the configured limit to drive eviction or rejection behavior
+
+### Requirement: Background work does not outrank active editing
+`clice` SHALL schedule compile and indexing work so that opened-document responsiveness takes priority over background throughput.
+
+#### Scenario: Open document work outranks background indexing
+- **WHEN** a user edits an opened document while background indexing is pending
+- **THEN** `clice` prioritizes the opened-document work ahead of non-urgent background indexing
+
+### Requirement: Production debugging information is observable
+`clice` SHALL emit enough logging and trace information to diagnose compile-context selection, worker failures, and request/response mismatches in production-style usage.
+
+#### Scenario: Compile failure includes useful context
+- **WHEN** a compile, header-context selection, or worker request fails
+- **THEN** logs include enough context to identify the affected file, command/context, and failure site

openspec/changes/assess-clice-production-readiness/tasks.md

@@ -0,0 +1,49 @@
+## 1. Buffer-Aware Document Model
+
+- [ ] 1.1 Introduce an explicit opened-document state model that tracks text, editor version, build generation, AST generation, and readiness state in the master/worker boundary
+- [ ] 1.2 Make `didOpen`, `didChange`, `didSave`, and `didClose` update one consistent source-of-truth flow for opened documents
+- [ ] 1.3 Replace the `ensure_compiled()` stub with generation-aware gating for AST-backed requests
+- [ ] 1.4 Reject or defer stale AST-backed feature requests instead of serving results from older generations
+- [ ] 1.5 Prevent AST-backed feature execution on fatal or otherwise unusable compilation units
+- [ ] 1.6 Add tests that cover unsaved edits, stale compile completion discard, and close-time state release
+
+## 2. Compilation Context Management
+
+- [ ] 2.1 Implement real project-derived compilation-context selection for headers without direct compile commands
+- [ ] 2.2 Define and persist distinct runtime identities for header contexts and source-file compilation contexts
+- [ ] 2.3 Make query paths accept an explicit active context instead of blindly unioning context-sensitive results
+- [ ] 2.4 Surface missing or degraded compilation-context selection through logs or diagnostics
+- [ ] 2.5 Add tests for header opening, project-context borrowing, and multi-context file handling
+
+## 3. Server Runtime Hardening
+
+- [ ] 3.1 Wire `didClose` to worker eviction and ownership cleanup so closed documents do not linger in worker memory
+- [ ] 3.2 Surface worker IPC failures, crashes, and timeouts as explicit server-side errors with useful logs
+- [ ] 3.3 Enforce configured resource controls such as worker memory limits instead of relying on hardcoded thresholds
+- [ ] 3.4 Prioritize opened-document compile work ahead of non-urgent background indexing
+- [ ] 3.5 Expand runtime logging for compile commands, context selection, worker failure causes, and request/result mismatches
+- [ ] 3.6 Add lifecycle and scheduling tests that cover worker cleanup, timeout handling, and active-edit priority
+
+## 4. Live-State Navigation Correctness
+
+- [ ] 4.1 Resolve source-side symbol lookup for opened files from the current AST before consulting disk-backed index data
+- [ ] 4.2 Define how active-document state is combined with index-backed remote results for definition and related navigation flows
+- [ ] 4.3 Remove or disable stubbed navigation fallback paths that cannot yet return correct results
+- [ ] 4.4 Add tests for navigation from unsaved buffers and mixed AST/index result paths
+
+## 5. AST-Only Feature Baseline
+
+- [ ] 5.1 Enrich hover so it returns semantic detail beyond bare symbol kind and name
+- [ ] 5.2 Add `documentHighlight` as an AST-backed feature with end-to-end capability advertisement and routing
+- [ ] 5.3 Expose `selectionRange` using the existing local selection machinery
+- [ ] 5.4 Upgrade completion and signature help with parameter-aware insertion and richer callable assistance
+- [ ] 5.5 Respect requested scope for inlay-hint computation instead of forcing full-document evaluation
+- [ ] 5.6 Implement the first production-worthy AST-only code actions or stop advertising stubbed code-action support
+- [ ] 5.7 Audit advertised AST-only capabilities and remove any remaining stub or placeholder surfaces
+- [ ] 5.8 Add or update feature-level tests and golden cases for every newly exposed AST-only feature
+
+## 6. Documentation And Readiness Tracking
+
+- [ ] 6.1 Write and maintain the detailed production-readiness gap analysis in `temp/`
+- [ ] 6.2 Update developer documentation for opened-buffer semantics, compilation-context handling, and feature ownership boundaries
+- [ ] 6.3 Define a dogfooding readiness checklist that combines server/core acceptance criteria with the minimum AST-only feature baseline

openspec/changes/improve-code-completion-parity/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-03

openspec/changes/improve-code-completion-parity/design.md

@@ -0,0 +1,250 @@
+## Context
+
+`clice` currently routes `textDocument/completion` through `MasterServer::forward_stateless()`, which prepares open-buffer text plus available PCH/PCM paths and sends a one-shot completion request to the stateless worker. The worker builds `CompilationParams`, invokes `feature::code_complete()`, and returns a raw `std::vector<CompletionItem>`.
+
+The implementation in `src/feature/code_completion.cpp` is intentionally small:
+
+- run Sema code completion at a single file/offset
+- compute the local identifier prefix
+- fuzzy-match candidate labels against the typed prefix
+- emit only basic LSP fields such as `label`, `kind`, `textEdit`, and `sortText`
+- bundle function overloads only by qualified name, with `detail = "(...)"` for grouped overloads
+
+Compared with the local `clangd` implementation in `.llvm/clang-tools-extra/clangd`, the gap is large and structural rather than cosmetic. `clangd` has a full completion pipeline:
+
+- request shaping from client capabilities and trigger context in `ClangdLSPServer`
+- `CodeCompleteFlow` as a staged completion engine rather than direct Sema rendering
+- candidate fusion from Sema, project index, and raw identifiers
+- context capture such as completion kind, query scopes, expected type, and following token
+- scoring that combines name match with semantic/contextual signals
+- richer LSP rendering including signatures, return types, docs, snippets, fix-its, additional edits, deprecation, `filterText`, `isIncomplete`, and include insertion
+
+At the same time, `clice` has infrastructure that clangd either lacks or does not currently integrate into completion as deeply:
+
+- explicit header-context modeling for headers shared by multiple includers
+- existing PCH/PCM request plumbing in the master/stateless worker path
+- merged per-file index shards and project-wide symbol/reference data
+- a project goal of instantiation-aware template processing
+
+There is also a hard constraint: `clice`'s current index symbol payload only stores `name`, `kind`, and reference files. That is enough for navigation-oriented lookup, but not enough for clangd-style index completion, which needs scope, signature, return type, documentation, deprecation, canonical declaration/header ownership, and dependency insertion hints.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- close the highest-value completion gap with clangd in behavior, not in file-by-file implementation shape
+- replace the current direct Sema-to-LSP path with a staged completion pipeline
+- support rich, capability-aware LSP completion responses
+- augment Sema completion with identifier and project-index candidates
+- introduce heuristics that use semantic/contextual signals instead of raw fuzzy score alone
+- define how fix-its and dependency insertion edits attach to completion items
+- use `clice`'s header-context, module, and template machinery to define completion behaviors clangd does not currently provide
+
+**Non-Goals:**
+
+- byte-for-byte parity with clangd internals or its exact scoring constants
+- introducing `completionItem/resolve` in this change
+- shipping a learned ranking model in the first implementation; heuristic ranking is sufficient
+- requiring the global index to become fully clangd-equivalent before completion quality improves
+- solving every completion-related editor quirk across all clients before the core pipeline exists
+
+## Decisions
+
+### 1. Split completion into request shaping, candidate collection, scoring, and rendering
+
+`clice` should stop treating code completion as "run Sema and immediately serialize `CompletionItem`s". Instead, completion will become a staged pipeline:
+
+1. request shaping at the LSP/server edge
+2. candidate collection in the worker
+3. merge/deduplicate/bundle
+4. score and truncate
+5. render to LSP according to client capabilities
+
+Why this approach:
+
+- it matches the actual gap with clangd, which is pipeline depth rather than one missing field
+- it keeps protocol negotiation in the server and semantic work in the worker
+- it allows `clice`-specific signals to affect ranking without polluting the LSP layer
+
+Alternative considered:
+
+- continue returning `std::vector<CompletionItem>` directly from `feature::code_complete()`
+  Rejected because `isIncomplete`, score-aware truncation, richer origins, and delayed rendering all need an intermediate completion model.
+
+### 2. Extend the completion request contract with client capabilities and trigger context
+
+The current stateless completion request only carries file text, compile arguments, and offset. The request contract should be extended so the worker can render results correctly:
+
+- completion trigger kind/character
+- client snippet support
+- documentation format preference
+- label-details support
+- supported completion item kinds
+- requested limit
+- overload-bundling preference
+
+The master server should negotiate these from `initialize` capabilities and pass a normalized completion-options struct to the worker.
+
+Why this approach:
+
+- `clangd` already proves that completion quality depends on client capabilities
+- several existing `CodeCompletionOptions` fields in `clice` are never meaningfully driven by the LSP client today
+- it keeps editor-specific policy out of the core collector logic
+
+Alternative considered:
+
+- hardcode one rendering mode for all clients
+  Rejected because it prevents snippet/doc behavior from ever becoming correct and makes the existing options struct mostly dead code.
+
+### 3. Keep Sema as the primary source of truth, but augment it with identifiers and index symbols
+
+Collection order should be:
+
+- Sema candidates from the active compilation context
+- local/raw identifiers from the open buffer and active file context
+- project/index candidates when the completion context allows them
+
+Sema remains primary because it understands visibility, module state, recovery fix-its, and the exact active compile command. Identifier and index sources fill gaps when Sema is incomplete or when project-wide results are useful.
+
+Merge rules should deduplicate by insertion semantics, not just by display label. Function overload bundling should group only candidates that render identically and require the same dependency edits.
+
+Why this approach:
+
+- it preserves correctness for the current file while still expanding recall
+- it fits `clice`'s current stateless worker path, which already builds the correct compile inputs
+- it allows richer completion without waiting for index-only correctness
+
+Alternative considered:
+
+- move to index-first completion with Sema as fallback
+  Rejected because `clice`'s strongest current signals for modules, fix-its, and header contexts come from active compilation, not from the persisted index.
+
+### 4. Expand the index schema specifically for completion metadata
+
+`clice`'s current `index::Symbol` payload is too small for rich completion. To support index-backed completion, the index data model should be extended with completion-oriented fields such as:
+
+- qualified scope / shortest usable qualifier
+- signature and return type
+- deprecation flag
+- documentation summary or documentation lookup key
+- canonical declaration path
+- preferred include header or module/import source
+- symbol origin/category for ranking
+
+The first implementation does not need every clangd field, but it does need enough metadata to render and rank project-index candidates meaningfully.
+
+Why this approach:
+
+- without extra index payload, project-index completion can only return weak name-only suggestions
+- dependency insertion cannot be justified without declaration ownership metadata
+- the serialization boundary already exists in `TUIndex`, `ProjectIndex`, and merged shards, so this is the right architectural layer
+
+Alternative considered:
+
+- use the current index unchanged and limit project-index completion to `name + kind`
+  Rejected because it would add complexity without delivering clangd-level value, and would likely need to be rewritten immediately after.
+
+### 5. Use heuristic ranking first, and encode the signals explicitly
+
+The first ranking model should remain heuristic, but it must go beyond raw fuzzy score. Candidate scoring should combine:
+
+- prefix/exact name match
+- semantic availability from Sema
+- in-scope vs required-qualifier insertion
+- expected type / preferred type compatibility when available
+- file/header-context proximity
+- deprecation penalty
+- module availability and dependency-edit cost
+- template-instantiation compatibility when `clice` can infer it
+
+This keeps the design testable and explainable without blocking on a learned model.
+
+Why this approach:
+
+- it delivers most user-visible value quickly
+- it maps naturally onto `clice`'s existing semantics-heavy architecture
+- it leaves room for a later learned ranker without locking the system into clangd's exact model
+
+Alternative considered:
+
+- adopt clangd-style decision-forest ranking immediately
+  Rejected because `clice` does not yet have the surrounding instrumentation and labeled data pipeline, and heuristic ranking is sufficient for this change.
+
+### 6. Treat completion-related edits as first-class output, with staged support
+
+Two classes of edits matter:
+
+- Sema-provided fix-its near the completion site
+- dependency insertion edits such as `#include` or `import`
+
+The completion model should carry both as structured edits and render them into LSP `additionalTextEdits` or merged `textEdit`s where appropriate.
+
+Implementation should be staged:
+
+- stage 1: preserve and emit Sema fix-its
+- stage 2: add dependency insertion for header-backed symbols once index metadata can justify it
+- stage 3: add module import insertion where the active TU and candidate source indicate a module-based dependency is the right form
+
+Why this approach:
+
+- it closes a large clangd parity gap without forcing all edit types at once
+- module-aware insertion is a place where `clice` can exceed clangd's current include-centric design
+
+Alternative considered:
+
+- postpone all completion edits until after ranking/index parity
+  Rejected because Sema fix-its are already available and should not be discarded.
+
+### 7. Make `clice`-specific header, module, and template context part of completion semantics
+
+The main "beyond clangd" opportunities should not be separate side features. They should influence the same completion pipeline:
+
+- **Header context**: completion in a header should use the active includer/source context for that header, instead of treating the header as a single global state.
+- **Modules**: available PCM/module dependencies should affect both candidate visibility and dependency insertion strategy.
+- **Template instantiation**: when `clice` can identify concrete instantiation or expected-type information, ranking should prefer candidates compatible with that instantiated context.
+
+This means the primary completion request must always be evaluated in one active compilation context, not a union of all possible contexts. Alternate contexts can be explored later, but blindly merging them would produce unstable and misleading completions.
+
+Why this approach:
+
+- it uses the architecture `clice` already claims as a differentiator
+- it avoids the worst failure mode for shared headers: mixing incompatible contexts into one result set
+- it keeps "beyond clangd" work aligned with user-visible completion quality
+
+Alternative considered:
+
+- add cross-context completion by merging all known header contexts
+  Rejected because it sacrifices correctness and predictable ranking for recall.
+
+## Risks / Trade-offs
+
+- [Index payload expansion increases serialization and background-index cost] → Mitigation: add only completion-relevant fields first and measure shard-size growth before expanding documentation payloads further.
+- [Ranking heuristics become opaque or brittle] → Mitigation: keep signals explicit, loggable, and unit-tested rather than encoding hidden constants throughout the collector.
+- [Header-context-aware completion can produce confusing behavior if the active context is wrong] → Mitigation: bind completion to the same active header-context selection model used by navigation/AST features, not an ad hoc completion-only heuristic.
+- [Dependency insertion can apply the wrong form (`#include` vs `import`)] → Mitigation: gate edits on explicit symbol metadata and active compilation mode, and prefer no edit over a wrong edit.
+- [More completion metadata increases protocol churn between master and stateless workers] → Mitigation: add a dedicated options/result struct instead of spreading new fields loosely across existing request params.
+
+## Migration Plan
+
+1. Extend the LSP/server edge to capture completion capabilities, trigger context, and limits.
+2. Introduce an internal completion result model and return a completion list shape with `isIncomplete`.
+3. Refactor the worker pipeline to separate candidate collection, merging, scoring, and rendering while preserving current Sema behavior.
+4. Add local-identifier completion and heuristic ranking improvements.
+5. Expand the index schema and integrate project-index candidates.
+6. Add completion-related edits, first for Sema fix-its and then for dependency insertion.
+7. Integrate header-context, module, and template-instantiation signals into ranking and edit policy.
+8. Expand unit and integration coverage around rendering, ranking, index augmentation, module-aware completion, and shared-header contexts.
+
+Rollback strategy:
+
+- keep Sema-only completion as a safe fallback path until the staged pipeline is stable
+- disable index augmentation or dependency insertion independently if they prove noisy
+- prefer full completion results without advanced edits over partially wrong completion behavior
+
+## Open Questions
+
+- How much documentation should be stored directly in `clice`'s index versus fetched/lazily summarized from declarations on demand?
+- Should project-index completion support all-scopes insertion from the first version, or require explicit qualifiers only after scope metadata is fully modeled?
+- What is the right UX for exposing the currently active header context to users when completion results differ across includers?
+- How aggressive should template-instantiation-aware ranking be before users perceive it as "hiding" generic but still legal completions?
+- Whether dependency insertion for modules should be represented as ordinary additional text edits or as a future code-action-style completion extension.

openspec/changes/improve-code-completion-parity/proposal.md

@@ -0,0 +1,36 @@
+## Why
+
+`clice` already answers `textDocument/completion`, but the current implementation is still a thin Sema wrapper: it gathers only compiler candidates, applies local fuzzy filtering, and returns minimal `CompletionItem` fields. Compared with the local `clangd` implementation under `.llvm/clang-tools-extra/clangd`, it is missing most of the completion pipeline that makes results accurate, stable, and editor-friendly: client capability negotiation, context-aware triggering, richer ranking, index-backed augmentation, richer rendering, and completion-related edits.
+
+This is worth addressing now because `clice` already has the infrastructure that can support a stronger design: background project indexing, merged per-file index shards, header-context modeling, stateless completion workers, and PCH/PCM plumbing for module-aware compilation. Closing the clangd gap will materially improve day-to-day usability, while `clice`'s existing header-context, module, and instantiation-aware architecture creates opportunities to implement completion behaviors clangd does not currently provide.
+
+## What Changes
+
+- Define a full code-completion pipeline for `clice` instead of the current direct Sema-to-LSP conversion path.
+- Add parity-oriented completion behavior for the highest-value clangd features:
+  - client capability negotiation for snippets, documentation format, label details, completion item kinds, and overload bundling
+  - trigger-character handling and suppression of obviously spurious auto-triggered completion
+  - richer `CompletionItem` rendering including `filterText`, stable `sortText`, signatures/details, return types, documentation, deprecation, snippet suffixes, and completion-related edits
+  - result limiting and `isIncomplete` signaling
+  - completion candidates from project index and local identifiers in addition to Sema results
+  - ranking that combines fuzzy match with semantic/contextual signals rather than raw name matching alone
+- Define how `clice` should attach edits associated with completion candidates, including fix-its and insertion of missing dependencies when the completion source can justify them.
+- Specify `clice`-specific completion extensions that go beyond clangd's current model:
+  - header-context-aware completion for headers shared by multiple includers
+  - module-aware completion that exploits existing PCM dependency tracking
+  - instantiation-aware ranking and filtering for template-heavy code
+- Add targeted unit and integration coverage so completion behavior can evolve without regressions.
+
+## Capabilities
+
+### New Capabilities
+- `code-completion`: Provide context-aware, multi-source C++ code completion with rich LSP rendering, ranking, dependency edits, and `clice`-specific support for header contexts, modules, and template instantiation.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- Affected code: `src/feature/code_completion.cpp`, `src/feature/feature.h`, `src/server/master_server.cpp`, `src/server/stateless_worker.cpp`, `src/server/protocol.h`, and completion-related protocol wiring in the IPC/LSP layer.
+- Likely affected subsystems: project/merged index integration, document/client capability tracking, completion request routing, and any helper code used for include/import insertion or completion scoring.
+- Affected tests: completion unit tests, stateless worker tests, server integration tests, module fixtures, and new comparison-oriented cases for header-context and template-heavy completion.

openspec/changes/improve-code-completion-parity/specs/code-completion/spec.md

@@ -0,0 +1,77 @@
+## ADDED Requirements
+
+### Requirement: Capability-aware completion responses
+The server SHALL shape code-completion responses according to client capabilities, trigger context, and requested limits instead of returning one fixed completion-item format to every client.
+
+#### Scenario: Snippet-capable client receives snippet completions
+- **WHEN** the client advertises snippet support and a completion candidate has callable arguments, template arguments, or other structured suffix text
+- **THEN** the completion response MUST encode that candidate using snippet-formatted insertion text rather than degrading it to plain text
+
+#### Scenario: Plain-text client receives compatible completion items
+- **WHEN** the client does not advertise snippet support or label-details support
+- **THEN** the server MUST return completion items that remain correct for that client and MUST NOT require unsupported snippet or label-details fields to preserve meaning
+
+#### Scenario: Completion result limit is enforced
+- **WHEN** the client or server applies a completion result limit and more matching candidates exist than can be returned
+- **THEN** the server MUST truncate the response to the chosen limit and MUST mark the completion list as incomplete
+
+#### Scenario: Spurious auto-triggered completion is suppressed
+- **WHEN** completion is auto-triggered by a trigger character in a syntactic position that cannot produce meaningful completion candidates
+- **THEN** the server MUST return an empty completion list instead of forcing a normal completion run
+
+### Requirement: Multi-source candidate collection and semantic ranking
+The server SHALL build completion results from multiple candidate sources and rank them using semantic/contextual signals rather than using only raw label matching.
+
+#### Scenario: Sema and index candidates are merged by insertion semantics
+- **WHEN** Sema and project-index collection both produce candidates that insert the same symbol in the same way
+- **THEN** the server MUST return a single merged completion item rather than duplicate visible entries
+
+#### Scenario: Local identifiers supplement Sema completion
+- **WHEN** the open document contains matching identifiers that are not surfaced by Sema at the completion point
+- **THEN** the server MUST be able to return those identifiers as completion candidates when they are relevant to the typed prefix
+
+#### Scenario: Required qualifiers are preserved for out-of-scope symbols
+- **WHEN** a project-index completion candidate is not directly visible at the completion point but remains a valid suggestion through qualification
+- **THEN** the completion item MUST preserve the required qualifier in its rendered insertion text instead of pretending the symbol is already in scope
+
+#### Scenario: Semantic relevance outranks weaker textual matches
+- **WHEN** two otherwise similar candidates match the typed prefix but only one is strongly favored by semantic/contextual signals such as active scope, expected type, or availability in the current compilation context
+- **THEN** the semantically favored candidate MUST rank above the weaker match
+
+### Requirement: Rich completion item rendering and completion-related edits
+The server SHALL render completion items with enough metadata and edits to make them useful in modern editors, including signatures, detail fields, filtering/sorting metadata, documentation, deprecation, and completion-associated edits.
+
+#### Scenario: Function completion includes signature and return-type detail
+- **WHEN** a callable declaration is returned as a completion candidate
+- **THEN** the completion item MUST expose its callable signature and MUST expose return-type or overload-summary detail in the rendered result
+
+#### Scenario: Documentation and deprecation are preserved
+- **WHEN** a completion candidate has documentation text or is marked deprecated by Sema or index metadata
+- **THEN** the completion item MUST surface the documentation and deprecation state to the client
+
+#### Scenario: Sema fix-its are attached to the completion item
+- **WHEN** Sema provides fix-it edits that are required or strongly suggested for a completion candidate
+- **THEN** the server MUST attach those edits to the completion item so the accepted completion can apply them
+
+#### Scenario: Dependency insertion edits are attached when justified
+- **WHEN** a completion candidate refers to a symbol that requires adding a missing dependency and the completion source can identify the correct insertion form
+- **THEN** the completion item MUST attach the corresponding dependency insertion edits instead of returning only the symbol name
+
+### Requirement: Context-sensitive completion for headers, modules, and templates
+The server SHALL use `clice`'s compilation-context machinery so completion reflects the active header context, module dependency state, and template-instantiation information instead of treating all files as context-free.
+
+#### Scenario: Shared header completion follows the active header context
+- **WHEN** the same header is completed under different active includer/source contexts
+- **THEN** the completion results MUST reflect the active header context rather than a context-free union of all possible includers
+
+#### Scenario: Module-aware completion uses available PCM dependencies
+- **WHEN** the active file depends on C++20 modules whose PCMs are available to the completion worker
+- **THEN** the completion pipeline MUST consider symbols made visible by those module dependencies when producing results
+
+#### Scenario: Module dependency insertion prefers import-aware edits
+- **WHEN** the selected completion candidate is best satisfied by adding a module dependency rather than a textual include and the active translation unit supports that form
+- **THEN** the completion item MUST use a module-aware dependency insertion edit instead of forcing a header-style include edit
+
+#### Scenario: Template-instantiation-aware ranking prefers concretely compatible candidates
+- **WHEN** the active completion site provides concrete template-instantiation or expected-type information that distinguishes candidate relevance
+- **THEN** the ranking logic MUST prefer candidates compatible with that instantiated context over otherwise similar generic alternatives

openspec/changes/improve-code-completion-parity/tasks.md

@@ -0,0 +1,40 @@
+## 1. Completion Request Contract
+
+- [ ] 1.1 Audit the current `textDocument/completion` request path and extend the master/worker protocol to carry trigger context, requested limit, and normalized client completion capabilities.
+- [ ] 1.2 Store completion-related client capabilities from `initialize` in the server and thread them into completion requests instead of relying on default `CodeCompletionOptions`.
+- [ ] 1.3 Change completion responses from a raw item vector to a completion-list shape that can represent `isIncomplete` and future completion metadata cleanly.
+
+## 2. Internal Completion Pipeline
+
+- [ ] 2.1 Introduce an internal completion-candidate/result model that separates collection, deduplication/bundling, scoring, truncation, and final LSP rendering.
+- [ ] 2.2 Refactor `src/feature/code_completion.cpp` so Sema collection populates the internal model instead of directly constructing final `CompletionItem`s.
+- [ ] 2.3 Implement capability-aware rendering for snippets, signatures/details, documentation, deprecation, `filterText`, and stable `sortText`.
+- [ ] 2.4 Add request-side suppression for obviously spurious auto-triggered completions and preserve correct fallback behavior for manual completion.
+
+## 3. Candidate Sources And Ranking
+
+- [ ] 3.1 Add local-identifier collection from the active buffer/file context and merge those candidates with Sema results.
+- [ ] 3.2 Implement semantic deduplication and overload bundling based on insertion semantics rather than label-only equality.
+- [ ] 3.3 Replace raw fuzzy-only ordering with explicit heuristic scoring that incorporates scope visibility, expected type, deprecation, and active compilation-context signals.
+- [ ] 3.4 Enforce result limits after scoring and verify that truncation drives `isIncomplete` correctly.
+
+## 4. Index Completion And Completion Edits
+
+- [ ] 4.1 Extend completion-relevant index data structures and serialization to store the metadata needed for index-backed completion rendering and ranking.
+- [ ] 4.2 Add project-index candidate lookup for completion and merge index candidates with Sema/identifier candidates without duplicating visible entries.
+- [ ] 4.3 Preserve and render Sema fix-it edits as completion-associated edits.
+- [ ] 4.4 Implement dependency insertion edits for header-backed symbols once index metadata can identify the correct declaration owner and insertion path.
+
+## 5. `clice`-Specific Completion Extensions
+
+- [ ] 5.1 Bind completion in headers to the active header-context selection model instead of treating shared headers as context-free.
+- [ ] 5.2 Integrate available PCM/module dependency information into candidate visibility and ranking for module-aware completion.
+- [ ] 5.3 Implement module-aware dependency insertion policy for completion items that should add `import`-style dependencies instead of header includes.
+- [ ] 5.4 Add template-instantiation-aware ranking signals where `clice` can derive concrete instantiation or expected-type compatibility.
+
+## 6. Validation
+
+- [ ] 6.1 Add focused unit tests for completion rendering, capability negotiation, overload bundling, sorting/filtering metadata, and `isIncomplete` behavior.
+- [ ] 6.2 Add unit or fixture-based tests for identifier augmentation, index-backed completion, fix-it edits, and dependency insertion edits.
+- [ ] 6.3 Add integration coverage for shared-header contexts, module-aware completion, and template-heavy completion cases.
+- [ ] 6.4 Run the relevant completion, worker, index, and integration test targets and fix regressions uncovered during verification.

openspec/changes/improve-document-symbol-outline/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-03

openspec/changes/improve-document-symbol-outline/design.md

@@ -0,0 +1,101 @@
+## Context
+
+The current `src/feature/document_symbols.cpp` implementation reuses the generic `FilteredASTVisitor`. Its advantage is brevity, but it does not model outline-specific semantics such as which declarations should become outline nodes, which should only forward traversal to children, and which subtrees should be skipped entirely.
+
+Compared with `clangd`'s `DocumentOutline`, the current implementation has several structural shortcomings:
+
+- Function nodes continue recursive traversal into function bodies, so local `VarDecl`, `RecordDecl`, `EnumDecl`, `BindingDecl`, and similar declarations may leak into the document outline.
+- Only implicit template instantiations are filtered today; explicit instantiations and explicit specializations do not have distinct visit policies.
+- Declarations produced by macro expansion are placed directly according to the expanded declaration instead of being grouped under main-file macro invocations as `clangd` does.
+- The implementation computes `range` / `selection_range` per declaration but does not repair parent-child range relationships after tree construction, and it does not provide fallback handling for macro locations or inconsistent written-name ranges.
+- Existing tests mostly assert total node counts, which is too weak to prevent hierarchy, naming, and range regressions.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Align `clice` document outline behavior with `clangd` on the core semantic cases.
+- Show only document-level symbols users actually care about while preserving namespace, type, enum, and member hierarchy.
+- Define stable, testable behavior for templates and macros.
+- Replace count-only assertions with structural assertions that provide long-term regression protection.
+
+**Non-Goals:**
+
+- This change does not introduce `#pragma mark`-style outline grouping.
+- This change does not modify `workspace/symbol` behavior or index-layer symbol handling.
+- This change does not refactor unrelated AST traversal infrastructure.
+
+## Decisions
+
+### 1. Use a dedicated outline traversal instead of piling more special cases onto `FilteredASTVisitor`
+
+The core issue in document symbol collection is not "filter a few more decl kinds". It is the need to explicitly distinguish:
+
+- do not visit
+- visit declaration only
+- visit children only
+- visit both declaration and children
+
+This is exactly what `clangd`'s `VisitKind` model addresses. Keeping the generic visitor and layering more contextual flags on top would scatter function-body filtering, template behavior, and macro-container insertion across multiple callbacks and make the implementation harder to maintain.
+
+The alternative is to keep the current visitor and add more contextual checks such as "do not collect local declarations inside function bodies". That approach is smaller, but it does not naturally express leaf-only explicit instantiations, wrapper decl pass-through, or macro container insertion, so it is not chosen.
+
+### 2. Define template and wrapper-declaration behavior using explicit visit policies
+
+The new traversal should cover at least these rules:
+
+- `LinkageSpecDecl`, `ExportDecl`, and similar wrappers do not become outline nodes and only forward traversal to their children.
+- Functions and methods become nodes, but traversal must not descend into function-local declarations.
+- Implicit template instantiations are skipped entirely.
+- Explicit instantiations are shown as declaration-only leaf nodes and do not synthesize member children.
+- Explicit specializations show both the declaration itself and the children actually written in source.
+
+This makes the outline reflect the structure users wrote in the file instead of all declarations that happen to be traversable in the AST.
+
+### 3. Create container nodes for macro invocations written in the main file
+
+`clangd` includes macro invocations written directly in the main file as outline hierarchy nodes. `clice` already has enough macro-location decomposition support to adopt a similar strategy:
+
+- When a declaration originates from macro expansion, walk up the macro-caller chain until reaching a direct invocation written in the main file.
+- Create at most one container node per invocation site.
+- Attach all outline declarations produced by that invocation under the macro container.
+
+This avoids having multiple macro-expanded declarations appear as if they were written directly in the enclosing namespace or class scope, and it keeps the outline aligned with the entry points users actually see in the source.
+
+The alternative is to keep the current behavior and only repair ranges. That is simpler to implement, but it leaves macro-heavy outlines difficult to understand, so it is not chosen.
+
+### 4. Repair ordering and ranges after building the tree
+
+The protocol requires `selectionRange` to be contained within `range`, and editors generally assume parent ranges contain child ranges. The current implementation sorts declarations individually but does not apply a tree-level repair pass.
+
+This change adds a post-processing step that:
+
+- sorts siblings stably in source order
+- expands parent ranges when child ranges extend beyond the initially collected parent range
+- repairs inconsistent `selectionRange` values by falling back to a more reliable location, and collapses to a single range if necessary
+
+This keeps editor-facing invariants centralized instead of scattering boundary-fix logic across declaration collection paths.
+
+### 5. Test structure directly instead of asserting only node counts
+
+New and updated tests should assert:
+
+- top-level and child hierarchy
+- `name` / `kind` for key nodes
+- the absence of leaked local declarations
+- macro container presence and correct children
+- expected behavior for explicit instantiations and explicit specializations
+- `selectionRange` containment within `range`
+
+This is the minimum needed to cover the semantics that actually matter in this change.
+
+## Risks / Trade-offs
+
+- [Higher implementation complexity] -> The traversal logic will be longer than the current visitor-based version. Split visit-policy handling, macro-container logic, and range repair into separate helpers to keep it manageable.
+- [Macro container icon semantics may be imperfect] -> LSP `SymbolKind` does not offer an ideal macro-specific visual category. Prioritize correct hierarchy and ranges first.
+- [Template edge cases are numerous] -> Cover the highest-value cases first with tests for implicit instantiation, explicit instantiation, and explicit specialization behavior.
+- [Snapshot-style tests would be brittle] -> Prefer structural assertions over full JSON snapshots to reduce churn from unrelated field changes.
+
+## Open Questions
+
+- Should this change also add deprecated document symbol metadata, depending on whether the current protocol schema supports `DocumentSymbol.tags` or `deprecated` fields cleanly?

openspec/changes/improve-document-symbol-outline/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+`clice`'s current `document_symbols` implementation collects `NamedDecl`s through the generic `FilteredASTVisitor`. Compared with `clangd`'s dedicated outline builder, it still lacks several important constraints: filtering function-local declarations, differentiating template specializations from instantiations, grouping macro-expanded declarations, and repairing `range` / `selectionRange` / parent-child nesting invariants.
+
+These gaps directly affect outline stability and readability in editors, and they leave a visible behavior gap between `clice` and `clangd` on real C++ code. Closing them now should materially improve document outline quality without changing the LSP surface area.
+
+## What Changes
+
+- Replace the generic "collect interesting decls during recursive traversal" approach with an outline-specific traversal model.
+- Exclude declarations that should not appear in document outline results, especially function-local declarations, implicit entities, and implicit template instantiations.
+- Define template behavior explicitly so specializations, explicit instantiations, and ordinary template declarations appear in the outline in a source-intuitive way.
+- Introduce macro container symbols for macro invocations written in the main file so expanded declarations appear under a stable hierarchy instead of leaking into the enclosing scope.
+- Normalize symbol ordering and range invariants so `selectionRange` is always contained in `range`, and parent ranges always contain child ranges.
+- Strengthen unit and integration coverage so regressions are caught by structural assertions instead of node counts alone.
+
+## Capabilities
+
+### New Capabilities
+- `document-symbols`: Provide document outline output that matches source structure more closely and behaves robustly in template and macro-heavy code.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- Affected code: `src/feature/document_symbols.cpp` and any reused helpers for macro locations or source range repair.
+- Affected tests: `tests/unit/feature/document_symbol_tests.cpp` and `tests/integration/test_server.py`.
+- User-visible behavior: editor Outline / Breadcrumb / Document Symbols views will behave more like `clangd`, especially for local declarations, templates, and macro-heavy code.

openspec/changes/improve-document-symbol-outline/specs/document-symbols/spec.md

@@ -0,0 +1,59 @@
+## ADDED Requirements
+
+### Requirement: Document outline excludes non-structural local declarations
+The document symbol response SHALL include user-written document-structure declarations from the main file, including namespaces, records, enums, fields, top-level variables, functions, methods, constructors, destructors, conversion functions, deduction guides, concepts, and structured bindings.
+
+The document symbol response SHALL NOT include declarations that are local to a function or method body, and SHALL NOT include implicit declarations or implicit template instantiations.
+
+#### Scenario: Local variable does not appear in outline
+- **WHEN** a function body contains a local variable declaration and a local class declaration
+- **THEN** the function itself appears in document symbols
+- **THEN** the local variable and local class do not appear as document symbol children
+
+#### Scenario: Member hierarchy is preserved
+- **WHEN** a record contains nested records, fields, methods, and enum members
+- **THEN** the outer record appears in document symbols
+- **THEN** the nested declarations appear as children of that record in source order
+
+### Requirement: Template specializations follow written-source structure
+The document symbol response SHALL ignore implicit template instantiations.
+
+The document symbol response SHALL include user-written explicit specializations and explicit instantiations exactly once. Explicit specializations that define nested members SHALL expose those nested members as children. Explicit instantiations SHALL appear as leaf symbols unless the source itself contains nested declarations at that location.
+
+#### Scenario: Explicit specialization exposes children
+- **WHEN** a class template has an explicit specialization with user-written members in the main file
+- **THEN** the explicit specialization appears in document symbols
+- **THEN** its user-written members appear as children of that specialization
+
+#### Scenario: Explicit instantiation is a leaf
+- **WHEN** the main file contains an explicit template instantiation declaration or definition
+- **THEN** the instantiated symbol appears in document symbols exactly once
+- **THEN** it does not synthesize member children that are not written at the instantiation site
+
+### Requirement: Macro-expanded declarations are grouped by macro invocation
+When a declaration included in the outline originates from a macro expansion whose invocation is written directly in the main file, the document symbol response SHALL group the expanded declarations under a macro container symbol associated with that invocation.
+
+The macro container SHALL appear at the invocation site and SHALL contain all outline declarations produced by that invocation within the current scope.
+
+#### Scenario: Function-like macro groups expanded declarations
+- **WHEN** a function-like macro invocation in the main file expands to a class declaration with members
+- **THEN** document symbols include a container node for that macro invocation
+- **THEN** the expanded class appears as a child of that container node
+
+#### Scenario: One macro invocation creates one container
+- **WHEN** a single macro invocation expands to multiple top-level declarations
+- **THEN** document symbols include one container node for that invocation
+- **THEN** all declarations produced by that invocation appear beneath the same container node
+
+### Requirement: Document symbol ranges are editor-safe
+Document symbols SHALL be returned in source order within each sibling list.
+
+For every returned symbol, `selectionRange` SHALL be contained within `range`. For every parent symbol with children, the parent `range` SHALL contain each child `range`, including declarations originating from macro expansions.
+
+#### Scenario: Selection range is repaired when written name range is inconsistent
+- **WHEN** a declaration's preferred name location would produce a `selectionRange` outside its declaration `range`
+- **THEN** the response repairs the symbol ranges so that `selectionRange` is contained within `range`
+
+#### Scenario: Parent range contains nested child symbols
+- **WHEN** a symbol has nested child declarations whose ranges extend beyond the initially collected parent range
+- **THEN** the parent symbol range is expanded so that all child ranges are contained within it

openspec/changes/improve-document-symbol-outline/tasks.md

@@ -0,0 +1,17 @@
+## 1. Outline Traversal
+
+- [ ] 1.1 Replace the generic document symbol collector with a dedicated outline traversal that can distinguish skip / only-decl / only-children / decl-and-children behavior.
+- [ ] 1.2 Filter out function-local declarations, implicit entities, and implicit template instantiations while preserving namespace, type, enum, field, and member hierarchy.
+- [ ] 1.3 Implement explicit specialization and explicit instantiation behavior so written specializations can expose children and explicit instantiations remain leaf symbols.
+
+## 2. Macro And Range Handling
+
+- [ ] 2.1 Build macro invocation container nodes for declarations expanded from main-file macro calls.
+- [ ] 2.2 Add post-processing to stabilize sibling ordering and enforce `selectionRange`-within-`range` plus parent-range-contains-child-range invariants.
+- [ ] 2.3 Confirm whether the current protocol layer can carry deprecated document symbol metadata and either implement it here or record a follow-up.
+
+## 3. Validation
+
+- [ ] 3.1 Rewrite unit tests to assert symbol names, kinds, hierarchy, and range invariants instead of only total node counts.
+- [ ] 3.2 Add regression cases covering local declarations, explicit specialization/instantiation, and macro-expanded declarations.
+- [ ] 3.3 Extend integration coverage so the server request path exercises representative document symbol responses.

openspec/changes/improve-folding-range-support/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-03

openspec/changes/improve-folding-range-support/design.md

@@ -0,0 +1,199 @@
+## Context
+
+`clice` currently implements folding ranges in [`src/feature/folding_ranges.cpp`](/home/ykiko/C++/clice/src/feature/folding_ranges.cpp). The implementation is primarily an AST visitor with extra handling for conditional compilation and `#pragma region` data from `CompilationUnitRef::directives()`. It already covers many structural folds that clangd does not currently expose, such as namespaces, records, function parameter lists, lambda captures, call argument lists, access-specifier sections, and initializer lists.
+
+Compared with `.llvm/clang-tools-extra/clangd`, the current gap is clear:
+
+- clangd already has behavior that `clice` still lacks:
+  - multiline comment folding
+  - `lineFoldingOnly` client-capability handling
+  - a more complete and assertion-backed folding-range test matrix
+- `clice` already has behavior that clangd does not:
+  - richer AST-structure folding
+  - `#pragma region` and some conditional-compilation folding
+  - `collapsedText`
+- `clice` still has obvious opportunities that are not fully implemented yet:
+  - fully closing the last `#if/#elif/#else` branch at `#endif`
+  - folding inactive branches
+  - folding multiline macro definitions
+  - grouping contiguous `#include` / `import` blocks
+  - capability-aware `kind` and `collapsedText` rendering
+
+In addition, the current public output exposes many internal categories directly through `FoldingRange.kind`, such as `"namespace"`, `"class"`, and `"functionBody"`. This is more aggressive than clangd, but standard LSP only defines `comment`, `imports`, and `region` as interoperable folding kinds. The design therefore needs to preserve richer internal classification while presenting a compatible external contract.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Preserve `clice`'s current advantage in AST-structure folding instead of regressing to clangd's much narrower block-only baseline.
+- Fill the high-value baseline gaps that clangd already covers, especially multiline comments and `lineFoldingOnly`.
+- Turn preprocessor metadata into a differentiating `clice` capability covering conditional branches, macro definitions, and include/import grouping.
+- Make folding-range output respect client capabilities with predictable fallback behavior.
+- Lock behavior down with unit and integration tests across AST, comments, preprocessor handling, and protocol negotiation.
+
+**Non-Goals:**
+
+- Achieve byte-for-byte or range-for-range parity with clangd in this change.
+- Add fine-grained folding for every C++ syntax detail such as template parameter lists, requires-clauses, or attribute arguments before their value is proven.
+- Introduce editor-specific behavior that only exists to satisfy one frontend.
+- Add cross-file or index-backed folding behavior.
+
+## Decisions
+
+### 1. Split the folding-range pipeline into collection, normalization, and rendering
+
+The current implementation mixes "how a range is discovered" with "how it is emitted as LSP". The new design separates this into three layers:
+
+- collection: produce internal `RawFoldingRange` entries from AST, comment scanning, and preprocessor metadata
+- normalization: sort, deduplicate, validate, and reconcile nested or overlapping ranges
+- rendering: decide line/column boundaries, `kind`, and `collapsedText` based on client capabilities
+
+Why:
+
+- `lineFoldingOnly`, `collapsedText`, and standards-compatible kind downgrading are rendering concerns and should not pollute collection logic
+- comments, macros, and include/import groups do not naturally belong inside the AST visitor
+- future range limiting or prioritization should also live in normalization/rendering instead of collector code
+
+Alternative considered:
+
+- Keep generating final LSP ranges directly inside the visitor. Rejected because capability negotiation and multi-source collection will keep making the function larger and harder to test.
+
+### 2. Keep rich internal categories, but only promise standard-compatible public kinds
+
+Internally, the implementation may still distinguish namespace, class, function body, macro definition, conditional branch, and similar categories so tests, prioritization, and `collapsedText` selection remain precise. However, public LSP output should default to standard kinds only:
+
+- comment folds -> `comment`
+- contiguous include/import groups -> `imports`
+- all other structural and preprocessor folds -> `region`
+
+If some client later proves it needs clice-specific kinds, that can be evaluated separately. This change does not make non-standard kind strings part of the compatibility contract.
+
+Why:
+
+- many current custom strings will not be understood by clients and do not produce stable UI semantics
+- the real differentiator is what `clice` can fold, not the literal `kind` label
+- once public kinds are standardized, `collapsedText` and range boundaries become the primary user-visible expression
+
+Alternative considered:
+
+- Continue exposing all custom kinds directly. Rejected because that leaves client compatibility up to luck rather than protocol design.
+
+### 3. Implement comment folding through lexical/source scanning, not AST
+
+Multiline comments are handled independently in clangd's pseudo-parser path, and `clice` should do the same. The design adds a comment collector that scans the main-file source or token stream directly:
+
+- fold multiline `/* ... */` block comments
+- fold contiguous `//` comment groups
+- do not fold single-line comments
+- adjust closing boundaries for `lineFoldingOnly` mode so the final visible line is not swallowed incorrectly
+
+Why:
+
+- comments are not AST structure, so trying to derive them from AST produces fragile behavior
+- lexical scanning naturally handles adjacent-comment grouping and block-comment boundaries
+
+Alternative considered:
+
+- Only support block comments. Rejected because clangd already demonstrates that contiguous `//` comment groups are a useful folding case.
+
+### 4. Rework preprocessor folding around complete branch blocks instead of the current half-open stack
+
+Today `collect_condition_directives()` only closes the previous branch when it sees `#else`, but when it sees `#endif` it only pops the stack and does not emit a folding range for the final `#if/#elif/#else` branch. As a result, `#if` folding is incomplete.
+
+The new design treats conditional compilation as an explicit branch-group model:
+
+- maintain the ordered branch chain for each `#if` group
+- allow every branch to close at the next `#elif`, `#else`, or `#endif`
+- distinguish active and inactive branches
+- allow inactive branches to produce region folds, optionally with distinct `collapsedText`
+
+Why:
+
+- this is the minimum sound model needed to fix the current logical gap
+- `Condition::ConditionValue` already records true/false/skipped state and can drive inactive-branch folding directly
+
+Alternative considered:
+
+- Patch only the `#endif` closing case. Rejected because nested conditions, inactive branches, and range ordering would remain structurally weak.
+
+### 5. Add dedicated directive-based collectors for macros and include/import groups
+
+`clice` already collects:
+
+- `directive.macros`
+- `directive.includes`
+- `directive.imports`
+
+The new design therefore adds directive-based folding collectors for:
+
+- multiline `#define` macro definitions, using continuation backslashes or stable definition ranges
+- contiguous `#include` blocks, merged into a single `imports` folding range
+- contiguous `import Foo;` / `import Foo:Bar;` module-import blocks, also emitted as `imports`
+
+Why:
+
+- the necessary data already exists in preprocessing metadata and does not require new AST modeling
+- this is one of the easiest places for `clice` to provide value beyond clangd
+
+Alternative considered:
+
+- Leave include/import grouping for a later change. Rejected because the metadata already exists, the implementation cost is relatively low, and the editor-facing value is immediate.
+
+### 6. Folding-range output must be explicitly bound to client capabilities
+
+The master server currently only advertises `foldingRangeProvider = true`, but it does not read or propagate folding-specific client capabilities. The new design requires the session to track at least:
+
+- `lineFoldingOnly`
+- whether `collapsedText` is supported
+- optional `rangeLimit`
+
+Rendering rules:
+
+- when `lineFoldingOnly = true`, only emit ranges that remain meaningful as line-based folds, adjusting end lines where necessary
+- when the client does not support `collapsedText`, omit it
+- when a `rangeLimit` is declared, trim results deterministically rather than arbitrarily
+
+Alternative considered:
+
+- Continue always returning exact columns and `collapsedText`. Rejected because that relies on client tolerance instead of following the protocol contract.
+
+### 7. Organize tests by source category and protocol behavior
+
+Tests will be split into two dimensions:
+
+- source-category unit tests: AST structure, comments, conditional compilation, multiline macros, `#pragma region`, and include/import groups
+- protocol-behavior tests: `lineFoldingOnly`, `collapsedText` support, public kind mapping, and range limiting
+
+In particular, the current [`tests/unit/feature/folding_range_tests.cpp`](/home/ykiko/C++/clice/tests/unit/feature/folding_range_tests.cpp) contains `Directive` and `PragmaRegion` cases that do not actually assert results. This change upgrades them into strong assertion-based tests.
+
+Alternative considered:
+
+- Rely mostly on manual editor validation. Rejected because folding details regress easily, especially for preprocessor handling and line-only rendering.
+
+## Risks / Trade-offs
+
+- [Client capabilities must flow from initialize state into request-time rendering] -> Mitigation: introduce a dedicated folding-options structure so session details do not leak broadly into the feature layer.
+- [Inactive-branch and macro-definition ranges can be unstable around expansion locations] -> Mitigation: prefer spelling/main-file ranges and explicitly filter or special-case macro-expansion ranges when necessary.
+- [Adding comments, macros, and include/import groups can increase the number of ranges quickly] -> Mitigation: implement stable sorting and `rangeLimit` trimming in the normalization layer.
+- [Mapping public kinds back to standard values changes current metadata output] -> Mitigation: the folds themselves remain; the user-visible change is mostly in optional metadata, and tests plus change notes will make that explicit.
+- [Multiple collectors may produce overlapping or duplicate ranges] -> Mitigation: normalize by source category and boundary rules so collectors do not amplify noise.
+
+## Migration Plan
+
+1. Refactor the internal folding-range data flow and add render options plus standard kind mapping.
+2. Add the comment collector and assertion-backed tests for multiline comment folding.
+3. Rewrite conditional-directive and `#pragma region` collection so `#if` branches close correctly through `#endif`.
+4. Add multiline macro folding and grouped include/import collectors.
+5. Wire folding client capabilities through initialize/request handling and add integration coverage.
+6. Add `rangeLimit` trimming and regression cleanup after the new collectors are in place.
+
+Rollback strategy:
+
+- If protocol negotiation proves unstable, keep the new collectors but temporarily disable outward behavior changes tied to `collapsedText` or `rangeLimit`.
+- If a particular new fold category proves noisy, roll it back collector-by-collector instead of reverting the entire folding-range refactor.
+
+## Open Questions
+
+- Should multiline macro folding cover only the macro body, or the full `#define NAME(...)` line plus body as one fold region?
+- Should `rangeLimit` prioritize outer structure, top-of-file regions, or longer ranges when trimming results?
+- For structural AST folds originating from macro expansion, should `clice` preserve current behavior or restrict itself to cases with stable spelling ranges only?

openspec/changes/improve-folding-range-support/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+`clice`'s folding range support is already more aggressive than clangd's: it can fold namespaces, records, function parameter lists and bodies, lambda captures, call argument lists, access-specifier sections, and some preprocessor regions. However, it still lacks several useful baseline capabilities that clangd already has, especially multiline comment folding, client capability negotiation, and a stronger regression test matrix. Its preprocessor branch folding is also not yet fully closed.
+
+More importantly, `clice` already has preprocessor metadata that clangd does not fully exploit, such as `directive.macros`, `directive.includes`, `directive.imports`, and evaluated conditional-branch state. That means `clice` should not stop at matching clangd: folding ranges can become a feature that is more useful for real-world C/C++ editing by covering macro definitions, `#if` branches, and include/import groups that clangd does not currently handle well.
+
+## What Changes
+
+- Fill the remaining folding-range baseline gaps between `clice` and clangd, especially multiline comment folding and protocol-level client capability handling.
+- Complete preprocessor-related folding so full `#if/#elif/#else/#endif` branch regions, nested `#pragma region` blocks, and inactive branches have well-defined behavior.
+- Add folding features that take advantage of `clice`'s existing preprocessor metadata, including multiline macro definitions and grouped `#include` / `import` blocks.
+- Normalize `FoldingRange.kind` and `collapsedText` output so standard kinds remain compatible while clice-specific fold categories degrade predictably.
+- Make folding range responses honor client capabilities such as `lineFoldingOnly`, `collapsedText` support, and range limiting.
+- Expand unit and integration coverage for AST folds, comments, preprocessor regions, macros, include/import groups, and protocol negotiation behavior.
+
+## Capabilities
+
+### New Capabilities
+- `folding-ranges`: Provide LSP-compatible, C/C++-focused folding regions that cover AST structure, comments, preprocessor branches, macro definitions, and include/import groups.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- Primary impact is in `src/feature/folding_ranges.cpp`, the compile-unit/preprocessor metadata access paths, and folding range request handling plus capability negotiation around `src/server/master_server.cpp`.
+- Tests need expansion in `tests/unit/feature/folding_range_tests.cpp`, server/integration coverage, and any required fixtures for preprocessor and module scenarios.
+- User-visible behavior will be folding results that are closer to clangd where clangd already has coverage, while also adding high-value C/C++ folds that clangd does not currently provide well, especially macro-definition and conditional-compilation folding.

openspec/changes/improve-folding-range-support/specs/folding-ranges/spec.md

@@ -0,0 +1,61 @@
+## ADDED Requirements
+
+### Requirement: Folding range responses honor client capabilities
+The server SHALL render folding ranges according to the client's declared folding capabilities instead of always returning the richest possible payload.
+
+#### Scenario: Line-only folding is respected
+- **WHEN** the client declares `textDocument.foldingRange.lineFoldingOnly = true`
+- **THEN** the server MUST return folding ranges that remain valid when interpreted as whole-line folds, including adjusting end boundaries for bracketed or comment ranges whose closing delimiter is on the last line
+
+#### Scenario: Collapsed text is gated by client support
+- **WHEN** the client does not declare support for `textDocument.foldingRange.foldingRange.collapsedText`
+- **THEN** the server MUST omit `collapsedText` from the folding range response
+
+#### Scenario: Standard kinds are emitted compatibly
+- **WHEN** a folding range represents a comment block, an include/import block, or any other foldable region
+- **THEN** the server MUST emit `kind = comment`, `kind = imports`, or `kind = region` respectively, and MUST NOT require clients to understand clice-specific kind strings in order to fold correctly
+
+### Requirement: Structural and comment folding baseline
+The server SHALL provide folding ranges for multi-line C/C++ structural regions and multi-line comments in the main file.
+
+#### Scenario: Multi-line comment blocks can be folded
+- **WHEN** a document contains a multi-line `/* ... */` comment or a contiguous block of `//` comments spanning more than one line
+- **THEN** the server MUST return a folding range for that comment block with `kind = comment`
+
+#### Scenario: Single-line comments are not folded
+- **WHEN** a document contains a single-line comment that does not extend across multiple lines and is not part of a larger contiguous comment block
+- **THEN** the server MUST NOT return a folding range for that comment
+
+#### Scenario: Existing structural regions remain foldable
+- **WHEN** a document contains a multi-line namespace, record, function body, parameter list, lambda body, initializer list, or other supported structural region already collected by clice
+- **THEN** the server MUST continue to return a folding range for that region if its boundaries can be mapped back to the main file
+
+### Requirement: Preprocessor regions fold as complete branch blocks
+The server SHALL provide complete and nested folding ranges for preprocessor branch structures instead of leaving the final branch in a conditional block unclosed.
+
+#### Scenario: Final conditional branch closes at endif
+- **WHEN** a document contains a `#if/#elif/#else/#endif` chain
+- **THEN** the server MUST generate a folding range for each multi-line branch body, including the last branch body that ends at `#endif`
+
+#### Scenario: Inactive conditional branches can be folded
+- **WHEN** a conditional branch is known to be inactive or skipped in the current preprocessing configuration
+- **THEN** the server MUST be able to return a folding range covering that inactive branch region using `kind = region`
+
+#### Scenario: Nested pragma regions are folded
+- **WHEN** a document contains nested `#pragma region` / `#pragma endregion` pairs in the main file
+- **THEN** the server MUST return properly nested folding ranges for each matched region pair
+
+### Requirement: C/C++ directive groups and multiline macros are foldable
+The server SHALL use clice's preprocessor metadata to expose foldable ranges that clangd does not currently provide.
+
+#### Scenario: Multi-line macro definitions can be folded
+- **WHEN** a document contains a multi-line macro definition whose body spans more than one physical line
+- **THEN** the server MUST return a folding range for that macro definition using `kind = region`
+
+#### Scenario: Consecutive include directives are grouped
+- **WHEN** a document contains a contiguous block of `#include` directives with no intervening non-trivia code lines
+- **THEN** the server MUST return a folding range covering that include block using `kind = imports`
+
+#### Scenario: Consecutive module imports are grouped
+- **WHEN** a document contains a contiguous block of C++ module `import` declarations with no intervening non-trivia code lines
+- **THEN** the server MUST return a folding range covering that import block using `kind = imports`

openspec/changes/improve-folding-range-support/tasks.md

@@ -0,0 +1,29 @@
+## 1. Folding Range Pipeline
+
+- [ ] 1.1 Refactor `src/feature/folding_ranges.cpp` so collection, normalization, and LSP rendering are separated by an internal raw-range model.
+- [ ] 1.2 Add folding render options for `lineFoldingOnly`, `collapsedText` support, and optional `rangeLimit`, and thread them through the folding request path.
+- [ ] 1.3 Replace direct exposure of clice-specific public folding kinds with a stable mapping to standard LSP `comment` / `imports` / `region` kinds.
+
+## 2. Comment and Structural Baseline
+
+- [ ] 2.1 Add a comment collector that folds multi-line block comments and contiguous multi-line `//` comment groups in the main file.
+- [ ] 2.2 Preserve existing AST structural folding behavior while routing it through the new normalization/rendering pipeline.
+- [ ] 2.3 Add focused unit tests for comment folding, single-line comment exclusion, and structural folding regressions.
+
+## 3. Preprocessor Folding
+
+- [ ] 3.1 Rework conditional-directive collection so each `#if/#elif/#else/#endif` branch body closes correctly, including the final branch ending at `#endif`.
+- [ ] 3.2 Add folding support for inactive conditional branches using the existing preprocessor condition metadata.
+- [ ] 3.3 Strengthen `#pragma region` handling and add assertion-based tests for nested region folding.
+
+## 4. Clice-Specific Folding Extensions
+
+- [ ] 4.1 Add folding ranges for multi-line macro definitions using `directive.macros` and stable main-file source ranges.
+- [ ] 4.2 Add grouping folds for contiguous `#include` blocks and return them as `imports` ranges.
+- [ ] 4.3 Add grouping folds for contiguous C++ module `import` declarations and cover mixed include/import layouts with tests.
+
+## 5. Protocol and Validation
+
+- [ ] 5.1 Capture client folding capabilities during initialize and use them when serving `textDocument/foldingRange`.
+- [ ] 5.2 Add integration coverage for `lineFoldingOnly`, `collapsedText` gating, and kind/output compatibility.
+- [ ] 5.3 Run the relevant folding-range unit and integration tests, then fix any ordering, deduplication, or boundary regressions found during verification.

openspec/changes/improve-semantic-tokens-and-module-highlighting/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-03

openspec/changes/improve-semantic-tokens-and-module-highlighting/design.md

@@ -0,0 +1,141 @@
+## Context
+
+`clice` already exposes `textDocument/semanticTokens/full` and advertises a legend derived from `SymbolKind` and `SymbolModifiers`, but the implementation in `src/feature/semantic_tokens.cpp` only emits:
+
+- lexical tokens such as comments, strings, numbers, directives, headers, and keywords
+- declaration/definition markers for named declarations and macros
+- a template marker for templated declarations
+
+This leaves most of the declared semantic surface unused. In particular, `SymbolKind::Module`, `Attribute`, `Operator`, `Paren`, `Bracket`, `Brace`, `Angle`, `Concept`, and several declaration kinds/modifiers are either never emitted or emitted only indirectly. The current merge logic also degrades overlapping classifications to `Conflict`, which throws away useful semantic information instead of preferring the more specific token.
+
+The gap is visible when compared with clangd: clangd classifies more AST constructs, supports semantic token delta responses with `resultId`, and refreshes tokens when a more accurate AST becomes available. `clice` also already contains C++20 module infrastructure, `directive.imports`, `CompilationUnitRef::module_name()`, and a reserved `handleModuleOccurrence()` hook, so module-aware semantic tokens fit the current architecture rather than requiring a new subsystem.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Emit materially richer semantic token kinds and modifiers from AST information instead of relying mostly on lexical fallback.
+- Highlight C++20 module declarations and imports, including named modules and partitions.
+- Replace `Conflict`-style overlap handling with deterministic precedence so semantic meaning is preserved.
+- Support semantic token `resultId` and `/full/delta` responses, with cache invalidation and refresh when rebuilds change highlighting.
+- Add tests that lock in token kinds, modifiers, and module-specific behavior.
+
+**Non-Goals:**
+
+- Achieve byte-for-byte parity with clangd's full highlighting matrix in a single change.
+- Add `textDocument/semanticTokens/range`.
+- Add end-user configuration for disabling token kinds/modifiers in this change.
+- Redesign the broader `SymbolKind` taxonomy used by completion, hover, or indexing.
+
+## Decisions
+
+### 1. Keep the existing two-phase model, but turn semantic tokens into an overlay with precedence
+
+The collector will continue to start with a lexical pass so comments, literals, directives, and headers remain available even before AST-specific enrichment. Semantic passes will then add higher-priority tokens for declarations, operators, attributes, concepts, brackets, and modules.
+
+Instead of collapsing equal-range overlaps to `Conflict`, the merge step will apply explicit precedence:
+
+- semantic classification beats lexical classification
+- more specific semantic kinds beat generic ones
+- modifiers are merged when the underlying symbol identity is compatible
+- `Conflict` remains only as a last-resort debugging state, not the normal output
+
+Why this approach:
+
+- it preserves the current fast lexical baseline
+- it minimizes churn in call sites
+- it matches how editors expect semantic tokens to augment syntax coloring rather than erase it
+
+Alternative considered:
+
+- emit semantic tokens from AST only and drop lexical fallback entirely. Rejected because it would lose highlighting for comments/directives/headers and make partially-built AST states visibly worse.
+
+### 2. Use existing compile-layer module metadata for module token extraction
+
+Module highlighting will use data already available in `CompilationUnitRef` and compile directives:
+
+- `CompilationUnitRef::module_name()` and `is_module_interface_unit()` for the current unit
+- `directives().imports` for imported module names
+- `TokenBuffer` / spelled token APIs for mapping module names and separators to source ranges
+
+This is preferred over trying to rely only on `VisitImportDecl` because the repository already captures import metadata during preprocessing, and the current `SemanticVisitor` module hooks are intentionally incomplete. The design can still route final token creation through `handleModuleOccurrence()`, but the source of truth for locating module-name tokens should be the compile-layer token data.
+
+Alternative considered:
+
+- finish the commented-out `SemanticVisitor::VisitImportDecl` path first and derive all module tokens from AST traversal. Rejected for now because preprocessing already records import structure reliably, while AST-only extraction is more fragile around partitions and special module forms.
+
+### 3. Fill the most valuable semantic gaps first
+
+The implementation should prioritize the categories that are already modeled in `SymbolKind`/`SymbolModifiers` and easy to validate in tests:
+
+- declaration kinds already discoverable from `NamedDecl`
+- module names and partitions
+- attributes such as `final` / `override` and explicit attribute syntax
+- overloaded and built-in operators
+- bracket-like punctuation tied to templates and explicit operators/casts
+- modifiers such as `Const`, `Overloaded`, and `Typed` where the current AST plumbing can support them without ambiguity
+
+Why this scope:
+
+- it closes the largest visible gap quickly
+- it avoids inventing new token kinds before the existing taxonomy is exercised
+- it keeps the change aligned with the user's clangd comparison request
+
+Alternative considered:
+
+- introduce new token kinds/modifiers to mirror clangd more directly. Rejected because `clice` already has an internal taxonomy and the first priority is to use it consistently.
+
+### 4. Add delta responses in the server layer, not inside feature collection
+
+`feature::semantic_tokens()` should continue returning a full logical token stream for one snapshot of a document. Delta computation, `resultId` assignment, and cache management belong in the server/request layer because they depend on per-document history rather than AST semantics.
+
+Expected server changes:
+
+- advertise `semanticTokensProvider.full.delta = true`
+- accept `textDocument/semanticTokens/full/delta`
+- cache the last encoded token stream per document
+- invalidate the cache on close, rebuild, and version changes that replace the document snapshot
+- send `workspace/semanticTokens/refresh` when the server has moved from a stale/partial semantic view to a fresh compiled view and the client supports refresh
+
+Alternative considered:
+
+- compute deltas in the feature layer on raw tokens. Rejected because delta state must be keyed by document lifecycle and LSP request history, which the feature layer does not own.
+
+### 5. Treat tests as the contract for token stability
+
+This change will expand test coverage instead of relying on manual editor inspection alone:
+
+- unit tests for token kinds/modifiers in small annotated snippets
+- unit tests for merge precedence and multiline encoding invariants
+- integration tests for full-token and delta requests
+- module fixture tests covering named modules, partitions, global module fragments, private fragments, and importers
+
+Alternative considered:
+
+- validate only through smoke tests in an editor. Rejected because token regressions are subtle and easy to reintroduce without precise assertions.
+
+## Risks / Trade-offs
+
+- [Token overlap rules become too ad hoc] → Define a small explicit precedence table and test it directly instead of scattering special cases through the merge code.
+- [Template angle brackets and parser-token splitting differ from `TokenBuffer` behavior] → Scope bracket highlighting to ranges that can be proven from spelled tokens and add regression tests for nested templates.
+- [Module syntax has corner cases such as global module fragments, private fragments, and partitions] → Require stable highlighting only for named module/import identifiers and avoid inventing semantics for punctuation that cannot be located robustly.
+- [Delta cache becomes stale after recompilation or close/reopen cycles] → Tie cache lifetime to document URI/version and clear it on close, invalidation, and failed rebuilds.
+- [More semantic passes increase feature latency] → Keep lexical scanning unchanged, reuse existing AST traversal hooks, and benchmark only if tests show material slowdown.
+
+## Migration Plan
+
+1. Extend token collection and merge rules while preserving the current full-token API.
+2. Add module-aware token extraction and expand unit tests.
+3. Wire server-side delta support and refresh/invalidation behavior.
+4. Update integration tests to cover both full and delta semantic token requests.
+
+Rollback strategy:
+
+- disable delta advertisement and continue serving full tokens if cache invalidation proves unstable
+- keep lexical fallback so the editor still receives usable highlighting even if some semantic categories are temporarily rolled back
+
+## Open Questions
+
+- Whether `Const`, `Typed`, and `Overloaded` should be emitted only when derived with high confidence, or whether some heuristic cases are acceptable.
+- Whether refresh notifications should be sent only after successful recompilation or also after dependency-driven module invalidation.
+- Whether bracket/operator highlighting should be limited to the kinds already modeled in `SymbolKind`, or whether a follow-up change should align names more closely with standard LSP token vocabularies.

openspec/changes/improve-semantic-tokens-and-module-highlighting/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+`clice` already advertises semantic tokens, but the current implementation only covers a narrow subset of the available `SymbolKind` and modifier space. Compared with clangd, it is missing several high-value semantic classifications, has no protocol support for semantic token deltas or refresh, and leaves C++20 module names unhighlighted even though the semantic visitor already reserves hooks for them.
+
+Improving this now will make highlighting materially more accurate in real C++ code, reduce the visible gap with clangd, and let `clice`'s existing C++20 module pipeline surface richer editor feedback instead of treating modules as plain identifiers.
+
+## What Changes
+
+- Expand semantic token collection beyond lexical tokens and basic declaration/reference handling so `clice` can emit more of its declared `SymbolKind` and modifier set.
+- Add AST-driven classification for operators, bracket-like punctuation, attributes, concepts, and other symbols that currently fall back to plain lexical highlighting or are omitted entirely.
+- Implement semantic highlighting for C++20 module declarations and imports, including named modules and partitions.
+- Improve token conflict resolution so overlapping lexical and semantic classifications prefer the most specific semantic meaning instead of collapsing to `Conflict`.
+- Add server-side support for semantic token result IDs and delta updates, with refresh support wired where document recompilation changes highlighting.
+- Strengthen unit and integration coverage for semantic tokens, especially module-specific fixtures and multi-token semantic cases.
+
+## Capabilities
+
+### New Capabilities
+- `semantic-tokens`: Provide richer semantic token classification for C++ code, including AST-derived symbol kinds, modifiers, incremental token delivery, and C++20 module-aware highlighting.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- Affected code: `src/feature/semantic_tokens.cpp`, `src/semantic/semantic_visitor.h`, semantic token request handling in the server, and semantic token protocol wiring.
+- Affected tests: `tests/unit/feature/semantic_tokens_tests.cpp`, server integration tests, and module fixtures under `tests/data/modules/`.
+- User-visible behavior: editors will receive more accurate semantic token kinds/modifiers and module-aware highlighting without requiring API-breaking changes.

openspec/changes/improve-semantic-tokens-and-module-highlighting/specs/semantic-tokens/spec.md

@@ -0,0 +1,50 @@
+## ADDED Requirements
+
+### Requirement: Rich semantic token classification
+The server SHALL classify semantic tokens using AST-derived symbol kinds and modifiers when that information is available, instead of limiting output to lexical token classes and basic declaration markers.
+
+#### Scenario: Declaration kinds use semantic classification
+- **WHEN** a document contains declarations and references for namespaces, records, enums, functions, methods, fields, variables, parameters, labels, concepts, or macros
+- **THEN** the semantic token response MUST encode those occurrences with the corresponding `SymbolKind` rather than a generic lexical fallback
+
+#### Scenario: Semantic modifiers are preserved
+- **WHEN** a token represents a declaration, definition, template-related symbol, const-qualified symbol, overloaded symbol, or typed punctuation that `clice` can determine from the AST
+- **THEN** the semantic token response MUST include the corresponding `SymbolModifiers` bits for that token
+
+#### Scenario: Semantic meaning wins over lexical overlap
+- **WHEN** lexical and semantic passes produce overlapping classifications for the same source token
+- **THEN** the server MUST prefer the most specific semantic classification and MUST NOT degrade the final response to `Conflict` for normal supported cases
+
+### Requirement: C++20 module-aware semantic highlighting
+The server SHALL emit semantic tokens for C++20 module declarations and imports so module names and partitions are distinguishable from ordinary identifiers.
+
+#### Scenario: Named module declaration is highlighted
+- **WHEN** a module interface or implementation unit contains a named module declaration such as `export module Foo;` or `module Foo;`
+- **THEN** the `module` keyword MUST be highlighted as a keyword and the module-name tokens MUST be highlighted with `SymbolKind::Module`
+
+#### Scenario: Module import is highlighted
+- **WHEN** a translation unit imports a named module or partition such as `import Foo;` or `import Foo:Bar;`
+- **THEN** the `import` keyword MUST be highlighted as a keyword and the imported module-name tokens MUST be highlighted with `SymbolKind::Module`
+
+#### Scenario: Non-module fragments do not invent module-name tokens
+- **WHEN** a file contains module-related fragment syntax such as `module;` or `module :private;`
+- **THEN** the server MUST highlight the language keywords normally and MUST only emit `SymbolKind::Module` tokens for the actual named module identifiers that exist in source
+
+### Requirement: Semantic token incremental delivery
+The server SHALL support stable semantic token result IDs and delta responses for documents whose previous semantic token result is known.
+
+#### Scenario: Full request returns a result identifier
+- **WHEN** a client sends `textDocument/semanticTokens/full`
+- **THEN** the response MUST include the full semantic token data for the current document snapshot and a `resultId` that can be used for a later delta request
+
+#### Scenario: Delta request returns edits when previous result matches
+- **WHEN** a client sends `textDocument/semanticTokens/full/delta` with the latest known `resultId` for a document
+- **THEN** the server MUST return semantic token edits relative to that previous result instead of forcing a full token payload
+
+#### Scenario: Delta request falls back to full tokens when history is unavailable
+- **WHEN** a client sends `textDocument/semanticTokens/full/delta` with an unknown or stale `resultId`
+- **THEN** the server MUST return a full semantic token result for the current document snapshot
+
+#### Scenario: Rebuild-driven semantic changes trigger refresh
+- **WHEN** recompilation, dependency invalidation, or module rebuild changes the semantic token output for an open document and the client supports semantic token refresh
+- **THEN** the server MUST request a semantic token refresh so the client can fetch updated tokens

openspec/changes/improve-semantic-tokens-and-module-highlighting/tasks.md

@@ -0,0 +1,23 @@
+## 1. Semantic Token Collection
+
+- [ ] 1.1 Audit `src/feature/semantic_tokens.cpp` against `SymbolKind` and `SymbolModifiers`, and add collection paths for the high-value AST-derived kinds/modifiers covered by the spec.
+- [ ] 1.2 Replace equal-range `Conflict` collapsing with explicit token precedence and modifier-merging rules, and add focused unit tests for overlap behavior.
+- [ ] 1.3 Extend token encoding tests to cover newly emitted semantic kinds/modifiers without regressing multiline and UTF-8/UTF-16 behavior.
+
+## 2. C++20 Module Highlighting
+
+- [ ] 2.1 Implement module-name token extraction for named module declarations using existing `CompilationUnitRef`, directive, and token-buffer APIs.
+- [ ] 2.2 Implement module-name token extraction for `import` statements, including partition forms such as `Foo:Bar`.
+- [ ] 2.3 Add regression tests for named modules, imports, global module fragments, private fragments, and dotted/partitioned module fixtures.
+
+## 3. LSP Semantic Token Delivery
+
+- [ ] 3.1 Extend server capability advertisement and request routing to support `textDocument/semanticTokens/full/delta`.
+- [ ] 3.2 Add per-document semantic token caching with stable `resultId` handling and full-result fallback for stale delta requests.
+- [ ] 3.3 Invalidate semantic token caches on document lifecycle changes and trigger semantic token refresh when recompilation changes highlighting for open documents.
+
+## 4. Validation
+
+- [ ] 4.1 Add or expand unit tests for operators, attributes, concepts, bracket-like tokens, and semantic modifiers that are newly emitted.
+- [ ] 4.2 Add integration coverage for semantic token full and delta requests in the server test suite.
+- [ ] 4.3 Run the relevant semantic token and module test targets, then fix any fixture or behavior mismatches discovered during verification.

openspec/changes/improve-signature-help-parity-with-clangd/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-03

openspec/changes/improve-signature-help-parity-with-clangd/design.md

@@ -0,0 +1,115 @@
+## Context
+
+`clice` currently implements signature help in `src/feature/signature_help.cpp` by subclassing `clang::CodeCompleteConsumer`, iterating overload candidates, and manually rendering labels for a handful of candidate kinds. That gives a usable baseline, but it leaves several visible gaps compared with clangd:
+
+- the collector always picks `active_signature = 0` and largely forwards `current_arg` directly, without clangd-style remapping for variadics or other candidate-specific parameter lists
+- signature labels are assembled manually rather than from Clang's `CodeCompletionString`, so optional parameters, documentation chunks, and rendered parameter metadata are less faithful
+- the server advertises a bare `SignatureHelpOptions{}` rather than clangd-like trigger and retrigger characters
+- the request path does not thread signature-help-specific client capabilities or context into feature generation
+- tests only verify a minimal overload case and non-crash request flow, while clangd covers overload ordering, function pointers, constructors, aggregates, nested expressions, variadics, templates, stale preambles, and prerequisite modules
+
+clangd's implementation is a good reference because it solves these problems without inventing a separate subsystem: it still uses overload candidates, but builds signatures from `CodeCompletionString`, maps active arguments to rendered parameters, negotiates documentation format and offset support, and validates the behavior with broad regression coverage.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Align `clice`'s user-visible signature help behavior with clangd for the major C++ call forms that users hit in practice.
+- Advertise and honor signature-help protocol details that affect editor behavior, especially trigger characters, documentation format, and parameter label offsets.
+- Make active-parameter selection robust for variadic, defaulted, templated, constructor, aggregate, and function-pointer signatures.
+- Add test coverage strong enough to prevent the current behavior gap from reopening.
+
+**Non-Goals:**
+
+- Achieve byte-for-byte parity with every clangd-only extension or internal API.
+- Redesign completion, scheduling, or the broader server architecture outside what signature help needs.
+- Introduce unrelated LSP features such as snippet completion changes or semantic-token work in this change.
+
+## Decisions
+
+### 1. Keep the overload-candidate pipeline, but switch rendering to `CodeCompletionString`
+
+`clice` should keep using `clang::CodeCompleteConsumer` and `ProcessOverloadCandidates()`, but the collector should stop hand-formatting signatures for each candidate kind wherever Clang already provides a `CodeCompletionString`. This matches clangd's approach and brings several benefits at once:
+
+- rendered labels stay closer to Clang's own completion view
+- placeholder and optional chunks can drive parameter extraction directly
+- signature and parameter documentation become available without bespoke formatting logic
+
+Alternative considered:
+
+- keep the current manual `switch(candidate.getKind())` rendering and patch missing cases individually. Rejected because it duplicates logic clangd already solved and makes edge cases like optional parameters and documentation much harder to maintain.
+
+### 2. Treat active parameter as a negotiated LSP field backed by candidate-aware remapping
+
+The top-level `SignatureHelp.activeParameter` should remain the primary LSP signal, but `clice` should remap the current argument index against the rendered parameter list for the active candidate instead of forwarding `current_arg` blindly. In particular:
+
+- variadic calls should clamp to the final variadic parameter
+- constructor and aggregate initializers should map to the field or constructor slot actually being edited
+- function-pointer and template cases should use the rendered parameter list rather than raw AST counts when they differ
+
+Alternative considered:
+
+- add per-signature active-parameter support first. Rejected for now because clangd does not rely on it either, and the highest-value fix is correct top-level `activeParameter` behavior.
+
+### 3. Thread signature-help capabilities and context through the server and worker boundary
+
+The feature layer needs more than just file path and offset. This change should carry enough request metadata to shape the output:
+
+- requested documentation format
+- whether parameter label offsets are supported
+- any signature-help request context needed for retrigger behavior or follow-up refinements
+
+This keeps protocol negotiation in the server layer while allowing feature code to decide which fields to populate.
+
+Alternative considered:
+
+- hardcode plain-text output and always return offset labels regardless of client support. Rejected because clangd already demonstrates that clients negotiate these details, and ignoring them makes interoperability less predictable.
+
+### 4. Advertise clangd-like trigger coverage, but only promise behavior that `clice` can validate
+
+The server should advertise trigger and retrigger characters for the call and initializer delimiters that matter in C++ editing: `(`, `)`, `{`, `}`, `<`, `>`, and `,`. This is close to clangd and matches the call forms already exercised by clangd's tests.
+
+The implementation should still avoid overpromising beyond validated behavior. If a trigger reaches an unsupported syntactic corner case, the request may still return no signatures, but the advertised surface should cover the common forms users expect in editors.
+
+Alternative considered:
+
+- advertise only `(` and `,`. Rejected because it would keep `clice` visibly behind clangd for constructors, aggregates, and template-argument contexts.
+
+### 5. Use clangd's existing tests as the baseline for `clice` regression coverage
+
+This change should not invent a new test matrix from scratch. Instead, it should translate the highest-value clangd signature-help cases into `clice`'s unit, worker, integration, and module test suites:
+
+- overloads and ordering
+- default and optional arguments
+- active argument detection inside nested expressions
+- constructors, aggregates, and function pointers
+- variadics and template arguments
+- imported declarations and prerequisite module builds
+
+Alternative considered:
+
+- rely on manual editor checks and the current smoke tests. Rejected because most of the gap is in edge cases that regress silently without precise assertions.
+
+## Risks / Trade-offs
+
+- [Eventide LSP bindings do not expose all signature-help capability fields] -> Extend the local protocol surface or add thin adapter fields in `clice`'s request path, then lock that behavior down with serialization tests.
+- [Switching to `CodeCompletionString` changes overload ordering or rendered labels unexpectedly] -> Keep ordering rules explicit and update tests to assert the intended contract rather than incidental string formatting.
+- [Documentation lookup adds latency or becomes stale] -> Prefer AST docs when immediately available, use bounded index fallback where it materially improves output, and keep empty-documentation paths cheap.
+- [Module and imported-declaration cases depend on prerequisite build state] -> Reuse the existing module test infrastructure and make module-specific coverage part of the acceptance criteria instead of an optional follow-up.
+
+## Migration Plan
+
+1. Extend protocol and options plumbing so signature-help requests can carry client capability details and the server can advertise trigger coverage.
+2. Refactor the collector to use richer completion-string data, fix active-parameter mapping, and add documentation support.
+3. Add clangd-inspired unit, worker, integration, and module tests until the intended behavior is covered end to end.
+
+Rollback strategy:
+
+- revert to the previous manual rendering path while keeping the safer request plumbing if the richer collector proves unstable
+- reduce advertised trigger coverage temporarily if a specific delimiter family produces repeated false positives
+
+## Open Questions
+
+- Whether the current eventide protocol types already carry enough signature-help context, or whether `clice` needs to extend its local wrappers.
+- Whether parameter-level documentation is worth populating in this change, or whether signature-level documentation is sufficient for parity.
+- Whether `clice` should exactly mirror clangd's trigger set or trim it slightly if one delimiter family remains under-tested after implementation.

openspec/changes/improve-signature-help-parity-with-clangd/proposal.md

@@ -0,0 +1,24 @@
+## Why
+
+`clice` already returns basic signature help, but compared with clangd it mostly exposes raw overload candidates and misses several behaviors that make signature help reliable in real code: protocol trigger coverage, documentation, robust active-parameter mapping, and regression-tested handling for constructors, aggregates, variadics, templates, and imported declarations. Closing this gap now will make call-site assistance materially more useful and establish a spec-backed contract for one of `clice`'s core interactive features.
+
+## What Changes
+
+- Audit `clice`'s current signature help implementation against clangd and close the highest-value gaps that affect LSP-visible behavior.
+- Improve signature construction so parameter labels, optional/defaulted arguments, variadics, templates, constructors, aggregates, and function-pointer calls are rendered consistently and the active parameter is chosen correctly.
+- Extend the server and request path to advertise and honor signature-help protocol details such as trigger/retrigger characters, documentation format, and parameter label offsets where supported by the client and protocol layer.
+- Add coverage for imported or module-provided declarations and other clangd-tested edge cases so signature help stays stable as the compiler pipeline evolves.
+
+## Capabilities
+
+### New Capabilities
+- `signature-help`: Provide clangd-aligned signature help behavior for callable expressions, including robust active-parameter tracking, richer signature metadata, protocol negotiation, and regression-tested edge-case coverage.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- Affected code: `src/feature/signature_help.cpp`, `src/feature/feature.h`, `src/server/master_server.cpp`, `src/server/stateless_worker.cpp`, `src/server/protocol.h`, and any eventide protocol bindings touched by signature-help capability negotiation.
+- Affected tests: `tests/unit/feature/signature_help_tests.cpp`, `tests/unit/server/stateless_worker_tests.cpp`, `tests/integration/test_server.py`, and new fixtures inspired by `.llvm/clang-tools-extra/clangd/unittests/CodeCompleteTests.cpp`.
+- User-visible behavior: editors should receive more complete and predictable signature help, especially while typing nested calls, constructor or aggregate initializers, variadic calls, and declarations coming from imported modules or prerequisite module builds.

openspec/changes/improve-signature-help-parity-with-clangd/specs/signature-help/spec.md

@@ -0,0 +1,52 @@
+## ADDED Requirements
+
+### Requirement: Server advertises signature help trigger coverage
+The server SHALL advertise a signature help provider that includes the trigger and retrigger characters needed to keep signature help updated while the user edits callable and initializer argument lists.
+
+#### Scenario: Initialize returns signature help triggers
+- **WHEN** a client initializes against the server
+- **THEN** the advertised `signatureHelpProvider` includes trigger support for `(`, `)`, `{`, `}`, `<`, `>`, and `,`
+
+### Requirement: Signature help returns overload sets and the active parameter
+The server SHALL return all applicable signature candidates for the callable at the cursor and SHALL report the active signature and active parameter for the call being edited.
+
+#### Scenario: Overloaded function call
+- **WHEN** the cursor is inside a call to an overloaded function
+- **THEN** the result contains each viable overload signature
+- **THEN** the result identifies the active parameter for the preferred signature
+
+### Requirement: Signature help maps arguments to rendered parameters across C++ call forms
+The server SHALL remap the current argument index to the correct rendered parameter for variadic, defaulted, templated, constructor, aggregate, and function-pointer signatures instead of exposing raw argument indices when they exceed or differ from the displayed parameter list.
+
+#### Scenario: Variadic call stays on the variadic parameter
+- **WHEN** the user types beyond the fixed parameters of a variadic callable
+- **THEN** the reported active parameter remains the final variadic parameter instead of advancing past the signature
+
+#### Scenario: Constructor or aggregate initializer
+- **WHEN** the cursor is inside a constructor call or aggregate braced initializer
+- **THEN** the result describes the constructor or aggregate fields being initialized
+- **THEN** the reported active parameter matches the current initializer slot
+
+### Requirement: Signature help returns stable parameter metadata and documentation
+The server SHALL return parameter label metadata aligned with the rendered signature label, and SHALL include signature documentation in the format negotiated with the client when documentation is available from AST comments or indexed symbols.
+
+#### Scenario: Client supports label offsets and markdown documentation
+- **WHEN** the client declares parameter label offset support and markdown signature documentation
+- **THEN** returned signatures include offset-based parameter labels
+- **THEN** returned signatures include markdown-formatted documentation when documentation is available
+
+#### Scenario: Callable without documentation
+- **WHEN** a callable has no available documentation
+- **THEN** the server still returns the signature label and parameter metadata without failing the request
+
+### Requirement: Signature help works for imported declarations and nested expressions
+The server SHALL provide signature help for call sites that resolve through imported or prerequisite-module declarations and for cursors nested inside expressions within argument lists.
+
+#### Scenario: Imported module declaration
+- **WHEN** the user requests signature help for a function imported from a prerequisite C++20 module
+- **THEN** the result includes the imported declaration's signature
+
+#### Scenario: Cursor inside nested argument expression
+- **WHEN** the cursor is inside an expression that itself appears in an argument position
+- **THEN** the server reports signature help for the innermost active call
+- **THEN** the reported active parameter matches that nested call site

openspec/changes/improve-signature-help-parity-with-clangd/tasks.md

@@ -0,0 +1,21 @@
+## 1. Protocol And Request Plumbing
+
+- [ ] 1.1 Extend signature-help capability advertisement and request plumbing to carry trigger or retrigger characters, documentation format, parameter label-offset support, and any required request context across the server and worker boundary.
+- [ ] 1.2 Expand `SignatureHelpOptions` and related protocol serialization tests so feature code can choose output shape based on negotiated client capabilities.
+
+## 2. Signature Collection Parity
+
+- [ ] 2.1 Refactor `src/feature/signature_help.cpp` to build labels and parameters from richer completion-string data instead of relying only on manual overload formatting.
+- [ ] 2.2 Add candidate-aware active-parameter mapping for variadic, defaulted, templated, constructor, aggregate, and function-pointer signatures, keeping overload ordering deterministic.
+- [ ] 2.3 Populate signature documentation and parameter metadata from AST comments and index or preamble lookups where available, without regressing empty-documentation cases.
+
+## 3. Edge Cases And Module Coverage
+
+- [ ] 3.1 Verify signature help for nested calls, opening delimiters, braced initializers, function pointers, and imported or module-provided declarations, fixing any parser or snapshot assumptions that block these cases.
+- [ ] 3.2 Add or update worker and server handling needed for stale compile state and prerequisite module builds so signature help remains available after document edits and module preparation.
+
+## 4. Validation
+
+- [ ] 4.1 Expand `tests/unit/feature/signature_help_tests.cpp` with clangd-inspired cases for overloads, active arguments, default arguments, variadics, templates, constructors, aggregates, and nested expressions.
+- [ ] 4.2 Add server and worker tests that assert capability advertisement and returned signature metadata instead of only checking for non-crash behavior.
+- [ ] 4.3 Run the relevant signature-help, stateless-worker, integration, and module test targets, then fix any regressions uncovered during verification.

openspec/config.yaml

@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours