refactor(cli): start the command registry, migrate merge-chunks (#1212)

[PathGao]

Summary

Executes the second half of #1212: split cli.dispatch_command's ~3,100-line if/elif chain into a graphify/commands/ package with a COMMANDS registry, mirroring the graphify/extractors/ split. This PR lands the seam and the first command so the rest can follow one-per-PR, and adds the porting playbook.

Deliberately small — it establishes the pattern, not a big-bang rewrite:

• dispatch_command consults COMMANDS before its remaining if/elif chain (registry-first, fallback for everything not yet ported).
• merge-chunks moves verbatim into graphify/commands/merge_chunks.py (body dedented one level; it reads sys.argv and calls sys.exit exactly as before), and its old branch is removed.
• graphify/commands/MIGRATION.md is the porting playbook, mirroring graphify/extractors/MIGRATION.md.
• tests/test_commands_registry.py fails if a command is ever both in COMMANDS and still present as an elif cmd == "..." branch — i.e. a half-migrated command whose old body is now dead.

Why merge-chunks first

Self-contained (no shared local state with neighbouring branches), already covered by tests/test_merge_chunks_validation.py, and small enough to make the diff easy to read while still exercising real argv parsing, untrusted-input validation, and atomic write. Its test passes unchanged through the new dispatch path, confirming the move is behavior-preserving.

Type of change

• Refactoring (no behavior change)

How was this tested?

• tests/test_merge_chunks_validation.py (10 tests) passes unchanged — it drives main() → dispatch_command → the registry end to end.
• New tests/test_commands_registry.py (registry populated/callable; no register-and-branch overlap).
• Full suite shows no new failures attributable to this change (the pre-existing reds are missing optional deps — terraform tree-sitter grammar, skillgen/ollama network — red on main too).

Breaking changes

None. merge-chunks behaves identically; every other command is untouched.

🤖 Generated with Claude Code

[graphify-labs]

Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).

Graphify reviewed this change.

Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).

---

Graphify review — findings

This PR begins refactoring the monolithic dispatch_command if/elif chain in graphify/cli.py into a new graphify/commands/ package (per issue #1212). It adds a COMMANDS registry that dispatch_command now consults before falling through to the remaining if/elif chain, and migrates the merge-chunks command as the first example—moving its branch body verbatim into graphify/commands/merge_chunks.py and removing the old branch. It also adds a MIGRATION.md playbook documenting how to port additional commands, plus a test_commands_registry.py test asserting the registry is populated and callable. The surface area is limited to CLI dispatch plumbing and the merge-chunks handler.

No blocking issues surfaced.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 202 functions depend on the 56 node(s) this change touches.

Health — grade A; 5 existing hotspot(s) in the area this change touches (pre-existing, not introduced here):

• dispatch_command() — 2 callers, 108 callees (high)
• main() — 79 callers, 2 callees (high)
• _run_hook_guard() — 3 callers, 6 callees (medium)
• _invoke() — 15 callers, 1 callees (medium)
• _stale_graph_sources() — 7 callers, 2 callees (medium)

Verification — 202 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 164 function(s) in the blast radius were not formally verified this run