| 1 | <!-- English translation of adr/0002-debug-human-agent-parity.md. Canonical Russian: ../../adr/0002-debug-human-agent-parity.md --> |
| 2 | |
| 3 | #ADR 0002: Single debug state layer for human and agent |
| 4 | |
| 5 | **Status:** Accepted |
| 6 | **Date:** 2026-04-02 (retrospective; content recorded previously in [debug-human-agent-parity-v1.md](../debug-human-agent-parity-v1.md)) |
| 7 | ## Related ADRs |
| 8 | |
| 9 | ### Outside ADR |
| 10 | |
| 11 | | Document | Role | |
| 12 | |----------|------| |
| 13 | | [architecture-policy.md](../../architecture-policy.md) | debugging | |
| 14 | | [MCP-PROTOCOL.md](../../MCP-PROTOCOL.md) | MCP PROTOCOL | |
| 15 | |
| 16 | --- |
| 17 | ## Context |
| 18 | |
| 19 | The agent can control debugging through MCP, and the user can control debugging through the UI IDE. If breakpoints, stop, stack, and variables diverge between the outer loop and what a human sees, joint debugging becomes unreliable. |
| 20 | |
| 21 | ## Solution |
| 22 | |
| 23 | **One source of truth** for debug status **inside CascadeIDE**: |
| 24 | |
| 25 | 1. Breakpoints are consistent with the editor's glyphs and with what tools like `ide_set_breakpoint` and display of a list of points reflect. |
| 26 | 2. Stop: the current line and highlighting in the editor are consistent with the MCP (`ide_get_debug_snapshot`, `ide_debug_stack_trace`, debug panel state). |
| 27 | 3. Stack and Variables: The debug panel UI and data for the agent via MCP (`ide_debug_stack_trace`, `ide_debug_variables`, `ide_get_debug_snapshot`) comes from **one session and one model**, not two unsynchronized processes. |
| 28 | |
| 29 | The external debugger (netcoredbg, DAP) remains the **engine**; **state** for human and MCP goes through the IDE layer. |
| 30 | |
| 31 | ## Consequences |
| 32 | |
| 33 | - The implementation entails an explicit layer (for example, a DAP session in the IDE), rather than separate traversals. |
| 34 | - The document [debug-human-agent-parity-v1.md](../debug-human-agent-parity-v1.md) remains the canonical description of the goal; this ADR captures the decision in ADR format. |
| 35 | |
| 36 | ## Rejected alternatives |
| 37 | |
| 38 | - Two independent circuits without synchronization - rejected as contrary to the purpose of the product. |