muse shelf read — files list bug and help UX fixes

muse shelf read — UX fixes and files list bug

Background

muse shelf read has two problems discovered during normal development use:

1. Bug: files_count and files are semantically inconsistent. files_count counts files that differ from HEAD (the actual change set), but files dumps the entire snapshot manifest — every tracked file in the repo. On a large repo this means files_count: 6 with a 1000+ entry files list, which is actively misleading.

2. UX: The JSON schema in the --help output for all shelf subcommands is a single dense line. It is hard to read at a glance — you have to actively parse it rather than letting your eyes scan line-by-line.

3. Docs gap: It is not documented that muse shelf (bare, no subcommand) is identical to muse shelf save, or that custom names are supported (muse shelf save my-auth-refactor).

Goal

• files in muse shelf read --json contains only the files that differ from HEAD — the same set that files_count counts.
• The human-readable muse shelf read output shows only changed files.
• JSON schema blocks in all shelf --help descriptions break each key onto its own line.
• muse shelf --help and muse shelf save --help document the bare-command alias and custom name support.

Phases

Phase 1 — Fix files list bug

The invariant that must hold after this phase: len(output["files"]) + len(output["deleted"]) == output["files_count"]

• SF_01 — run_read: compute changed_files as paths where entry["snapshot"][p] != head_manifest.get(p) (covers new files and modifications)
• SF_02 — run_read JSON: emit files=changed_files instead of all snapshot keys
• SF_03 — run_read human output: iterate changed_files instead of all snapshot keys
• SF_04 — Test: files_count == len(files) + len(deleted) invariant holds when HEAD has a mix of changed, unchanged, and new files
• SF_05 — Test: files list is empty when shelf snapshot matches HEAD exactly

Phase 2 — Pretty-print help JSON schemas

• SF_06 — muse shelf save --help: break JSON schema across lines (one key per line)
• SF_07 — muse shelf read --help: same
• SF_08 — muse shelf list --help: same
• SF_09 — muse shelf apply --help: same
• SF_10 — muse shelf pop --help: same
• SF_11 — muse shelf drop --help: same
• SF_12 — muse shelf diff --help: same

Phase 3 — Document bare muse shelf and custom names

• SF_13 — muse shelf --help (top-level): note that muse shelf with no subcommand is equivalent to muse shelf save
• SF_14 — muse shelf save --help: add example showing custom name (muse shelf save my-auth-refactor -m "intent text")
• SF_15 — muse shelf save --help: clarify auto-name format (branch/NNN) and that custom names are looked up by exact string or integer index

Acceptance criteria

• muse shelf read 0 --json | jq '.files | length' returns 6 (not 1000+) on the test shelf entry
• muse shelf read --help JSON schema block has one key per line
• muse shelf --help mentions the bare-command alias
• All SF_0x tests pass

Out of scope

• created_by enrichment (read username from ~/.muse/identity.toml) — tracked separately; requires identity config integration
• Shelf entry expiry and GC — separate concern