Execution rulings, sub-project 1

Sub-project 1 (connectome ingestion, brain engine, and this book) was implemented on 2026-09-15 by a controller session dispatching one fresh implementer per plan task with a review after each, followed by a whole-branch review, two independent code reviews, and one consolidated fix wave. Decisions the controller took on the owner’s behalf are listed here in the order they were made, with what each costs if it turns out wrong. The ledger they were copied from lived in the gitignored SDD workspace and was deleted after the merge; this chapter is the record.

Process rulings

1. Work proceeded on branch engine in the main checkout rather than a worktree: the repository was new with nothing on master to protect. Cost if wrong: a branch switch.
2. .superpowers/ was added to .gitignore before the first task so the execution workspace could never be committed. Cost: a one-line merge.
3. Docstring-only __init__.py stubs need no from __future__ import annotations; the style rule exists for annotated code. Cost: one import per stub.
4. A commit-message-only amend was verified by the controller instead of a scoped re-review, since the file diff was empty. Cost: none.
5. The commit trailer named in the plan binds every subagent regardless of the model that actually ran it. Cost: none.
6. Two small changes to finished modules (the gain_group field and the pre_ids filter) were folded into a later task rather than reopening finished ones. Cost: none.
7. At the owner’s request the book task ran in parallel with the engine tasks in a separate worktree on branch book, with the benchmark notebook entry deferred until the benchmark existed. Cost: a merge, which was clean.
8. Two defects in the plan’s own test code (a zip(..., strict=True) over a shifted slice, and a mutable default argument) were fixed by ruling rather than by changing the engine. Cost: none.
9. After the re-review of the fix wave, the controller edited two documentation lines and one configuration comment directly, gated by make all. Cost: none.

Design rulings

1. A photoreceptor’s column is the hex column receiving the largest summed synapse count, not its single strongest target, because a lamina cartridge is what a photoreceptor innervates; the side comes from the winning column. On this dataset the two rules agree on nearly every cell. Cost if wrong: a re-placement pass.
2. The external review’s findings were accepted and folded into the spec and plan, except the single-strongest-target rule above.
3. Config and checkpoint schemas are deferred to the sub-project plans that create them.
4. The book keeps a paraphrased lead-in and drops a cross-reference in the data chapter, because the referenced section is not in the book. A reviewer’s objections to the background chapter’s sourcing were overruled: the neuron and edge counts, the FlyWire brain being female, and the characterizations of the cited work are correct. Cost: a sentence edit.
5. MathJax stays enabled and genuine equations are rendered as math, at the owner’s instruction.
6. The retina correction was redesigned after the whole-branch review measured that the per-photoreceptor rule left the median lamina cell with one sixth of the intended drive and 27% of lamina cells with none. It is now per lamina cell (six cell-equivalents from whatever reaches the cell) with virtual photoreceptors wherever a lamina cell has no drive. Cost: a rebuild, already done; the first benchmark entry records both builds.
7. The shuffled control was redesigned after the code review measured that the synapse-stub model quadrupled the edge count and flattened every weight. It now permutes destinations within synapse-count classes, preserving each neuron’s synapse totals, the edge count, and the weight distribution, and it never touches edges from input neurons, so the control shares the real sensory interface. Cost: the control’s definition changed before any training used it.
8. The event propagator’s second host synchronization per step, the pandas typing convention, and the duplication between the spec and the book chapters are deferred follow-ups, recorded in the notebook and below.

Parked and deferred

• The shuffle’s int16 merge clamp is latent: the largest merged count in the v1.0 control is 2,601 against a ceiling of 32,767, and no counter reports a clamp. Real, not load-bearing.
• Per-task minor findings, all triaged “can wait” by the whole-branch review: broader ruff selection than the standard; pick_device("") auto-selects; shared tables and meta between derived imagos; the fixture’s repeated photoreceptor loops; mislabeled type-ignore codes and an unused import in one test; pandas cast density; path comments and a rebound local in ingestion; an untyped test helper; no CLI handling of missing paths (must be fixed before the flight supervisor ships); a shared helper for the two edge-orientation functions; no direct test of class-based mask inclusion or of the Metal batched propagator selection; per-step temporaries in the engine step and an untested noise branch; recorder docstrings; two type-ignores in the benchmark test.