Skip to content

Refactor: split monolithic learning_layers/harness.py and resolve core->layers import inversion #38

@bordeauxred

Description

@bordeauxred

Why

`clawloop/learning_layers/harness.py` is 1139 lines and mixes five conceptually distinct things in one file:

  • `ToolConfig`
  • `PlaybookEntry` / `Playbook` (ACE-style memory)
  • `PromptCandidate` / `ParetoFront` (GEPA)
  • `Insight` (reflector output validation)
  • `Harness` itself (Layer-protocol orchestration)

A reader trying to grok the layering can't see the boundaries.

There's also an architectural smell: `clawloop/core/curator.py:25` imports from `clawloop/learning_layers/harness.py`. Core depending on a layer is the wrong direction; `Playbook`/`Insight` should live in core (they're domain types, not layer mechanics).

What

  • Move `Insight`, `Playbook`, `PlaybookEntry` from `learning_layers/harness.py` to a new `clawloop/core/playbook.py`. Update `curator.py`'s import.
  • Split GEPA pieces: extract `PromptCandidate`, `ParetoFront`, `_dominates` into `clawloop/core/pareto.py` (pure data + algorithm) or `learning_layers/harness_pareto.py` (if it stays layer-coupled).
  • Extract `ToolConfig` into a small module (`clawloop/core/tool_config.py`) — it's referenced by multiple layers.
  • Leave `harness.py` as a Layer-protocol orchestrator only. Target ≤350 lines.
  • Update all imports across `clawloop/`, `tests/`, and `examples/`.
  • All existing tests pass with no behavioral change.

Acceptance

  • `grep -r "from clawloop.learning_layers.harness import" clawloop/core/` returns nothing
  • `learning_layers/harness.py` is ≤400 lines
  • `pytest tests/ -x -q` green

Effort

~2-3 hours. Mechanical refactor; risk is import cycles.

Source

Code audit and Codex review, 2026-04-18. Both auditors independently flagged this as the top S1 refactor.

Metadata

Metadata

Assignees

No one assigned

    Labels

    refactorInternal restructuring, no behavior change

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions