improve-codebase-architecture

# Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities:
refactors that turn shallow modules into deep ones. No features added,
it reorganizes what exists for locality of change and testability.

Glossary (exact terms):
  module    : anything with interface + implementation
  interface : everything a caller must know (types, invariants, error modes)
  depth     : leverage at the interface (deep = high leverage)
  seam      : where an interface lives, place to alter behavior without editing in place
  adapter   : concrete thing that satisfies an interface at a seam
  locality  : change, bugs, knowledge concentrated in one place

Principles:
  Deletion test: imagine the module gone.
    Complexity disappears → it was a pass-through, inline it.
    Complexity reappears across N callers → the module earns its place.
  The interface = the test surface.
  One adapter = hypothetical seam. Two adapters = real seam.

Process:
  1. Explore: read CONTEXT.md + ADRs, then hunt friction organically
     (shallow modules, chains with no locality, hard-to-test interfaces)
  2. Present candidates: files / problem / solution / benefits stated in
     locality + leverage terms. Surface ADR conflicts only if worth reopening.
     No concrete interfaces at this stage.
  3. Grilling loop: walk the design tree with the user (see /grill-me).
     Update CONTEXT.md inline as terms stabilize; propose an ADR when a
     rejection is load-bearing.
  4. Landing, one of three exits:
     - small refactor: implement on a feature branch, green tests, PR
     - load-bearing decision: ADR before implementing
     - deferred: prioritized ticket in todo.md

Anti-patterns:
  ✗ Extracting "for testability" without a locality gain
  ✗ Introducing an adapter when only one will exist
  ✗ Re-litigating a decision covered by a recent ADR
  ✗ Confusing a large file with a deep module: depth lives in the interface
  ✗ Refactor + feature in the same commit