badline 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7150f883c604da9d4f9bd4712412a020f9352dbbdba08a5051fee95e7f8bce30
-  data.tar.gz: cac44823e8c8afcc4637ad40383da5c624f51d29a60a45084b2ba6b81d6ae68e
+  metadata.gz: 2c5aff63e93f3b5e40dfee64086b8e633e0a523d5c82403f0c64270701dc701b
+  data.tar.gz: 5e1b663ccbc425e672bfd569360740f6d9dd7911a2747e8ca8e86d4575d5aba2
 SHA512:
-  metadata.gz: d09600dbf17cfa3df1d32e6ca5b8b25cd6f3cb012fd54c0cc0f7a4f700d98aaa45e9b0ba6cde95fa6c37e7310368f692e75c0f332f55fad84c5181a07df5da61
-  data.tar.gz: e3b2796713ab7701ab0a536276b6e845bb1751586c7706bdbe19a918129bb978927aef395062c98331c493af515a8ef77455446ca21289e434360753bf1aa89a
+  metadata.gz: a4cf2f04c4ad639baf9c03ef4d1140aaa6cda90b8f4d2468950f87018072aeb98610a2c268f871a9c211b9b893a10a0d65a7ee242fbfaf9979e0356b6e3df4b5
+  data.tar.gz: 0a74de512d21d0cbb905b3c8b0851dfd76ab501333a878fa7a9abcc8f104b688b25b8ee9ee651e8ba990cde98202237eaa408c491d8e8fce1b4cd2b85e38bb3a

data/.claude/hooks/session-start.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# Prepares a Claude Code on the web container to run `bundle exec rubocop`
+# and `bundle exec rspec`. The regression suites need vendor/ and aren't set
+# up here.
+set -euo pipefail
+
+if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
+  exit 0
+fi
+
+cd "${CLAUDE_PROJECT_DIR:-$(dirname "$0")/../..}"
+
+# The SDL specs open libSDL2 through Fiddle, so only the runtime library is
+# needed, as in CI.
+if ! ldconfig -p | grep 'libSDL2-2\.0\.so\.0' >/dev/null; then
+  export DEBIAN_FRONTEND=noninteractive
+  apt-get update -qq
+  apt-get install -y -qq libsdl2-2.0-0 >/dev/null
+fi
+
+# The image ships Ruby 3.3 and an rbenv. Install the newest Ruby 4.0.x, as
+# CI's ruby-version "4.0" picks, from the prebuilt binaries setup-ruby uses,
+# unless a 4.0 is installed already.
+export RBENV_ROOT=/opt/rbenv
+export PATH="$RBENV_ROOT/bin:$RBENV_ROOT/shims:$PATH"
+ruby_version=$(rbenv versions --bare | grep -E '^4\.0\.[0-9]+$' | sort -V | tail -1 || true)
+if [ -z "$ruby_version" ]; then
+  ruby_version=$(curl -fsSL https://raw.githubusercontent.com/ruby/setup-ruby/master/ruby-builder-versions.json |
+    ruby -rjson -e 'puts JSON.parse($stdin.read)["ruby"].grep(/\A4\.0\.\d+\z/).max_by { Gem::Version.new(_1) }')
+  # The binaries only run from the prefix they were built with, so unpack
+  # there and link it into rbenv.
+  . /etc/os-release
+  prefix="/opt/hostedtoolcache/Ruby/$ruby_version/x64"
+  mkdir -p "$prefix"
+  if curl -fsSL "https://github.com/ruby/ruby-builder/releases/download/ruby-$ruby_version/ruby-$ruby_version-ubuntu-$VERSION_ID-x64.tar.gz" |
+      tar -xz -C "$prefix" --strip-components=1; then
+    ln -sfn "$prefix" "$RBENV_ROOT/versions/$ruby_version"
+  else
+    # No binary for this Ubuntu release: build from source, which takes minutes.
+    rm -rf "$prefix"
+    git -C "$RBENV_ROOT/plugins/ruby-build" pull --ff-only -q || true
+    MAKE_OPTS="-j$(nproc)" rbenv install --skip-existing "$ruby_version"
+  fi
+fi
+rbenv global "$ruby_version"
+rbenv rehash
+
+# Put rbenv's shims ahead of /usr/local/bin/ruby for the session.
+if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
+  {
+    echo "export RBENV_ROOT=$RBENV_ROOT"
+    echo "export PATH=\"$RBENV_ROOT/bin:$RBENV_ROOT/shims:\$PATH\""
+  } >> "$CLAUDE_ENV_FILE"
+fi
+
+# Bundler switches to the version Gemfile.lock was bundled with.
+bundle install --jobs "$(nproc)"

