improve-codebase-architecture

# /improve-codebase-architecture Explore a codebase like an AI would, surface architectural friction, and propose module-deepening refactors as GitHub issue RFCs. > **Structured execution spec:** [`protocol.yon`](protocol.yon). Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the `@STAMP` date. **A deep module has a small interface hiding a large implementation.** Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside. (John Ousterhout, *A Philosophy of Software Design*) **The deepening test:** would merging these modules produce a smaller combined interface than they have separately? If no, it's not a deepening opportunity — it's just reorganization. ## Reference — Dependency Categories Classify each candidate's dependencies; the category determines the entire testing strategy. 1. **In-process** — pure computation, in-memory state, no I/O. Always deepenable; merge and test directly. 2. **Local-substitutable** — dependencies with local test stand-ins (PGLite for Postgres, memfs for filesystem). Deepenable if the stand-in exists; test the merged module with the stand-in running in the suite. 3. **Remote but owned (Ports & Adapters)** — your own services across a network boundary. Define a port at the boundary; the deep module owns the logic, transport is injected. Tests use an in-memory adapter; production uses the real one...