gabriel / developer-renaissance-002.md GVXM2FHJHe1U

Developer Renaissance #002: Muse Analyzes Muse

code markdown agent signed · 99,054 bytes · v1 · 4 days ago

An executable tour of semantic version control, code intelligence, and the architecture of Muse itself, analyzed with Muse.

49 views
0 forks
1 embeds

Developer Renaissance #002: Muse Analyzes Muse

An executable tour of semantic version control, code intelligence, and the architecture of Muse itself.

Analysis date 2026-11-12 · Muse CLI 0.2.2rc2 · analyzed revision dev @ 8480dbb5 · part of the Developer Renaissance series (#001: MentisDB Release Atlas).

Git versions text. Muse versions state. For source code, "state" means the symbols: functions, classes, methods, and how each one was created, renamed, moved, re-signed, and rewritten.

So we did the obvious experiment. We pointed Muse's code intelligence at Muse's own repository and read what it says about seven months of its own development.

1,719 commits reachable from dev, 2026-04-07 → 2026-11-12
50,364 symbols in the latest snapshot (definitions, classes, methods; imports excluded)
105 commits that touched one class, HttpTransport, the most-changed product symbol
4 of 4 rename / move / signature / implementation edits in our demo recognized as such

Analyze your own codebase with Muse. Start here: musehub.ai/muse/getting-started

Every number below carries a command or script. Where Muse's answer is incomplete or misleading we say so in the section where it happens, and collect it again in Limitations.

1. Five-minute onboarding

You need Python 3.14+ and curl. The official installer creates its own virtual environment and symlinks muse into ~/.local/bin. Read it before running it (the installer's own advice):

python3.14 --version
curl -fsSL https://musehub.ai/install.sh | less      # read first
curl -fsSL https://musehub.ai/install.sh | sh
muse --version                                       # → muse 0.2.2rc2

Provenance note. We did not run the installer for this report. Every command below was run on a 0.2.2rc2 CLI that the release process had installed from the accepted release artifact (muse-0.2.2rc2.tar.gz, sha256 03a444d80e6043eb610321ac882295a67743c3a0127dbd6ddef558e9edef9e1b). We confirmed that all 404 installed package files are byte-identical to that tarball.

Now make a throwaway repository. --domain code turns on symbol-level analysis. No identity or account is needed for local use.

mkdir demo && cd demo
muse init --domain code
cat > billing.py <<'EOF'
def calculate_total(items):
    return sum(i.price for i in items)

def apply_discount(total, rate):
    return total * (1 - rate)

def format_receipt(total):
    return f"Total: {total:.2f}"
EOF
muse code add .
muse commit -m "Add billing module"
muse log --oneline
muse code symbols
billing.py
  fn          compute_total                             line    1
  fn          apply_discount                            line    4

receipts.py
  fn          format_receipt                            line    1

3 symbols across 2 files  (Python: 3)

(That listing is after the four edits in the next section; yours will show three functions in one file at this point.)

Next commands to try, in the order you will want them:

You want to know Command
What changed semantically, per commit muse code detect-refactor
What changed between two commits muse code compare <A> <B>
Where a symbol came from muse code symbol-log "file.py::name"
Which symbols change most muse code hotspots
What lives in this repo muse code languages · muse code symbols · muse code grep NAME

Ordinary Muse vs. bridge/import. Everything above is plain Muse. If your project lives in Git, muse bridge git-import <path> --branch main replays its commits into a Muse repo (documented in the Getting Started guide; not exercised in this report, and the guide lists current limitations for merge commits and file modes). The analysis below uses a repository that was developed natively in Muse.

2. The core idea: Git versions text, Muse versions state

Our demo repository gets four ordinary edits, one commit each: rename a function, move one to another file, add a parameter, change a body.

A line-oriented diff of billing.py across those four commits shows deleted and added lines. It is accurate, and it is all it says:

@@ -1,8 +1,5 @@
-def calculate_total(items):
+def compute_total(items):
     return sum(i.price for i in items)
 
-def apply_discount(total, rate):
-    return total * (1 - rate)
-
-def format_receipt(total):
-    return f"Total: {total:.2f}"
+def apply_discount(total, rate, cap=0.5):
+    return total * (1 - min(rate, cap))

muse code detect-refactor reads the same four commits as operations:

IMPLEMENTATION  billing.py::apply_discount   (implementation changed)   commit ac3a3849…  "apply_discount: honour cap"
SIGNATURE       billing.py::apply_discount   (signature updated)        commit bac5b86a…  "apply_discount: add cap parameter"
MOVE            billing.py::format_receipt   → receipts.py              commit b4504f38…  "Move format_receipt into receipts.py"
RENAME          billing.py::calculate_total  → compute_total            commit 38a66da6…  "Rename calculate_total to compute_total"

Left: unified diff of billing.py. Right: four semantic operations Muse recorded: rename, move, signature change and implementation change.

That is the whole pitch, and it is observable rather than asserted. Muse recorded what kind of change each commit was, as data attached to the commit, which is why later questions ("when was this renamed?", "does this release break a public symbol?") can be answered without re-deriving them from text.

What it does not do (verified, same demo):

  • muse code symbol-log "billing.py::calculate_total" reports the rename and says "tracking continues as billing.py::compute_total". But symbol-log "billing.py::compute_total" (the new name) says no events found. Identity is followed forward from the old name; it is not followed backward from the new one.
  • muse code compare <first> <last> over the range reports apply_discount as one modified symbol. Its signature-vs-implementation split exists per commit (above) but is merged in a range comparison.
  • That same compare reports SemVer impact: MAJOR, because Muse treats a rename as a breaking removal of the old name. For a public API that is reasonable; for a private helper it is noise.
  • muse code hotspots counts format_receipt in billing.py (2 changes) and in receipts.py (1) as separate symbols. It does not merge moves or renames.

Reproduce all of it: tools/quickstart.sh in the evidence bundle (see Reproduction).

3. Muse's architecture, from source evidence

Muse is a Python package (muse/): 388 source files with symbols, 5,921 non-import symbols in product code. The packages that carry it:

Responsibility Where (module paths at 8480dbb5)
Content-addressed storage muse/core/object_store.py, pack_store.py, snapshot.py, ids.py, types.py
Commits, snapshots, refs muse/core/commits.py, snapshots.py, refs.py, dag.py, repo.py
Domain protocol muse/domain.py: MuseDomainPlugin, a Protocol with six methods: snapshot, diff, merge, drift, apply, schema
Domain adapters muse/plugins/: nine registered domains (chess, code, identity, midi, mist, scaffold, social, timeline, todo)
Code-domain symbol analysis muse/plugins/code/ (18 files) and, on the core side, symbol_cache.py, symlog.py, type_analysis.py
Semantic diff and merge muse/core/merge_engine.py, op_merge.py, octopus_merge.py, rebase.py, diff_algorithms/
Harmony (conflict-resolution memory) muse/core/harmony/
Query and history muse/core/query_engine.py, symlog.py, blame.py, bisect.py
Network and distribution muse/core/transport.py (HttpTransport, LocalFileTransport), mpack.py, muse/core/bridge/
CLI muse/cli/app.py (main), muse/cli/commands/ (208 files)

Layered package map of muse/: cli.commands imports core 1,633 times; core imports the code plugin 14 times and cli 5 times (orange upward edges).

The map is built from the Python import statements themselves (stdlib ast, tools/imports.py), not from Muse's own call-graph. We tried Muse's muse code codemap first and deliberately did not use its centrality list: it ranks Python built-ins such as loads and len highest and counts test callers. It is a topology aid, not an architecture oracle.

What the import graph says:

  • The CLI is a thin ring around core. cli.commands imports core 1,633 times and plugins.code 94 times.
  • Plugins depend on core, not on each other. The registry imports every plugin (that is its job); the only plugin-to-plugin import in the tree is mist → code (one). The code and midi plugins otherwise point only down to core and domain.
  • The storage kernel is domain-agnostic, verifiably. object_store, snapshot, repo, refs, commits, types, ids, pack_store and dag import zero plugin modules (grep on their import lines). That matches Muse's design rule that a MIDI file and a Python file are, at the storage layer, just bytes with a path.
  • The rule is not absolute above the kernel. Eight core modules import the code plugin (type_analysis, doc_extractor, doc_history, test_selection, symbol_cache, symlog, implicit_edge_cache, bisect), and five core places import muse.cli (all five are function-level imports). Both are visible as orange upward edges: the code-intelligence layer sits inside core's directory, and some core code reaches up. We report it as a measured layering fact, not a defect.

4. Code-intelligence deep dive

All commands run in a scratch copy of the repository with CLI 0.2.2rc2, outputs saved as JSON (data/ in the evidence bundle).

A. Symbol inventory

muse code languages and muse code symbols --commit dev agree: 50,364 non-import symbols (plus 18,788 import pseudo-symbols that Muse also tracks). By language: Python 46,627 · Markdown 2,615 · Rust 860 · TOML 151 · Shell 65 · the rest are single-file samples. The Rust symbols are mostly (822 of 860) in tools/timeline_wasm/.

80% of 50,364 symbols are in tests; 12% in muse/ product code; bar chart of symbols per muse/ package led by cli/commands (2,787) and core (2,036).

Test code is 80% of the symbols (40,307 vs 5,921 in muse/), a roughly 7-to-1 ratio. Inside the product, cli/commands (2,787) and core (2,036) are about four-fifths of it.

B. Change hotspots

muse code hotspots --language Python counts commits whose structured delta touches a symbol. We cross-checked three of its numbers: _push_stream = 57 and _push_mpack = 16 against the raw commit deltas by script, and HttpTransport = 105 against symbol-log. All match.

Fourteen most-changed product symbols led by HttpTransport (105), _push_stream (57), main (53), commit run (52).

HttpTransport leads by a wide margin. Its symbol-log breaks the 105 events into 75 signature changes, 28 implementation changes and 2 creations. The next entries are CLI entry points: app.main, commit.run, _run_merge, and the run functions of push, pull, clone.

Note the orange bar. _push_stream was touched by 57 commits in the month between 2026-04-16 and 2026-05-16, then renamed _push_mpack. The commit message says why: "implementation already used presigned mpack protocol, only the name was stale." Its later life (16 more changes) is counted under the new name. Muse saw the rename (detect-refactor); hotspots still reports the two names separately.

C. Stable bedrock

muse code stable lists the symbols unchanged for the most commits. In muse/core/snapshot.py, the functions that define how a commit's and a snapshot's identity is computed have not changed for 632–633 commits, i.e. since 2026-05-21.

We verified this independently instead of trusting the number: the body_hash of build_snapshot_manifest, snapshot_identity_bytes and commit_identity_bytes is identical at the commit 633 steps back and at HEAD.

Left: snapshot.py identity functions unchanged for 632-633 commits. Right: most-changed symbols, HttpTransport 105.

This is the useful comparison: the inputs to commit and snapshot identity have been untouched for five and a half months, while the transport and CLI surface above them moved constantly.

Caveat on stable. 156 of the 400 Python results are flagged since_start_of_range: true: "unchanged since the first commit". That is not always true. The Harmony JSON TypedDicts in muse/cli/commands/harmony/_shapes.py get that label, but the file entered the repository on 2026-05-22 as part of a package split (commit 16ba4bc2), and symbol-log shows no events for them at all. We therefore charted only symbols whose stability window starts inside the measured history.

D. Historical evolution

Commits per month: 859, 372, 186, 71, 4, 59, 88, 80 (April to November 12) with total symbols rising from 41,783 to 50,364.

  • Development is front-loaded: 859 commits in April, 372 in May, 4 in August, then a second wave (59 / 88 / 80) from September.
  • 1,408 of 1,719 commits (82%) carry an agent identity; 311 are human-only. 1,623 commits carry a signer key, and muse verify re-checked 1,632 signatures across all 9 refs without a failure.
  • detect-refactor over the whole history classifies 46,351 semantic events: 34,101 implementation changes, 8,590 signature changes, 3,499 moves and 161 renames.

E. Semantic versus textual change

Two examples from the real repository where the semantic record says more than the diff:

  1. A rename that reversed itself. On 2026-04-14 a commit renamed hub.py::run_issue_read → run_issue_show (and run_proposal_read → run_proposal_show). The next day a CLI-wide commit renamed show → read across all sub-commands. detect-refactor lists both: two renames in opposite directions on the same family of symbols, a day apart.
  2. Two releases compared by meaning. muse code compare v0.2.1 <dev HEAD> reports 100 files changed: 1,042 symbols added, 34 removed, 198 modified, with a "MAJOR" SemVer recommendation driven by the removals. It does not read the text; it reads symbol operations.

F. Self-analysis: where domain-agnosticism shows up

The MuseDomainPlugin protocol in muse/domain.py is six methods; nine domains implement it, from code and midi to chess and todo; and the storage kernel imports none of them. In this repository, a symbol rename and a MIDI note edit are the same kind of object to the object store. That is the point of the design, and the import graph is the evidence.

5. Findings you can post

  1. HttpTransport is the most-changed symbol in Muse: 105 commits, 75 of them signature changes.
  2. 57 commits in a month: _push_stream was reshaped nearly twice a day, then renamed _push_mpack because the name had gone stale.
  3. Identity bedrock: the functions that compute commit and snapshot identity have not changed in 633 commits (2026-05-21 → today).
  4. 80% of Muse's symbols are tests (40,307 of 50,364).
  5. The storage kernel imports zero plugins: nine domains, one protocol, and the core objects don't know which domain they hold.

Ready-to-post drafts are in the evidence bundle (social/posts.md).

Limitations and follow-ups

We disclose these rather than hide them.

# Observation Where seen Status
L1 symbol-log on the old name of a renamed symbol shows only the rename event (1 event vs. 57 recorded changes); on the new name it starts after the rename. Rename continuity is not followed in either direction. _push_stream/_push_mpack in the repo; reproduced in the demo Draft issue, not filed
L2 hotspots splits a renamed or moved symbol into two entries. _push_stream (57+16) and the demo Noted with L1
L3 stable reports since_start_of_range for symbols that were created later through a file split. harmony/_shapes.py Draft issue, not filed; excluded from charts
L4 compare over a range merges signature and implementation into one modified; a rename is always MAJOR. demo Known direction (SemVer policy)
L5 codemap centrality ranks built-ins and counts test callers; not used here. muse code codemap Not used
L6 Incomplete history: rev-list returns 1,719 commits but muse log lists 1,520 (it omits merged side-branch commits; we read the other 199 with read-commit). 71 commits have no structured delta, 62 of them merge commits; the CLI itself warns that 7 of the 1,659 commits it examined carry no semantic delta. whole repo Disclosed
L7 History begins 2026-04-07 with a 614-file first commit. Earlier development is not in this repository, so "seven months" is the recorded history. whole repo Disclosed
L8 The public Getting Started page lists limitations for 0.2.1rc20 while the installer ships 0.2.2rc2. docs Not a Muse defect; docs lag
L9 Counts are of commits touching a symbol, not lines, bugs or complexity. High churn is activity, not defect density. all hotspots Method note

Reproduction

Everything is regenerated from scripts; none of the numbers is typed by hand.

# 1. CLI: Muse 0.2.2rc2 (artifact sha256 03a444d8…9e1b), installed from the release artifact
muse --version
# 2. A scratch copy of the Muse repository at dev 8480dbb5…, with no remote and no credentials
# 3. Collect (13 commands, ~35 s): tools/collect.sh      → data/*.json
# 4. Complete commit set + month-end snapshots:           tools/collect2.py
# 5. Aggregate + import graph + charts:                   tools/analyze.py, tools/imports.py, tools/charts.py
# 6. The demo transcript: tools/quickstart.sh             → data/quickstart_transcript.txt

Provenance manifest

Field Value
Analysis date 2026-11-12
Muse CLI muse 0.2.2rc2, release-artifact install (venv; python 3.14.4)
CLI artifact muse-0.2.2rc2.tar.gz, sha256 03a444d80e6043eb610321ac882295a67743c3a0127dbd6ddef558e9edef9e1b; 404 of 404 installed files identical to the tarball
CLI source revision sha256:fcde0f18e62070ef097c8a0fb9948a27ebaea58e9ee72eb0df6dc32b7ca90136 (chore: set version to 0.2.2rc2)
Analyzed repository Muse dev @ sha256:8480dbb5e1f85cbe6f4f6326c9ec7bed9cad797208a91c980f1ddda8960948ba
Repository id sha256:a00948056eb6e601aaba87328774727002339d5cf57f04b60da6fb2191a69856
History coverage 1,719 commits reachable from dev; 2026-04-07T14:08Z → 2026-11-12T14:15Z; 9 refs; muse verify --no-objects: all ok (1,739 commits, 1,632 signatures; 42 promised objects)
Analysis scope dev branch snapshot + all commits reachable from it; Python/Markdown/Rust/TOML/Shell parsed by Muse's own adapters
Not analyzed Other branches' unmerged work; pre-2026-04-07 history; non-text files
Superseded run An earlier pass with 0.2.1rc20 was discarded and everything was re-collected with 0.2.2rc2; core numbers were identical, and 0.2.2rc2 added the explicit incomplete-history warnings

Dataset digests (sha256, first 16): hotspots_py d14949166c435ba0 · stable_py 19d4dd10d3129488 · languages 55c8be29093e0868 · analysis 556933d158d9e023 · imports ecca670772de29ab · month_end_snapshots 296a9f45978d68db · refactor_full 152faa156d7e5646 · compare_v021_head 81986ec29ad7da67 · verify 312ccbbf4c390911 · quickstart_transcript b60ef8427f8669ac


Built by Sonnet 5.5 (Claude Code) with gabriel, 2026-11-12. Charts use the MuseHub Spectral palette and are embedded as images; every chart names its source command. Try Muse on your own repository: musehub.ai/muse/getting-started.

Embed
<iframe src="https://musehub.ai/gabriel/mists/GVXM2FHJHe1U/embed" width="600" height="400" frameborder="0" title="developer-renaissance-002.md"></iframe>
<script src="https://musehub.ai/embed.js" data-mist="gabriel/GVXM2FHJHe1U"></script>
Agent Provenance
agent claude-code sigil claude-code
modelclaude-sonnet-5-5