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
                         ConflictPattern, Resolution, Policy, PolicyCondition,
                         EscalationRecord, AgentProvenance, AuditEvent,
                         ResolutionProposal, EngineStatus, etc.
  paths.py             ← all path helpers
                         patterns_dir, policies_dir, audit_dir, escalations_dir,
                         escalation_path, pattern_dir, resolution_path, etc.
  fingerprint.py       ← all ID/fingerprint computation (no I/O)
                         blob_fingerprint, compute_pattern_id, compute_resolution_id,
                         compute_escalation_id, compute_semantic_fingerprint
  patterns.py          ← pattern persistence
                         record_pattern, load_pattern, list_patterns,
                         forget_pattern, clear_all
  resolutions.py       ← resolution persistence
                         save_resolution, load_resolution, list_resolutions,
                         best_resolution, increment_applied_count, gc_stale
  audit.py             ← audit log persistence
                         append_audit, list_audit
  policies.py          ← policy persistence + matching
                         save_policy, load_policy, list_policies, remove_policy,
                         match_policy, _condition_matches
  escalations.py       ← escalation persistence
                         record_escalation, load_escalation, list_escalations,
                         resolve_escalation
  engine.py            ← merge muse/core/harmony_engine.py content here
                         HarmonyPlugin, EngineConfig, EngineResult, resolve,
                         find_similar, 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 (_register_*_parser) extracted into the submodule that owns the relevant domain logic, or into a muse/core/harmony/cli_parsers.py module.
• Shell file reduced to ≤ 200 lines: register() + subparser delegation + no domain logic.
• TypedDicts stay in the CLI file (they are presentation-layer contracts, not domain types).

Implementation Phases

Phase 0 — Baseline audit

• Run full test suite, record pass count.
• Run muse code breakage --json and muse code deps muse/core/harmony.py --json.
• Document all import sites in a comment at the top of the work branch.
• No code changes. Commit: chore(harmony): baseline audit.

Phase 1 — Extract types.py

Move all dataclasses, TypedDicts, and enums from harmony.py into muse/core/harmony/types.py:

• ConflictType, ResolutionStrategy, PolicyAction, PolicyScope, AuditEventType, EscalationStatus
• AgentProvenance, PolicyCondition, ConflictPattern, Resolution, Policy
• ResolutionProposal, EscalationRecord
• Private TypedDicts: _PatternDict, _ResolutionDict, _PolicyConditionDict, _PolicyDict, AuditEvent, _EscalationDict
• Re-export all from harmony/ __init__.py.
• Update all imports in harmony_engine.py, harmony_shelf.py, cli/commands/harmony.py.
• Run tests. 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 + path-level validation helpers _validate_id, _validate_fingerprint, _validate_policy_id.

• Re-export from __init__.py.
• Run tests. Zero regressions.

Phase 3 — Extract fingerprint.py

Move pure-computation functions (no I/O, no filesystem access): blob_fingerprint, compute_pattern_id, compute_resolution_id, compute_escalation_id, compute_semantic_fingerprint, _now_utc, _parse_dt.

• Re-export from __init__.py.
• Run tests. 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.
• Run tests. 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 helpers: _resolution_to_dict, _dict_to_resolution.

• Re-export from __init__.py.
• Run tests. Zero regressions.

Phase 6 — Extract audit.py

Move append_audit, list_audit.

• Re-export from __init__.py.
• Run tests. 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.
• Run tests. Zero regressions.

Phase 8 — Extract escalations.py + merge harmony_engine.py → engine.py

Move record_escalation, load_escalation, list_escalations, resolve_escalation. Move _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.
• Run tests. Zero regressions.

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

Extract parser-builder functions from the CLI file to the relevant submodule (or to a harmony/cli_parsers.py). Target: CLI shell ≤ 200 lines, containing only register() + subparser delegation.

• TypedDicts / JSON envelope classes stay in the CLI file.
• Run tests. Zero regressions.

Phase 10 — Sweep

Full acceptance-criteria sweep (see below). 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 exists with the 9 submodules listed above.
• muse/core/harmony/__init__.py re-exports the full prior public API (backward-compat: no import sites outside harmony/ 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, don't annotate).
• All cross-cutting rules from the agent guide satisfied (no git calls, no re-exports of deleted symbols).

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.
• Any inline comments citing line numbers in the old flat file removed or updated.
• agent-guide.md harmony section updated if commands or import paths changed.

Constraints (apply to every phase)

1. Never run the full test suite — python3 -m pytest tests/test_harmony*.py tests/test_bridge_harmony*.py -q is the scoped run. Full suite is gabriel's call.
2. One phase per commit — do not batch phases.
3. No backward-compat shims — if a file previously imported from muse.core.harmony import X and X moves to harmony/patterns.py, update that import. Do not leave a re-export stub in the old location.
4. Delete harmony_engine.py in phase 8, not before.
5. __init__.py re-exports must stay complete — external callers (merge.py, commit.py, bridge/harmony_shelf.py) must continue working without import changes.

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 development of separate persistence layers
• The Rust port (issue forthcoming) to map 1:1 to module boundaries
• Cleaner harmony_engine.py removal (it is already a wrapper — it should be the engine, not a wrapper around the engine)