ADR 0042: Pre-flight briefing — Planned Changes и Review Before Apply¶
Статус: Proposed
Дата: 2026-04-13
Связанные ADR¶
| ADR | Роль |
|---|---|
| 0039 | семантическая карта и связанные файлы |
| 0021 | PFD/MFD, situational awareness |
| 0038 | агент, ACP, MCP |
| 0008 | контракты MCP |
| 0031 | пакеты уточнений; ортогонально этому ADR |
| 0016 | ACP как транспорт внешнего агента |
Контекст¶
При высокой автономности агента ошибка «первой перезаписанной строки» дороже, чем в режиме «ассистент под рукой»: последующий откат смешивается с другими изменениями, частично применённые правки оставляют репозиторий в неясном состоянии, доверие к системе падает быстрее, чем растёт скорость итераций.
В авиации брифинг перед действием (pre-flight / pre-action briefing) задаёт общую картину: что будет сделано, в каком порядке, какие риски, что запрещено. Аналог для кокпита разработки: пилот (человек) и агент договариваются о намерении до того, как изменения физически попадут на диск — не как замена code review, а как предохранитель и носитель ситуационной осведомлённости (SA).
Классические IDE и потоки вроде «агент сразу пишет в файлы» заставляют выбирать между слепым доверием и поштучным одобрением каждой строки (медленно). Цель Cascade IDE — пакеты смысла: сначала план и границы воздействия, затем согласованное применение с возможностью частичного одобрения и чистого отказа.
Решение (принципы)¶
1. Два явных этапа: Planned Changes и Review Before Apply¶
Planned Changes («план полёта»): до любой физической записи в рабочие файлы агент (через ACP/MCP и контракт IDE) выдаёт структурированное намерение: не только «список путей», а привязка к семантической карте — какие узлы/границы (контракты, тесты, границы проектов, связанные файлы по политике 0039) затрагиваются или рискуют быть затронуты. Человек может одобрить часть плана и исключить файлы/области («здесь не трогай»).
Review Before Apply («сличение перед посадкой»): после фиксации плана система показывает финальное согласование перед apply: не обязательно построчное одобрение каждого токена, но обязательно осознанное «взведение» (arming) перед записью.
2. Семантический слой поверх текста¶
Текстовый diff (как в Git) остаётся базовым слоем проверки. Поверх него целевой контур — семантический diff: что меняется в контрактах, видимых символах, публичных API (ориентир: Roslyn и модель проекта; см. north-star 0039). Цель — подсветить риск для соседних модулей и тестов, а не только синтаксическую перестановку.
Точная глубина v1 не фиксируется этим ADR как обязательная: допускается поэтапное внедрение (сначала «затронутые файлы + виды связей из навигационного контекста», затем уточнение до символов).
3. Превью и отказ без мусора¶
Перед подтверждением пользователь видит in-place preview (образ «призрачных» правок в основной рабочей области — Forward / лобовое стекло в терминах 0021): что вступит в силу после Confirm.
Reject / отмена на этом этапе обязана возвращать редактор и рабочее состояние к стабильному снимку до попытки apply — без частично вставленных фрагментов и «полуприменённых» файлов. Реализация (staging-патчи, буфер, транзакционная модель) — решение реализации; принцип нормативен.
4. Машина состояний (аналог «Arming the Autoland»)¶
Зафиксировать для продукта явные состояния цикла изменений, например:
| Состояние | Смысл |
|---|---|
| DISARMED | Нет утверждённого плана записи на диск |
| PLANNED | План (Planned Changes) выдан и может редактироваться/резаться человеком |
| ARMED | План и превью согласованы; готовность к одной атомарной записи (или к явно определённым чанкам) |
| COMMITTED | Изменения применены; дальше — обычный git/рабочий цикл |
Переходы ARMED → COMMITTED только по явному действию пользователя (или по политике безопасности с более высоким уровнем автономности — отдельное решение и не смешивается с baseline этого ADR). Формулировка «курс выставлен — верификация — касание полосы» (autoland arming) остаётся продуктовой метафорой; точные имена состояний в UI могут отличаться.
5. Транспорт и авторитет¶
MCP / IdeCommands (0008) — канал команд и наблюдаемости. ACP (0016) — транспорт внешнего агента. Авторитет подтверждения опасных переходов состояния — у IDE и пользователя; агент не должен обходить Review Before Apply скрытым записью в файлы в обход заявленного контракта (при нормальной конфигурации безопасности).
6. Связь с MFD и SA¶
Визуализация Planned Changes целесообразна в вторичном контуре (MFD) или выделенной карточке, согласованной с моделью внимания 0021: пользователь видит не «N файлов», а смысловые затрагиваемые области (контракт ↔ тесты ↔ соседний модуль). Это и есть продуктовый ответ на требование SA для высокой автономности.
Не цели (v1 этого ADR)¶
- Полная формальная верификация или доказательство эквивалентности поведения.
- Замена Git или обязательный семантический merge на уровне всего репозитория без текстового слоя.
- Обещание, что семантический diff всегда полон на уровне всех языков; north-star остаётся C# / .NET в духе 0039.
Последствия¶
- Появляется явный продуктовый контур между «обсудили намерение» и «коснулись диска», согласованный с кокпитной метафорой.
- Реализация потребует снимков состояния редактора/документов до apply и дисциплины команд в MCP-PROTOCOL.md (новые или уточнённые команды — отдельные итерации и, при необходимости, отдельные ADR по границам).
- Усиливается требование к навигационному и семантическому слою (0039): без него план деградирует в «список файлов» и теряет заявленную SA.
Открытые вопросы¶
- Гранулярность частичного одобрения (файл, диапазон, символ) и влияние на атомарность apply.
- Политика для полностью автономного режима (если когда-либо разрешён): отдельный уровень безопасности, не смешиваемый с baseline «человек в контуре».
- Связь с Emergency Mode и interlock (0034) — при необходимости ссылка в следующих ревизиях.