disasm/AGENTS.md

# AGENTS.md

## What this repo is

Thirty-six AI-generated disassemblies of NES ROMs: 17 promoted to top-level folders and 19 skeletons still under `_wip/`. The contract (stated in `PROMPTS.md` and verified by `make` in every `copilot/` folder) is **byte-identical rebuilds**: `reconstructed.nes` must match the original ROM exactly. Not for distribution (`README.md`).

## Layout

- Each project owns a folder with a `copilot/` build dir (`prg.s`, `header.s`, `chr.s`, `linker.cfg`, `symbols.inc`, `locals.inc`, `Makefile`, and a copy/symlink `rom.nes`) and a per-project `OVERVIEW.md` at the folder root (power-on flow analysis). Some older ones use `main.s` instead of `prg.s`, and a few lack `prg.bin` (carve the PRG out of `rom.nes` instead).
- Root `OVERVIEW.md` is the index: vectors, build fixes, and summary for all 36 projects. **Keep it in sync** when a project changes — its DK Jr. entries drifted badly before being corrected, and its vector column later turned out to have five rows wrong from copy-paste duplication.
- `TODO.md` is the handoff: open work per project, plus the gotchas that cost real time. Read it before starting anything non-trivial.
- `PROMPTS.md` is the workflow contract. `default_project.tar.gz` is the empty-project skeleton (prg.s, symbols.inc, linker.cfg, Makefile, locals.inc). `_ROMS/` is the master ROM store.
- `_tools/`: `nesdis.py` (Pass 1 tracer), `pass2.py` and `bytecode_dis.py` (Pass 2/3 emitters), `trace_stage_payload.py` (py65-based runtime tracer), `cdl_reclass.py` (Mesen-CDL-driven code/data split fix), `verify_pass1.py` (rebuild + re-trace check across all projects), `splitnes.py`, `chr2gif.py`.

## Commands

```bash
cd "<Project>/copilot" && make   # builds reconstructed.nes, then cmp vs rom.nes
python3 _tools/verify_pass1.py  # rebuilds and re-traces every project
```

`make`'s default target includes the byte-identity `cmp` — a build that doesn't print "Byte-identical ROM verified." is a failure. Requires `ca65`/`ld65` on PATH.

**There are two build tiers, and the difference is real.** Top-level projects compare the whole ROM against `copilot/rom.nes`. The 20 `_wip/` projects only run `cmp reconstructed_prg.bin prg.bin`, so their **header and CHR are not proven** — do not describe them as byte-identical to the ROM.

## Promoting a project out of `_wip/`

1. `git mv "_wip/<name>" "<name>"` — the relative `copilot/rom.nes -> ../<name>.nes` symlink survives untouched.
2. Add `copilot/rom.nes` (a space-free copy or symlink of the original) and switch the Makefile from `cmp reconstructed_prg.bin prg.bin` to `cmp reconstructed.nes rom.nes`.
2b. A Pass-0 skeleton has no `header.s`/`chr.s` and its `linker.cfg` declares only the PRG memory area, so add all three (copy the shape from `Burger Time (U)/copilot/`: two one-line `.incbin`s and `HEADER: start = $0000, size = $0010` ahead of PRG) or the whole-ROM compare has nothing to link. `Lunar Pool (U)` is the worked example (2026-10-18).
3. Change `../../../_tools/` to `../../_tools/` in the Makefile — the depth changed by one.
4. Verify `make`, then `make regen` if a regen pipeline exists.
5. Add it to the root inventory table and re-number the `_wip` rows.


## Irreversible conventions (do not "clean up" past these)

- Every instruction carries a trailing audit comment with its CPU address, PRG offset and exact emitted bytes. The dominant spelling is `; CPU:$C123 PRG:0123  AD 21 03` — 8 of the 17 top-level projects use exactly it — but **six other spellings are in use across the repo** and 1,013 of Excitebike's 5,376 instruction lines carry no comment at all (`_tools/verify_pass1.py` reports the split; it needs `re.M` on the canonical pattern, fixed 2026-10-18, or it misreports every project). This is the byte-identity audit trail — preserve whatever spelling a file uses even while renaming labels or restructuring files. See the TODO in root `OVERVIEW.md` for closing the gap.
- Unreached/unresolved bytes stay as data (`Label_/Data/` `.byte` or `.incbin` blocks with ROM provenance), never deleted or reformatted.
- Routine headers follow the template in `prg.s`: global + local description, parameters, returns, clobbers.
- Two separate symbol files: `symbols.inc` = NES hardware constants only; `locals.inc` = zero-page and forward references. Unresolved zero-page bytes keep neutral `ZpXX` names rather than speculative names. Proven semantic names may sit *beside* the generated `ZpXX` entries as aliases.
- Pass discipline: Pass 1 = code/data split (stop for review), Pass 2 = label replacement, Pass 3 = semantic naming of data tables/structures. Do not skip straight to guessy rewrites. When a pass is only partly achievable, record the residue and why rather than inventing names.
- `make regen` (where it exists, e.g. MUSCLE) must keep reproducing `prg.s` byte-for-byte on the standard library alone. Re-check it after any `nesdis.py` change.

