push: refspec syntax local:remote for cross-branch pushes

Background

muse push <remote> <branch> always pushes the named local branch to the identically-named remote branch. There is no way to push a local branch to a differently-named remote branch without first switching to it — a friction point when doing release promotion (dev → main) or cross-branch CI uploads from a detached state.

Git solved this with refspec syntax: git push origin local:remote. The colon separates the source (local) ref from the destination (remote) ref. Muse should support the same pattern.

Goal

# Push local main to remote main without leaving dev
muse push staging main:main

# Push local dev up to remote main (release promotion without switching)
muse push staging dev:main

# Existing single-name syntax unchanged
muse push staging dev          # → local dev → remote dev (unchanged)
muse push local dev            # → same

The + force prefix in refspec (git: +local:remote) is also supported as an alternative to --force:

muse push staging +dev:main    # → force-push local dev to remote main

How git does it

Git parses a positional <refspec> argument as [+]<src>:<dst>:

• src — the local ref to send (branch name, or full refs/heads/…)
• dst — the remote ref to update
• + prefix — sets force flag for this refspec only

Git's push plumbing separates "what to send" (commit walk from src) from "what to update on the remote" (the dst ref). Muse's push protocol already has the same separation: the DAG walk uses the local branch tip, and the unpack-mpack call passes branch=<dst> to tell the server which ref to advance.

The only missing piece is the CLI: today the BRANCH positional is used for both roles. Adding a local:remote parse step decouples them.

Implementation

Refspec parsing

A small utility parse_push_refspec(raw: str) -> tuple[str, str, bool] that returns (local_branch, remote_branch, force). Called before any push logic runs. No changes to the push protocol or server.

Empty src or dst is an error — muse push --delete <remote> <branch> is the correct way to delete a remote branch.

Push command wiring

push.py calls parse_push_refspec on the BRANCH positional, derives local_branch and remote_branch, then:

• Uses local_branch as the ref for the DAG walk (commit deduplication)
• Passes remote_branch to the unpack-mpack call as the target branch name
• If the refspec + prefix is set, OR --force is passed, force-push

JSON output

The branch field in push JSON output reflects the remote branch that was updated (what matters to the caller), not the local branch. This is consistent with current behavior where local == remote.

Phases

Phase 1 — Refspec parser + unit tests

New function parse_push_refspec (in push.py or a shared refspec.py). Pure function; no I/O.

Deliverables

• [ ] RS_01 — parse_push_refspec("dev") returns ("dev", "dev", False)
• [ ] RS_02 — parse_push_refspec("dev:main") returns ("dev", "main", False)
• [ ] RS_03 — parse_push_refspec("+dev:main") returns ("dev", "main", True)
• [ ] RS_04 — parse_push_refspec("+dev") returns ("dev", "dev", True)
• [ ] RS_05 — parse_push_refspec("dev:") raises ValueError with clear message; same for ":main" and "dev:main:extra"

Phase 2 — Wire into push command + integration tests

Update muse/cli/commands/push.py to call parse_push_refspec and route the two branch names correctly through the push engine.

Deliverables

• [ ] RS_06 — muse push local dev:dev --json succeeds; JSON branch == "dev"; remote dev advances (behaviorally identical to existing muse push local dev)
• [ ] RS_07 — On a repo with commits on dev not on main: muse push local dev:main --json advances remote main to local dev's tip; remote dev is unchanged
• [ ] RS_08 — muse push local +dev:main --json force-pushes; equivalent to muse push local dev:main --force
• [ ] RS_09 — muse push local dev:nonexistent --json creates nonexistent on the remote (same as pushing a new branch by name — no special handling needed; server already supports this)
• [ ] RS_10 — muse push local dev: --json exits 1 with "invalid refspec" error before any network call

Phase 3 — Docs

Update docs/agent-guide.md push section and the Gitism glossary to document the new syntax. Run muse agent-config sync afterwards.

Deliverables

• [ ] RS_11 — refspec syntax documented in push section of agent-guide.md with the four canonical forms (same-name, cross-name, force prefix, existing --force flag still works)
• [ ] RS_12 — muse agent-config sync reports no drift

Acceptance criteria

1. muse push staging main:main from dev branch advances remote main to local main's tip without requiring a branch switch.
2. muse push staging dev:main advances remote main to local dev's tip.
3. muse push staging +dev:main force-pushes; rejects fast-forward check.
4. Existing muse push staging dev behaviour is unchanged.
5. All RS_01–RS_12 tests green.
6. JSON branch field in push output always reflects the remote branch updated.

Out of scope

• Delete via refspec (:remote) — use muse push --delete <remote> <branch>
• Full git refspec syntax (refs/heads/…) — branch names only
• Multi-refspec in one command (muse push local dev:main feat:feat) — single refspec only for now