# Tech Debt Tracker

Known technical debt items with priority and ownership. Review this document on a regular cadence (suggested: bi-weekly).

## Priority Levels

- **P0**: Blocks new feature work or causes user-visible issues. Fix immediately.
- **P1**: Significant quality or maintainability impact. Fix within current cycle.
- **P2**: Moderate impact. Schedule for next cycle.
- **P3**: Minor impact. Track but tolerate. Fix opportunistically.

## Status Values

- **open**: identified, not yet started
- **in-progress**: actively being worked on (link to exec plan if applicable)
- **resolved**: fixed, awaiting verification or merged
- **wont-fix**: accepted as-is with documented rationale

---

## Debt Items

| ID     | Area          | Description                                                                                                               | Priority | Status      | Last Reviewed | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------ | ------------- | ------------------------------------------------------------------------------------------------------------------------- | -------- | ----------- | ------------- | -------------------------------------------------------------------------- |
| TD-001 | Documentation | Documentation sprawl: 600+ files in `docs/`, many stale or redundant. See `QUALITY_SCORE.md` Documentation domain.        | P1       | in-progress | 2026-02-16    | Added CI guardrails for top-level `docs/*.md` (`scripts/check_markdown_location.py` + `scripts/docs_top_level_allowlist.txt`) and entrypoint link integrity (`scripts/check_docs_links.py`). Consolidation/archival remains in-progress; docs count is 654 as of 2026-02-16.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| TD-002 | Codebase      | Duplicated logic across workspace crates. Common patterns reimplemented instead of shared via `vtcode-commons`.           | P2       | resolved    | 2026-05-15    | Ref: `vtcode-commons/` shared utilities are used across `src/` and `vtcode-core/`; verify: `rg -n 'vtcode_commons' src vtcode-core vtcode-commons -g '\*.rs' && rg -n 'vtcode-commons' src vtcode-core vtcode-commons -g '\*.rs'`. |
| TD-003 | Features      | Session log export feature incomplete. Users cannot export conversation history in a portable format.                     | P2       | resolved    | 2026-02-15    | `/share-log` now supports portable JSON and Markdown exports (`/share-log [json, markdown, md]`, alias `/export-log`) and writes timestamped files in workspace root. |
| TD-004 | Features      | Deprecated feature surfaces were removed from runtime/config/docs. Keep stale references out of future docs and examples. | P2       | resolved    | 2026-03-02    | Completed hard-removal cleanup across tooling, slash UX, config, and docs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| TD-005 | TUI           | Large event handler modules in `src/`. Some files likely exceed 500-line invariant. Hard for agents to navigate.          | P2       | in-progress | 2026-05-16    | Completed [EP-001](exec-plans/active/001-tui-runloop-decomposition.md) across the highest-risk slash-command roots and `src/agent/runloop/unified/turn/session/interaction_loop_runner.rs`, then followed with support splits for `src/agent/runloop/unified/turn/session_loop_runner/mod.rs`, `src/agent/runloop/unified/session_setup/ui.rs`, `src/agent/runloop/unified/turn/context.rs`, `src/agent/runloop/unified/turn/tool_outcomes/execution_result.rs`, `src/agent/runloop/unified/turn/session/slash_commands/diagnostics/memory.rs`, `src/agent/runloop/unified/turn/turn_processing/plan_mode.rs`, `src/agent/runloop/unified/turn/turn_loop.rs`, `src/agent/runloop/unified/turn/session/slash_commands/share_log/timeline.rs`, `src/agent/runloop/unified/turn/turn_processing/llm_request/mod.rs`, `src/agent/runloop/unified/turn/tool_outcomes/handlers/tests.rs`, and a full compaction pass on `src/agent/runloop/unified/turn/compaction/mod.rs`. The current tracked roots are now all below the 500-line target: `session_setup/ui.rs` is 464 lines after extracting `ui/local_agents.rs`, `ui/persistent_memory.rs`, `ui/tests.rs`, `ui/resume_render.rs`, and `ui/header_context.rs`; `turn/context.rs` is 276 lines after extracting `context/continuation.rs`, `context/message_history.rs`, `context/tests.rs`, `context/runtime_context.rs`, and `context/response_handling.rs`; `turn/tool_outcomes/execution_result.rs` is 441 lines after extracting `execution_result/auto_mode_probe.rs`, `execution_result/failure_path.rs`, and `execution_result/tests.rs`; `turn/session/slash_commands/diagnostics/memory.rs` is 499 lines after extracting `memory/config_persistence.rs`, `memory/prompts.rs`, `memory/presentation.rs`, and `memory/navigation.rs`; and `turn/turn_processing/plan_mode.rs` is 334 lines after extracting `plan_mode/interview_context.rs`, `plan_mode/interview_payload.rs`, and `plan_mode/interview_forcing.rs`. `scripts/check_agent_legibility.py --mode warn` still reports zero missing headers and zero delegation gaps across the tracked hotspot roots. `src/agent/runloop/unified/turn/compaction/mod.rs` is down to 840 lines after extracting `compaction/file_read_dedup.rs`, `compaction/memory_envelope.rs`, and `compaction/recovery_preview.rs`, with `compaction/memory_envelope/local_summary.rs` and `compaction/memory_envelope/persistence.rs` splitting the memory-envelope path further. Remaining oversized follow-up roots are now led by `src/agent/runloop/unified/turn/turn_processing/llm_request/copilot_runtime.rs` (1921), `src/agent/runloop/unified/turn/compaction/tests.rs` (1847), `src/agent/runloop/unified/turn/session/slash_commands/agents_authoring.rs` (1773), `src/codex_app_server/runtime.rs` (1374), `src/agent/runloop/unified/tool_routing/mod.rs` (1346), `src/agent/runloop/unified/turn/session_loop_runner/mod.rs` (1299), `src/agent/runloop/unified/turn/session/slash_commands/oauth.rs` (1294), and `src/agent/runloop/unified/turn/session/slash_commands/agents/runtime.rs` (1210); the compaction area still includes an oversized orchestration root in `src/agent/runloop/unified/turn/compaction/mod.rs` (840). Verify: `find src -name '\*.rs' -type f -exec wc -l {} + \| sort -nr \| head -n 20 && find src/agent/runloop/unified/turn/compaction -name '\*.rs' -type f -exec wc -l {} + \| sort -nr && python3 scripts/check_agent_legibility.py --mode warn`. |
| TD-006 | Security      | Security documentation scattered across 10+ files.                                                                        | P2       | resolved    | 2026-02-15    | Consolidated into `docs/security/` with unified index.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| TD-007 | Testing       | PTY session management has low test coverage due to inherent difficulty of testing terminal interactions.                 | P2       | in-progress | 2026-05-15    | Ref: `vtcode-core/tests/pty_tests.rs` and `vtcode-bash-runner/tests/pipe_tests.rs`; PTY regression coverage exists for command/session and pipe flows, but shell-init and cross-platform cases remain open. Verify: `cargo test -p vtcode-core --test pty_tests && cargo test -p vtcode-bash-runner --test pipe_tests`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| TD-008 | Testing       | MCP OAuth flow and provider lifecycle lack integration tests.                                                             | P2       | in-progress | 2026-02-16    | Added startup-failure and partial-provider-failure coverage in `vtcode-core/tests/mcp_startup_timeout_test.rs`, plus existing lifecycle tests (`tests/fixtures/mock_mcp_server.py`) and CLI OAuth guardrails (`mcp login/logout` unsupported). Remaining gap: full OAuth callback-flow integration once implementation lands.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| TD-009 | Documentation | Tree-sitter language support optimization.                                                                                | P3       | resolved    | 2026-02-25    | Optimized tree-sitter integration: removed heavy language grammars in favor of LLM-native understanding. Retained tree-sitter-bash for critical shell safety. Updated `docs/protocols/LANGUAGE_SUPPORT.md`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| TD-010 | Configuration | Individual config field documentation is partial. Not all `vtcode.toml` fields have descriptions.                         | P3       | resolved    | 2026-02-15    | Added schema-generated field reference: `docs/config/CONFIG_FIELD_REFERENCE.md` (generated via `scripts/generate_config_field_reference.py`, sourced from `vtcode-config` schema).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| TD-011 | Harness       | Harness documentation review.                                                                                             | P2       | resolved    | 2026-02-16    | Full harness review conducted. Updated `QUALITY_SCORE.md` scoring rubric and aligned priority actions with active debt.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| TD-012 | Codebase      | Legacy output patterns in tools may violate the new Agent Legibility invariant.                                           | P2       | resolved    | 2026-02-15    | Applied `badlogic-pi-mono` patterns for code quality and git safety. All new docs follow legibility invariant.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| TD-013 | Codebase      | Structured logging audit. Legacy `println!` may exist in non-TUI crates.                                                  | P2       | resolved    | 2026-02-15    | Audited crates and replaced `println!`/`eprintln!` with `tracing` macros in `vtcode-core` agent runner and registry modules.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| TD-014 | Tooling       | Custom lints with remediation not yet implemented in CI.                                                                  | P2       | resolved    | 2026-02-15    | CI now runs custom invariant checks with remediation guidance: `scripts/check_large_files.py` and `scripts/check_markdown_location.py`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

---

## How to Add a New Item

1. Assign the next sequential ID (`TD-NNN`).
2. Fill in all columns. Description should be specific enough for an agent to act on.
3. Set priority based on impact (see priority levels above).
4. Set status to `open`.
5. Set Last Reviewed to today's date.
6. Add notes with pointers to related docs, exec plans, or code locations.

## How to Resolve an Item

1. Update status to `resolved`.
2. Update Last Reviewed date.
3. Add a `Ref:` token in Notes (for example `PR-123`, `COMMIT-<sha>`, `PLAN-...`) plus one verification command (`git log`, test command, or invariant check).
4. Keep the row in the table for historical reference (do not delete).

## Review Cadence

- **P0 items**: review daily until resolved.
- **P1 items**: review weekly.
- **P2–P3 items**: review bi-weekly.
- **All items**: full table review monthly. Archive `resolved` items older than 3 months to a separate section.