## Hard-won quirks (details in root `OVERVIEW.md` per-project "Build fix")

- The flat disassembler mislabels `bne` as `bpl`; fixes use `bne *-$XX` to reproduce the original bytes (Clu Clu Land, Defender 2, Excitebike).
- Zero pages are reused across modes; aliases may be required in `locals.inc` (e.g. `RandomStateAlt = $E4` beside `RandomState0 = $54`).
- Donkey Kong Jr. is architecturally different: reset entry is $C66E, the reset path idles forever in an LFSR loop, and the entire frame state machine runs inside NMI. Its `DeferredTaskHandlerTable` entry 0 deliberately mirrors the IRQ vector word at $BFFE.
- IRQ vectors often point at unused/data targets in these games — verify before assuming a handler is broken.
- Unlicensed titles break static-trace assumptions: Pyramid (U) pokes a mapper unlock at `$4100` (beyond the register space) despite a mapper-0 header, and dispatches through `jmp ($0002)` built from RAM — trace via its two queue tables (`$C3A6`, `$CCD5`), and do NOT fall-through-seed gaps that follow `rts`/`jmp`/`brk` (that misclassifies data as code).
- ROM filenames contain spaces **and parentheses** (e.g. `M.U.S.C.L.E. (U).nes`); builds `incbin` a space-free `rom.nes` inside `copilot/`. Keep that copy/symlink working and don't rename it. Note that a name with spaces/parens is also what makes FCEUX hang headless — symlink it to a clean name and run under Xvfb.
- `.gitignore` contains `ROMS/*` but the actual directory is `_ROMS` — the pattern matches nothing, so ROM binaries stay tracked. Check before committing large blobs.

## Tracer and toolchain gotchas (2026-10-17)

Full detail and reasoning in `TODO.md`. These are the ones that silently corrupt results rather than failing loudly.

- **Undocumented opcodes silently truncate a trace.** A tracer that knows only the 151 official opcodes halts on the first one used as ordinary code. Joypad Test Cartridge died at `$C09E` on `DCP $3C20` (`$CF`) and filed **3,256 bytes of real code as `.byte`**. `nesdis.py --undocumented` decodes all 105 (default **off**, so existing `make regen` pipelines stay byte-stable).
- **ca65 V2.19 implements none of the undocumented opcodes**, so they cannot be written as mnemonics. `nesdis.py` emits them as explicit `.byte` with the disassembly in the comment — that keeps them in the code region, so both the split and the audit trail survive. ca65 is also happy to accept plain `nop`, which is official (`0xEA`).
- **Vectors are not in the iNES header.** They are the three little-endian words at the *end* of the 16 KB PRG (`$FFFA–$FFFF` in the `$C000` mirror). Header bytes 0–9 carry only sizes, mirroring and mapper. Parsing them from `header.bin` as if they were header fields yields garbage.
- **RESET and IRQ are usually the same address.** The semantic-name map must not overwrite on collision, or the primary entry gets renamed to `IrqHandler`. Use `setdefault` in RESET/NMI/IRQ priority order.
- **Control-flow targets must win over fall-through.** A fall-through decode whose *operand* spans an address that another path branches to is the wrong decode — no assembler branches mid-instruction. Mario Bros had a `bne` at `$C4BA` targeting `$C528` swallowed by a `NOP #$A5` at `$C527`.
- **Branch targets inside a surviving instruction must be pruned** from the target set, or the emitter's linear walk consumes those bytes as an operand, the label is referenced but never defined, and **the file does not assemble at all**.
- **A plain vector trace reaches only ~15% of a real game.** Almost everything sits behind computed dispatch. Look for `jmp ($xx)`, and for dispatchers that pop the table address with `pla` — that form cannot be followed from the dispatcher because the pointer is only knowable in the caller's frame (Mario Bros `$CD9E`). Probing a suspected data region linearly with `nesdis.py --probe` is cheap and settles whether it is code; `--auto-seed` plus a couple of `--extra-seed` addresses took Mario Bros from 14.6% to 72.2%.
- **When emulating to trace, NMI must fire once per frame, not per `$2002` read.** The main loop polls `$2002` to sync on vblank, and each read clears bit 7, re-arming NMI within the same scanline. Guarding on the vblank flag alone gave **40,900 NMIs across 3,000 frames** and flattened coverage at 26%.
- **Controller input goes on joy1 = `$4016`** with a real latch/shift register. The poll routine's `lda $4016,X` with X=1 lands on `$4017`, but only bits 0–1 are compared, so driving `$4017` consumes nothing and changes no coverage at all.
- **`ca65 -l` listings contain no source line numbers** — they emit `<offset>r <n>  <bytes>  <source text>`. You cannot key listing entries back to source lines, and the listing prints `rr rr` for relocatable words, so byte values must come from `prg.bin`.
- **py65 is not a build dependency.** Unpack on demand (`pip download --no-deps py65`, then `unzip` into a lib dir; `PY65LIB` env var points at it). `/tmp` is volatile — a reboot wiped it mid-session. Anything reusable belongs in `_tools/`.