5 million steps was picked when the worst macro (clb_add_ip with B=2047) sat just
under a million, so it caught hangs quickly. The interactive programs changed the
arithmetic: one printed line of the desk calculator costs about 225k steps (40k
for clb_undigits, up to 32k for the operation, ~141k for clb_digits), which is only
about twenty lines before the cap, and examples_test applies the same cap to every
example.
At roughly 2.3e8 steps per second a 20M cap costs 0.09 s when a program really does
run away, and byte_op_test (the only place that runs 465k programs) is unchanged --
so the safety net stays cheap while a session gets four times the room.
docs/calc.md, docs/divmod.md, docs/byte-ops.md and SPEC's "500 ?" mentions now say
2000 ?.
The three documents had grown to 2038 lines and quoted each other: 2199 appeared
seven times, 3977 ten times, AGENTS carried a 200-line copy of SPEC's byte-level
tables while README carried another 155-line copy still showing 8-bit-era numbers
(clb_add_nc 688, clb_not_ip 17, ...) that are wrong at 11 bits.
Split by responsibility, keep every fact exactly once:
README.md front door: what it is, 30-second build+run, directory map, where
to read next 547 -> 143 lines
SPEC.md the contract: %synth, geometry, every macro's signature / cells /
tape length / who verifies it, test matrix, boundaries, maintenance
901 -> 807 lines
AGENTS.md the manual: hard rules, build and self-check commands, the traps,
current state, next candidates, do-not-touch list
590 -> 132 lines
Long-form reasoning moves into docs/ instead of being dropped:
docs/divmod.md the shift-restore division story (was SPEC 14, 102 lines;
renumbered 1..6, SPEC keeps a pointer and the references in
SPEC 7.6 and asm/divmod.r8asm now point there)
docs/byte-ops.md the byte-level design history (was README's 155-line section,
rewritten with 11-bit numbers since the old ones were
measured at 8 bits)
Also fixes what the dedupe exposed: SPEC no longer claims only the multiplier has
a step bound, and raw_sub's comment no longer repeats the retracted "1.48M steps"
figure. Every section reference in the tree resolves; the baseline still passes
(asm/test.r8asm 64513 characters, 21 byte-op items, 14 examples, 48 macros).