docs(backlog): add Weft-inspired items #103 and #104

[carlos-alm]

Summary

• chore(release): v2.4.0 #103 — Recursively foldable graph viewer (Tier 1g): Directory-level expand/collapse in codegraph plot so large graphs are navigable instead of spaghetti. --collapsed and --expand-depth N flags.
• docs: add dogfood report for v2.3.1-dev.1aeea34 #104 — Architecture-as-code validation gate (Tier 1j): Unify boundaries + manifesto + check into a single architecture{} config block with check --architecture as a one-command CI gate.

Both ideas inspired by WeaveMindAI/weft design principles (recursive composability and compile-time architecture validation). Scored as zero-dep, foundation-aligned, problem-fit 4, non-breaking.

Test plan

• Verify BACKLOG.md renders correctly on GitHub (table formatting)
• Confirm IDs 103/104 don't collide with existing entries

[claude]

Claude finished @carlos-alm's task —— View job

---

PR Review Complete ✅

Todo List

• Read the modified BACKLOG.md file
• Phase 1: Root Cause Analysis
• Phase 2: Configuration Change Detection
• Phase 3: Test Integrity
• Phase 4: Code Quality
• Phase 5: Backlog Compliance Assessment
• Provide Final Assessment with rating

---

Root Cause Analysis

