Stage 1.5 Refactor

Problem

After Stage 1 worked, several maintainability issues remained visible in the implementation.

Why

The teaching system should stay small, but not brittle. Refactoring after a working checkpoint makes the production lesson explicit: preserve behavior while improving boundaries, diagnostics, and testability.

Implementation

The refactor/v1.5-maintainability branch made six observable changes:

  • clearer verification diagnostics;
  • scripted actions derived from task state;
  • finish verification failures surfaced by the agent;
  • runtime dependencies injected into the agent;
  • tool specifications centralized in the dispatcher path;
  • tool payloads typed in contracts.

How it works

The refactor keeps the Stage 1 contract intact while making internal responsibilities sharper. The agent loop receives dependencies rather than constructing everything implicitly. Tool schemas move toward a single source of truth. Payload typing makes model and tool boundaries more explicit.

Test

The refactor updated tests in:

  • tests/test_verification.py
  • tests/test_agent.py
  • tests/test_dispatcher.py

Those tests anchor the behavior that should not change while internals become clearer.

Observed failure or limitation

The refactor history does not add a new stage capability. It improves the maintainability of Stage 1 and prepares the code for later stages.

Next step

Future stages can add investigation, repair, persistence, and policy on top of the cleaned Stage 1 shape. Their implementation history is not present in the current refs.