Code cleanup review: YAGNI, DRY, KISS

The whole repository was read area by area: 104,000 lines of source and the tests. No code was changed. The result is a plan doc with 25 workstreams and a findings file per area, for an agent to work from.

246findings in 14 areas
19major: reshape a module or remove a concept
70moderate
157minor: a local tidy-up

156 are DRY (one piece of knowledge in several places), 69 KISS (more machinery than the job needs), 21 YAGNI (code nothing needs).

The verdict

Already in good shape

Where the debt is

The 19 major findings

FindingAreaWorkstream
T1"A card started, a commit in its workspace, handed over" is written about a dozen timesTestsW2
T2The workers fixture cannot be told its adapter: 27 "remove it and set it up again" calls, about 85 tests build everything twiceTestsW2
T3The one-repository canvas harness is rebuilt in file after file: there is a workers fixture but no canvas fixtureTestsW3
E1"Git steps" generators serve a synchronous runner that only two scripts and tests useGit and workspacesW5
E2The git runner is private to workspaces.ts, so seven modules wrote their ownGit and workspacesW5
E5workspaces.ts is three modules; most importers want only the smallest oneGit and workspacesW5
C2What a card row's JSON columns hold is cast by hand at about ninety placesBoard and databaseW7
C1Board repeats the Store's sheet and history API method by methodBoard and databaseW8
C3board.ts holds three subsystems that are not the boardBoard and databaseW9
A1workers.ts is a grab bag: one 4,860-line class behind five bannersWorkersW11
B1runtime.ts is the interface, the Claude Code runtime and a shell reader in one 1,167-line fileRuntimesW13
D1canvas.ts is four modules in one file, and CanvasRuntime alone runs 2,680 linesCanvas and assistantW14
F1serve() is one 1,120-line functionHTTP serverW16
J1types.ts is a grab bag: 89 functions and constants in a file called "shapes", several of them used by one side onlyCoreW19
H3Phone() is one 616-line component that does six jobsUI: phone and panelsW21
G1Canvas is one 2,045-line component with about 120 hooksUI: app shell and cardW21
G2Detail renders four kinds of card through early returns and some twenty booleansUI: app shell and cardW22
P1director.ts is five modules in one filePluginW24
R1scratch-obeya.ts stages in 580 lines of top-level statementsScriptsW25

The 25 workstreams, in order

Each is a package that can land on its own. An agent takes one, reads its findings, checks each against the code again, and changes no behaviour.

WorkstreamFindings
W1Dead code and stray comments26
W2A workers test fixture that covers the common setups221
W3A canvas test fixture12
W4The rest of the test infrastructure51
W5One git module342
W6Small shared server helpers, each written once313
W7A card's row and its events typed in one place145
W8The sheet as an object of its own1
W9board.ts holds the board after W7 and W811
W10The pause protocol once for every kind of agent2
W11workers.ts split along its seams, by moves only after W2 and W7111
W12The long functions of the workers after W1168
W13The runtimes117
W14canvas.ts and coordinator.ts by subject after W3115
W15The commands24
W16The HTTP server and the configuration149
W17Sharing, demo sites and demo pages615
W18Forges, the PR watcher, hosts and folders after W515
W19src/core134
W20The UI's shared mechanisms314
W21The app shell and the phone after W20236
W22The card after W20146
W23The settings sheets and panels after W2059
W24The plugin1210
W25The scripts and the desktop app146

n major n moderate n minor

What the report does not cover

No second opinion from Codex. The Codex review was stopped before it produced results, so the findings are one model's reading. About forty claims, the ones the 19 major findings rest on among them, were checked a second time against the code and held.

The tests were read in part. The shared test infrastructure and all setup code were read, the test bodies of the twelve largest files only to about 15 %.

Nothing was tried. No proposed change was compiled or run. Each finding says how sure its reviewer was.

41 bugs were noticed in passing. They are listed at the end of each findings file and are outside the cleanup, since fixing one changes behaviour.

Where it is

docs/plan/code-cleanup.md is the plan doc: the goal, how the review was made, the rules for the agent that works from it, and the workstreams. Once it is on main, Obeya shows it as a project. The findings are in docs/plan/code-cleanup/, one file per area, each finding with where the code is, what it does now, the proposed change, the win, the risk and the reviewer's confidence.