Closed
#89
Docs
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) andmuse 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 mergeCLI referencemuse hub proposal merge— how proposal merges map to local merges--explainflag 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_PHASESinmusehub/api/routes/musehub/ui_docs.py, positioned between Code Intelligence (04) and Harmony (05).DO_02— AddGET /muse/mergeroute toui_docs.py.DO_03— Createmusehub/templates/musehub/pages/docs_muse_merge.htmlwith 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_05— Overview: one paragraph on why symbol-level granularity changes the merge UX.DO_06— Three altitudes: directory, file, symbol — what each means and when each fires.DO_07— The merge engine model:diff_unit×resolution_policytable showing how named strategies decompose.DO_08— Strategy reference:recursive,overlay,snapshot,replay,ours(alias),theirs(alias) — what each does in plain English with a one-line CLI example for each.DO_09— History modes:merge,squash,rebase— commit graph shape, Harmony implications.DO_10—--on-conflictflag:escalate,ours,theirs— when to use each.DO_11—muse mergeCLI reference: flags table, exit codes, JSON output shape.DO_12— Proposal merge: howmuse hub proposal merge --strategy Xmaps tomuse merge --strategy X; why parity matters.DO_13—--explainflag: sample JSON output and human-readable output showing per-path decision trace.DO_14— Safe merge protocol: the four-step pre-merge checklist (topology → commit inspection → dry-run → merge/push) with exact commands.DO_15— Harmony integration: brief section + link to/muse/harmony.
Acceptance criteria
/muse/mergereturns 200 and is navigable from the docs index.- All 15 deliverables checked off.
- Page appears in the sidebar nav on every other docs page.
- 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
closed this issue
3 days ago