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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```json
{
  "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:**
```bash
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:**
```json
{
  "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.