fix(docs): sync README roadmap ordering with ROADMAP.md

[carlos-alm]

Summary

• Fix README roadmap phase ordering to match docs/roadmap/ROADMAP.md (source of truth)
  • Moved Expanded Language Support from position 12 to 9 (Phase 7)
  • Added missing Quality, Security & Technical Debt phase (Phase 9)
  • Renamed Visualization & Advanced → Advanced Features (Phase 13)
  • Renumbered all subsequent phases to match ROADMAP.md
• Add roadmap ordering cross-check to /release skill (Step 6, item 5) so future releases catch this drift automatically

Test plan

• README roadmap list matches ROADMAP.md phase order, names, and count
• /release skill includes the new cross-check instruction

[claude]

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

---

PR Review: Documentation Alignment Fix

Todo List:

• Read changed files to understand modifications
• Read ROADMAP.md to verify alignment
• Conduct 5-phase review analysis
• Provide final assessment and recommendation

---

Root Cause Analysis

Problem Being Solved: Documentation drift between README roadmap and ROADMAP.md source of truth. The README roadmap phases had become out of sync with the authoritative ROADMAP.md, with incorrect ordering and missing phases.

Why This Approach: The fix correctly identifies ROADMAP.md as the source of truth and updates README to match. The addition of an automated cross-check to the release process prevents future drift by making this verification part of the release workflow.

Risk Assessment: ✅ Low risk - This is pure documentation synchronization with no code changes.

---

Changes Analysis

README.md Changes:

• ✅ Moved "Expanded Language Support" from position 12 to 9 (matching Phase 7)
• ✅ Added missing "Quality, Security & Technical Debt" phase (Phase 9)
• ✅ Renamed "Visualization & Advanced" → "Advanced Features" (Phase 13)
• ✅ Renumbered all subsequent phases to match ROADMAP.md sequence

.claude/skills/release/SKILL.md Changes:

• ✅ Added Step 6, item 5: "Roadmap ordering cross-check"
• ✅ Makes this verification automatic in future releases
• ✅ Clear instructions to use ROADMAP.md as source of truth

Verification Against ROADMAP.md:

I confirmed the README now correctly matches the ROADMAP.md phase sequence:

• Phase 7: Expanded Language Support ✅
• Phase 8: Runtime & Extensibility ✅
• Phase 9: Quality, Security & Technical Debt ✅ (was missing)
• Phase 10: Intelligent Embeddings ✅
• Phase 11: Natural Language Queries ✅
• Phase 12: GitHub Integration & CI ✅
• Phase 13: Advanced Features ✅ (renamed correctly)

---

Backlog Compliance

• Zero-dep: ✓ - No new dependencies, pure documentation fix
• Foundation-aligned: ✓ - Fully aligned, improves documentation accuracy
• Problem-fit: 3/5 - Useful maintenance but doesn't directly address core AI navigation problem
• Breaking: No - Documentation-only change
• Tier: 1 (zero-dep ✓ + foundation-aligned ✓)

---

Code Quality Assessment

✅ Excellent approach:

• Identifies root cause (drift between docs)
• Fixes the immediate issue
• Prevents recurrence with automated check
• No code changes to introduce bugs
• Clear, accurate documentation updates

✅ Process improvement: The addition to the release skill is exactly the right preventive measure.

✅ Accuracy: I verified every phase number, name, and ordering against ROADMAP.md - all correct.

---

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: This is an exemplary documentation maintenance PR. It identifies a real drift problem, fixes it correctly, and implements a preventive measure to avoid future recurrence. The changes are accurate and well-executed. Only missing the 5th star because it's maintenance rather than a significant feature/improvement.

Minor note: The commit messages correctly follow conventional commit format and avoid Claude Code references as required by the project guidelines.

This PR demonstrates good engineering practices: fixing the immediate issue while addressing the systemic cause.

---

[greptile-apps]

Greptile Summary

This PR fixes a silent drift between the README roadmap summary and the canonical docs/roadmap/ROADMAP.md, and adds a preventative release-time cross-check to stop the drift from recurring.\n\n- README.md — Roadmap positions 9–15 now match ROADMAP.md exactly: Phase 7 (Expanded Language Support) moved from position 12 to 9; Phase 9 (Quality, Security & Technical Debt) added at position 11; "Visualization & Advanced" renamed to "Advanced Features" at position 15 with the correct sub-items (removing the "web UI" entry that does not appear in ROADMAP.md Phase 13).\n- .claude/skills/release/SKILL.md — A new Step 6 item 5 "Roadmap ordering cross-check" is inserted, instructing the release agent to compare phase order, names, and count between README and ROADMAP.md on every release, regardless of whether any phase status changed.

Confidence Score: 5/5

Safe to merge — documentation-only changes with no runtime impact, verified to correctly match ROADMAP.md.

Both changed files are pure documentation/instruction files. The README roadmap update was cross-checked against ROADMAP.md and is accurate in phase order, names, descriptions, and count. No logic, code, or configuration is affected.

No files require special attention.

Important Files Changed

Filename	Overview
README.md	Roadmap section updated to correctly sync with ROADMAP.md: Phase 7 (Expanded Language Support) moved to position 9, Phase 9 (Quality, Security & Technical Debt) added as position 11, Phase 13 (Advanced Features) renamed with accurate sub-items, and all phases renumbered to match.
.claude/skills/release/SKILL.md	Adds roadmap ordering cross-check as Step 6 item 5, renumbers old items 5→6 and 6→7, and clarifies the check runs even for non-user-facing releases.

_{Reviews (1): Last reviewed commit: "fix(docs): sync README roadmap phase ord..." | Re-trigger Greptile}