docs: add dead symbols, community drift, and function cycles to audit/roadmap

[carlos-alm]

Summary

• Add three missing items to generated/architecture.md (sections 18-20) and docs/roadmap/ROADMAP.md (items 3.14-3.16) addressing gaps found during self-analysis:
  • Dead symbols: 221 dead symbols (27%) — audit pass, max-dead-ratio manifesto rule, target <10%
  • Community drift: 40% of files in wrong logical module — directory restructuring, max-community-drift rule, target <20%
  • Function cycles: 9 circular deps — classify, break accidental ones, no-new-cycles CI gate, target 0
• Architecture priority table updated from 21 to 24 items (new docs: cold architectural audit + publish workflow fix #17-19)
• Roadmap Phase 3 overview updated to include new deliverables

Test plan

• Verify architecture.md renders correctly with new sections 18-20
• Verify ROADMAP.md sections 3.14-3.16 are properly numbered and 3.17 renumbering is consistent
• Confirm Phase 3 overview table row includes the three new deliverables

[claude]

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

---

PR Review Complete ⭐⭐⭐⭐☆ (4/5)

Root Cause Analysis

Problem Being Solved: Documents three critical architectural health gaps discovered during codegraph's self-analysis that weren't previously tracked in roadmap or architecture docs.

Why This Approach: The PR addresses real gaps by adding concrete metrics and actionable items rather than hiding symptoms. Each item includes:

• Current measured state (27% dead code, 40% drift, 9 cycles)
• Target goals (reduce to <10%, <20%, 0 respectively)
• Implementation approach (audit passes, manifesto rules, CI gates)

Risk Assessment: Very low risk - this is pure documentation with no code changes.

Critical Concerns

None. The additions are well-researched and align with the existing architecture audit's findings.

Detailed Review

✅ Phase 1: Root Cause Analysis - PASS

This PR addresses real architectural health gaps rather than hiding symptoms:

• The three items (dead symbols, community drift, function cycles) are concrete metrics discovered through actual codebase analysis
• Each includes measured current state and specific improvement targets
• The approach focuses on cleanup + prevention rather than workarounds

✅ Phase 2: Configuration Change Detection - PASS

No configuration changes - pure documentation additions.

✅ Phase 3: Test Integrity - PASS

No test modifications - documentation only.

✅ Phase 4: Code Quality Assessment

Excellent technical depth:

• Dead symbols section (3.14): Correctly identifies the dual-function pattern and 120+ speculative exports as root causes. Proposes systematic cleanup + manifesto rule prevention.
• Community drift section (3.15): 40% drift metric indicates misaligned directory structure. Proposes restructuring + CI tracking.
• Function cycles section (3.16): Distinguishes intentional recursion from accidental coupling. Proposes classification + targeted refactoring.

Well-integrated additions:

• Sections 18-20 in architecture.md flow naturally from existing content
• ROADMAP.md items 3.14-3.16 fit logically in Phase 3 architectural refactoring
• Phase 3 overview correctly updated to include all three new deliverables
• Priority table properly renumbered from docs: cold architectural audit + publish workflow fix #17-19 to docs: cold architectural audit + publish workflow fix #17-21

Content accuracy verified: The metrics cited (27% dead symbols, 40% community drift, 9 function cycles) align with findings mentioned in the existing architecture audit, indicating these numbers come from actual analysis rather than speculation.

Minor observations:

• Documentation-heavy PR (+177 lines) but entirely appropriate for capturing discovered architectural debt
• No redundancy with existing content - these are genuinely new gaps being documented

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: High-quality documentation that systematically captures real architectural health issues with concrete metrics, root cause analysis, and actionable improvement plans. This fills genuine gaps in the project's self-documentation without any risk of breaking changes. The -1 star is only because this is "just" documentation rather than implementation, but it's exactly the right documentation at the right level of detail.

Recommendation: Merge this PR to establish proper tracking of these architectural health metrics before they get worse.

[greptile-apps]

Greptile Summary

Documentation update adding three architectural concerns discovered during self-analysis.

Changes:

• Added sections for dead symbol cleanup (27% dead code), community drift reduction (40% misplaced files), and function-level cycle breaking (9 circular dependencies)
• Updated ROADMAP.md Phase 3 overview and added sections 3.14-3.16 with deliverables and targets
• Updated generated/architecture.md with sections 18-20 and expanded priority table from 21 to 24 items
• All metrics, targets, and cross-references are consistent between both files
• Section numbering properly maintained (3.14-3.17 in roadmap, docs: cold architectural audit + publish workflow fix #17-24 in priority table)

Confidence Score: 5/5

• This PR is safe to merge with no risk
• Documentation-only changes that add well-structured content with consistent formatting, accurate cross-references, and aligned metrics between files. No code changes, no breaking changes, no security concerns.
• No files require special attention

Important Files Changed

Filename	Overview
docs/roadmap/ROADMAP.md	Added sections 3.14-3.16 for dead symbols, community drift, and function cycles; renumbered 3.17; updated Phase 3 overview
generated/architecture.md	Added sections 18-20 for three new architectural concerns; updated priority table from 21 to 24 items with consistent renumbering

_{Last reviewed commit: 8f506ff}

[greptile-apps]

_{2 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}