sprint-docstring.md markdown

195 lines 10.2 KB

sha256:88ac91129873e6a496e9189515aa690eb893ae25d69c8f72af141a2be5068eb3 docs: docstring sprint contract→find-symbol — idiomatic run… Sonnet 4.6 patch 142 days ago

Docstring Sprint — Non-MIDI Commands

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

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.)
Terse quickstart entry in docs/agent-guide.md — one or two lines under the appropriate section heading, e.g.:
```
muse code age --json        # symbol evolutionary distance
muse code age --explain file.py::Fn --json
```
Envelope on every --json output — {**make_envelope(elapsed), ...} pattern, elapsed = start_timer() at the top of run().

Status legend

[ ] not started
[d] docstring done
[g] agent-guide entry done
[e] envelope confirmed
[x] all three complete

Commands (alphabetical, MIDI excluded)

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

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 1 commit

sha256:88ac91129873e6a496e9189515aa690eb893ae25d69c8f72af141a2be5068eb3 docs: docstring sprint contract→find-symbol — idiomatic run… Sonnet 4.6 patch 142 days ago