gabriel / muse public
sprint-docstring.md markdown
233 lines 16.5 KB
Raw
sha256:b636f72dcba9e190afb980bece906fa5b717fbde014b76ef023df8cb96e01eb9 docs: expand cache plan with all seven testing tiers and do… Sonnet 4.6 132 days ago

CLI Audit — Non-MIDI Commands

For every command listed below, ensure all eight of the following are in place:

  1. Comprehensive, idiomatic run() docstring — uniform structure:

    • One-line summary sentence
    • Brief prose description (2–4 lines)
    • Agent quickstart block with :: code fence showing 2–4 --json invocations
    • JSON fields section — one line per key, name left-padded, description after gap
    • Exit codes section — one line per code (0 Success., 1 User error., etc.)

  2. Terse quickstart entry in docs/agent-guide.md — one or two lines under the appropriate section heading.

  3. Envelope on every --json output — {**make_envelope(elapsed), ...} pattern, elapsed = start_timer() at the top of run().

  4. TypedDict inherits EnvelopeJson — every JSON output shape uses the idiomatic wire type.

  5. --json / -j normalized — action="store_true", dest="json_out", local var json_out: bool = args.json_out. No --format/-f dual-flag pattern. No store_const.

  6. Short flags idiomatic — every flag that warrants a shorthand has one; no shorthand collides with convention (e.g. -n must not be used for --name when -n is the ecosystem-wide shorthand for --dry-run).

  7. Default output is text — when --json is not passed, the command prints human-readable text (not JSON). json_out = False → text path required.

  8. Flag tests complete — test file has TestRegisterFlags covering every registered flag (test_default_json_out_is_false, test_json_flag_sets_json_out, test_j_shorthand_sets_json_out, plus one test per non-trivial flag).

Status legend

  • [ ] not started / not confirmed
  • [x] confirmed done
  • [-] not applicable

Columns: d docstring · g agent-guide · e envelope · t TypedDict · j --json/-j normalized · dt default text · sf short flags idiomatic · ft flag tests complete

Cross-command flag conventions

Short flags that must be consistent across all commands that expose that concept:

Flag Short Notes
--json -j All commands with JSON output
--verbose -v All commands with verbose mode
--quiet -q All commands with quiet mode
--dry-run -n All commands with dry-run mode
--force -f All commands with force mode
--all -a All commands with an "all" flag
--branch -b All commands accepting a branch name
--message -m All commands accepting a commit/shelf message
--commit -c All commands accepting a commit ref
--file -F All commands accepting a file path input
--output -o All commands writing to an output path
--delete -d All commands deleting something
--recursive -r All commands with recursive behavior
--yes -y All commands requiring confirmation bypass
--name (none) No short — avoid collision with -n (dry-run)
--format (removed) Replaced by --json / -j everywhere

Commands (alphabetical, MIDI excluded)

