2 Commits
Author SHA1 Message Date
dsh b2ba20b885 vms: raise the step cap from 5M to 20M
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 ?.
2026-11-11 11:04:14 +08:00
dsh a82d95658e docs: one home per fact -- README as the front door, SPEC as the contract, AGENTS as the manual
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).
2026-11-09 16:34:15 +08:00