ADR 0062: GitMap — карта git-границ (submodules) отдельно от workspace navigation context¶

Статус: Proposed — черновик для обсуждения; реализация не зафиксирована.
Дата: 2026-04-17
Обновлено: 2026-04-17 — зафиксировано намеренное разделение с Semantic Map / WSNC (см. Почему не WSNC). Подробности — § История.

Связанные ADR¶

ADR / документ	Роль
0039	WSNC — навигация по коду (не GitMap)
0019	Общий Git core
0055	Общий pipeline отрисовки
0056	Adoption pipeline в карте
0067	GitMap как graph-backed surface
`git-and-submodules-v1.md`	Продуктовый контур

Резюме¶

GitMap: submodules и git-границы отдельно от WSNC/карты намерений.
Общий Skia pipeline; собственный контракт/MCP.

Решение по смыслу (обсуждение → зафиксировано в черновике): визуализация submodules не является расширением get_code_navigation_context / CodeNavigationContextBuilder и не встраивается в Semantic Map как ещё один kind в том же JSON.

Причины:

WSNC про решение и код. Текущий контракт завязан на дерево .sln / .slnx, файлы проектов и эвристики архитектуры исходников (partial, проект, namespace, каталог, control flow — см. 0039, 0053). Это слой «где в коде я и что рядом по смыслу разработки».
Submodules — про git-топологию, не про дизайн ПО. Граница репозитория — артефакт истории и модулей VCS (gitlink, .gitmodules, checkout). К архитектуре приложения относится опосредованно; смешивать с графом «соседей по коду» — смешивать две оси смысла (код vs репозиторий).
Продуктово: отдельный режим/инструмент проще объяснить пользователю и агенту, чем пресеты include_kinds, в которых половина узлов «про git», половина «про файлы».

Именование WSNC: формулировка «workspace navigation» сегодня пересекается с git-картой в голове читателя; возможное переименование контракта/команды MCP в сторону «solution graph» / «code navigation context» — отдельное решение (не блокер этого ADR), см. открытые вопросы.

GitMap — отдельная поверхность, общий пайплайн¶

Рабочее имя: GitMap — мини-карта (и при необходимости список) git-соседей: родительский репозиторий, вложенные submodules, рёбра «содержит / вложен».

Переиспользование: тот же Skia pipeline композиции, что и у Semantic Map (0055, 0056): Intent → (опционально) Declutter → Layout → Render — с другим источником графа (git-метаданные, не CodeNavigationContextBuilder) и, при необходимости, другим инструментом/слотом в PFD (0047), чтобы не смешивать «карту намерений» и «карту репозиториев» в одном виджете.

Семантическая карта (Semantic Map) остаётся про код и задачу; GitMap — про где в git-дереве я и что за соседние репозитории.

Контекст задачи¶

В монорепозиториях часть путей ведёт в отдельные git worktrees (submodule). Пользователь и агент должны видеть границу репозитория без обязательного открытия Git UI — в согласовании с git-and-submodules-v1.md.

Источник данных (открыто)¶

Подход	Плюсы	Минусы
Парсинг `.gitmodules` + пути от корня worktree	Без обязательного `git` в горячем пути	Согласование с фактическим `.git` в submodule
`git submodule status` (GitMcp.Core / 0019)	Commit, грязь, расхождения	Процесс, кэш, потоки
Гибрид	Богаче подписи	Два источника

Корень для привязки: git worktree, в котором открыт workspace (вопрос multi-root — отдельно).

Контракт данных GitMap (черновик, не WSNC)¶

Отдельное описание графа (узлы/рёбра/метки), не расширение payload related / subgraph из 0039:

Узлы: как минимум корень текущего репо, submodule roots (путь каталога), опционально метки состояния (грязь, отставание) — по мере наличия данных.
Рёбра: «родитель — submodule», при вложенности — цепочка.
MCP: отдельная команда уровня get_git_map_context (имя обсуждаемо) или эквивалент в git-слое IDE — не параметры к get_code_navigation_context.

Пресеты уровня кода ([code_navigation] в settings.toml) к GitMap не применяются; у GitMap — свои лимиты и настройки (или дефолты в коде до появления TOML).

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

Слот PFD: вкладка рядом с Semantic Map, отдельный instrument_id, или переключатель режима внутри одного слота — что дешевле по вниманию (0021)?
Вложенные submodules: глубина и капы.
Клик по узлу: reveal в explorer, открыть путь, смена корня сессии — MVP.
Переименование публичного имени WSNC / команды MCP для ясности «solution/code graph».
Паритет агента: отдельный tool в контракте vs секция в get_ide_state.

Не цели (пока)¶

Подмена полноценного Git UI (diff, commit, sync submodule) — GitMap навигационная подсказка, не замена панелей git.
Полный граф всех remote и политик обновления.
Смешение узлов «файл из WSNC» и «submodule» в одном JSON-ответе без явного слоя (отклонено; см. Почему не WSNC).

Отклонённые альтернативы¶

Расширить только Semantic Map новыми kind в том же subgraph — отклонено: разные оси смысла, см. выше.
Только список без графа — допустимо как режим деградации GitMap, не как единственный вид.

После согласования: обновить статус, описать MCP/git-слой и слот инструмента; реализация.

История изменений¶

Дата	Изменение
2026-04-17	зафиксировано намеренное разделение с Semantic Map / WSNC (см. Почему не WSNC).