Scope & Assumptions

Goal

Eliminate all lateral coupling violations between Layer 2 peer modules (tools, indexing, lsp, infrastructure). These modules should only depend downward to foundation layers (utils, types, configuration), never sideways to each other.

Non-goals:

• Major architectural changes beyond fixing the 3 identified violations
• Adding new features to affected tools
• Changing tool behavior (only dependency flow)

Scope & Assumptions

In scope:

• 3 lateral imports to eliminate:
  1. tools/glob.py:12 → indexing.CodeIndex
  2. tools/decorators.py:73 → lsp.{get_diagnostics, format_diagnostics}
  3. tools/lsp_status.py:5 → lsp.servers.get_server_command

Out of scope:

• Other Layer 2 modules (infrastructure)
• UI layer changes
• New test files (existing tests must pass)

Assumptions:

• PR #317 has merged (core→utils violations fixed)
• No new lateral violations added since research
• LSP and indexing modules remain stable during refactor

Deliverables (DoD)

1. Zero lateral imports between Layer 2 modules

   • grep -rn "from tunacode.indexing" src/tunacode/tools/ returns empty
   • grep -rn "from tunacode.lsp" src/tunacode/tools/ returns empty

2. All existing tests pass

   • uv run pytest exits 0

3. Type checking passes

   • uv run mypy src/tunacode/ no new errors

4. Architecture documentation updated

   • docs/architecture/NEW_layers.html reflects resolved state

Readiness (DoR)

• Research document complete
• Violations verified in current codebase
• PR #317 merged (prerequisite)
• Architecture diagram ready

Milestones

M1: Fix Violation 3 (lsp_status.py)

Effort: Low | Risk: Low

Move get_server_command() to configuration layer OR merge tools/lsp_status.py into core/lsp_status.py.

Recommended: Merge into core - eliminates unnecessary indirection.

M2: Fix Violation 2 (decorators.py → lsp)

Effort: Medium | Risk: Medium

Remove LSP orchestration from @file_tool decorator. Core should handle post-write diagnostics, not the decorator.

Recommended: Callback injection - decorator accepts optional on_write_callback, core injects LSP check.

M3: Fix Violation 1 (glob.py → indexing)

Effort: Medium-High | Risk: Medium

Two viable options:

• Option A: Protocol abstraction - define FileRegistry in types/, inject from core
• Option C: Remove indexing check entirely from glob (simplest)

Recommended: Option C - glob should not need to know about indexing state. The performance optimization can be handled at core level if needed.

M4: Validation & Documentation

Effort: Low | Risk: None

Run validation commands, update architecture docs, close issue.

Work Breakdown (Tasks)

Task Details

T1: Merge lsp_status into core

• Move get_lsp_status() logic from tools/lsp_status.py to core/lsp_status.py
• Delete tools/lsp_status.py
• Update any imports
• Acceptance: tools/lsp_status.py deleted, no tools→lsp import for status

T2: Remove LSP from decorators

• Add optional diagnostics_callback: Callable[[Path], str | None] = None to @file_tool
• Remove lazy import of tunacode.lsp in _get_lsp_diagnostics()
• Core injects the callback when registering tools
• Acceptance: grep "from tunacode.lsp" decorators.py returns empty

T3: Remove CodeIndex from glob

• Remove from tunacode.indexing import CodeIndex line
• Remove _get_code_index() function and _glob_with_index() optimization
• Keep only filesystem scan path
• Acceptance: grep "from tunacode.indexing" glob.py returns empty

T4: Validation

• Run lateral import checks
• Run uv run pytest
• Update NEW_layers.html to show 0 violations
• Close issue #314

Risks & Mitigations

Test Strategy

Existing tests must pass. No new tests required for this refactor since:

• We're simplifying, not adding features
• Tests already cover tool behavior
• Integration tests validate end-to-end

References

• Research: memory-bank/research/2026-01-27_13-11-55_issue-314-lateral-coupling-tools-indexing-lsp.md
• Issue: https://github.com/alchemiststudiosDOTai/tunacode/issues/314
• Architecture: docs/architecture/NEW_layers.html
• Prior PR #317: commit 076cbf3c

Tickets Created

Dependencies

tun-2ddf → tun-be3d → tun-5681 → tun-1012

Sequential execution - each task builds on the previous.