docs: add Phase 5 (Runtime & Extensibility) to roadmap

[carlos-alm]

Summary

• Moved the 8 deferred items from Phase 3.16 ("Remaining Items") into a new Phase 5 — Runtime & Extensibility, positioned after Phase 4 (TypeScript Migration)
• Each item expanded with detailed descriptions, rationale, affected files, and implementation notes
• Renumbered all subsequent phases (old 5→6, 6→7, 7→8, 8→9, 9→10) with cross-references updated throughout

New Phase 5 sub-items

• 5.1 Event-driven pipeline (streaming, progress, cancellation)
• 5.2 Unified engine interface (Strategy pattern)
• 5.3 Subgraph export filtering (--focus, --depth)
• 5.4 Transitive import-aware confidence
• 5.5 Query result caching (LRU/TTL)
• 5.6 Configuration profiles (--profile)
• 5.7 Pagination standardization (SQL LIMIT/OFFSET)
• 5.8 Plugin system for custom commands

Test plan

• Verify all internal cross-references resolve correctly (phase numbers, dependency annotations)
• Confirm overview table and dependency graph are consistent with section headers

[claude]

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

---

Review Complete ⭐⭐⭐⭐☆

Root Cause Analysis

Problem Being Solved: The PR addresses organizational debt in the roadmap. Phase 3.16 had become a "catch-all" section with 8 important but lower-priority items that lacked proper detailed descriptions and implementation guidance.

Why This Approach: Creating a dedicated Phase 5 with full specifications makes these items:

• More actionable for future implementation
• Better integrated with the overall roadmap structure
• Positioned after Phase 4 (TypeScript) which provides type safety for plugin contracts and streaming APIs

Risk Assessment: ✅ Low Risk - Pure documentation reorganization with no code changes.

Configuration & Test Analysis

✅ No configuration changes - Documentation-only PR
✅ No test modifications - Documentation-only PR
✅ No dependency changes - Documentation-only PR

Code Quality Review

✅ Structure: All cross-references correctly updated (overview table, dependency graph, phase numbering)
✅ Content Quality: Each Phase 5 item expanded from bullet points to detailed subsections with:

• Clear implementation rationale
• Affected files specified
• Technical approach outlined
• Dependencies and timing explained

✅ Consistency: Phase numbering cascade handled correctly (5→6, 6→7, 7→8, 8→9, 9→10)

Backlog Compliance

• Zero-dep: ✅ N/A (documentation only)
• Foundation-aligned: ✅ Fully aligned - organizes existing planned features without violating any principles
• Problem-fit: 4/5 - Improves organizational clarity for features that directly address AI agent needs (caching, streaming, plugin extensibility)
• Breaking: ✅ No - purely additive documentation structure
• Tier: Tier 1 (foundation-aligned ✓ + zero-dep ✓)

Critical Concerns

None. This is well-executed documentation cleanup that:

• Makes deferred features more implementable
• Maintains full structural consistency
• Provides clear rationale for the reorganization
• Positions runtime improvements after architectural foundations

Cross-Reference Verification ✅

• Overview table: All 10 phases correctly numbered with updated links
• Dependency graph: Proper phase ordering maintained
• Internal references: All Phase X mentions updated consistently
• Section headers: All anchors match table links

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: High-quality documentation reorganization that transforms a "miscellaneous items" section into a properly structured phase. The expanded descriptions make these features more actionable for future implementation. No technical concerns.

Minor enhancement opportunity: Consider adding rough effort estimates or complexity ratings to the new Phase 5 items to help with future sprint planning, but this is not blocking.

---

[greptile-apps]

Greptile Summary

This PR inserts a new Phase 5 — Runtime & Extensibility into the roadmap (8 sub-items covering event-driven pipeline, unified engine strategy, subgraph export filtering, transitive import confidence, query caching, configuration profiles, pagination, and a plugin system), then renumbers all subsequent phases (old 5→6 through 9→10) with cross-references updated throughout.

• All phase-level anchor links in the overview table correctly point to the renamed section headers (#phase-6--intelligent-embeddings, etc.)
• All **Depends on:** annotations within Phases 6–10 are correctly updated (e.g. 5.1 → 6.1, 5.4 → 6.4, 8.1 → 9.1)
• The ASCII dependency graph is correctly updated, including the Phases 1-6 → Phase 9 → Phases 1-7 → Phase 10 line
• Phase 3 section renaming (old 3.17 CLI Composability → 3.16) is clean; no orphan references remain
• docs/roadmap/BACKLOG.md has a forward-reference note ("After Phase 4, also preserves embeddings and semantic metadata") that was not updated by this PR. With embeddings now in Phase 6 instead of Phase 5, the note is still technically correct (Phase 4 precedes Phase 6) but could be made more precise — however this is out of scope for this PR
• One minor diagram inconsistency: Phase 5 appears as a terminal node in the ASCII dependency graph with no downstream arrow, while Phases 1-7 → Phase 10 only captures it implicitly (see inline comment)

Confidence Score: 4/5

• Safe to merge — documentation-only change with all cross-references correctly updated; one minor diagram presentation issue noted.
• All phase number references, anchor links, "Depends on" annotations, and the ASCII dependency graph are consistently updated. The only imprecision is that Phase 5 has no explicit outgoing arrow in the dependency diagram, which is a presentation clarity issue rather than a correctness bug.
• No files require special attention beyond the minor dependency diagram clarification in docs/roadmap/ROADMAP.md.

Important Files Changed

Filename	Overview
docs/roadmap/ROADMAP.md	New Phase 5 (Runtime & Extensibility) correctly inserted with 8 well-documented sub-items; all phase number cross-references (5→6, 6→7, 7→8, 8→9, 9→10) and "Depends on" annotations updated consistently throughout. One minor observation: Phase 5 has no explicit outgoing arrows in the ASCII dependency diagram, while "Phases 1-7 → Phase 10" only covers it implicitly.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    P1["Phase 1 — Rust Core ✅"] --> P2["Phase 2 — Foundation Hardening ✅"]
    P2 --> P25["Phase 2.5 — Analysis Expansion ✅"]
    P25 --> P27["Phase 2.7 — Deep Analysis ✅"]
    P27 --> P3["Phase 3 — Architectural Refactoring 🔄"]
    P3 --> P4["Phase 4 — TypeScript Migration"]
    P4 --> P5["Phase 5 — Runtime & Extensibility 🆕"]
    P4 --> P6["Phase 6 — Intelligent Embeddings"]
    P4 --> P8["Phase 8 — Expanded Language Support"]
    P4 --> P9["Phase 9 — GitHub Integration & CI"]
    P6 --> P7["Phase 7 — Natural Language Queries"]
    P6 -- "risk_score, side_effects" --> P9
    P5 --> P10["Phase 10 — Interactive Visualization & Advanced Features"]
    P6 --> P10
    P7 --> P10
    P8 --> P10
    P9 --> P10

    style P5 fill:#d4edda,stroke:#28a745,color:#000

Loading

_{Last reviewed commit: 6eadbc6}

[greptile-apps]

Missed renumber: 9.6 → 10.6

This section was originally 9.6 under old Phase 9 (Visualization & Advanced). Since old Phase 9 became Phase 10, this should be 10.6. It's the only sub-item that wasn't renumbered in the PR.

Suggested change

	### 9.6 -- Auto-generated Docstrings
	### 10.6 -- Auto-generated Docstrings

[carlos-alm]

Fixed in 6eadbc6 — renumbered 9.6 to 10.6 for Auto-generated Docstrings.

[carlos-alm]

@greptileai