| 1 | <!-- English translation of adr/0062-git-submodules-semantic-map-subgraph.md. Canonical Russian: ../../adr/0062-git-submodules-semantic-map-subgraph.md --> |
| 2 | |
| 3 | # ADR 0062: GitMap - a map of git boundaries (submodules) separate from the workspace navigation context |
| 4 | |
| 5 | **Status:** Proposed - draft for discussion; implementation is not fixed. |
| 6 | **Date:** 2026-04-17 |
| 7 | **Updated:** 2026-04-17 - Fixed **intentional split** with Semantic Map / WSNC (see [Why not WSNC](#adr0062-not-wsnc)). Details - [§ History](#adr0062-history). |
| 8 | |
| 9 | ## Related ADRs |
| 10 | |
| 11 | | ADR/document | Role | |
| 12 | |----------------|------| |
| 13 | | [0039](0039-workspace-navigation-affordances.md) | WSNC - Code Navigation (**not** GitMap) | |
| 14 | | [0019](0019-shared-git-core-ide-and-git-mcp.md) | General Git core | |
| 15 | | [0055](0055-skia-instrument-composition-pipeline.md) | General rendering pipeline | |
| 16 | | [0056](0056-semantic-map-pipeline-adoption.md) | Adoption pipeline in the map | |
| 17 | | [0067](0067-graph-backed-surfaces-contract.md) | GitMap as graph-backed surface | |
| 18 | | [`git-and-submodules-v1.md`](../../git-and-submodules-v1.md) | Product circuit | |
| 19 | |
| 20 | ## Summary |
| 21 | |
| 22 | - **GitMap:** submodules and git boundaries **separate** from WSNC/intent map. |
| 23 | - General Skia pipeline; own contract/MCP. |
| 24 | |
| 25 | |
| 26 | <a id="adr0062-not-wsnc"></a> |
| 27 | |
| 28 | ## Why not mix with workspace navigation context (WSNC) |
| 29 | |
| 30 | **Meaning solution (discussion → committed to draft):** visualization submodules **not** is an extension of `get_code_navigation_context` / `CodeNavigationContextBuilder` and **not** built into Semantic Map as another `kind` in the same JSON. |
| 31 | |
| 32 | Reasons: |
| 33 | |
| 34 | 1. **WSNC about the solution and code.** The current contract is tied to the tree **`.sln` / `.slnx`**, project files and heuristics **source architecture** (partial, project, namespace, directory, control flow - see [0039](0039-workspace-navigation-affordances.md), [0053](0053-semantic-map-control-flow-pfd.md)). This is the layer **“where am I in the code and what is nearby in terms of development”**. |
| 35 | |
| 36 | 2. **Submodules are about git topology, not about software design.** The repository boundary is an artifact of **history and VCS modules** (gitlink, `.gitmodules`, checkout). It relates indirectly to the application architecture; mix with the graph of “code neighbors” - mix **two axes of meaning** (code vs repository). |
| 37 | |
| 38 | 3. **Productive:** a separate mode/tool is easier to explain to the user and agent than the `include_kinds` presets, in which half the nodes are “about git”, half are “about files”. |
| 39 | |
| 40 | **WSNC naming:** the wording “workspace navigation” today intersects with the git map in the reader’s head; possible **renaming** of the MCP contract/command towards “solution graph” / “code navigation context” - **separate** solution (not a blocker for this ADR), see [open questions](#adr0062-open). |
| 41 | |
| 42 | <a id="adr0062-gitmap"></a> |
| 43 | |
| 44 | ## GitMap - separate surface, common pipeline |
| 45 | |
| 46 | **Working name:** **GitMap** - mini-map (and optional list) of **git neighbors**: parent repository, nested submodules, "contains/nested" edges. |
| 47 | |
| 48 | **Reuse:** same **Skia pipeline** composition as Semantic Map ([0055](0055-skia-instrument-composition-pipeline.md), [0056](0056-semantic-map-pipeline-adoption.md)): Intent → (optional) Declutter → Layout → Render - with **another** graph source (git metadata, not `CodeNavigationContextBuilder`) and, if necessary, **another** tool/slot in the PFD ([0047](0047-cockpit-instrument-descriptor-and-slot-composition.md)) so as not to mix the "intent map" and the "repository map" in the same widget. |
| 49 | |
| 50 | The semantic map (**Semantic Map**) remains about **code and task**; **GitMap** - about **where in the git tree I am and what the neighboring repositories are**. |
| 51 | |
| 52 | --- |
| 53 | ## Task context |
| 54 | |
| 55 | In monorepositories, some paths lead to **separate git worktrees** (submodule). The user and agent should see the **repository boundary** without necessarily opening the Git UI - in accordance with [git-and-submodules-v1.md](../../git-and-submodules-v1.md). |
| 56 | |
| 57 | ## Data source (open) |
| 58 | |
| 59 | | Approach | Pros | Cons | |
| 60 | |--------|--------|--------| |
| 61 | | Parsing `.gitmodules` + paths from worktree root | Without the required `git` in the hot path | Consistency with actual `.git` in submodule | |
| 62 | | `git submodule status` (GitMcp.Core / [0019](0019-shared-git-core-ide-and-git-mcp.md)) | Commit, dirt, discrepancies | Process, cache, threads | |
| 63 | | Hybrid | Richer signatures | Two sources | |
| 64 | |
| 65 | Root for binding: **git worktree**, in which the workspace is open (the multi-root issue is separate). |
| 66 | |
| 67 | ## GitMap Data Contract (draft, not WSNC) |
| 68 | |
| 69 | Separate graph description (nodes/edges/labels), **not** payload `related` / `subgraph` extension from [0039](0039-workspace-navigation-affordances.md): |
| 70 | - Nodes: at least **root of the current repo**, **submodule roots** (directory path), optional status labels (dirt, lag) - as data is available. |
| 71 | - Edges: “parent - submodule”, when nested - a chain. |
| 72 | - MCP: separate **`get_git_map_context`** level command (name debated) or equivalent in the git IDE layer - **not** parameters to `get_code_navigation_context`. |
| 73 | |
| 74 | **code level** presets (`[code_navigation]` in `settings.toml`) **do not apply** to GitMap; GitMap has its own limits and settings (or defaults in the code before TOML appeared). |
| 75 | |
| 76 | ## Open questions |
| 77 | |
| 78 | <a id="adr0062-open"></a> |
| 79 | |
| 80 | 1. PFD slot: **tab** next to Semantic Map, **separate instrument_id**, or mode switch inside one slot - which is cheaper in terms of attention ([0021](0021-pfd-mfd-cockpit-attention-model.md))? |
| 81 | 2. Nested submodules: depth and caps. |
| 82 | 3. Click on the node: reveal in explorer, open the path, change the session root - MVP. |
| 83 | 4. Renaming public name **WSNC** / MCP command for clarity "solution/code graph". |
| 84 | 5. Agent parity: separate tool in the contract vs section in `get_ide_state`. |
| 85 | |
| 86 | ## Not goals (yet) |
| 87 | |
| 88 | - Replacement of **full Git UI** (diff, commit, sync submodule) - GitMap **navigation** tooltip, not replacement of git panels. |
| 89 | - Full graph of **all** remotes and update policies. |
| 90 | - Mixing "file from WSNC" and "submodule" nodes in **single** JSON response without explicit layer (rejected; see [Why not WSNC](#adr0062-not-wsnc)). |
| 91 | |
| 92 | ## Rejected alternatives |
| 93 | |
| 94 | - **Extend only Semantic Map** with new `kind` in the same subgraph - rejected: different axes of meaning, see above. |
| 95 | - **List only without graph** - acceptable as a GitMap degradation mode, not as the only type. |
| 96 | |
| 97 | --- |
| 98 | |
| 99 | *After approval: update the status, describe the MCP/git layer and tool slot; implementation.* |
| 100 | |
| 101 | --- |
| 102 | |
| 103 | ## History of changes |
| 104 | |
| 105 | <a id="adr0062-history"></a> |
| 106 | |
| 107 | | Date | Change | |
| 108 | |------|-----------| |
| 109 | | 2026-04-17 | fixed **intentional split** with Semantic Map / WSNC (see [Why not WSNC](#adr0062-not-wsnc)). | |