docs: clarify implementation status in GAP_DETECTION.md

[timduly4]

Summary

Clarified what's currently implemented vs. planned in GAP_DETECTION.md. Unlike EVALUATION.md and RANKING.md, most of the content was already accurate (the detection pipeline is fully implemented), so this is a light simplification focused on removing non-working features and adding clear status indicators.

Changes Made

Removed (20 lines)

• ❌ Historical Analysis section (lines 560-575)
  • Referenced GET /api/v1/gaps endpoint which returns empty
  • Gap persistence not yet implemented
• ❌ Cross-source detection mentioned as fully implemented (actually planned)

Added Clarifications

1. Clear disclaimer at top:

   "Currently, only duplicate work detection is fully implemented. Other gap types (missing context, stale docs, knowledge silos) are planned for future milestones."

2. Gap type status in Overview:

   - Duplicate Work ✅ Implemented
   - Missing Context (planned)
   - Stale Documentation (planned)
   - Knowledge Silos (planned)
   

3. Note in Stage 6:

   "Gaps are currently returned in the detection response only. Persistent storage is planned for a future milestone."

4. New "Future Gap Types" section:

   • Moved missing context, stale docs, knowledge silo descriptions
   • Clearly marked as "Planned"

5. Updated status footer:

   "Status: Duplicate work detection implemented; gap persistence and other gap types planned for future milestones"

Kept (579 lines) - Accurate Content

✅ Complete 6-stage detection pipeline (all implemented)
✅ Duplicate work detection criteria and examples
✅ Confidence scoring formula and tiers
✅ Impact assessment methodology
✅ Tuning parameters (similarity threshold, temporal overlap, etc.)
✅ Best practices for using the system
✅ Comprehensive troubleshooting guide
✅ All working API examples

---

Why Minimal Reduction?

EVALUATION.md: 982 → 218 lines (78% reduction) - Most content was unimplemented
RANKING.md: 843 → 338 lines (60% reduction) - Many features unimplemented
GAP_DETECTION.md: 599 → 579 lines (3% reduction) - Most content was accurate

The detection pipeline (clustering, entity extraction, temporal analysis, LLM verification) is fully implemented, so most of the documentation is correct and useful.

---

Impact

Before: 599 lines, unclear what works vs. what's planned
After: 579 lines, clear separation of implemented vs. future features

Key Improvements:

• Users immediately know only duplicate work detection is ready
• No confusion about GET /api/v1/gaps endpoint
• Clear roadmap for future gap types
• All examples and code accurate to implementation

---

Testing

• ✅ Verified all code examples match actual implementation
• ✅ Confirmed detection pipeline stages are accurate
• ✅ All curl commands tested and work
• ✅ Historical analysis section removed (endpoint doesn't work)

---

Related PRs

Part of post-Milestone 3 documentation cleanup:

• PR docs: cleanup and fixes after Milestone 3 completion #42: Fixed DEMO.md bugs and collection UUID issue
• PR fix(docs): correct DEMO.md commands and improve usability #43: Fixed DEMO.md command syntax
• PR docs: remove unimplemented API endpoints from API_EXAMPLES.md #44: Cleaned up API_EXAMPLES.md
• PR docs: remove QUICKSTART.md (redundant with DEMO.md) #45: Removed redundant QUICKSTART.md
• PR docs: remove milestone references from TESTING.md #46: Removed milestone references from TESTING.md
• PR docs: radically simplify EVALUATION.md and RANKING.md #47: Simplified EVALUATION.md and RANKING.md

---

Philosophy

Unlike the other docs, GAP_DETECTION.md was already mostly accurate because the detection system is actually built. This PR focuses on:

• Clarifying implementation status
• Removing the one non-working section (historical analysis)
• Adding clear visual indicators (✅ vs "planned")
• Helping users understand current capabilities