From 5f1a11d842b1607e537c93eb05149a6504c7e96a Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Fri, 20 Mar 2026 01:51:15 -0600 Subject: [PATCH 1/7] docs: add community leverage features to backlog (IDs 97-99) Add three Leiden-powered features: weighted community labels (#97), hierarchical decomposition (#98), and community-aware impact scoring (#99). Mark ID 96 (README dep count) as done after graphology removal. Update ID 54 to reference Leiden instead of Louvain. --- docs/roadmap/BACKLOG.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/roadmap/BACKLOG.md b/docs/roadmap/BACKLOG.md index e4ca10fd..6dc2fe9b 100644 --- a/docs/roadmap/BACKLOG.md +++ b/docs/roadmap/BACKLOG.md @@ -109,9 +109,19 @@ Co-change data captures historical coupling from git history. Currently only use | ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | |----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| | 53 | Co-change coupling in triage | Files with high co-change Jaccard scores are maintenance risks — changing one always requires changing the other. Add `coChangeCoupling` as a triage scoring dimension using the max Jaccard score for each file. | Intelligence | Triage surfaces tightly coupled file pairs that static dependency analysis may miss — hidden coupling from shared business logic or implicit contracts | ✓ | ✓ | 4 | No | — | -| 54 | Co-change communities vs dependency communities | Compare Louvain communities from the dependency graph with clusters from co-change data. Files that co-change frequently but live in different dependency communities indicate hidden coupling or architectural drift. | Architecture | Surfaces coupling that the static graph can't see — two modules may have no import relationship but always change together due to shared assumptions | ✓ | ✓ | 3 | No | — | +| 54 | Co-change communities vs dependency communities | Compare Leiden communities from the dependency graph with clusters from co-change data. Files that co-change frequently but live in different dependency communities indicate hidden coupling or architectural drift. | Architecture | Surfaces coupling that the static graph can't see — two modules may have no import relationship but always change together due to shared assumptions | ✓ | ✓ | 3 | No | — | | 55 | Missing co-change partner warning in `check` | When `--staged` changes touch file A but not its historical partner file B (high Jaccard), emit a warning: "file A historically co-changes with file B — did you forget to update it?" | CI | Catches incomplete changes in CI — the most common source of subtle bugs is changing one file in a coupled pair but forgetting the other | ✓ | ✓ | 4 | No | — | +### Tier 1e′ — Community leverage (build on vendored Leiden algorithm) + +Community detection uses a vendored Leiden/Louvain optimiser (`src/graph/algorithms/leiden/`) with full control over resolution, quality functions, and refinement. Currently only consumed by `communities` command and HTML viewer enrichment. These features deepen community awareness across the analysis pipeline. + +| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | +|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| +| 97 | Weighted community labels | Auto-generate a human-readable label for each community from its member files and symbols. Heuristics: most common directory prefix, dominant symbol kinds, shared naming patterns (e.g., "parsing pipeline", "CLI presentation", "graph algorithms"). Store labels in `communities` output and `graph-enrichment.js`. Expose as `--labels` flag on `communities` command. | Intelligence | Raw community IDs (0, 1, 2…) are meaningless to agents and humans. Labels like "database layer" or "test utilities" make community output immediately actionable — agents can reference architectural groups by name instead of number | ✓ | ✓ | 3 | No | — | +| 98 | Hierarchical community decomposition | Run Leiden at multiple resolution levels (e.g., γ=0.5, 1.0, 2.0) and expose nested community structure — macro-clusters containing sub-clusters. The vendored optimiser already computes multi-level coarsening internally; surface it as `communities --hierarchical` with a tree output showing which fine-grained communities nest inside coarse ones. Store hierarchy in a `community_hierarchy` table or JSON metadata. | Architecture | Single-resolution communities force a choice between broad architectural groups and tight cohesion clusters. Hierarchical decomposition gives both — agents can zoom from "this is the graph subsystem" to "specifically the Leiden algorithm cluster within it" without re-running at different resolutions | ✓ | ✓ | 3 | No | — | +| 99 | Community-aware impact scoring | Factor community boundaries into `fn-impact` and `diff-impact` risk scoring. Changes that cross community boundaries are architecturally riskier than changes within a single community — they indicate coupling between modules that should be independent. Add `crossCommunityCount` to impact output and weight it in triage risk scoring. A function with blast radius 5 all within one community is lower risk than blast radius 5 spanning 4 communities. | Analysis | Directly improves blast radius accuracy — the core problem codegraph exists to solve. Community-crossing impact is a strong signal for architectural coupling that raw call-chain fan-out doesn't capture | ✓ | ✓ | 4 | No | — | + ### Tier 1f — Embeddings leverage (build on existing `embeddings` table) Symbol embeddings and FTS index are populated via `codegraph embed`. Currently only consumed by the `search` command. The vectors and `cosineSim()` function already exist. @@ -190,7 +200,7 @@ Items identified by the architectural audit (v3.1.4) that don't fit existing tie | 93 | ~~Shell completion for CLI~~ | ~~Commander supports shell completion but it's not implemented. `codegraph completion bash\|zsh\|fish` outputs the appropriate script. Basic UX gap for a CLI tool with 40+ commands.~~ | Developer Experience | ~~Tab completion makes the CLI discoverable — users find commands without reading docs. Reduces friction for new users and agents exploring available commands~~ | ✓ | ✓ | 2 | No | — | **PROMOTED** — Moved to ROADMAP Phase 7.11 | | 94 | VS Code extension | Replace the planned Web UI (removed from roadmap Phase 12) with a VS Code extension providing: webview-based graph visualization (reusing the existing `viewer.js` HTML), go-to-definition via graph edges, inline impact annotations on hover, integration with the MCP server for queries, and a sidebar panel for triage/audit results. VS Code is the right UI target for developer tools in 2026. | Visualization | Developers get graph intelligence directly in their editor — no context switching to a browser or terminal. Impact annotations on hover surface blast radius without running commands | ✗ | ✓ | 3 | No | — | | 95 | SARIF output for cycle detection | Add SARIF output format so cycle detection integrates with GitHub Code Scanning, showing issues inline in PRs. Currently planned for Phase 11 but could be delivered as early as Phase 7 since it's a pure output format addition. | CI | GitHub Code Scanning integration surfaces cycle violations directly in PR review — no separate CI step or comment bot needed | ✓ | ✓ | 3 | No | — | -| 96 | Fix README runtime dependency count | README claims "Only 3 runtime dependencies" but there are 5 — it omits `graphology` and `graphology-communities-louvain` which are in `package.json` `dependencies` (not optional). Correct to 5. | Documentation | Accuracy — users and contributors should be able to trust the README | ✓ | ✓ | 1 | No | — | +| 96 | ~~Fix README runtime dependency count~~ | ~~README claims "Only 3 runtime dependencies" but there are 5 — it omits `graphology` and `graphology-communities-louvain` which are in `package.json` `dependencies` (not optional). Correct to 5.~~ | Documentation | ~~Accuracy — users and contributors should be able to trust the README~~ | ✓ | ✓ | 1 | No | — | **DONE** — `graphology` and `graphology-communities-louvain` removed by vendoring Leiden algorithm. Runtime dependency count is now back to 3. | ### Tier 2 — Foundation-aligned, needs dependencies From c97b21795e1f3459218b0b989a310c84c942cd4e Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Fri, 20 Mar 2026 02:19:38 -0600 Subject: [PATCH 2/7] fix(backlog): renumber community items to IDs 100-102, fix Leiden text IDs 97-99 conflicted with existing entry #97 (unified multi-repo graph). Renumbered to 100-102. Also corrected "Leiden/Louvain" to "Leiden" in the section description for consistency with the rest of the PR. --- docs/roadmap/BACKLOG.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/roadmap/BACKLOG.md b/docs/roadmap/BACKLOG.md index 6dc2fe9b..3fed17cc 100644 --- a/docs/roadmap/BACKLOG.md +++ b/docs/roadmap/BACKLOG.md @@ -114,13 +114,13 @@ Co-change data captures historical coupling from git history. Currently only use ### Tier 1e′ — Community leverage (build on vendored Leiden algorithm) -Community detection uses a vendored Leiden/Louvain optimiser (`src/graph/algorithms/leiden/`) with full control over resolution, quality functions, and refinement. Currently only consumed by `communities` command and HTML viewer enrichment. These features deepen community awareness across the analysis pipeline. +Community detection uses a vendored Leiden optimiser (`src/graph/algorithms/leiden/`) with full control over resolution, quality functions, and refinement. Currently only consumed by `communities` command and HTML viewer enrichment. These features deepen community awareness across the analysis pipeline. | ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | |----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| -| 97 | Weighted community labels | Auto-generate a human-readable label for each community from its member files and symbols. Heuristics: most common directory prefix, dominant symbol kinds, shared naming patterns (e.g., "parsing pipeline", "CLI presentation", "graph algorithms"). Store labels in `communities` output and `graph-enrichment.js`. Expose as `--labels` flag on `communities` command. | Intelligence | Raw community IDs (0, 1, 2…) are meaningless to agents and humans. Labels like "database layer" or "test utilities" make community output immediately actionable — agents can reference architectural groups by name instead of number | ✓ | ✓ | 3 | No | — | -| 98 | Hierarchical community decomposition | Run Leiden at multiple resolution levels (e.g., γ=0.5, 1.0, 2.0) and expose nested community structure — macro-clusters containing sub-clusters. The vendored optimiser already computes multi-level coarsening internally; surface it as `communities --hierarchical` with a tree output showing which fine-grained communities nest inside coarse ones. Store hierarchy in a `community_hierarchy` table or JSON metadata. | Architecture | Single-resolution communities force a choice between broad architectural groups and tight cohesion clusters. Hierarchical decomposition gives both — agents can zoom from "this is the graph subsystem" to "specifically the Leiden algorithm cluster within it" without re-running at different resolutions | ✓ | ✓ | 3 | No | — | -| 99 | Community-aware impact scoring | Factor community boundaries into `fn-impact` and `diff-impact` risk scoring. Changes that cross community boundaries are architecturally riskier than changes within a single community — they indicate coupling between modules that should be independent. Add `crossCommunityCount` to impact output and weight it in triage risk scoring. A function with blast radius 5 all within one community is lower risk than blast radius 5 spanning 4 communities. | Analysis | Directly improves blast radius accuracy — the core problem codegraph exists to solve. Community-crossing impact is a strong signal for architectural coupling that raw call-chain fan-out doesn't capture | ✓ | ✓ | 4 | No | — | +| 100 | Weighted community labels | Auto-generate a human-readable label for each community from its member files and symbols. Heuristics: most common directory prefix, dominant symbol kinds, shared naming patterns (e.g., "parsing pipeline", "CLI presentation", "graph algorithms"). Store labels in `communities` output and `graph-enrichment.js`. Expose as `--labels` flag on `communities` command. | Intelligence | Raw community IDs (0, 1, 2…) are meaningless to agents and humans. Labels like "database layer" or "test utilities" make community output immediately actionable — agents can reference architectural groups by name instead of number | ✓ | ✓ | 3 | No | — | +| 101 | Hierarchical community decomposition | Run Leiden at multiple resolution levels (e.g., γ=0.5, 1.0, 2.0) and expose nested community structure — macro-clusters containing sub-clusters. The vendored optimiser already computes multi-level coarsening internally; surface it as `communities --hierarchical` with a tree output showing which fine-grained communities nest inside coarse ones. Store hierarchy in a `community_hierarchy` table or JSON metadata. | Architecture | Single-resolution communities force a choice between broad architectural groups and tight cohesion clusters. Hierarchical decomposition gives both — agents can zoom from "this is the graph subsystem" to "specifically the Leiden algorithm cluster within it" without re-running at different resolutions | ✓ | ✓ | 3 | No | — | +| 102 | Community-aware impact scoring | Factor community boundaries into `fn-impact` and `diff-impact` risk scoring. Changes that cross community boundaries are architecturally riskier than changes within a single community — they indicate coupling between modules that should be independent. Add `crossCommunityCount` to impact output and weight it in triage risk scoring. A function with blast radius 5 all within one community is lower risk than blast radius 5 spanning 4 communities. | Analysis | Directly improves blast radius accuracy — the core problem codegraph exists to solve. Community-crossing impact is a strong signal for architectural coupling that raw call-chain fan-out doesn't capture | ✓ | ✓ | 4 | No | — | ### Tier 1f — Embeddings leverage (build on existing `embeddings` table) From 7f4a0367f156b04a4b814191dfd01d00778a7a13 Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Fri, 20 Mar 2026 03:09:23 -0600 Subject: [PATCH 3/7] =?UTF-8?q?docs:=20rename=20Tier=201e=E2=80=B2=20to=20?= =?UTF-8?q?Tier=201e.1=20for=20ASCII=20compatibility?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/roadmap/BACKLOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/roadmap/BACKLOG.md b/docs/roadmap/BACKLOG.md index a895e0eb..4f18ed80 100644 --- a/docs/roadmap/BACKLOG.md +++ b/docs/roadmap/BACKLOG.md @@ -112,7 +112,7 @@ Co-change data captures historical coupling from git history. Currently only use | 54 | Co-change communities vs dependency communities | Compare Leiden communities from the dependency graph with clusters from co-change data. Files that co-change frequently but live in different dependency communities indicate hidden coupling or architectural drift. | Architecture | Surfaces coupling that the static graph can't see — two modules may have no import relationship but always change together due to shared assumptions | ✓ | ✓ | 3 | No | — | | 55 | Missing co-change partner warning in `check` | When `--staged` changes touch file A but not its historical partner file B (high Jaccard), emit a warning: "file A historically co-changes with file B — did you forget to update it?" | CI | Catches incomplete changes in CI — the most common source of subtle bugs is changing one file in a coupled pair but forgetting the other | ✓ | ✓ | 4 | No | — | -### Tier 1e′ — Community leverage (build on vendored Leiden algorithm) +### Tier 1e.1 — Community leverage (build on vendored Leiden algorithm) Community detection uses a vendored Leiden optimiser (`src/graph/algorithms/leiden/`) with full control over resolution, quality functions, and refinement. Currently only consumed by `communities` command and HTML viewer enrichment. These features deepen community awareness across the analysis pipeline. From 61b11c9788d54fc86931ce96f8a34d890bf489e6 Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Fri, 20 Mar 2026 04:17:18 -0600 Subject: [PATCH 4/7] docs: fix premature Leiden references in backlog The section description referenced src/graph/algorithms/leiden/ which does not exist yet (pending PR #545). Item #96 was incorrectly marked DONE when graphology is still a live dependency. Updated section to be forward-looking and reverted #96 to BLOCKED on #545. --- docs/roadmap/BACKLOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/roadmap/BACKLOG.md b/docs/roadmap/BACKLOG.md index 4f18ed80..3f0d8ea7 100644 --- a/docs/roadmap/BACKLOG.md +++ b/docs/roadmap/BACKLOG.md @@ -114,7 +114,7 @@ Co-change data captures historical coupling from git history. Currently only use ### Tier 1e.1 — Community leverage (build on vendored Leiden algorithm) -Community detection uses a vendored Leiden optimiser (`src/graph/algorithms/leiden/`) with full control over resolution, quality functions, and refinement. Currently only consumed by `communities` command and HTML viewer enrichment. These features deepen community awareness across the analysis pipeline. +Community detection will use a vendored Leiden optimiser (PR #545) with full control over resolution, quality functions, and refinement. Currently consumed by `communities` command and HTML viewer enrichment via `graphology-communities-louvain`. These features deepen community awareness across the analysis pipeline once the Leiden vendoring lands. | ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | |----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| @@ -200,7 +200,7 @@ Items identified by the architectural audit (v3.1.4) that don't fit existing tie | 93 | ~~Shell completion for CLI~~ | ~~Commander supports shell completion but it's not implemented. `codegraph completion bash\|zsh\|fish` outputs the appropriate script. Basic UX gap for a CLI tool with 40+ commands.~~ | Developer Experience | ~~Tab completion makes the CLI discoverable — users find commands without reading docs. Reduces friction for new users and agents exploring available commands~~ | ✓ | ✓ | 2 | No | — | **PROMOTED** — Moved to ROADMAP Phase 7.11 | | 94 | VS Code extension | Replace the planned Web UI (removed from roadmap Phase 12) with a VS Code extension providing: webview-based graph visualization (reusing the existing `viewer.js` HTML), go-to-definition via graph edges, inline impact annotations on hover, integration with the MCP server for queries, and a sidebar panel for triage/audit results. VS Code is the right UI target for developer tools in 2026. | Visualization | Developers get graph intelligence directly in their editor — no context switching to a browser or terminal. Impact annotations on hover surface blast radius without running commands | ✗ | ✓ | 3 | No | — | | 95 | SARIF output for cycle detection | Add SARIF output format so cycle detection integrates with GitHub Code Scanning, showing issues inline in PRs. Currently planned for Phase 11 but could be delivered as early as Phase 7 since it's a pure output format addition. | CI | GitHub Code Scanning integration surfaces cycle violations directly in PR review — no separate CI step or comment bot needed | ✓ | ✓ | 3 | No | — | -| 96 | ~~Fix README runtime dependency count~~ | ~~README claims "Only 3 runtime dependencies" but there are 5 — it omits `graphology` and `graphology-communities-louvain` which are in `package.json` `dependencies` (not optional). Correct to 5.~~ | Documentation | ~~Accuracy — users and contributors should be able to trust the README~~ | ✓ | ✓ | 1 | No | — | **DONE** — `graphology` and `graphology-communities-louvain` removed by vendoring Leiden algorithm. Runtime dependency count is now back to 3. | +| 96 | Fix README runtime dependency count | README claims "Only 3 runtime dependencies" but there are 5 — it omits `graphology` and `graphology-communities-louvain` which are in `package.json` `dependencies` (not optional). Correct to 5. | Documentation | Accuracy — users and contributors should be able to trust the README | ✓ | ✓ | 1 | No | #545 | **BLOCKED** — Will be resolved when PR #545 (vendor Leiden) lands, removing `graphology` and `graphology-communities-louvain`. | ### Tier 2 — Foundation-aligned, needs dependencies From 9217342fdef934aaacbb6cfe7f6ecf6feb5b1646 Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Fri, 20 Mar 2026 04:23:14 -0600 Subject: [PATCH 5/7] docs: add #545 dependency to community leverage items 100-102 --- docs/roadmap/BACKLOG.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/roadmap/BACKLOG.md b/docs/roadmap/BACKLOG.md index 3f0d8ea7..45145a8c 100644 --- a/docs/roadmap/BACKLOG.md +++ b/docs/roadmap/BACKLOG.md @@ -118,9 +118,9 @@ Community detection will use a vendored Leiden optimiser (PR #545) with full con | ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | |----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| -| 100 | Weighted community labels | Auto-generate a human-readable label for each community from its member files and symbols. Heuristics: most common directory prefix, dominant symbol kinds, shared naming patterns (e.g., "parsing pipeline", "CLI presentation", "graph algorithms"). Store labels in `communities` output and `graph-enrichment.js`. Expose as `--labels` flag on `communities` command. | Intelligence | Raw community IDs (0, 1, 2…) are meaningless to agents and humans. Labels like "database layer" or "test utilities" make community output immediately actionable — agents can reference architectural groups by name instead of number | ✓ | ✓ | 3 | No | — | -| 101 | Hierarchical community decomposition | Run Leiden at multiple resolution levels (e.g., γ=0.5, 1.0, 2.0) and expose nested community structure — macro-clusters containing sub-clusters. The vendored optimiser already computes multi-level coarsening internally; surface it as `communities --hierarchical` with a tree output showing which fine-grained communities nest inside coarse ones. Store hierarchy in a `community_hierarchy` table or JSON metadata. | Architecture | Single-resolution communities force a choice between broad architectural groups and tight cohesion clusters. Hierarchical decomposition gives both — agents can zoom from "this is the graph subsystem" to "specifically the Leiden algorithm cluster within it" without re-running at different resolutions | ✓ | ✓ | 3 | No | — | -| 102 | Community-aware impact scoring | Factor community boundaries into `fn-impact` and `diff-impact` risk scoring. Changes that cross community boundaries are architecturally riskier than changes within a single community — they indicate coupling between modules that should be independent. Add `crossCommunityCount` to impact output and weight it in triage risk scoring. A function with blast radius 5 all within one community is lower risk than blast radius 5 spanning 4 communities. | Analysis | Directly improves blast radius accuracy — the core problem codegraph exists to solve. Community-crossing impact is a strong signal for architectural coupling that raw call-chain fan-out doesn't capture | ✓ | ✓ | 4 | No | — | +| 100 | Weighted community labels | Auto-generate a human-readable label for each community from its member files and symbols. Heuristics: most common directory prefix, dominant symbol kinds, shared naming patterns (e.g., "parsing pipeline", "CLI presentation", "graph algorithms"). Store labels in `communities` output and `graph-enrichment.js`. Expose as `--labels` flag on `communities` command. | Intelligence | Raw community IDs (0, 1, 2…) are meaningless to agents and humans. Labels like "database layer" or "test utilities" make community output immediately actionable — agents can reference architectural groups by name instead of number | ✓ | ✓ | 3 | No | #545 | +| 101 | Hierarchical community decomposition | Run Leiden at multiple resolution levels (e.g., γ=0.5, 1.0, 2.0) and expose nested community structure — macro-clusters containing sub-clusters. The vendored optimiser already computes multi-level coarsening internally; surface it as `communities --hierarchical` with a tree output showing which fine-grained communities nest inside coarse ones. Store hierarchy in a `community_hierarchy` table or JSON metadata. | Architecture | Single-resolution communities force a choice between broad architectural groups and tight cohesion clusters. Hierarchical decomposition gives both — agents can zoom from "this is the graph subsystem" to "specifically the Leiden algorithm cluster within it" without re-running at different resolutions | ✓ | ✓ | 3 | No | #545 | +| 102 | Community-aware impact scoring | Factor community boundaries into `fn-impact` and `diff-impact` risk scoring. Changes that cross community boundaries are architecturally riskier than changes within a single community — they indicate coupling between modules that should be independent. Add `crossCommunityCount` to impact output and weight it in triage risk scoring. A function with blast radius 5 all within one community is lower risk than blast radius 5 spanning 4 communities. | Analysis | Directly improves blast radius accuracy — the core problem codegraph exists to solve. Community-crossing impact is a strong signal for architectural coupling that raw call-chain fan-out doesn't capture | ✓ | ✓ | 4 | No | #545 | ### Tier 1f — Embeddings leverage (build on existing `embeddings` table) From e87760ce400ffb6ea5fd39919ca21455aa3c7b4f Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Fri, 20 Mar 2026 13:09:16 -0600 Subject: [PATCH 6/7] docs: add #545 dependency to item #54 for Leiden consistency --- docs/roadmap/BACKLOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/roadmap/BACKLOG.md b/docs/roadmap/BACKLOG.md index 45145a8c..6259015a 100644 --- a/docs/roadmap/BACKLOG.md +++ b/docs/roadmap/BACKLOG.md @@ -109,7 +109,7 @@ Co-change data captures historical coupling from git history. Currently only use | ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | |----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| | 53 | Co-change coupling in triage | Files with high co-change Jaccard scores are maintenance risks — changing one always requires changing the other. Add `coChangeCoupling` as a triage scoring dimension using the max Jaccard score for each file. | Intelligence | Triage surfaces tightly coupled file pairs that static dependency analysis may miss — hidden coupling from shared business logic or implicit contracts | ✓ | ✓ | 4 | No | — | -| 54 | Co-change communities vs dependency communities | Compare Leiden communities from the dependency graph with clusters from co-change data. Files that co-change frequently but live in different dependency communities indicate hidden coupling or architectural drift. | Architecture | Surfaces coupling that the static graph can't see — two modules may have no import relationship but always change together due to shared assumptions | ✓ | ✓ | 3 | No | — | +| 54 | Co-change communities vs dependency communities | Compare Leiden communities from the dependency graph with clusters from co-change data. Files that co-change frequently but live in different dependency communities indicate hidden coupling or architectural drift. | Architecture | Surfaces coupling that the static graph can't see — two modules may have no import relationship but always change together due to shared assumptions | ✓ | ✓ | 3 | No | #545 | | 55 | Missing co-change partner warning in `check` | When `--staged` changes touch file A but not its historical partner file B (high Jaccard), emit a warning: "file A historically co-changes with file B — did you forget to update it?" | CI | Catches incomplete changes in CI — the most common source of subtle bugs is changing one file in a coupled pair but forgetting the other | ✓ | ✓ | 4 | No | — | ### Tier 1e.1 — Community leverage (build on vendored Leiden algorithm) From c52a75a3c4208c76f4c734ad07e13f2d822c3e6e Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Fri, 20 Mar 2026 13:16:49 -0600 Subject: [PATCH 7/7] docs: mark #96 as SUPERSEDED instead of BLOCKED MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Once #545 merges, the README's "3 runtime dependencies" claim becomes correct automatically — no further action needed. BLOCKED implied someone still needs to act on the item after #545 lands. --- docs/roadmap/BACKLOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/roadmap/BACKLOG.md b/docs/roadmap/BACKLOG.md index 6259015a..36c61d81 100644 --- a/docs/roadmap/BACKLOG.md +++ b/docs/roadmap/BACKLOG.md @@ -200,7 +200,7 @@ Items identified by the architectural audit (v3.1.4) that don't fit existing tie | 93 | ~~Shell completion for CLI~~ | ~~Commander supports shell completion but it's not implemented. `codegraph completion bash\|zsh\|fish` outputs the appropriate script. Basic UX gap for a CLI tool with 40+ commands.~~ | Developer Experience | ~~Tab completion makes the CLI discoverable — users find commands without reading docs. Reduces friction for new users and agents exploring available commands~~ | ✓ | ✓ | 2 | No | — | **PROMOTED** — Moved to ROADMAP Phase 7.11 | | 94 | VS Code extension | Replace the planned Web UI (removed from roadmap Phase 12) with a VS Code extension providing: webview-based graph visualization (reusing the existing `viewer.js` HTML), go-to-definition via graph edges, inline impact annotations on hover, integration with the MCP server for queries, and a sidebar panel for triage/audit results. VS Code is the right UI target for developer tools in 2026. | Visualization | Developers get graph intelligence directly in their editor — no context switching to a browser or terminal. Impact annotations on hover surface blast radius without running commands | ✗ | ✓ | 3 | No | — | | 95 | SARIF output for cycle detection | Add SARIF output format so cycle detection integrates with GitHub Code Scanning, showing issues inline in PRs. Currently planned for Phase 11 but could be delivered as early as Phase 7 since it's a pure output format addition. | CI | GitHub Code Scanning integration surfaces cycle violations directly in PR review — no separate CI step or comment bot needed | ✓ | ✓ | 3 | No | — | -| 96 | Fix README runtime dependency count | README claims "Only 3 runtime dependencies" but there are 5 — it omits `graphology` and `graphology-communities-louvain` which are in `package.json` `dependencies` (not optional). Correct to 5. | Documentation | Accuracy — users and contributors should be able to trust the README | ✓ | ✓ | 1 | No | #545 | **BLOCKED** — Will be resolved when PR #545 (vendor Leiden) lands, removing `graphology` and `graphology-communities-louvain`. | +| 96 | Fix README runtime dependency count | README claims "Only 3 runtime dependencies" but there are 5 — it omits `graphology` and `graphology-communities-louvain` which are in `package.json` `dependencies` (not optional). Correct to 5. | Documentation | Accuracy — users and contributors should be able to trust the README | ✓ | ✓ | 1 | No | #545 | **SUPERSEDED** — PR #545 removes `graphology` and `graphology-communities-louvain`, making the README's "3 runtime dependencies" claim correct again. No further action needed once #545 merges. | ### Tier 2 — Foundation-aligned, needs dependencies