gitlore/docs/command-surface-analysis/07-consolidation-proposals.md

Consolidation Proposals

5 proposals to reduce 34 commands to 29 by merging high-overlap commands.

---

A. Absorb file-history into trace --shallow

Overlap: 75%. Both do rename chain BFS on mr_file_changes, both optionally include DiffNote discussions. trace follows entity_references to linked issues; file-history stops at MRs.

Current state:

# These do nearly the same thing:
lore file-history src/auth/ -p proj --discussions
lore trace src/auth/ -p proj --discussions
# trace just adds: issues linked via entity_references

Proposed change:

• trace <path> — full chain: file -> MR -> issue -> discussions (existing behavior)
• trace <path> --shallow — MR-only, no issue following (replaces file-history)
• Move --merged flag from file-history to trace
• Deprecate file-history as an alias that maps to trace --shallow

Migration path:

1. Add --shallow and --merged flags to trace
2. Make file-history an alias with deprecation warning
3. Update robot-docs to point to trace
4. Remove alias after 2 releases

Breaking changes: Robot output shape differs slightly (trace_chains vs merge_requests key name). The --shallow variant should match file-history's output shape for compatibility.

Effort: Low. Most code is already shared via resolve_rename_chain().

---

B. Absorb auth into doctor

Overlap: 100% of auth is contained within doctor.

Current state:

lore auth     # checks: token set, GitLab reachable, user identity
lore doctor   # checks: all of above + DB + schema + Ollama

Proposed change:

• doctor — full check (existing behavior)
• doctor --auth — token + GitLab only (replaces auth)
• Keep health separate (fast pre-flight, different exit code contract: 0/19)
• Deprecate auth as alias for doctor --auth

Migration path:

1. Add --auth flag to doctor
2. Make auth an alias with deprecation warning
3. Remove alias after 2 releases

Breaking changes: None for robot mode (same JSON shape). Exit code mapping needs verification.

Effort: Low. Doctor already has the auth check logic.

---

C. Remove related query-mode

Overlap: 80% with search --mode semantic.

Current state:

# These are functionally equivalent:
lore related "authentication flow"
lore search "authentication flow" --mode semantic

# This is UNIQUE (no overlap):
lore related issues 42

Proposed change:

• Keep entity-seeded mode: related issues 42 (seeds from existing entity embedding)
• Remove free-text mode: related "text" -> error with suggestion: "Use search --mode semantic"
• Alternatively: keep as sugar but document it as equivalent to search

Migration path:

1. Add deprecation warning when query-mode is used
2. After 2 releases, remove query-mode parsing
3. Entity-mode stays unchanged

Breaking changes: Agents using related "text" must switch to search --mode semantic. This is a strict improvement since search has filters.

Effort: Low. Just argument validation change.

---

D. Merge who overlap into who expert

Overlap: 50% functional, but overlap is a strict simplification of expert.

Current state:

lore who src/auth/               # expert mode: scored rankings
lore who --overlap src/auth/     # overlap mode: raw touch counts

Proposed change:

• who <path> (expert) adds touch_count and last_touch_at fields to each expert row
• who --overlap <path> becomes an alias for who <path> --fields username,touch_count
• Eventually remove --overlap flag

New expert output:

{
  "experts": [
    {
      "username": "jdoe", "score": 42.5,
      "touch_count": 15, "last_touch_at": "2026-02-20",
      "detail": { "mr_ids_author": [99, 101] }
    }
  ]
}

Migration path:

1. Add touch_count and last_touch_at to expert output
2. Make --overlap an alias with deprecation warning
3. Remove --overlap after 2 releases

Breaking changes: Expert output gains new fields (non-breaking for JSON consumers). Overlap output shape changes if agents were parsing { "users": [...] } vs { "experts": [...] }.

Effort: Low. Expert query already touches the same tables; just need to add a COUNT aggregation.

---

E. Merge count and status into stats

Overlap: count and stats both answer "how much data?"; status and stats both report system state.

Current state:

lore count issues           # entity count + state breakdown
lore count mrs              # entity count + state breakdown
lore status                 # sync cursors per project
lore stats                  # document/index counts + integrity

Proposed change:

• stats — document/index health (existing behavior, default)
• stats --entities — adds entity counts (replaces count)
• stats --sync — adds sync cursor positions (replaces status)
• stats --all — everything: entities + sync + documents + integrity
• stats --check / --repair — unchanged

New --all output:

{
  "data": {
    "entities": {
      "issues": { "total": 5000, "opened": 200, "closed": 4800 },
      "merge_requests": { "total": 1234, "opened": 100, "closed": 50, "merged": 1084 },
      "discussions": { "total": 8000 },
      "notes": { "total": 282000, "system_excluded": 50000 }
    },
    "sync": {
      "projects": [
        { "project_path": "group/repo", "last_synced_at": "...", "document_count": 5000 }
      ]
    },
    "documents": { "total": 61652, "issues": 5000, "mrs": 2000, "notes": 50000 },
    "embeddings": { "total": 80000, "synced": 79500, "pending": 500 },
    "fts": { "total_docs": 61652 },
    "queues": { "pending": 0, "in_progress": 0, "failed": 0 },
    "integrity": { "ok": true }
  }
}

Migration path:

1. Add --entities, --sync, --all flags to stats
2. Make count an alias for stats --entities with deprecation warning
3. Make status an alias for stats --sync with deprecation warning
4. Remove aliases after 2 releases

Breaking changes: count output currently has { "entity": "issues", "count": N, "breakdown": {...} }. Under stats --entities, this becomes nested under data.entities. Alias can preserve old shape during deprecation period.

Effort: Medium. Need to compose three query paths into one response builder.

---

Summary

Consolidation	Removes	Effort	Breaking?
file-history -> trace --shallow	-1 command	Low	Alias redirect, output shape compat
auth -> doctor --auth	-1 command	Low	Alias redirect
related query-mode removal	-1 mode	Low	Must switch to search --mode semantic
who overlap -> who expert	-1 sub-mode	Low	Output gains fields
count + status -> stats	-2 commands	Medium	Output nesting changes

Total: 34 commands -> 29 commands. All changes use deprecation-with-alias pattern for gradual migration.