muse diff treats a bare path as a commit ref instead of a pathspec (git-parity gap)

Background

While reviewing a working-tree change during the muse clone hash-mismatch debug session, muse diff musehub/services/musehub_wire_shared.py produced no output. The path argument is interpreted as a commit ref (commit_a), fails to resolve, and the command prints ⚠️ Commit '<path>' not found.

muse diff does support path scoping — but only via the --path / -p flag. A bare positional path, and the git-universal -- pathspec separator, are not recognized. This diverges from git diff, where git diff <path> (when the name is unambiguous) and git diff -- <path> both scope the diff to that path. The result is a surprising "no diff" for a natural, git-idiomatic invocation.

Observed behavior

Run from a repo with an uncommitted change to musehub/services/musehub_wire_shared.py:

muse diff --help documents positionals as [commit_a] [commit_b] and a separate --path/-p flag; there is no -- pathspec handling.

Problems

1. No bare-path scoping. muse diff <path> treats the path as a commit ref. Git accepts git diff <path> when the token is not also a ref.
2. No -- pathspec separator. git diff -- <path>... is the universal, unambiguous way to force path interpretation. muse diff -- <path> ignores the separator and still treats the token as a commit.
3. Inconsistent exit code. "Commit not found" exits 1 for a bare path but 0 for the -- form. A not-found ref should fail consistently.

Expected (git parity)

• muse diff -- <path>... — everything after -- is treated as paths (pathspec), never as commits. This is the primary fix; it is unambiguous and universally idiomatic.
• muse diff <path> — when the token does not resolve to a commit/ref but does match a tracked path, scope the diff to that path (git's disambiguation). If a token is both a valid ref and a path, follow git: require -- to disambiguate (or prefer the ref and emit a clear warning).
• Consistent, correct exit codes for an unresolved ref.

Repro

cd <any muse repo with an uncommitted change to FILE>
muse diff FILE            # expect a path-scoped diff; actual: "Commit 'FILE' not found"
muse diff -- FILE         # expect a path-scoped diff; actual: same warning, exit 0
muse diff --path FILE     # works today (workaround)

Acceptance criteria

• muse diff -- <path>... scopes the diff to the given path(s); no commit interpretation after --.
• muse diff <path> scopes by path when the token is not a valid commit/ref but is a tracked path.
• Documented ref/path ambiguity rule (matches git: -- disambiguates).
• Consistent exit code when a positional does not resolve to a commit.
• --help documents -- and bare-path behavior.
• Tests: -- separator, bare-path scoping, ref-vs-path ambiguity, exit codes.

Out of scope

• Changing or removing --path / -p — it works and stays.

Provenance

Discovered 2026-06-16 during the muse clone snapshot hash-mismatch investigation, when muse diff <path> silently returned nothing while reviewing a fix diff.