062-enhance: convergent refinement of existing knowledge

[ahoward]

Summary

brane enhance — convergent refinement. Sharpen what brane already knows without adding new topics. Fill gaps, merge duplicates, surface contradictions, deepen thin areas.

Why

After digest and storm fill the graph, it gets messy. Concepts overlap, edges are missing, some areas are shallow. Enhance is the cleanup pass — it operates inward, not outward. Bunny has this and it's essential for knowledge quality.

What

CLI

brane enhance                          # refine entire knowledge base
brane enhance "authentication"         # focus on a topic
brane enhance --rounds 3               # iterative refinement

Flags

• --focus <topic> — narrow refinement to a topic area
• --rounds <n> — iterative passes (default: 1)
• --dry-run / -n — preview changes
• --json / -j — JSON output

Flow

1. Load context — if focused, vector search for topic; otherwise sample broadly
2. LLM analysis — Claude examines existing knowledge for:
   • Redundant/overlapping concepts → merge
   • Missing edges between related concepts → create
   • Shallow episodes that should be expanded → update
   • Contradictions → flag as episodes with "contradiction" tag
3. Apply — update concepts, create edges, store observations

LLM Response Schema

{
  operations: {
    merge_concepts: { keep_id: number, remove_id: number, reason: string }[],
    new_edges: { source: string, target: string, relation: string }[],
    observations: { observation: string, tags: string[] }[],
  },
  reasoning: string
}

Key Constraint

Enhance does NOT add new topics. It only refines what's already there. This is what distinguishes it from storm (divergent) and digest (new input).

MCP Tool

enhance: { focus?: string, rounds?: number, dry_run?: boolean }

Depends On

• 059-digest: consume URLs, files, directories, stdin into knowledge graph #82 (059-digest) — needs populated graph to refine
• Existing consolidation (Episode consolidation: distill episodes into semantic knowledge #38) and fuzzy dedup (Fuzzy dedup: prevent concept fragmentation on create #53) infrastructure

Acceptance

• Identifies and merges redundant concepts
• Creates missing edges between related concepts
• Surfaces contradictions as tagged episodes
• Focus mode narrows scope
• Multi-round refinement
• Dry-run preview
• MCP tool exposed
• Spike test passes