README.md
markdown
| 1 | # Muse Tools |
| 2 | |
| 3 | ## Demo |
| 4 | |
| 5 | `demo.py` runs a 5-act VCS stress test against a real (temporary) Muse |
| 6 | repository and renders a shareable, self-contained HTML visualization. |
| 7 | |
| 8 | ### Run |
| 9 | |
| 10 | ```bash |
| 11 | # From the repo root, with the venv active: |
| 12 | python tools/demo.py |
| 13 | ``` |
| 14 | |
| 15 | Output lands in `artifacts/` (gitignored): |
| 16 | |
| 17 | | File | Description | |
| 18 | |---|---| |
| 19 | | `artifacts/demo.json` | Structured event log + full commit DAG | |
| 20 | | `artifacts/demo.html` | Self-contained shareable visualization | |
| 21 | |
| 22 | Open the HTML in any browser: |
| 23 | |
| 24 | ```bash |
| 25 | open artifacts/demo.html # macOS |
| 26 | xdg-open artifacts/demo.html # Linux |
| 27 | ``` |
| 28 | |
| 29 | ### Options |
| 30 | |
| 31 | ``` |
| 32 | --output-dir PATH Write output here (default: artifacts/) |
| 33 | --json-only Skip HTML rendering, emit JSON only |
| 34 | ``` |
| 35 | |
| 36 | ### What the 5 acts cover |
| 37 | |
| 38 | | Act | Operations | |
| 39 | |---|---| |
| 40 | | 1 · Foundation | `init`, 3 commits on `main` | |
| 41 | | 2 · Divergence | 3 branches (`alpha`, `beta`, `gamma`), 5 branch commits | |
| 42 | | 3 · Clean Merges | `merge alpha`, `merge beta` — auto-resolved two-parent commits | |
| 43 | | 4 · Conflict & Resolution | `conflict/left` + `conflict/right` → CONFLICT → manual resolve + commit | |
| 44 | | 5 · Advanced Ops | `cherry-pick`, `show`, `diff`, `stash`, `stash pop`, `revert`, `tag`, `log` | |
| 45 | |
| 46 | --- |
| 47 | |
| 48 | ## Typing Audit |
| 49 | |
| 50 | `typing_audit.py` scans the codebase for banned typing patterns (enforcing the |
| 51 | "ratchet of zero" policy from `AGENTS.md`). |
| 52 | |
| 53 | ```bash |
| 54 | python tools/typing_audit.py --dirs muse/ tests/ --max-any 0 |
| 55 | ``` |