Skip to content

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

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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