Architecture Decision Records (ADR) — CascadeIDE¶
Здесь фиксируются принятые архитектурные решения: контекст, выбор, последствия и отклонённые альтернативы. architecture-policy.md — краткий навигатор и таблица ссылок сюда; пошаговая миграция и контракты MCP — в architecture-migration.md, MCP-PROTOCOL.md.
Связь с политикой: крупные смены направления — отдельным коммитом с обновлением навигатора и новой записью здесь.
Статусы и жизненный цикл (без списка ADR): status-lifecycle.md.
Индекс¶
Статус в индексе: только Accepted / Proposed / Superseded. Детали (Implemented, «направление», strangler) — в шапке ADR и status-lifecycle.md.
Тематические кластеры¶
Краткая навигация; полный список — ниже. У крупных ADR в начале файла есть блок ## Резюме.
Отладка и IDE Health¶
| ID | ADR |
|---|---|
| 0001–0004 | гипотезы · паритет агент/человек · режим Debug · UI thread |
| 0011 | ситуационная осведомлённость |
| 0089, 0090–0091, 0095 | IDE Health naming · launch profiles · PFD debug deck · стратификация Health |
Конфигурация и TOML¶
| ID | ADR |
|---|---|
| 0010, 0028–0029 | UI modes · settings.toml · TOML-first UI |
| 0030, 0040, 0050–0051, 0083, 0086 | команды/хоткеи · LSP presets · инструменты в TOML · intent routing · [ai] · тема UI |
Кокпит, CDS и вычислительный контур¶
| ID | ADR |
|---|---|
| 0021 | PFD/MFD — модель внимания |
| 0036, 0046–0047, 0066 | канал→CDS→surface · layout authority · instrument descriptor · cockpit vs presentation |
| 0063–0065, 0068, 0097 | instrument deck · примитивы deck · таксономия · payload vs projection · CCU |
| 0094, 0099 | ingestion bus · IDE DataBus |
Агент, MCP и индексация¶
| ID | ADR |
|---|---|
| 0008, 0016, 0038 | контракты MCP · ACP · фасад агента |
| 0031, 0045, 0048, 0082, 0087 | чат · persistence · Cursor parity · loopback MCP · MAF |
| 0105–0106, 0118 | hybrid index · интеграция в CIDE · agent-notes 2.0 |
Граф, semantic map и навигация¶
| ID | ADR |
|---|---|
| 0039, 0053, 0062 | workspace navigation · control flow PFD · GitMap |
| 0067, 0113–0115 | graph-backed contract · HCI orientation · relation_kind · CDS graph layer |
Превью и документация (Markdown)¶
| ID | ADR |
|---|---|
| 0023, 0026→0069 | язык/diagrams · 0026 Superseded → 0069 |
Полный индекс¶
| ID | Название | Статус |
|---|---|---|
| 0001 | Хранение гипотез отладки в одном JSON-файле | Accepted |
| 0002 | Единый слой состояния отладки для человека и агента | Accepted |
| 0003 | Отдельный UI-режим Debug (не кокпит Power) | Accepted |
| 0004 | Маршалинг обновлений UI через IUiScheduler |
Accepted |
| 0005 | Отложить динамические плагины (MEF и аналоги) | Accepted |
| 0006 | Слои, срезы фич, роль MainWindowViewModel |
Accepted |
| 0007 | Сигналы, связность, нагрузка на UI | Accepted |
| 0008 | Контракты MCP и тестируемая инфраструктура | Accepted |
| 0009 | Strangler-миграция и исключения для spike | Accepted |
| 0010 | Данные UI-режимов в TOML | Accepted |
| 0011 | Ситуационная осведомлённость в отладке (полоска, hover; детали в панели) | Accepted |
| 0012 | Плавающий и отцепляемый хром workspace (телеметрия, полоски; не доки в v1) | Accepted |
| 0013 | Поверхность команд и discoverability (палитра, минимальный toolbar) | Accepted |
| 0014 | Ситуационные чеклисты (модель, триггеры, UI; родитель — 0013) | Accepted |
| 0015 | Подсветка TOML в редакторе (шипнутый TextMate-пакет taplo; не LSP в v1) | Accepted |
| 0016 | Внешний агент по ACP (stdio, Cursor CLI); вендор SDK; UTF-8; ортогонально MCP | Accepted |
| 0017 | Несколько окон приложения, зоны экрана, поверхности агента; MCP multi-root в scope | Accepted |
| 0018 | Каноничные XML-доки для IdeCommands и ProtocolDocGen (вместо мини-языка только в summary) |
Accepted |
| 0019 | Общий Git Core для Cascade IDE и git-mcp (паритет логики, прецедент agent-notes-core) | Accepted |
| 0020 | Видимость рассуждения агента: слои (ответ, трасс, опциональный лог), честные ограничения провайдеров LLM | Proposed |
| 0021 | PFD / MFD — модель внимания кокпита Cascade IDE | Accepted |
| 0022 | Визуальная поверхность разработки UI (AXAML / Blazor), ориентир WinForms, размещение на MFD | Proposed |
| 0023 | Markdown + диаграммы (Mermaid/PlantUML) — first-class опыт через LSP и workflow | Proposed |
| 0024 | SDK для CascadeIDE — стабильные контракты для внутреннего расширения и будущих плагинов | Proposed |
| 0025 | SDK: привязка capabilities к зонам внимания (PFD/MFD/Forward/EICAS/HUD) | Proposed |
| 0026 | Превью Markdown: поверхности и размещение (workspace.toml); внутренние отсылки (peek по «п. N»/якорям); не смешивать с языковым ADR 0023 |
Superseded |
| 0027 | Узкая команда (человек + ассистент) vs зрелость «для открытия»: две оси (границы vs очередь) | Accepted |
| 0028 | Пользовательские настройки: settings.toml, %LocalAppData%\CascadeIDE\, секреты в ai-keys.toml |
Accepted |
| 0029 | Конфигурация: TOML-first; целостный UI настроек deferred; точечный UI — фасад канона | Accepted |
| 0030 | Слои command_id, хоткеев и UI: IdeCommands, палитра, TOML, мост VM; чертёж единого каталога |
Accepted |
| 0031 | Чат агента: пакеты уточнений, ответы сложнее да/нет, треды; не смешивать с PFD-подтверждениями | Proposed |
| 0032 | HUD над редактором: настраиваемое содержимое, грамматика как у presentation; EBNF в ADR, парсер — по сложности DSL |
Proposed |
| 0033 | i18n: ResX / культура .NET, Avalonia; строки UI не в TOML как основной слой; плюрализация — ключи или библиотека | Proposed |
| 0034 | Incapacitation, Emergency Mode; EICAS + сигналы КВС; liveness, контекстный HUD, safety interlock; webcam/analysis MCP opt-in | Proposed |
| 0035 | Встроенный браузер в MFD (WebView2), внешние веб-LLM; граница доверия с MCP; гибрид через оператора; мост веб↔MCP — вне baseline | Proposed |
| 0036 | Канал → CDS → композитор поверхности → поверхность; CDS как маршрутизация в модели внимания (Agent-first) | Accepted |
| 0037 | PFD: инварианты поверхности; Roslyn; канон [PfdStrict] / PfdStrictControl |
Proposed |
| 0038 | Фасад агента: AiProviderManager, чат vs ACP vs автономный JSON-цикл; внешние MCP; идеи оркестрации и tool-calling |
Accepted |
| 0039 | Навигация по workspace; C# / .NET north-star (не polyglot v1); граф/semantic map; PFD/MFD; MCP: пресеты, kind_filter, subgraph |
Accepted |
| 0040 | LSP C#/Markdown: командная строка в settings.toml, пресеты, опциональные ключи; env — открыто в ADR |
Accepted |
| 0041 | Protobuf vs JSON для сообщений агента/IDE: границы, критерии, гибрид; точка входа (Proposed) | Proposed |
| 0042 | Pre-flight briefing: Planned Changes (намерение + SA) и Review Before Apply (превью, семантический слой, отказ без мусора); машина состояний; ортогонально «построчному доверию» | Proposed |
| 0043 | Паритет восстановления MCP-транспорта (человек ↔ агент), граница хоста (Cursor) vs IDE; ортогонально ADR 0002 | Proposed |
| 0044 | Avalonia как хост (фюзеляж), кастомная отрисовка чата (Skia — гипотеза); модель первична, спайк следом; см. ADR 0031 | Accepted |
| 0045 | Persistence истории чата: append-only NDJSON события + метаданные и проекции; UI/рендер не источник правды | Accepted |
| 0046 | CDS: CockpitPresentationLayoutPolicy и инварианты P/F/M; presentation как источник истины для меню/MCP/режимов/реактивного слоя |
Accepted |
| 0047 | Инструмент кабины (Instrument): дескриптор слота (CockpitInstrumentDescriptor), не Control; SE vs карта намерений как примеры |
Accepted |
| 0048 | Чат через Cursor ACP в IDE: mcpServers, авто IDE MCP; приложения — пробелы тулов, разбор mcp.json ↔ CIDE |
Accepted |
| 0049 | Поэтапный rollout Skia-поверхностей по CIDE при Avalonia-host; миграция волнами и dual-path | Accepted |
| 0050 | Декларативная карта «инструмент → зона/слот» в TOML | Accepted |
| 0051 | Intent-based attention routing (TOML) | Accepted |
| 0052 | CLI для контракта агента (паритет с MCP) и снапшот-тесты | Accepted |
| 0053 | Карта намерений и поток управления на PFD (control flow, KISS, subgraph) | Accepted |
| 0054 | Бенчмарки производительности и baseline-метрики для CIDE | Proposed |
| 0055 | Общий pipeline композиции Skia-инструментов (Intent -> Declutter -> Layout -> Render) | Accepted |
| 0056 | Карта намерений: внедрение общего Skia pipeline (композитор, controlFlow layout, cursor semantics) | Accepted |
| 0057 | Chat surface: adoption общего Skia pipeline (threads, confirmations, dual-path rollout) | Accepted |
| 0058 | Сопряжение агента и Roslyn MCP в settings.toml (лимиты, виды узлов, таймауты, пресеты) |
Proposed |
| 0059 | Профили Roslyn MCP, Manager, тактика (PFD) / EFB на MFD, Auto-Focus / Combat / Echelon | Proposed |
| 0060 | Аккордный слой (Ctrl+K), FMS-style, S/T, overlay; расширение ADR 0013 | Accepted |
| 0061 | Контекстная карта ADR ↔ пути в workspace.toml, индикатор на PFD, intent/tooltip, advisory для агента (GPWS для доков) |
Proposed |
| 0062 | GitMap: submodules и git-границы отдельно от WSNC/карты намерений; общий Skia pipeline; собственный контракт/MCP; git-and-submodules-v1 | Proposed |
| 0063 | Instrument deck + ContentRepresentation; таксономия примитивов (в т.ч. Readout, Trend, Gauge, Presence); Presence/Activity vs Dark Cockpit; DedicatedPage — режим Page для WH, не deck |
Accepted |
| 0064 | Виды индикаторов deck: единое графическое воплощение; библиотека отрисовки + семантическая палитра; без лишнего архитектурного слоя; DeckPrimitiveKind = каталог видов |
Accepted |
| 0065 | Категории инструментов и типы графов (graph_kind): домен ортогонально слоту/instrument_id; «Карта намерений» = карта намерений кода; см. таблицу graph_kind |
Accepted |
| 0066 | Cockpit UI vs presentation IDE (хром, оверлеи, тема): две опоры; не смешивать приборы/deck с оболочкой; PrimitivesKit vs UiChrome |
Accepted |
| 0067 | Graph-backed surfaces: общий контракт для семейства графовых экранов (данные, взаимодействие, навигация, layout, выделение, sync); карта намерений, GitMap, будущие графы | Accepted |
| 0068 | Полезная нагрузка строки канала vs проекция представления vs слот: таблица/полоса ≠ тип ячейки; v1 — один DTO; гетерогенность — дискриминатор и шаблоны | Accepted |
| 0069 | Markdown Preview: MFD tool как primary surface, native Markdig renderer first, WebView как optional adaptor; authoring-расширение ортогонально preview | Accepted |
| 0070 | Command Palette: прямой overlay surface в host, маршрутизация в активный TopLevel; ModalOverlay не канон для palette baseline |
Accepted |
| 0071 | AI / ассистент в IDE: суверенитет, локальность, невидимость; анти-паттерн «облачный inline по умолчанию без контроля»; нарратив — cascadeide-philosophy-v1 | Proposed |
| 0072 | Чат: topic cards, drill-in/back, adaptive default; intent-based Melody/Chords v1 для навигации по темам; уточняет 0060 в chat-domain | Accepted |
| 0073 | PFD instrument deck: каталог вариантов состава (SA, code metrics, карта намерений, ADR indicator…); критерии «PFD vs по запросу»; живой черновик до выбора пресета | Proposed |
| 0074 | Настройки: компактнее, якорь на MFD; нехватка места в P+F+M — таблица стратегий (scroll, min width, fallback-окно, …) | Proposed |
| 0075 | UI: тематический указатель UI/README.md; соглашения по страницам MFD (payload vs проекция, keyboard-first); не заменяет плоский индекс |
Proposed |
| 0076 | UI/UX: центр принципов — связный текст из snippets/ui/ (внимание/кокпит, философия продукта); не заменяет исходные ADR |
Proposed |
| 0077 | TECH: центр принципов — связный текст из snippets/tech/ (границы/контракты, агент/отладка/наблюдаемость); не заменяет исходные ADR |
Proposed |
| 0078 | Git preflight: шум-контроль (EOL/BOM/whitespace), safe fixes, подсказки логических коммитов и post-push отчёт | Accepted |
| 0079 | IDS (Ide Display System): пайплайн IDE-оверлеев (intent → композитор → снимок → поверхность), ортогонально CDS; единый input host и слоты — по плану; Roslyn CASCOPE013–016 | Accepted |
| 0080 | Intercom: продуктовое имя канала связи вместо узкого «чат»; агент + команда + системные реплики; внешний командный контур vs своя «гора»; discoverability/i18n; strangler для кода | Accepted |
| 0081 | Параметрические Intent Melody: суффикс :startLine:endLine для операций над текстом редактора; валидация; рефакторинги по диапазону; UX (индикатор, chord vs палитра) |
Accepted |
| 0082 | ACP + IDE MCP: одна копия процесса — loopback HTTP/SSE вместо второго CascadeIDE --mcp-stdio; безопасность localhost; stdio для внешнего хоста сохранить |
Proposed |
| 0083 | [ai] в settings.toml: mode = local | acp | mcp_only | cloud; вложенные секции; без обратной совместимости со старым provider |
Accepted |
| 0084 | Правки агента: единственный текст в редакторе; чат — намерение/статус; слой присутствия (курсор, «пишет»); дифф в чате не основной; без обязательного CRDT | Proposed |
| 0085 | Editor HUD: inline-слой в редакторе (каретка, текст, gutter) vs HUD banner (полоса над текстом); IDS оверлеи отдельно; конфиг баннера — 0032 | Proposed |
| 0086 | Тема UI: канон кистей в settings.toml; JSON для ide_get/set_ui_theme как транспорт; strangler Themes/*.json |
Proposed |
| 0087 | Microsoft Agent Framework (MAF): ориентир на оркестрацию встроенного агентного контура; след. шаг — PoC | Accepted |
| 0088 | Host slot / регион / ячейка deck — таксономия уровней; не смешивать | Proposed |
| 0089 | get_ide_state вместо get_workspace_state; канал IDE Health вместо Workspace Health; ортогонально ADR 0002 |
Accepted |
| 0090 | Профили запуска / несколько стартовых конфигураций отладки (как launch profiles в VS), хранение, MCP, миграция с startup-project.json |
Accepted |
| 0091 | Гипотеза: PFD instrument deck в режиме отладки — одной страницы Mfd (DebugStack) может не хватить; PFD = краткая сводка, Mfd = детали | Proposed |
| 0092 | Трек Visual UI (дизайнер разметки): отдельная крупная программная линия; норматив по UX — 0022; приоритет Avalonia → Blazor → (опц.) Razor | Accepted |
| 0093 | Расширение 0090: опциональный встроенный просмотр URL Kestrel на MFD рядом с отладкой; внешний браузер остаётся default; WebView2 / кроссплатформа — в roadmap | Accepted |
| 0094 | Шина доставки в UI (аналогия AFDX): Channel<T>, батчинг, backpressure; ортогонально CDS-«каналу»; strangler с журнала сборки |
Proposed |
| 0095 | Три уровня Health: Workspace (папки, Git) · Solution (сборка, тесты) · IDE (LSP, MCP, окружение); таксономия для каналов/CDS/MCP; strangler от текущего IDE Health | Accepted |
| 0096 | Intercom: карточка темы = заголовок + сводка (картотека); spine продуктовой линии ортогональна main thread (CIDE — пример); дополняет 0072 | Accepted |
| 0097 | Вычислительные блоки кабины (CCU), аналог LRU Unit: свёртка сырья → DTO/снимок канала; ортогонально 0094 (транспорт) и CDS; IDE Health в коде — эталон цепочки | Accepted |
| 0098 | Semantic-first: первична семантическая карта; код/доки/git — проекции; согласование с 0084 по сессии правок; strangler | Proposed |
| 0099 | IDE DataBus: типизированные события в процессе IDE; развязка источников и проекций, без подмены 0094 (transport) и 0097 (CCU) | Accepted |
| 0100 | Конституция проекта: долговременные принципы, архитектурные инварианты, governance и порядок изменений основания проекта | Proposed |
| 0101 | Лицензирование и коммерциализация: матрица лицензий, правила зависимостей, guardrails для copyleft и план внедрения | Proposed |
| 0102 | Data Acquisition Layer (DAL): явная граница добычи внешних данных и контракт DAL ↔ CCU ↔ UI | Proposed |
| 0103 | Субстрат Editor HUD: SemanticProjectionPipeline / EditorHudEngine / IEditorSurfaceAdapter; DAL / CCU / DataBus; отдельный hi-freq bounded-контур; baseline AvaloniaEdit; сравнение хостов в design/, roadmap UI в ui-ux/ |
Accepted |
| 0105 | Hybrid codebase index: переносимое ядро + MCP для C#/Razor/AXAML (Roslyn истина для C#); гибрид FTS+vec | Accepted |
| 0106 | Встраивание hybrid index в CascadeIDE (DAL/CCU/DataBus/freshness) и граница Semantic Map | Proposed |
| 0107 | Пустое решение: dotnet new sln, меню/MCP, BlankSolutionCreator + IDotnetCommandRunner |
Accepted |
| 0108 | Веб-портал для внешних веб-ИИ: WebView, Host Object → IdeCommands/MCP; allowlist, согласие; PoC (Atlas / Search AI) |
Accepted |
| 0109 | Intent Melody: целевой каталог [[melody_root]] (shape + tail_signature); миграция с [aliases]+[[parametric]]; args в коде; плагины — обработка у плагина |
Accepted |
| 0110 | Рефакторинги Roslyn по диапазону: мост Intent Melody / IDE ↔ Roslyn MCP; без дублей Features в ядре; rmx/rix не в бандле до моста |
Proposed |
| 0111 | Редактор: LineNumber / LineRange (1-based, Start ≤ End); ParsedLineRange; граница к JSON — int в args команд |
Accepted |
| 0112 | Палитра (Ctrl+Q): режимы строки, стратегии и контракт бэкенда workspace-поиска (t:/m:/x:) с переключением в settings |
Accepted |
| 0113 | HCI × Semantic Map: ориентация; оси graph_kind / provenance / relation_kind; быстрый текстовый referenced-by → Roslyn; SemanticMapInputSnapshot / CCU |
Proposed |
| 0114 | Тип отношения на ребре (relation_kind): «наследует», «ссылается на», partial peer, текстовое совпадение; ортогонально graph_kind и provenance; связь с hit_kind |
Proposed |
| 0115 | CDS: общий слой реализации graph-backed приборов в кабине (не IDS); IGraphDataSource (v0); стык с 0036 и 0067 |
Accepted |
| 0116 | Intercom: дерево сессии (ветвление, rewind, bookmark) и steer / follow-up при работе агента; 0045, 0080, 0096 | Proposed |
| 0117 (SkiaKit) | SkiaKit: переиспользуемые Skia-примитивы IDE (sectioned cards, tile grid) | Accepted |
| 0117 | Remote operator surface: PWA-пульт с телефона/другого ПК, Operator Gateway; не mobile IDE; 0017, 0108 | Proposed |
| 0118 | Agent Notes Core 2.0: TOML in-proc, config_path SSOT с MCP, knowledge_path в IdeCommands |
Accepted |
| 0119 | Чат как command line: Intercom (/card) + IDE (/build run, /test run, /debug launch); autocomplete, command_id |
Accepted · Implemented |
| 0120 | primary_work_surface: Intercom или Editor в якоре Forward (аналог Agent/Editor в Cursor) |
Proposed |
| 0121 | Парадигма IOP (Intent-Oriented Programming) — концептуальный фундамент; манифест | Accepted |
| 0123 | Intercom → full-Skia surface (Slack/MM-like); strangler фазы 0–4; Avalonia = фюзеляж | Accepted |
| 0124 | Фича: параметрический slash = полный паритет melody_shape=parametric в TOML (wire_class, binders, TOML, SubAction) |
Accepted · Implemented |
| 0125 | Slash workspace/file: /file open, /solution new, динамические подсказки по файлам; create_project_in_solution (console/classlib/webapi) |
Accepted · Implemented |
| 0126 | Intercom inspect: /topic//spine list|tree (kind=report); статус в compact toolbar; UX открытия файла из slash |
Accepted · Implemented |
Сборка в один документ (HTML, TXT, PDF)¶
Склейка нумерованных ADR и те же директивы INCLUDE / INCLUDE_MANIFEST / INCLUDE_GLOB, что в resume/ (без DOCX). Запуск из этого каталога: dotnet script build-adr.csx. Зависимости и выходные пути — в build/README.md.
Соглашения¶
- Связанные ADR: не сплошной абзац в шапке — секция ## Связанные ADR с таблицей
| ADR | Роль |(шаблон и правила в snippets). - Имя файла:
NNNN-краткий-kebab-title.md, четыре цифры с ведущими нулями. - Статусы: в шапке ADR и в колонке «Статус» — см. status-lifecycle.md. Кратко: первый тег (Proposed / Accepted / Superseded / Deprecated); для внедрённого в код решения —
Accepted · Implemented(второй тег через·). Без подпапок по статусу — одинdocs/adr/. - Тематические подпапки (не по статусу): опционально указатель по теме — 0075 и
UI/README.md; TECH —TECH/README.mdи 0077. - Новый ADR добавляет строку в таблицу выше и при необходимости строку в таблицу в architecture-policy.md.
Внутренние якоря и отсылки (чтобы «см. п. N» работали как ссылки)¶
Канон текста — snippets/adr-anchors-policy.md (в сборке build-adr.csx можно подключать через {{ INCLUDE: snippets/adr-anchors-policy.md }} из adr-book.md).