data/.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

data/CHANGELOG.md

@@ -1,5 +1,112 @@
 # Changelog
 
+## [0.4.0](https://github.com/elektronaut/badline/compare/v0.3.0...v0.4.0) (2026-09-28)
+
+### Upgrading
+
+* The gem's executable is now `badline-ruby`. The name `badline` now belongs to the native build, which installs with `brew install elektronaut/tap/badline` on macOS.
+* `badline-sid` is gone. Play a tune with `badline-ruby --headless tune.sid` (or `badline --headless tune.sid`), and render one with `--audio-out out.wav`.
+
+### ⚠ BREAKING CHANGES
+
+* the `badline-sid` executable is gone. Use `badline-ruby --headless tune.sid` to play a tune and `badline-ruby tune.sid --audio-out out.wav` to render one. badline-sid's `-o`/`--output` option and positional output file became `--audio-out`, which has no short form. Badline::Audio::Options is now Badline::Options.
+* the gem's `badline` executable is now `badline-ruby`. There is no `badline` shim.
+
+### Features
+
+* add a Homebrew formula for the native badline ([33c2e98](https://github.com/elektronaut/badline/commit/33c2e983a12275195383e33230137d461b1a9fd0))
+* add mouse and paddle input to the native window ([f468c21](https://github.com/elektronaut/badline/commit/f468c2189b3b213561516a39ec0ffcedcb8c5b89))
+* emulate GEO-RAM and run the testbench geo512k rows ([9a5395f](https://github.com/elektronaut/badline/commit/9a5395fd34ad42d21e08a3b498038850d790f253)), closes [#239](https://github.com/elektronaut/badline/issues/239)
+* emulate the +60K and +256K RAM expansions ([9d60488](https://github.com/elektronaut/badline/commit/9d60488d01bd33c9d090f75f4765931f21911247)), closes [#240](https://github.com/elektronaut/badline/issues/240)
+* fold badline-sid into badline-ruby ([443d155](https://github.com/elektronaut/badline/commit/443d1559bb5253d58f5378e7e212beda5b734bda))
+* give the native badline badline-ruby's command-line options ([bd2ec0d](https://github.com/elektronaut/badline/commit/bd2ec0da269a95eccb37198dd3e03faf84651396))
+* headless .sid options for the native badline ([4354e80](https://github.com/elektronaut/badline/commit/4354e80e5b61da9148a2077d1e0557ea23a833df))
+* make the Spinel window the native badline executable ([54e8e71](https://github.com/elektronaut/badline/commit/54e8e7151e5ced11e536da6baaf779af7f4eae16))
+* model the 6526A CIA ([18a2012](https://github.com/elektronaut/badline/commit/18a201253c4612bb2ae821e544c9e6f3a6e1fb8c))
+* model the 8565 VIC-II ([e81b7fb](https://github.com/elektronaut/badline/commit/e81b7fb7053c8cca1b94dda66cda3357d2984aa1))
+* mount disk images read-only ([c35b808](https://github.com/elektronaut/badline/commit/c35b80852da7ebcf92cbf7de9478d62ba9197602))
+* pace the native window by vsync ([1fa4661](https://github.com/elektronaut/badline/commit/1fa4661b480cba2a79772096ee32327098719f1b))
+* pack the native badline with spin pack (rake native:pack) ([1d2288b](https://github.com/elektronaut/badline/commit/1d2288bd4f9c6589a35a0f99f8f1b0baeaa8e69a))
+* read SDL game controllers in the native window ([a80403c](https://github.com/elektronaut/badline/commit/a80403cefa5b75f4edbf9157631ff5eac9c234f9))
+* rename the executable to badline-ruby ([6050d9d](https://github.com/elektronaut/badline/commit/6050d9db2376ada76af5068b1e9703162adb90b3))
+* replace ruby-sdl2 with a Fiddle binding to libSDL2 ([f3a4b84](https://github.com/elektronaut/badline/commit/f3a4b8429330efaf2abfe2592e1df2fd0791a9ee)), closes [#253](https://github.com/elektronaut/badline/issues/253)
+* run the C64/ and general/ testbench rows as testbench-general ([53316c0](https://github.com/elektronaut/badline/commit/53316c03cd87e9e72d92ff8a6a9e13b6d0eae807))
+* run the Lorenz chain on a Spinel build with rake spinel:lorenz ([955d722](https://github.com/elektronaut/badline/commit/955d722a06865f6a704f14570d7b246963317551))
+* run the SID testprogs on a Spinel build with rake spinel:sidtests ([ecff9ba](https://github.com/elektronaut/badline/commit/ecff9bafa8b3621454e540d92707c0c139c7f7fd))
+* run the testbench suites on a Spinel build with rake spinel:testbench ([083911a](https://github.com/elektronaut/badline/commit/083911af7194c56992f529f67c4bf101a44fb450))
+* turn sound on by default in the native badline ([c4f65cf](https://github.com/elektronaut/badline/commit/c4f65cfa73fcad49399226f238b8b5b46799ed30))
+* type RESTORE, ↑, ← and cursor up/left from the host keyboard ([74623e3](https://github.com/elektronaut/badline/commit/74623e346d4ccad26f779d3f0c9f0c11426b96c3)), closes [#234](https://github.com/elektronaut/badline/issues/234)
+* write to disk images and swap them at runtime ([a6eebf5](https://github.com/elektronaut/badline/commit/a6eebf5e304186c8512e5cda4f6514a92ac64395)), closes [#233](https://github.com/elektronaut/badline/issues/233)
+
+### Bug Fixes
+
+* end a testbench run on the cycle the test writes its exit code ([58aa8c5](https://github.com/elektronaut/badline/commit/58aa8c52e639945a78cac40330e15a686081d8ec))
+* keep pixel 0 black out of an invalid mode into hi-res text on the 8565 ([5a6ff96](https://github.com/elektronaut/badline/commit/5a6ff96192455b9f3ca9fd8904aa9bb4760e99cc))
+* leave a PRG's end address in $AE/$AF on autostart ([d76ed18](https://github.com/elektronaut/badline/commit/d76ed1840850045ac7a1c1d3dc5c6d5d99685fdd))
+* leave the VIC's phi1 byte in the RAM under the CPU port ([55fc2f5](https://github.com/elektronaut/badline/commit/55fc2f52cd0d0a0edeb56cde140e67fb1ab50077))
+* make the mouse speed independent of the window size ([5cbabbf](https://github.com/elektronaut/badline/commit/5cbabbfade4e53c8aae265f2493466419ef67958)), closes [#280](https://github.com/elektronaut/badline/issues/280)
+* make the VIC's collision registers read-only ([141526c](https://github.com/elektronaut/badline/commit/141526ce755bf47582a25e2c209cdc950ff81f0b))
+* name the release tag in the native --version ([5654433](https://github.com/elektronaut/badline/commit/56544334b43ed992d0d54215a99a7be50fa74240))
+* read unused bits of $D016 and $D018 as 1 ([00a816b](https://github.com/elektronaut/badline/commit/00a816b9bdbe88c7f838f941b2ef2dc5cd7db075)), closes [#237](https://github.com/elektronaut/badline/issues/237)
+* say SDL2 is missing instead of raising from badline-ruby ([0f5ec9c](https://github.com/elektronaut/badline/commit/0f5ec9c7fabfa922ecb4c87339ba3ccc0f09bca0))
+* SID test bit writeback for noiselfsrinit, F->8 and the 8580's C->F ([bdb063f](https://github.com/elektronaut/badline/commit/bdb063f1aba3f1714e26bc3e8301adf9bc33fb3e)), closes [#238](https://github.com/elektronaut/badline/issues/238)
+* suggest the SDL2 runtime package when badline-ruby can't find it ([44a3375](https://github.com/elektronaut/badline/commit/44a3375973aafc0ec7aba672609517dd6571f85c))
+* **vic:** read the idle byte at $38ff where a DMA delay starts ([f3892aa](https://github.com/elektronaut/badline/commit/f3892aa0ac45fbc493bccd0f5980dfe7fc659848)), closes [#235](https://github.com/elektronaut/badline/issues/235)
+
+### Performance Improvements
+
+* **vic:** check the DMA-delay idle byte only when display state opens ([8d9b777](https://github.com/elektronaut/badline/commit/8d9b777b3554ed4d6bef67ac41c0a344c3b0a35b))
+
+
+## [0.3.0](https://github.com/elektronaut/badline/compare/v0.2.1...v0.3.0) (2026-09-24)
+
+Sound is the headline: `badline --sound` plays the SID in the emulator window and paces emulation to the audio device. It is off by default, because the emulator still runs below real time on CRuby and the sound stutters there. This release also brings the virtual drive closer to a real 1541 (buffer channels in drive RAM, DOS command parsing, the BAM in buffer 4, `LOAD"*"`), cartridge banking fixes, and `Badline::Checkpoint` with `bin/machine_diff` for checking that a change leaves emulation alone.
+
+
+
+### Features
+
+* add Badline::Checkpoint, a per-component digest of machine state ([183e164](https://github.com/elektronaut/badline/commit/183e16438b4b1bfae5c16b10f29f2b08d0a6b297))
+* add bin/machine_diff, a differential run harness ([58f695a](https://github.com/elektronaut/badline/commit/58f695a32096fe61d7395fcec9a76d8d84b5e440))
+* load ROMs from a configurable Badline.rom_path ([4fa12c8](https://github.com/elektronaut/badline/commit/4fa12c8e55004eebe0b1a14e80f03713306e3acf))
+* pace the window to the audio device while sound plays ([031b001](https://github.com/elektronaut/badline/commit/031b00196ee9a881740047c726231ffc0400d03d))
+* play the SID in the emulator window with --sound ([4cbd211](https://github.com/elektronaut/badline/commit/4cbd211ca986834e3d8fcbafdabc5586c87ec950))
+
+
+### Bug Fixes
+
+* answer a buffer channel's first read with its buffer number ([851e0d2](https://github.com/elektronaut/badline/commit/851e0d2bb71db51cc36607da90b4f7891b32bced))
+* bank BASIC out for PSID routines whose image reaches under it ([9c5bf57](https://github.com/elektronaut/badline/commit/9c5bf57646ca8de8687679accdca26ac4dd68931))
+* bank sparse and odd-sized cartridge images like the hardware ([1560f63](https://github.com/elektronaut/badline/commit/1560f63678a254bfa53e8915c35851dab00dc27b))
+* drop the carriage return that ends a file name, as the 1541 does ([3ca3d51](https://github.com/elektronaut/badline/commit/3ca3d518808cf87ab0e14a3b312e972883fc4699))
+* fail a block write at the block it names ([4b9664c](https://github.com/elektronaut/badline/commit/4b9664ca02bd0026334ffee01d4f6a5cfc354f73))
+* fail an append open on a write-protected disk ([b5c7baf](https://github.com/elektronaut/badline/commit/b5c7bafed7f189c3e7a0074d27f0b76e8ffb3b56))
+* fail an unreadable host file with a READ ERROR ([8b3d8f4](https://github.com/elektronaut/badline/commit/8b3d8f4eeae28a4ef61ef72e76dcfc02cefb738f))
+* fill a buffer channel with the bytes written to it ([36c3660](https://github.com/elektronaut/badline/commit/36c3660e1c170ea058b80d3a0b10ec019aa84058))
+* give single-bank mappers erased ROM when the image has no chip ([07e5bf3](https://github.com/elektronaut/badline/commit/07e5bf39b26e022f814c99b0d9226cecf3114400))
+* ignore whatever follows a star in a DOS file name ([b2f8831](https://github.com/elektronaut/badline/commit/b2f8831b193e496d19c03388fe0613b9f9c9abb3))
+* keep the drive's buffer channels in its RAM ([9efefe4](https://github.com/elektronaut/badline/commit/9efefe44520067db27496ea2af85468228c6579f))
+* keep the drive's RAM when the disk changes ([2c07d0e](https://github.com/elektronaut/badline/commit/2c07d0eb73120dfe1eda69a5fc8ad43a31d83ef2))
+* leave secondary address $60 in $B9 after a trapped LOAD ([d7366a8](https://github.com/elektronaut/badline/commit/d7366a8aaf0fe13d239035178751fc8f783d7a30))
+* mask Ocean and Magic Desk bank selection to the ROM size ([e6d36a0](https://github.com/elektronaut/badline/commit/e6d36a004583d18e225e4bb5cfccdd69380d523e))
+* play NTSC PSID tunes on an NTSC clock on the bare rig ([006e04b](https://github.com/elektronaut/badline/commit/006e04b03985ef5d2fe57bab6c862bbe97d65f50))
+* read DOS command parameters the way the 1541 does ([db5b4fc](https://github.com/elektronaut/badline/commit/db5b4fc06b82f5423453ee988d30f407a8565ed1))
+* read open bus from a cartridge's empty ROM socket ([fee013d](https://github.com/elektronaut/badline/commit/fee013dcff2a062b75713b268422171e79a50375))
+* read the BAM into buffer 4 when the drive initializes a disk ([c1320a5](https://github.com/elektronaut/badline/commit/c1320a5d2f7d9fcd24e800fcacaf07ba8b07b889))
+* reopen the last loaded file on a LOAD of "*" ([64b3991](https://github.com/elektronaut/badline/commit/64b3991b9e1c91190e9b47e44238b93e0ea74850))
+* report host SAVE and read failures on the drive's error channel ([039b6da](https://github.com/elektronaut/badline/commit/039b6da1779397e56ebf6cc25effe656ca85c1f6))
+* reset the drive with the machine, as the serial bus's RESET line does ([4044db6](https://github.com/elektronaut/badline/commit/4044db6ae1bd241381c2d7651cf2a44b1ae8a61a))
+* RUN BASIC RSID tunes instead of calling their first byte ([d9a51c2](https://github.com/elektronaut/badline/commit/d9a51c2eebd5092e97da576c438a647079458e78))
+* show a BMM falling out of multicolour bitmap or ECM+BMM at pixel 5 ([988a0c6](https://github.com/elektronaut/badline/commit/988a0c60e40c720e8e1cd7acf0506107902a1ccb))
+* **vic:** power on with every register zero, as VICE does ([d5bf757](https://github.com/elektronaut/badline/commit/d5bf75756d2edfdf3b6bf40214615262b79958a6))
+* wrap a buffer channel's reads back to its second byte, as the DOS does ([9c9f0ed](https://github.com/elektronaut/badline/commit/9c9f0edb7b92b580bb2cb71668e5fa07fa8e3bd9))
+
+
+### Performance Improvements
+
+* cut the SID's per-span catch-up overhead ([f50ede8](https://github.com/elektronaut/badline/commit/f50ede8472389c28c1dde70909794ef69ae77238))
+* type the hot core for Spinel with RBS seeds ([90d31b0](https://github.com/elektronaut/badline/commit/90d31b02331982e216284f2ac533f5a6aa934bf9))
+
 ## [0.2.1](https://github.com/elektronaut/badline/compare/v0.2.0...v0.2.1) (2026-09-23)
 
 

data/CLAUDE.md

@@ -18,18 +18,22 @@ live in subdirectories:
   modes, border and register timing
 - **CIA**: `cia.rb` and `cia/` (timers, serial), plus `time_of_day.rb`
 - **SID**: `sid.rb` and `sid/`. `audio/` plays and renders tunes for
-  `exe/badline-sid`
+  `badline-ruby --headless` and `--audio-out`
 - **Media and host I/O**: `storage/` (disk, tape and cartridge image
   formats), `cartridge/` (mappers), `kernal_trap/` (the LOAD/SAVE and IEC
   traps that stand in for a drive), `media.rb` (attach and autostart),
   `datasette.rb`, and `gui/` and `input/` (SDL front end, controllers)
+- **Native**: `native/` holds the native `badline`, the core compiled with
+  Spinel in an SDL2 window (`rake native:build`, `native/README.md`).
+  `spinel/` holds the Spinel test harnesses
 
 Timing-critical code lives in `cpu`, `interrupts`, `vic`, `cia` and `sid` and
 in the order `Computer#cycle!` clocks them. Changes there move the test
 suites below. `gui/` changes move none of them.
 
 Namespaced groups live in `lib/badline/<namespace>/`, with a sibling
-`lib/badline/<namespace>.rb` that requires the members. `lib/badline.rb`
+`lib/badline/<namespace>.rb` that requires the members, directly or through
+other members. `lib/badline.rb`
 requires only the namespace file.
 
 ### Oracles
@@ -52,9 +56,15 @@ timer test takes about 25 minutes.
 where that time goes. `test/baselines/README.md`
 documents the baseline format, the suites and how rows are compared.
 
+`bin/machine_diff <scenario|media> --against <rev>` checks that a change
+leaves emulation alone. It runs the scenario on this tree and on `<rev>`'s
+`lib/` side by side, digests the CPU, RAM, VIC, CIAs and SID every million
+cycles, and names the first component that differs. Use it for refactors
+and speed work.
+
 ## Driving the emulator headlessly
 
-`exe/badline <media>` opens the SDL window, which is no use for checking
+`exe/badline-ruby <media>` opens the SDL window, which is no use for checking
 work. Drive a `Badline::Computer` from Ruby instead, as the `bin/` runners do:
 
 ```ruby
@@ -113,11 +123,12 @@ worktree and owns a different set of files.
 
 - `rake vendor:checkout` fetches SingleStepTests and VICE-testprogs into
   `vendor/`
-- `bundle exec rspec`: line coverage is about 95%. `spec/spec_helper.rb`
+- `bundle exec rspec`: line coverage is about 97%. `spec/spec_helper.rb`
   fails a whole-suite run (every spec file, no filters) below 90%, while
   single-file and filtered runs skip the floor. `:slow` specs are excluded
   by default: run them with `bundle exec rspec --tag slow`
-- `rake test`: SingleStepTests. Run it for any CPU change
+- `rake test`: SingleStepTests, plus the Minitest tests for the regression
+  runners in `test/`. Run it for any CPU change
 
 The headless suites are expensive. `bin/testbench` forks over 4 shards by
 default. `SHARDS=N rake regression:<suite>` or `bin/testbench --shards N`
@@ -125,7 +136,7 @@ overrides that, capped by the core count, but keep the default, because
 other worktrees share the machine. Whole runs at 4 shards on an M-series
 laptop take 15 min for `testbench` (`VICII/`), 11 for `testbench-cia`, 1 for
 `testbench-interrupts`, 37 for `testbench-irqdma`, 11 for
-`testbench-cpu` and 2 for `testbench-carts`. `sid` takes about 12 min. `lorenz` chains itself and takes
+`testbench-cpu`, 2 for `testbench-carts` and 10 for `testbench-expansions`. `sid` takes about 12 min. `lorenz` chains itself and takes
 about 2.5 h on CI whole. `rake regression:lorenz-1` to `lorenz-4` run it as
 four stretches of about 40 min each, and they can run side by side.
 `test/baselines/README.md` has the full table. A killed `bin/testbench` run
@@ -158,17 +169,23 @@ the rows your change can't reach tell you nothing about it.
   nightly run. It also runs from the Actions tab on demand. It never runs
   on push or on pull requests, so one verdict can cover a day's merges.
   The `testbench-*` and `sid-8580` suites run from the Actions tab on
-  demand
+  demand. The Spinel workflow runs the Spinel suites on pull requests
+  that touch emulation, harness or build paths. Its jobs aren't required
+  checks yet, and the CRuby Regression nightly runs as before
 - The one exception is a change whose reach you can't bound to a set of
   filters, such as reordering `Computer#cycle!` or changing the LOAD trap
   every suite loads through. Ask before running a full suite for it, and
   don't start one on your own judgement
 
-Pick the filters from the suites your change can move: VIC → `testbench`;
+Pick the filters from the suites your change can move: VIC → `testbench`,
+plus `testbench-vicii-new` (`bin/testbench --vicii-new`, the 8565) for
+anything the VIC model reaches;
 CPU, interrupts or timing → the matching `testbench-*` suite, plus
 `rake test` for CPU; CIA → the slow CIA specs first, then the matching
-`testbench-cia` rows; cartridge mappers, banking or power-on state →
-`testbench-carts`; SID → `sid`, plus `sid-8580` for anything the 8580
+`testbench-cia` rows, plus `testbench-cia-new` (`bin/testbench --cia-new`,
+the 6526A) for anything the interrupt register or the CIA model reaches; cartridge mappers, banking or power-on state →
+`testbench-carts`, plus `testbench-expansions` for banking; GEO-RAM, +60K
+or +256K → `testbench-expansions`; SID → `sid`, plus `sid-8580` for anything the 8580
 model reaches (`bin/sidtests --sid 8580`). Lorenz isn't a per-change check:
 its full chain runs nightly, and the planner assigns any row it moves. The
 exception is code whose rule in `doc/pinned-behaviour.md` names Lorenz
@@ -201,17 +218,35 @@ you change code a pinned rule governs, re-derive the rule against its test
 and update the doc if the rule moves. A green suite alone isn't enough,
 because the suite can stay green while the rule breaks.
 
+## Issues and pull requests
+
+Before filing an issue or opening a pull request, read CONTRIBUTING.md and follow it. Use the exact headings from its skeletons. Report only what you observed or verified, and don't include hypotheses about causes. Open an issue before writing non-trivial code; only changes with one obvious fix (typos, broken links, clear-cut fixes) go straight to a pull request.
+
+### Working from issues
+
+Open issues are agreed work. An agent told to pick issues works this way:
+
+- Pick an open issue without the `in-progress` label whose dependencies
+  (named in its body) have merged. Add the label and a comment saying you've
+  taken it before you start
+- Work in a worktree from `origin/main` as described under *Working in
+  parallel*. The issue's text is your brief. If it turns out wrong or
+  blocked, comment on the issue and stop rather than widening the scope
+- Open one pull request per issue with `Closes #N` in its body, and run
+  only the rows your change can reach. Picking an issue is permission to
+  commit, push and open that pull request
+- Never merge, and never enable auto-merge. The planner session reviews
+  every pull request, answers through PR reviews, and merges
+- Fix review findings on the same branch. If you drop an issue, remove
+  the label and say why in a comment
+
 ## Git
 
-- **Don't stage, commit, push or open a PR** unless your task says so in
-  those words. Wanting a PR, a finished feature or green CI doesn't count
-  as permission. Finish the work, report what changed, and stop. A dirty
-  tree is the expected end state
 - Hunks are staged by hand during review, so a partially staged file is
   deliberate. Use `git diff HEAD` to see everything
 - Commit messages use Conventional Commits (`feat:`, `fix:`, `chore:`, …).
   release-please derives version bumps and the changelog from the prefixes
 - No `Co-Authored-By` or `Claude-Session` trailers, even where `git log`
   shows them
-- When a task explicitly asks for a PR, the branch is already from
-  `origin/main` (see above). Open it with `gh pr create --base main`
+- Open pull requests against `main`, from a branch cut from `origin/main`
+  (see above): `gh pr create --base main`

data/CONTRIBUTING.md

@@ -1,16 +1,58 @@
 # Contributing
 
+This guide covers bug reports, feature requests, and pull requests. It applies to everyone, including AI agents filing on someone's behalf.
+
+In the GitHub web interface, issue forms guide you through the structure. If you file through the API or the `gh` CLI, the forms are bypassed: copy the matching skeleton from [Skeletons](#skeletons) and keep the headings exactly as written.
+
 Bug reports and pull requests are welcome on
 [GitHub](https://github.com/elektronaut/badline). Everyone participating
 is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
 
+## Principles
+
+### For all issues and pull requests
+
+**Report only what you observed or verified.** Whoever investigates, human or agent, anchors on the claims in a report. Unverified claims cost more time than they save.
+
+**No hypotheses about causes.** Diagnosis is the maintainers' job. They add theories as comments, where the author shows how much weight to give them. Speculation in a report misleads everyone who reads it.
+
+**Keep it short.** Length hides the useful information. A long report usually means two reports, or padding.
+
+**One concern per issue or pull request.** Mixed concerns can't be tracked, reviewed, or reverted independently.
+
+**Use the exact headings.** Maintainers and their tools rely on them to process reports.
+
+### Bug reports
+
+**Minimal, numbered steps you actually ran.** A reproduction nobody has run is speculation too.
+
+**Raw output, not a paraphrase.** The details that matter are the ones a summary drops.
+
+**Ruled out: negative results only.** "Still happens with caching disabled" narrows the search without steering it.
+
+### Feature requests
+
+**Problem before solution.** A proposed solution constrains the design before anyone familiar with the code has weighed in.
+
+### Pull requests
+
+**Open an issue before writing non-trivial code.** Code is cheap to write; choosing the right change is the expensive part. An issue lets maintainers weigh in on the approach before anything is built, while an unsolicited implementation anchors the discussion on one solution. Open a pull request directly only when there's one obvious way to make the change: typos, broken links, or a clear-cut fix. Reporting those costs more than fixing them. They don't need the template; a one-line description is ideal.
+
+**Describe what changed, not what it might fix.** The diff shows how. Broad claims steer reviewers the same way hypotheses steer investigators.
+
+### Security
+
+**Never report vulnerabilities publicly.** Report them privately as described in [SECURITY.md](SECURITY.md).
+
 ## Getting started
 
-Badline needs SDL2, which is available from most package managers.
+Badline needs the SDL2 library, which is available from most package
+managers. Building the native `badline` also needs the SDL2 headers
+(`libsdl2-dev` on Debian/Ubuntu); see [native/README.md](native/README.md).
 
 ```sh
 brew install sdl2           # macOS
-apt install libsdl2-dev     # Debian/Ubuntu
+apt install libsdl2-2.0-0   # Debian/Ubuntu
 ```
 
 Install the dependencies and run the specs:
@@ -40,7 +82,7 @@ Check style before pushing:
 bundle exec rubocop
 ```
 
-## Pull requests
+## Tests and commits
 
 - Add tests for any behavior you change.
 - Write commit messages using
@@ -49,3 +91,53 @@ bundle exec rubocop
   `fix:` prefixes decide what ends up in the next release.
 - Leave the version and `CHANGELOG.md` alone. Both are updated
   automatically when a release is cut.
+
+## Skeletons
+
+Leave out optional sections you have nothing for.
+
+### Bug report
+
+```markdown
+### Expected behavior
+
+<!-- What should happen. -->
+
+### Actual behavior
+
+<!-- What happened instead, as observed. Include the error message, if any. -->
+
+### Steps to reproduce
+
+1.
+2.
+3.
+
+### Error output
+
+<!-- Optional. Raw stack trace or log lines in a code block. -->
+
+### Ruled out
+
+<!-- Optional. Negative results only, e.g. "Still happens with caching disabled." -->
+```
+
+### Feature request
+
+```markdown
+### Problem
+
+<!-- What you're trying to do, and what's blocking you. -->
+
+### Current workaround
+
+<!-- Optional. How you get around it today, if at all. -->
+
+### Proposed solution
+
+<!-- Optional, and brief. -->
+```
+
+### Pull request
+
+See [.github/pull_request_template.md](.github/pull_request_template.md).