post-migration: has the tooling tier painted itself into a complicated corner? nf-nd6v ← Beads

Twinned from https://github.com/cfsh/ninefold/issues/484 by tools/beads/import_github.py's reconcile pass.

Filed unclaimed and unlabelled from ninefold-a. Backlog, for a triage round after design 001's migration completes.

Raised by aedanpope in chat while reviewing #462:

> "once we finish migrating everything to py, we should take a look across these scripts and see what we can _simplify_ I think everything is getting quite complicated, with these long block comments, and complicated state machines. I can see why each piece is locally necessary, but I wonder if we've painted ourselves into a complicated corner a little bit"

The last sentence is the whole issue. Every piece is locally necessary — each block comment and each state closes a specific incident, and the reviewer verified them one at a time. The question is whether the accumulation is still the right design, and nobody has been in a position to ask that, because every round has been scoped to one finding.

Measured, 2026-08-04, at the top of the stack

Prose outweighs code almost everywhere:

| file | code | prose | prose % | |---|---|---|---| | poll.py | 452 | 409 | 41% | | dispatch.py | 419 | 519 | 47% | | merge_pr.py | 221 | 238 | 43% | | probe_gate.py | 219 | 205 | 40% | | proc.py | 141 | 129 | 41% | | verdict.py | 44 | 149 | 63% |

verdict.py is the clearest case: 44 lines of logic carrying 149 lines of explanation. Three and a half lines of justification per line of code.

The liveness check is the state machine he means:

dispatch_health — 129 lines, 15 branches, 16 return statements, for the question *"is the reviewer alive?"*. More branches than the dispatcher's entire trigger policy (decide: 9 branches, 80 lines).

It accreted across five commits, one state per finding:

``` d8ce802 fresh / stale / ok:false 3 states b95ee81 + mid-sweep (corroborate with dispatch.log) 4 1ea16e9 + writer-broken, + never-completing ceiling 6 03badb1 + warning must post-date the heartbeat 7 ```

Nobody chose a 7-state machine. That is what "painted into a corner" looks like mechanically: local correctness at every step, and no step at which the whole shape was up for review.

The distinction worth making first

Complexity that is in the CODE vs complexity that is only in the EXPLANATION. They have very different fixes and very different risks, and lumping them together is how a simplification pass deletes something load-bearing.

Initial read, offered as a starting hypothesis rather than a conclusion:

• Likely reducible — structure. dispatch_health is one function doing *gather evidence* + *classify* + *word the message*. Split three ways it is plausibly ~4 states plus a message table; the 16 returns are the symptom of the three jobs being interleaved.
• Likely reducible — prose. Much of the inline comment mass is *"here is the incident, here is why the obvious alternative is wrong"*. That is real value in the wrong container: it belongs in the commit message, the issue, or a design doc, not inline forever. verdict.py at 63% is the extreme.
• Probably NOT reducible. The || true-vs-strict distinction in dispatch.py, the three-state lockfile, the LOGDIR/LOCKDIR asymmetry, the cp1252 forcing. That is complexity the *domain* actually has, and design 001 §6 already lists several as things a "tidying" port must preserve verbatim. Deleting those comments is how #352 recurs.

A pass that cuts the second category hard and the third not at all is probably most of the win.

Why this likely wants /design rather than a straight implementation chunk

The deliverable is a judgement about shape, and the failure mode of doing it as ordinary work is obvious: a session simplifies locally, deletes a guard whose comment explained why it existed, and the next incident re-derives it. /design's output — a written conclusion in design_docs/ — is what lets a later session tell "this was considered and rejected" from "nobody thought about it".

It would also want to decide a standing convention, not just do one cleanup: what belongs inline vs in the commit vs in a design doc. Otherwise the ratio simply rebuilds. #450 and #481 are the same theme from the testing and reporting sides.

Scope note

Explicitly after the migration — aedanpope's own framing ("once we finish migrating everything to py"). Simplifying mid-stack would fight five open PRs and destroy the differential oracle's value, since every remaining port is verified against shell behaviour that a simplification would deliberately change.

Related: #450 (tests that cannot fail), #481 (claims that outlive their tree), #482 (throwaway mutation harnesses), #414 (scaffolding that does not survive a session). All four are the same underlying question — *how much of this machinery is carrying its own weight?* — and it is plausible they should be triaged together rather than one at a time.