ADR 0061: Контекстная привязка ADR к путям кода (GPWS для документации) и индикатор на PFD¶

Статус: Proposed (реализация отложена)
Дата: 2026-04-17

Связанные ADR¶

ADR	Роль
0021	PFD как зона внимания
0039	навигация, semantic map
0053	карта и курсор в методе
0028	Пользовательские настройки — `settings.toml`, каталог `%LocalAppData%\CascadeIDE\`, секреты отдельно
0050	декларативные карты в TOML

Резюме¶

Контекстная карта ADR ↔ пути в workspace.toml; индикатор на PFD.
Advisory для агента («GPWS для доков»); не заменяет чтение ADR.

Контекст¶

ADR в docs/adr/ — нормативный слой, но при работе в конкретном файле легко не знать, какие решения к этой области относятся, пока не пройдёшься по индексу. Документация рискует стать «кладбищем текстов»: формально есть, фактически не участвует в рабочем контексте.

Идея: трактовать привязку путь в репозитории → один или несколько ADR как слой ситуационной осведомлённости (аналог GPWS / terrain awareness в авиации): не обязательный full-screen документ, а сигнал рельефа — «здесь действуют такие-то архитектурные ограничения».

Цели¶

Зафиксировать декларативную карту «участок дерева исходников → ADR» в конфигурации workspace (TOML), версионируемой с репозиторием.
Описать минимальную подачу в UI Flight-режима: ненавязчивый индикатор на PFD / зоне знаний и краткий intent (намерение ADR) без обязательного открытия файла.
Заложить основу для ассистента/агента: при смене контракта в зоне, покрытой ADR, — мягкое предупреждение в логе/трассе («отклонение от ADR-NNN»), а не запрет без объяснения.

Не-цели (на первом этапе)¶

Полная автоматическая верификация соответствия кода тексту ADR (статический анализ «ADR vs реализация») — отдельная линия работы.
Замена существующего индекса README или обязательный просмотр длинных ADR из IDE при каждом сохранении.
Жёсткая блокировка правок при «нарушении ADR» без участия человека.

Предлагаемое решение (черновик)¶

1. Декларативная карта в TOML¶

Секция в workspace.toml (или согласованное имя, например [workspace.adr.map]), задающая правила сопоставления префикса пути (относительно корня репозитория) списку файлов ADR или идентификаторам:

[workspace.adr.map]
"src/engine/mcp" = "docs/adr/0008-mcp-contracts-and-testable-infrastructure.md"
"src/ui/skia" = [
  "docs/adr/0055-skia-instrument-composition-pipeline.md",
  "docs/adr/0049-skia-surface-rollout-over-avalonia-host.md",
]
"*" = "docs/adr/0006-presentation-layers-and-feature-slices.md"   # опциональный глобальный fallback

Требования к алгоритму (уточнить при принятии): приоритет самого длинного совпадающего префикса, затем fallback *; единообразие разделителей путей на Windows/Linux.

2. Визуализация в Flight (PFD / EFD)¶

Индикатор «знание»: когда текущий файл (или символ под курсором) попадает под маппинг, на PFD отображается лёгкий знак (например, условная литера «i» / «A» в стилистике кабины — детали UX отдельно).
HUD / tooltip: по наведению или короткой задержке — краткий intent (заголовок ADR + 1–2 строки из раздела «Решение» или front-matter, если появится), без открытия Markdown в редакторе по умолчанию.

Реализация опирается на существующий контур семантической карты / курсора и Skia-pipeline (0053, 0055), не дублируя второй источник истины для «где я в коде».

3. Роль агента¶

При наличии маппинга агент может:

подсвечивать в трассе ссылку на ADR, если изменение затрагивает зону с привязкой;
формулировать предупреждение как advisory («курс отклоняется от ADR-NNN — подтверди намерение»), а не как ошибку сборки.

Критерии «нарушения» на первом этапе — эвристические (смена публичного API, ключевых имён из ADR), чтобы избежать шума.

Открытые вопросы¶

Имя секции TOML и схема десериализации в модели CascadeIdeSettings / workspace-only.
Откуда брать краткий intent: первый абзац после заголовка, YAML front-matter, отдельное поле в ADR — нужна договорённость.
Взаимодействие с несколькими корнями решения (multi-root) и путями вне репо.

MVP (критерий «можно начинать»)¶

Парсинг карты из TOML + разрешение «текущий файл → список ADR».
Один вид индикатора на PFD и текст tooltip из выбранного ADR (без полного редактора документации).
Тесты на алгоритм матчинга путей и регресс при изменении нормализации путей.

Последствия¶

Плюс: ADR сложнее игнорировать при ежедневной работе; карта живёт рядом с кодом в git.
Минус: поддержка маппинга при крупных переездах каталогов — отдельная обязанность (ревью, возможно скрипт миграции путей).

Статус реализации¶

Не начато. При принятии направления — уточнить шапку (Accepted / Accepted (направление)), затем по факту поставки обновить согласно status-lifecycle.md.