Problem Being Solved: Adding two new feature requests (#103 and #104) to the product backlog inspired by WeaveMindAI/weft design principles.

Why This Approach: This is pure documentation — adding planned features to the backlog for future prioritization. No code changes or workarounds.

Risk Assessment: Zero risk. Documentation-only change with no impact on functionality.

---

Phase 2-4 Analysis

Configuration Changes: ❌ None — this is documentation-only
Test Changes: ❌ None — this is documentation-only
Code Quality: ❌ Not applicable — this is documentation-only

The PR adds exactly 2 lines to docs/roadmap/BACKLOG.md:

Line 161 (ID #103):

| 103 | Recursively foldable graph viewer | Add directory-level collapsing to the interactive HTML viewer (`codegraph plot`). Any directory group collapses into a single node showing only its external edges (imports in/out); click to expand into constituent symbols. Recursive: collapsed groups contain collapsed sub-groups. Inspired by Weft's "recursively foldable" design — a 100-node system still looks like 5 blocks at the top level. Implementation: extend `graph-enrichment.js` to compute directory-level aggregate edges, extend `viewer.js` to support expand/collapse toggling on `subgraph` cluster nodes (vis-network supports compound nodes via `clustering`). Add `--collapsed` flag to start fully collapsed, `--expand-depth N` to control initial expansion level. | Visualization | Large codebase graphs are currently unusable — hundreds of nodes render as spaghetti. Directory-level collapsing makes `codegraph plot` viable for real projects by letting users zoom from architecture overview to file-level detail interactively. Directly improves the "orientation" problem — agents and humans see module boundaries at a glance | ✓ | ✓ | 4 | No | — |

Line 204 (ID #104):

| 104 | Architecture-as-code validation gate | Elevate `codegraph check` + `manifesto` + `boundaries` into a unified "architecture-as-code" validation system. Define architectural invariants in `.codegraphrc.json` under a new `architecture{}` block: layer rules (existing `boundaries`), dependency direction rules ("domain must not import infrastructure"), module cohesion thresholds ("community drift score < 0.3"), fan-in caps per layer ("adapters must have fan-in < 5"), and cross-cutting constraints ("no file may import from more than 3 top-level directories"). `codegraph check --architecture` validates all rules in one pass, exit code 1 on any violation. Framing inspired by Weft's design principle "if it compiles, the architecture is sound" — the goal is that passing `codegraph check` in CI means the architecture is structurally valid, not just that individual metrics are below thresholds. Builds entirely on existing `boundaries`, `manifesto`, `communities`, and `check` infrastructure — the work is unification and config surface, not new analysis. | Architecture | Current architecture validation is scattered across three features (`boundaries`, `manifesto`, `check`) with separate configs and no unified mental model. A single `architecture{}` config block with a single `check --architecture` command makes it practical for teams to adopt architectural CI gates — the barrier today is config complexity, not capability. Directly prevents architectural decay by making violations as visible as test failures | ✓ | ✓ | 4 | No | — |

---

Backlog Compliance

• Zero-dep: ✓ — Both features build entirely on existing infrastructure (tree-sitter AST, SQLite, vis-network)
• Foundation-aligned: ✓ — Enhances developer planning/navigation tools without violating any principles
• Problem-fit: 4 — Both directly improve agent orientation: chore(release): v2.4.0 #103 makes large graphs navigable, docs: add dogfood report for v2.3.1-dev.1aeea34 #104 makes architecture validation practical
• Breaking: No — Purely additive features with new flags and config blocks
• Tier: 1 (zero-dep ✓ + foundation-aligned ✓)

---

Critical Concerns

None. This is a straightforward documentation update that:

1. ✅ Follows the exact table format used throughout BACKLOG.md
2. ✅ Uses sequential IDs (103, 104) without collisions
3. ✅ Provides appropriate tier classification (Tier 1g for visualization improvements)
4. ✅ Includes detailed implementation plans and benefit descriptions
5. ✅ Correctly scores both features as zero-dep, foundation-aligned, problem-fit 4, non-breaking

The entries are well-researched and properly scoped — both build on existing capabilities rather than requiring new dependencies.

---

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: Clean documentation addition that follows project conventions precisely. Both features are well-justified improvements to core functionality that directly address the "lost AI agents" problem codegraph exists to solve. No technical concerns since this is documentation-only.

Minor note: The test plan mentions verifying no ID collisions — confirmed that 103/104 are the next sequential IDs after 102 in Tier 1e.1.

---

[greptile-apps]

Greptile Summary

This PR adds two Weft-inspired planning entries to BACKLOG.md: item #103 (recursively foldable codegraph plot viewer, Tier 1g) and item #104 (unified architecture-as-code validation gate, Tier 1j). The previously flagged stale .js file references in #103 were corrected in this commit.

Confidence Score: 5/5

Documentation-only change; safe to merge with one minor tier-provenance clarification worth addressing

All findings are P2 (style/documentation accuracy). No code changes, no logic errors, no security concerns. The prior P1 comment about stale .js references was resolved in this commit.

No files require special attention

Important Files Changed

Filename	Overview
docs/roadmap/BACKLOG.md	Adds two new backlog entries (#103 foldable graph viewer in Tier 1g, #104 architecture-as-code gate in Tier 1j); stale .js file reference issue from prior review was resolved; minor tier-provenance question on #104

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph id103["#103 — Foldable Graph Viewer (Tier 1g)"]
        A["graph-enrichment.ts\ncompute directory-level aggregate edges"] --> C["viewer.ts\nexpand/collapse toggling on cluster nodes"]
        B["vis-network clustering API"] --> C
        C --> D["codegraph plot --collapsed / --expand-depth N"]
    end

    subgraph id104["#104 — Architecture-as-Code Gate (Tier 1j)"]
        E["boundaries\nlayer rules"] --> H["architecture block in .codegraphrc.json"]
        F["manifesto\ncohesion thresholds"] --> H
        G["check\nCI predicates"] --> H
        H --> I["codegraph check --architecture\nexit 1 on violation"]
    end

Loading

_{Reviews (2): Last reviewed commit: "fix(backlog): correct stale .js file ref..." | Re-trigger Greptile}

[greptile-apps]

Stale .js file references in implementation notes

The implementation notes for item 103 reference graph-enrichment.js and viewer.js, but the codebase has already migrated these to TypeScript — the actual files are src/features/graph-enrichment.ts and src/presentation/viewer.ts. Using the wrong extensions will confuse the implementer who follows this ticket.

Suggested change

| 103 | Recursively foldable graph viewer | Add directory-level collapsing to the interactive HTML viewer (`codegraph plot`). Any directory group collapses into a single node showing only its external edges (imports in/out); click to expand into constituent symbols. Recursive: collapsed groups contain collapsed sub-groups. Inspired by Weft's "recursively foldable" design — a 100-node system still looks like 5 blocks at the top level. Implementation: extend `graph-enrichment.js` to compute directory-level aggregate edges, extend `viewer.js` to support expand/collapse toggling on `subgraph` cluster nodes (vis-network supports compound nodes via `clustering`). Add `--collapsed` flag to start fully collapsed, `--expand-depth N` to control initial expansion level. | Visualization | Large codebase graphs are currently unusable — hundreds of nodes render as spaghetti. Directory-level collapsing makes `codegraph plot` viable for real projects by letting users zoom from architecture overview to file-level detail interactively. Directly improves the "orientation" problem — agents and humans see module boundaries at a glance | ✓ | ✓ | 4 | No | — |

| 103 | Recursively foldable graph viewer | Add directory-level collapsing to the interactive HTML viewer (`codegraph plot`). Any directory group collapses into a single node showing only its external edges (imports in/out); click to expand into constituent symbols. Recursive: collapsed groups contain collapsed sub-groups. Inspired by Weft's "recursively foldable" design — a 100-node system still looks like 5 blocks at the top level. Implementation: extend `graph-enrichment.ts` to compute directory-level aggregate edges, extend `viewer.ts` to support expand/collapse toggling on `subgraph` cluster nodes (vis-network supports compound nodes via `clustering`). Add `--collapsed` flag to start fully collapsed, `--expand-depth N` to control initial expansion level. | Visualization | Large codebase graphs are currently unusable — hundreds of nodes render as spaghetti. Directory-level collapsing makes `codegraph plot` viable for real projects by letting users zoom from architecture overview to file-level detail interactively. Directly improves the "orientation" problem — agents and humans see module boundaries at a glance | ✓ | ✓ | 4 | No | — |

[carlos-alm]

Fixed in 0d13263 — changed graph-enrichment.js to graph-enrichment.ts and viewer.js to viewer.ts in item #103.

[carlos-alm]

@greptileai