Command File d g e t j dt sf ft
age cli/commands/age.py [x] [x] [x] [x] [x] [x] [x] [x]
agent keygen / list / register cli/commands/agent.py [x] [x] [x] [x] [x] [x] [x] [x]
agent-config init/sync/read/status/inspect/set cli/commands/agent_config.py [x] [x] [x] [x] [x] [x] [x] [x]
annotate cli/commands/annotate.py [x] [x] [x] [x] [x] [x] [x] [x]
api-surface cli/commands/api_surface.py [x] [x] [x] [x] [x] [x] [x] [x]
apply cli/commands/apply.py [x] [x] [x] [x] [x] [x] [x] [x]
apply-patch cli/commands/apply_patch.py [x] [x] [x] [x] [x] [x] [x] [x]
archive cli/commands/archive.py [x] [x] [x] [x] [x] [x] [x] [x]
attributes cli/commands/attributes.py [x] [x] [x] [x] [x] [x] [x] [x]
auth keygen/register/whoami/logout cli/commands/auth.py [x] [x] [x] [x] [x] [x] [x] [x]
bisect cli/commands/bisect.py [x] [x] [x] [x] [x] [x] [x] [x]
blame cli/commands/blame.py [x] [x] [x] [x] [x] [x] [x] [x]
blast-risk cli/commands/blast_risk.py [x] [x] [x] [x] [x] [x] [x] [x]
branch cli/commands/branch.py [x] [x] [x] [x] [x] [x] [x] [x]
breakage cli/commands/breakage.py [x] [x] [x] [x] [x] [x] [x] [x]
bundle create/inspect/verify/diff/unbundle cli/commands/bundle.py [x] [x] [x] [x] [x] [x] [x] [x]
cat cli/commands/cat.py [x] [x] [x] [x] [x] [x] [x] [x]
cat-object cli/commands/cat_object.py [x] [x] [x] [x] [x] [x] [x] [x]
check cli/commands/check.py [x] [x] [x] [x] [x] [x] [x] [x]
check-attr cli/commands/check_attr.py [x] [x] [x] [x] [x] [x] [x] [x]
check-ignore cli/commands/check_ignore.py [x] [x] [x] [x] [x] [x] [x] [x]
check-ref-format cli/commands/check_ref_format.py [x] [x] [x] [x] [x] [x] [x] [x]
checkout cli/commands/checkout.py [x] [x] [x] [x] [x] [x] [x] [x]
checkout-symbol cli/commands/checkout_symbol.py [x] [x] [x] [x] [x] [x] [x] [x]
cherry-pick cli/commands/cherry_pick.py [x] [x] [x] [x] [x] [x] [x] [x]
clean cli/commands/clean.py [x] [x] [x] [x] [x] [x] [x] [x]
clone cli/commands/clone.py [x] [x] [x] [x] [x] [x] [x] [x]
clones cli/commands/clones.py [x] [x] [x] [x] [x] [x] [x] [x]
code-check cli/commands/code_check.py [x] [x] [x] [x] [x] [x] [x] [x]
code-query cli/commands/code_query.py [x] [x] [x] [x] [x] [x] [x] [x]
code-stage cli/commands/code_stage.py [x] [x] [x] [x] [x] [x] [x] [x]
codemap cli/commands/codemap.py [x] [x] [x] [x] [x] [x] [x] [x]
commit cli/commands/commit.py [x] [x] [x] [x] [x] [x] [x] [x]
commit-graph cli/commands/commit_graph.py [x] [x] [x] [x] [x] [x] [x] [x]
commit-tree cli/commands/commit_tree.py [x] [x] [x] [x] [x] [x] [x] [x]
compare cli/commands/compare.py [x] [x] [x] [x] [x] [x] [x] [x]
config cli/commands/config_cmd.py [x] [x] [x] [x] [x] [x] [x] [x]
conflicts cli/commands/conflicts.py [x] [x] [x] [x] [x] [x] [x] [x]
content-grep cli/commands/content_grep.py [x] [x] [x] [x] [x] [x] [x] [x]
contract cli/commands/contract.py [x] [x] [x] [x] [x] [x] [x] [x]
coord-gc cli/commands/coord_gc.py [x] [x] [x] [x] [x] [x] [x] [x]
coord-sync cli/commands/coord_sync.py [x] [x] [x] [x] [x] [x] [x] [x]
core-blame cli/commands/core_blame.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
core-cat cli/commands/core_cat.py [x] [x] [x] [x] [x] [ ] [ ] [ ]
count-objects cli/commands/count_objects.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
coupling cli/commands/coupling.py [x] [x] [x] [x] [x] [x] [x] [x]
coverage cli/commands/coverage.py [x] [x] [x] [x] [x] [x] [x] [x]
dag cli/commands/dag.py [x] [x] [x] [x] [x] [x] [x] [x]
dead cli/commands/dead.py [x] [x] [x] [x] [x] [x] [x] [x]
deps cli/commands/deps.py [x] [x] [x] [x] [x] [x] [x] [x]
describe cli/commands/describe.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
detect-refactor cli/commands/detect_refactor.py [x] [x] [x] [x] [x] [x] [x] [x]
diff cli/commands/diff.py [x] [x] [x] [x] [x] [ ] [ ] [x]
docs cli/commands/docs_cmd.py [x] [x] [x] [x] [x] [x] [x] [x]
domain-info cli/commands/domain_info.py [x] [x] [x] [x] [x] [ ] [ ] [x]
domains cli/commands/domains.py [x] [x] [x] [x] [x] [x] [x] [x]
entangle cli/commands/entangle.py [x] [x] [x] [x] [x] [x] [x] [x]
fetch cli/commands/fetch.py [x] [x] [x] [x] [x] [x] [x] [x]
find-symbol cli/commands/find_symbol.py [x] [x] [x] [x] [x] [x] [x] [x]
for-each-ref cli/commands/for_each_ref.py [x] [x] [x] [x] [x] [ ] [ ] [x]
forecast cli/commands/forecast.py [x] [x] [x] [x] [x] [x] [x] [x]
format-patch cli/commands/format_patch.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
gc cli/commands/gc.py [x] [x] [x] [x] [x] [ ] [ ] [x]
gravity cli/commands/gravity.py [x] [x] [x] [x] [x] [x] [x] [x]
grep cli/commands/grep.py [x] [x] [x] [x] [x] [x] [x] [x]
harmony cli/commands/harmony.py [x] [x] [x] [x] [x] [x] [x] [x]
hash-object cli/commands/hash_object.py [x] [x] [x] [x] [x] [x] [x] [x]
heartbeat-coord cli/commands/heartbeat_coord.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
hotspots cli/commands/hotspots.py [x] [x] [x] [x] [x] [x] [x] [x]
impact cli/commands/impact.py [x] [x] [x] [x] [x] [x] [x] [x]
index-rebuild cli/commands/index_rebuild.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
init cli/commands/init.py [x] [x] [x] [x] [x] [x] [x] [x]
invariants cli/commands/invariants.py [x] [x] [x] [x] [x] [x] [x] [x]
languages cli/commands/languages.py [x] [x] [x] [x] [x] [x] [x] [x]
lineage cli/commands/lineage.py [x] [x] [x] [x] [x] [x] [x] [x]
list-coord cli/commands/list_coord.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
log cli/commands/log.py [x] [x] [x] [x] [x] [ ] [ ] [x]
ls-files cli/commands/ls_files.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
ls-remote cli/commands/ls_remote.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
ls-tree cli/commands/ls_tree.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
maintenance cli/commands/maintenance.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
merge cli/commands/merge.py [x] [x] [x] [x] [x] [ ] [ ] [x]
merge-base cli/commands/merge_base.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
merge-tree cli/commands/merge_tree.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
migrate cli/commands/migrate.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
mv cli/commands/mv.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
name-rev cli/commands/name_rev.py [x] [x] [x] [x] [x] [ ] [ ] [x]
narrative cli/commands/narrative.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
pack-objects cli/commands/pack_objects.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
patch cli/commands/patch.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
patch-id cli/commands/patch_id.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
plan-merge cli/commands/plan_merge.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
predict cli/commands/predict.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
prune cli/commands/prune.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
pull cli/commands/pull.py [x] [x] [x] [x] [x] [ ] [ ] [ ]
push cli/commands/push.py [x] [x] [x] [x] [x] [ ] [ ] [ ]
query cli/commands/query.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
query-history cli/commands/query_history.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
range-diff cli/commands/range_diff.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
read cli/commands/read.py [x] [x] [x] [x] [x] [ ] [ ] [ ]
read-commit cli/commands/read_commit.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
read-snapshot cli/commands/read_snapshot.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
rebase cli/commands/rebase.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
reconcile cli/commands/reconcile.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
reflog cli/commands/reflog.py [x] [x] [x] [x] [x] [ ] [ ] [x]
release cli/commands/release.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
release-coord cli/commands/release_coord.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
remote cli/commands/remote.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
rename cli/commands/rename.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
reserve cli/commands/reserve.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
reset cli/commands/reset.py [x] [x] [x] [x] [x] [ ] [ ] [ ]
restore cli/commands/restore.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
rev-list cli/commands/rev_list.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
rev-parse cli/commands/rev_parse.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
revert cli/commands/revert.py [x] [x] [x] [x] [x] [ ] [ ] [ ]
rm cli/commands/rm.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
semantic-cherry-pick cli/commands/semantic_cherry_pick.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
semantic-test-coverage cli/commands/semantic_test_coverage.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
shard cli/commands/shard.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
shelf cli/commands/shelf.py [x] [x] [x] [x] [ ] [ ] [ ] [x]
shortlog cli/commands/shortlog.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
show-ref cli/commands/show_ref.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
sign cli/commands/sign.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
snapshot cli/commands/snapshot_cmd.py [x] [x] [x] [x] [x] [ ] [ ] [ ]
snapshot-diff cli/commands/snapshot_diff.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
sparse-checkout cli/commands/sparse_checkout.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
stable cli/commands/stable.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
status cli/commands/status.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
switch cli/commands/switch.py [x] [x] [x] [x] [ ] [ ] [ ] [x]
symbol-log cli/commands/symbol_log.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
symbolic-ref cli/commands/symbolic_ref.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
symbols cli/commands/symbols.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
tag cli/commands/tag.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
task-queue cli/commands/task_queue.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
test cli/commands/test_cmd.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
trust cli/commands/trust.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
type cli/commands/type_cmd.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
unpack-objects cli/commands/unpack_objects.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
update-ref cli/commands/update_ref.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
velocity cli/commands/velocity.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
verify cli/commands/verify.py [x] [x] [x] [x] [x] [ ] [ ] [ ]
verify-commit cli/commands/verify_commit.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
verify-object cli/commands/verify_object.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
verify-pack cli/commands/verify_pack.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
verify-tag cli/commands/verify_tag.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
watch-coord cli/commands/watch_coord.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
workspace cli/commands/workspace.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]
worktree cli/commands/worktree.py [x] [x] [x] [x] [ ] [ ] [ ] [ ]

MIDI commands (excluded from this sprint)

agent_map, arpeggiate, cadence, contour, density, find_phrase, humanize, instrumentation, intent, invert, midi_check, midi_compare, midi_harmony, midi_query, midi_shard, mist, mix, motif_detect, note_blame, note_hotspots, note_log, notes, piano_roll, quantize, retrograde, rhythm, scale_detect, tempo, tension, transpose, velocity_normalize, velocity_profile, voice_leading

File History 3 commits
sha256:b636f72dcba9e190afb980bece906fa5b717fbde014b76ef023df8cb96e01eb9 docs: expand cache plan with all seven testing tiers and do… Sonnet 4.6 132 days ago
sha256:7f9e2ef5286aedad9c1e6011b4c46ca27f39dbdad6e3409357e36b26e46b3b7c docs: docstring sprint for-each-ref→hotspots — idiomatic ru… Sonnet 4.6 patch 138 days ago
sha256:88ac91129873e6a496e9189515aa690eb893ae25d69c8f72af141a2be5068eb3 docs: docstring sprint contract→find-symbol — idiomatic run… Sonnet 4.6 patch 138 days ago