| 1 | <!-- English translation of adr/0071-ai-assistance-sovereignty-locality-invisibility.md. Canonical Russian: ../../adr/0071-ai-assistance-sovereignty-locality-invisibility.md --> |
| 2 | |
| 3 | # ADR 0071: Principles of AI/assistant integration in IDE - sovereignty, locality, invisibility |
| 4 | |
| 5 | **Status:** Proposed |
| 6 | **Date:** 2026-04-19 |
| 7 | ## Related ADRs |
| 8 | |
| 9 | | ADR | Role | |
| 10 | |-----|------| |
| 11 | | [0013](0013-command-surface-and-discoverability.md) | palette, discoverability | |
| 12 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | MCP, parity | |
| 13 | | [0020](0020-agent-reasoning-visibility-and-provider-limits.md) | visibility of the agent's reasoning | |
| 14 | | [0028](0028-user-settings-toml-localappdata-and-secrets.md) | settings and secrets | |
| 15 | | [0038](0038-agent-facade-ai-provider-and-tool-orchestration.md) | providers façade | |
| 16 | | [0060](0060-keyboard-chord-stack-fms-tactical-strategic.md) | chords; §10 - UX philosophy | |
| 17 | |
| 18 | ### Outside ADR |
| 19 | |
| 20 | | Document | Role | |
| 21 | |----------|------| |
| 22 | | [cascadeide-philosophy-v1.md](../../design/cascadeide-philosophy-v1.md) | cascadeide philosophy v1 | |
| 23 | |
| 24 | --- |
| 25 | ## Context |
| 26 | |
| 27 | IDE user experience has historically relied on **predictability** and **control**: action → expected effect, local operation, clear boundaries. The spread of **cloud inline assistants** in the built-in editor has created a risk class: assistance becomes **more noticeable than the task**, **sovereignty** is weakened (disabling, hint policy), **cognitive load** increases (“what will the model do next?”). |
| 28 | |
| 29 | CascadeIDE is inherently focused on an **agent-first** loop with **observability** (MCP, ADR, command parity), rather than an opaque "model within each character" mix without consensus and without an alternative path. |
| 30 | |
| 31 | --- |
| 32 | |
| 33 | ## Solution |
| 34 | |
| 35 | <a id="adr0071-p1"></a> |
| 36 | |
| 37 | ### 1. Fix the principles of integration of any AI/assistance function |
| 38 | |
| 39 | | Principle | Requirement | |
| 40 | |---------|-----------| |
| 41 | | **Sovereignty** | The user can **disable or limit** the class of hints/automation at the product level (not “just hide visually” without disabling the contract with the cloud, if there is such a contract - this must be **explicit** and controlled). | |
| 42 | | **Locality and borders** | Preferred scenarios where the **source of truth** and critical path are **repository, MCP, IDE**; external providers - **with an explicit** boundary and policy ([0008](0008-mcp-contracts-and-testable-infrastructure.md), [0028](0028-user-settings-toml-localappdata-and-secrets.md)). | |
| 43 | | **Transparency** | Behaviors that affect the code and work loop are **documented** (ADR, user help) rather than remaining just in the vendor model. | |
| 44 | | **Invisible by default** | UX features that compete with code for attention pass the “prompter, not director” bar** ([0060](0060-keyboard-chord-stack-fms-tactical-strategic.md) §6, §10). | |
| 45 | | **One command model** | Any action available to the assistant or automation has a path through **`command_id`** and parity with the palette/MCP, where applicable ([0013](0013-command-surface-and-discoverability.md), [0030](0030-command-ids-hotkeys-and-ui-registry-layers.md)). | |
| 46 | | **Honesty of reasoning** | Visibility layers and provider limits - according to [0020](0020-agent-reasoning-visibility-and-provider-limits.md); do not imitate “full thinking” without designated boundaries. | |
| 47 | |
| 48 | <a id="adr0071-p2"></a> |
| 49 | |
| 50 | ### 2. Anti-pattern (not target UX) |
| 51 | |
| 52 | Consider the following profile as an **unwanted reference** for baseline CascadeIDE: |
| 53 | |
| 54 | - cloud inline code completion **by default everywhere**, without permanent shutdown; |
| 55 | - behavior that **makes it** difficult to predict what will end up in the editor's buffer; |
| 56 | - mixing **subscription/vendor account** with the basic cycle “open solution - edit - build - debug” without a clear alternative. |
| 57 | |
| 58 | Details and historical narrative - in [cascadeide-philosophy-v1.md](../../design/cascadeide-philosophy-v1.md); ADR captures the **product norm**, not an overview of competitors. |
| 59 | |
| 60 | <a id="adr0071-p3"></a> |
| 61 | |
| 62 | ### 3. Non-purposes of this ADR |
| 63 | |
| 64 | - Do not prohibit **optional** integration of external LLMs ([0035](0035-mfd-embedded-webview-external-llm-and-mcp-boundary.md)) - with an explicit trust boundary. |
| 65 | - Do not lock in **specific SKU** or license of third-party products (policies change). |
| 66 | - Do not replace the **technical** specification of the agent facade ([0038](0038-agent-facade-ai-provider-and-tool-orchestration.md)) - only product principles of UX and trust. |
| 67 | |
| 68 | --- |
| 69 | |
| 70 | ## Consequences |
| 71 | - New features with AI/assistant are tested for compliance with §1; in case of conflict - a separate discussion or a conscious exception with an entry in the ADR. |
| 72 | - User documentation may refer to [cascadeide-philosophy-v1.md](../../design/cascadeide-philosophy-v1.md) as a **human-readable** layer; the standard for implementation is this ADR and related ADRs via links. |
| 73 | |
| 74 | --- |
| 75 | |
| 76 | ## Open questions |
| 77 | |
| 78 | - “sufficient off” criteria for specific inline-assist classes (full off vs depth modes). |
| 79 | - Is a separate **compliance matrix** needed for corporate modes (air-gapped, without cloud). |