Decompose muse/core/harmony.py (2210 lines) god object into focused modules

Summary

muse/core/harmony.py (2210 lines, 53 functions, 19 classes) is a god object in the same mould as the decomposed store.py (issue #13) and bridge.py (issue #14). It combines 13 distinct responsibilities in a single flat file. Companion file muse/cli/commands/harmony.py (2493 lines) is also over-large and will be thinned as part of this work.

Rule: at the end of every phase, all tests pass with no regressions. Out-of-date code, spec, comments, docstrings, and tests must be updated in the same commit that introduces each phase.

Current State

Target Architecture: muse/core/harmony/ package

muse/core/harmony/
  __init__.py       <- canonical public API re-exports (<=80 lines)
  types.py          <- all dataclasses + TypedDicts + enums
  paths.py          <- all path helpers
  fingerprint.py    <- ID/fingerprint computation (no I/O)
  patterns.py       <- pattern persistence
  resolutions.py    <- resolution persistence
  audit.py          <- audit log persistence
  policies.py       <- policy persistence + matching
  escalations.py    <- escalation persistence
  engine.py         <- merge harmony_engine.py here; auto_apply, record_resolutions

muse/core/harmony.py (flat file) -> deleted, replaced by the package. muse/core/harmony_engine.py -> merged into harmony/engine.py, then deleted.

CLI thinning (Phase 9)

muse/cli/commands/harmony.py follows the bridge.py pattern:

• All argparse parser builders extracted from the CLI shell.
• Shell file reduced to <=200 lines: register() + subparser delegation + no domain logic.
• TypedDicts stay in the CLI file (presentation-layer contracts, not domain types).

Implementation Phases

Phase 0 -- Baseline audit

Run test suite scoped to harmony tests. Run muse code breakage and muse code deps on harmony.py. Document all import sites. No code changes. Commit: chore(harmony): baseline audit

Phase 1 -- Extract types.py

Move all dataclasses, TypedDicts, and enums: ConflictType, ResolutionStrategy, PolicyAction, PolicyScope, AuditEventType, EscalationStatus, AgentProvenance, PolicyCondition, ConflictPattern, Resolution, Policy, ResolutionProposal, EscalationRecord, and all private TypedDicts. Re-export from init.py. Update all import sites. Zero regressions.

Phase 2 -- Extract paths.py

Move all path helpers: patterns_dir, policies_dir, audit_dir, escalations_dir, escalation_path, pattern_dir, _resolutions_dir, resolution_path plus path-level validation helpers _validate_id, _validate_fingerprint, _validate_policy_id. Re-export from init.py. Zero regressions.

Phase 3 -- Extract fingerprint.py

Move pure-computation functions (no I/O): blob_fingerprint, compute_pattern_id, compute_resolution_id, compute_escalation_id, compute_semantic_fingerprint, _now_utc, _parse_dt. Re-export from init.py. Zero regressions.

Phase 4 -- Extract patterns.py

Move pattern persistence: record_pattern, load_pattern, list_patterns, forget_pattern, clear_all. Move serialization helpers used only by patterns: _pattern_to_dict, _dict_to_pattern, _write_atomic. Re-export from init.py. Zero regressions.

Phase 5 -- Extract resolutions.py

Move resolution persistence: save_resolution, load_resolution, list_resolutions, best_resolution, increment_applied_count, gc_stale. Move serialization: _resolution_to_dict, _dict_to_resolution. Re-export from init.py. Zero regressions.

Phase 6 -- Extract audit.py

Move append_audit, list_audit. Re-export from init.py. Zero regressions.

Phase 7 -- Extract policies.py

Move save_policy, load_policy, list_policies, remove_policy, match_policy, _condition_matches. Move serialization: _policy_condition_to_dict, _policy_to_dict, _dict_to_policy. Re-export from init.py. Zero regressions.

Phase 8 -- Extract escalations.py + merge harmony_engine.py into engine.py

Move record_escalation, load_escalation, list_escalations, resolve_escalation, _escalation_to_dict, _dict_to_escalation. Merge muse/core/harmony_engine.py content into engine.py alongside auto_apply, record_resolutions. Delete muse/core/harmony_engine.py and muse/core/harmony.py (flat file). Re-export everything from init.py. Zero regressions.

Phase 9 -- Thin muse/cli/commands/harmony.py

Extract parser-builder functions from CLI shell. Target: <=200 lines, containing only register() + subparser delegation. TypedDicts / JSON envelope classes stay in the CLI file. Zero regressions.

Phase 10 -- Comprehensive sweep

Full acceptance-criteria sweep. Update all out-of-date code, spec, comments, docstrings, and tests. Commit: refactor(harmony): comprehensive spec sweep

Acceptance Criteria

Architecture

• muse/core/harmony.py (flat file) no longer exists
• muse/core/harmony_engine.py no longer exists
• muse/core/harmony/ package with 9 submodules exists
• muse/core/harmony/init.py re-exports full prior public API (no external import sites need to change their from muse.core.harmony import statements)
• muse/cli/commands/harmony.py <=200 lines (shell only, no domain logic)
• No submodule in muse/core/harmony/ exceeds 400 lines

Code quality

• Every submodule has a module-level docstring explaining its single responsibility
• Every public function/class has a correct, up-to-date docstring
• No dead code, no deprecated annotations, no backward-compat shims (delete, do not annotate)
• All cross-cutting rules from the agent guide satisfied

Tests

• All existing harmony tests pass with zero regressions
• Tests that patch muse.core.harmony.* updated to patch the canonical submodule path
• Tests that import from muse.core.harmony_engine updated to import from muse.core.harmony.engine
• muse code test --json reports green for every changed file

Docs / spec

• docs/ references to harmony.py (flat file) updated to reflect package structure
• agent-guide.md harmony section updated if commands or import paths changed

Constraints (every phase)

1. Never run the full test suite. Scoped run: python3 -m pytest tests/test_harmony.py tests/test_bridge_harmony.py -q
2. One phase per commit. Do not batch phases.
3. No backward-compat shims. Update every import site in the same commit.
4. Delete harmony_engine.py in phase 8, not before.
5. init.py re-exports must stay complete throughout all phases.
6. External callers (merge.py, commit.py, bridge/harmony_shelf.py) must continue working without changing their own import statements.

Why This Matters

auto_apply (called by merge.py) and record_resolutions (called by commit.py) are the two most load-bearing harmony entry points. They live in a 2210-line file that makes them hard to test in isolation and impossible to reason about without reading 2000+ lines of context. Decomposing this into focused modules enables per-concern unit tests with precise mocks, parallel agent development of separate persistence layers, a clean 1:1 mapping for the planned Rust port, and the elimination of harmony_engine.py which is currently a wrapper around a module that should itself be the engine.