gabriel / musehub public
Closed #88 Docs
filed by gabriel human · 3 days ago

Add comprehensive Merge Engine documentation page to /muse/merge

0 Anchors
Blast radius
Churn 30d
0 Proposals

Background

Muse's merge engine is one of its most powerful differentiators from git, but it has no dedicated documentation page in the /muse developer docs. The comprehensive merge matrix work (issue #86, fully shipped in rc12) implemented the full strategy × history × granularity system and Harmony integration — but nothing explains it to a developer or contributor arriving at the docs cold.

The gap is acute right now because:

  • Contributors cloning the repo for the first time need to understand how to merge their work
  • The strategy/history/on-conflict flag surface is non-obvious to anyone coming from git
  • The relationship between muse merge (local) and muse hub proposal merge (server) is not documented anywhere
  • The safe merge protocol developed during rc12 integration (topology check → commit inspection → dry-run → merge/push) needs to be captured for agent and human contributors alike

The merge documentation that existed previously was lost in a prior merge regression.


Goal

A complete /muse/merge documentation page in the developer docs that covers:

  • What makes Muse merges fundamentally different from git (symbol-level granularity)
  • The three altitude levels: directory, file, symbol
  • The strategy × history × on-conflict matrix
  • muse merge CLI reference
  • muse hub proposal merge — how proposal merges map to local merges
  • --explain flag for merge observability
  • Harmony integration (link to Phase 05 Harmony page)
  • The safe merge protocol checklist

Phases

Phase 1 — Page and routing

Deliverables:

  • DO_01 — Add ("merge", "04.5", "Merge Engine", "...") entry to _PHASES in musehub/api/routes/musehub/ui_docs.py, positioned between Code Intelligence (04) and Harmony (05).
  • DO_02 — Add GET /muse/merge route to ui_docs.py.
  • DO_03 — Create musehub/templates/musehub/pages/docs_muse_merge.html with full content (see sections below).
  • DO_04 — Merge card appears in the docs index at /muse.

Phase 2 — Content

The page must cover these sections in order:

  • DO_05Overview: one paragraph on why symbol-level granularity changes the merge UX.
  • DO_06Three altitudes: directory, file, symbol — what each means and when each fires.
  • DO_07The merge engine model: diff_unit × resolution_policy table showing how named strategies decompose.
  • DO_08Strategy reference: recursive, overlay, snapshot, replay, ours (alias), theirs (alias) — what each does in plain English with a one-line CLI example for each.
  • DO_09History modes: merge, squash, rebase — commit graph shape, Harmony implications.
  • DO_10--on-conflict flag: escalate, ours, theirs — when to use each.
  • DO_11muse merge CLI reference: flags table, exit codes, JSON output shape.
  • DO_12Proposal merge: how muse hub proposal merge --strategy X maps to muse merge --strategy X; why parity matters.
  • DO_13--explain flag: sample JSON output and human-readable output showing per-path decision trace.
  • DO_14Safe merge protocol: the four-step pre-merge checklist (topology → commit inspection → dry-run → merge/push) with exact commands.
  • DO_15Harmony integration: brief section + link to /muse/harmony.

Acceptance criteria

  1. /muse/merge returns 200 and is navigable from the docs index.
  2. All 15 deliverables checked off.
  3. Page appears in the sidebar nav on every other docs page.
  4. Content covers the full strategy × history × on-conflict surface without requiring the reader to cross-reference issue #86.

Out of scope

  • Renumbering existing phase display labels (existing /muse/* URLs are unchanged).
  • Documenting Harmony internals (those belong on /muse/harmony).
  • Adding new merge features — this is documentation only.
Activity
gabriel opened this issue 3 days ago
closed this issue 3 days ago