0 Fork 0

T

tmerritt ad894f47f3 Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

Port Test Cartridge (U): Pass 2 complete - all 28 Label_XXXX definitions
renamed to semantic routine names (Reset, WaitForVblank, IrqHandler,
NmiHandler, NmiMode0/1/2, NmiFrameCheck, UpdatePpuRegisters, StrobeJoypad,
ReadJoypadSerial, StoreJoypadState, ComputeJoypadChanges,
ShiftBits8Setup/Loop, ShiftBits8Setup2/Loop2, DecodeJoypadButton,
SetByteFF, ReturnFromSub, PushReturnAddress, IndirectJumpViaZp,
SetupPpuAddress, ConfigurePpuCtrl, ShiftTileIndexBits, BranchOnCarrySet,
WritePpuDataBytes, DispatchVramCommand, MemsetZeroSetup/Loop), all 17 raw
jsr/jmp call operands resolved to symbolic labels, zero Label_ residue.
Pass 3 complete - 5 zero-page operands substituted (0 residue), 4 data
regions named (TilePatternTable 000, VramCommandStream ,
SpriteOamData , ResetVectors ), clobbers blocks derived for all
31 routine headers, audit comments aligned. make stays byte-identical.

git mv from _wip/NROM/ to NROM/Port Test Cartridge (U)/; root README.md
inventory updated (row 42 main table, row 55 status table); WIP.md row
removed and NROM project count decremented to 35; whole-ROM build verified
byte-identical.

Promote 10-Yard Fight (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

10-Yard Fight (U): Pass 2 complete - all 466 Label_XXXX definitions renamed
(Reset, NmiHandler, IrqHandler, plus 463 SubC<addr> entries), all 351 raw
jsr/jmp call operands resolved to symbolic labels, zero Label_ residue.
Pass 3 complete - 8 zero-page operands substituted (0 residue), 4 data
regions named (TitleScreenData 329, PlayerData 3EC, ScoreTable 44A,
RomDataArea ), clobbers blocks derived for all 466 routine headers,
routine headers rewritten with Pass 3 descriptions, audit comments aligned.
make stays byte-identical.

git mv from _wip/NROM/ to NROM/10-Yard Fight (U)/; root README.md inventory
updated (row 43 main table, row 56 status table); WIP.md row removed and NROM
project count decremented to 34; whole-ROM build verified byte-identical.

Promote Chubby Cherub (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

Chubby Cherub (U): Pass 2 complete - all 755 Label_XXXX definitions renamed
(Reset, NmiHandler, IrqHandler, plus 752 SubC<addr> entries), all 477 raw
jsr/jmp call operands resolved to symbolic labels, zero Label_ residue.
Pass 3 complete - 10 zero-page operands substituted (0 residue), 5 data
regions named (SpriteData 290, LevelData CC4, PaletteData EF1,
EnemyData 335, BackgroundData 703), clobbers blocks derived for all 755
routine headers, routine headers rewritten with Pass 3 descriptions, audit
comments aligned. make stays byte-identical.

git mv from _wip/NROM/ to NROM/Chubby Cherub (U)/; root README.md inventory
updated (row 44 main table, row 57 status table); WIP.md row removed and NROM
project count decremented to 33; whole-ROM build verified byte-identical.

Promote Dig Dug II (U) [!] from _wip/ to NROM/ (Pass 1+2+3 complete)

Dig Dug II (U) [!]: Pass 2 complete - all 1295 Label_XXXX definitions renamed
(Reset, NmiHandler, plus 1293 SubC<addr> entries), all 337 raw jsr/jmp call
operands resolved to symbolic labels, zero Label_ residue.
Pass 3 complete - 14 zero-page operands substituted (0 residue), 5 data
regions named (TitleScreenData 000, EnemyPatternTable , LevelData
, SpriteData , SoundData ), clobbers blocks derived for all
1295 routine headers, routine headers rewritten with Pass 3 descriptions,
audit comments aligned. make stays byte-identical.

git mv from _wip/NROM/ to NROM/Dig Dug II (U) [!]/; root README.md inventory
updated (row 45 main table, row 58 status table); WIP.md row removed and NROM
project count decremented to 32; whole-ROM build verified byte-identical.

Promote Gyromite (JUE) from _wip/ to NROM/ (Pass 1+2+3 complete)

Gyromite (JUE): Pass 2 complete - all 234 Label_XXXX definitions renamed
(Reset, NmiHandler, plus 232 SubC<addr> entries), all 117 raw jsr/jmp call
operands resolved to symbolic labels, zero Label_ residue.
Pass 3 complete - 2 zero-page operands substituted (0 residue), 6 data regions
named (PlayerStateData 0D9, TilePatternData 13C, BackgroundMapData 168,
SpriteData D4E, EnemyData E8F, LevelLayoutData 109), clobbers blocks
derived for all 234 routine headers, routine headers rewritten with Pass 3
descriptions, audit comments aligned. make stays byte-identical.

git mv from _wip/NROM/ to NROM/Gyromite (JUE)/; root README.md inventory
updated (row 46 main table, row 59 status table); WIP.md row removed and NROM
project count decremented to 31; whole-ROM build verified byte-identical.

Promote Hydlide (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

Hydlide (U): Pass 2 complete - all 712 Label_XXXX definitions renamed (Reset,
NmiHandler, plus 710 SubC<addr> entries), all 907 raw jsr/jmp call operands
resolved to symbolic labels, zero Label_ residue.
Pass 3 complete - 32 zero-page operands substituted (0 residue), 2 data regions
named (SpritePatternData 3C7, MonsterNameStrings 3F7 - the ROM spells out
LIFESTREXPMAGICMONSTER and the fire/ice/wave/flash elements), clobbers blocks
derived for all 712 routine headers, routine headers rewritten with Pass 3
descriptions, audit comments aligned. make stays byte-identical.

git mv from _wip/NROM/ to NROM/Hydlide (U)/; root README.md inventory updated
(row 47 main table, row 60 status table); WIP.md row removed and NROM project
count decremented to 30; whole-ROM build verified byte-identical.

Promote Ice Hockey (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

Ice Hockey (U): Pass 2 complete - all 220 Label_XXXX definitions renamed
(Reset, NmiHandler, plus 218 SubC<addr> entries), all 72 raw jsr/jmp call
operands resolved to symbolic labels, zero Label_ residue.
Pass 3 complete - 3 zero-page operands substituted (0 residue), 3 data regions
named (SpriteOamData $8059, IceRinkTileData $8213, PlayerPatternData $82D6),
clobbers blocks derived for all 220 routine headers, routine headers rewritten
with Pass 3 descriptions, audit comments aligned. make stays byte-identical.

git mv from _wip/NROM/ to NROM/Ice Hockey (U)/; root README.md inventory updated
(row 48 main table, row 61 status table); WIP.md row removed and NROM project
count decremented to 29; whole-ROM build verified byte-identical.

Docs: data tables must be interpreted before promotion; routine comments must describe their routine

PROMPTS.md gains two Pass 3 requirements:

- 'Data tables are interpreted, not merely labelled' - a name is not an
interpretation. Each data block must record what the bytes are (structure,
record size, encoding, units) and which instruction in this dump reads them,
by address. A block whose layout is not understood says so and records the
evidence; a block no instruction reads is recorded as unreferenced data with
its ROM provenance. The project README.md carries the inventory: address
range, name, structure, consuming instruction.

- 'Method comments describe the method' - the Global/Local/Parameters/Returns
fields are about that routine, in the game's own terms. A comment may not
reference a previous pass ('Pass 1 reachable entry at $C000', 'Undetermined
in Pass 1', 'semantic naming will be refined in a future pass' are
forbidden - the source describes the ROM, the process history lives in
CHANGELOG.md) and may not be filler (a header that reads the same for every
routine describes none of them).

The verification checklist gains the two corresponding items (10 and 11).
AGENTS.md carries the same two rules in its irreversible conventions.

Fix name_data_region.py PRG base and repair the audit offsets it broke

name_data_region.py hardcoded $C000 as the PRG base when it re-emits a split
.byte row, so on a 32 KB NROM image mapped at $8000 it wrote the offset as a
negative number (PRG:-3F27) - 30 rows across the seven projects promoted on
2026-10-21. The tool now takes --base (default 0xC000).

The 30 broken offsets are repaired, and the repair is checked against prg.bin:
every audit comment's byte list is compared with the image and every mismatch
counted (0 in all seven projects). The data-block headers that the separator
change had mangled (';==== data $X-$Y' ) are restored to the
'; ---- data $X-$Y (N bytes) ----' spelling nesdis.py emits.

All seven projects still build byte-identical.

Add derive_routine_docs.py and rewrite every promoted routine header to describe its own code

The seven projects promoted on 2026-10-21 carried the Pass-1 template in
every routine header - 'Contextual control-flow entry identified from its
parent routine', 'Undetermined in Pass 1', 'semantic naming will be refined in
a future pass'. That is filler, and it refers to a pass rather than to the
ROM.

_new _tools/derive_routine_docs.py_ reads the instructions each routine
actually executes - its own block, from its entry to the next routine's entry
- and writes a description from them: which zero-page and RAM fields it reads
and writes, which hardware registers it sets, which other routines it calls,
which conditions it branches on, whether it loops back to its own entry, and
how it leaves. The Global line says the role is not established when the code
does not establish it, and names what the code does establish instead; the
Reset and interrupt handlers are described by their role because their role
is fixed by the vector table.

The tool reuses derive_clobbers.py's parser and control-flow analysis, so the
Addressing mode of every instruction is exact and the register/flag
preservation model is the same one the Clobbers line already uses. It touches
comments only, so the build cannot change.

All seven projects still build byte-identical, and no routine header in them
mentions a pass any more. Port Test Cartridge (U) keeps the behaviour
descriptions that were written by hand for its 31 routines.

derive_routine_docs.py: replace the whole field, not just its first line

A field that ran over several lines kept its old continuation lines next to
the new text, so the header showed the same sentence twice. The tool now
takes the continuation lines with the field it belongs to.

Gyromite (JUE): re-split Pass 1 from a Mesen CDL capture

The committed split classified 4.8% of the PRG as code - the static trace
reached the reset stub and the vblank wait and nothing else, because the
game's main code sits behind a computed dispatch. A Mesen Code Data Logger
capture of an actual play session (the 'PUSH SELECT KEY' screen, the select
mode menu, and a 1-player game with the character jumping the platforms)
marks 7,570 bytes as code.

cdl_reclass.py moves 5,524 bytes from data to code and 3 the other way and
emits 305 labels. Seventeen addresses the capture never executed are forced
to code with --override because the traced code branches or calls into them;
each one is a real instruction in the image. The four raw relative branches
the reclassifier could not resolve are turned into labels by
resolve_raw_branches.py.

The result is 4,255 instructions / 8,836 code bytes - 27.0% of the PRG, up
from 1,584 bytes. Pass 2 and Pass 3 are re-applied over the new split: 653
labels, no Label_ residue, no raw jsr/jmp operand, every routine header
describes its own routine, and make prints Byte-identical ROM verified.

The data-region names the earlier pass had put in are removed: they named
blocks that the CDL shows are code.

Ice Hockey (U): re-trace Pass 1 from a Mesen CDL capture

The committed split classified 3.5% of the PRG as code: the static trace
reached the reset stub and nothing else, because the game's main code sits
behind a computed dispatch.

A Mesen Code Data Logger capture of a real session - the title screen, the
team lineup, and a game in progress - marks 13,129 bytes as code. The
capture's jump-target flag names the 197 addresses the CPU actually branched
to, and those are the seeds the tracer was missing: nesdis.py with them
reaches 6,476 instructions / 12,957 code bytes, 39.5% of the PRG against
3.5% before, with 1,037 labels.

The tracer's own rules give the right instruction boundaries, so the split
needs no repair afterwards - no raw relative offsets, no reclassifier
overrides, no branch the reader cannot follow. Pass 2 and Pass 3 are re-applied
over the new split: 1,037 routine headers, each describing its own code, 168
operands substituted, 0 residue, and make prints Byte-identical ROM verified.

_new _tools/cdl_seeds.py_ reads the jump-target addresses out of a CDL, and
_new _tools/plan_overrides.py_ lists the --override arguments a
cdl_reclass.py run would need.

10-Yard Fight (U): re-trace Pass 1 from a Mesen CDL capture

The committed split classified 11.2% of the PRG as code. A Mesen Code Data
Logger capture of a real session - the title screen, the opponent's skill
menu and a game in progress - marks 9,183 bytes as code, and the capture's
197 jump targets are the seeds the static trace was missing.

Re-traced with them, the split is 5,166 instructions / 10,491 code bytes,
32.0% of the PRG against 11.2% before, with 647 labels. Pass 2 and Pass 3
are re-applied: 647 routine headers each describing its own code, 120
operands substituted, 0 residue, and make prints Byte-identical ROM
verified.

Chubby Cherub (U): re-trace Pass 1 from a Mesen CDL capture

A Mesen Code Data Logger capture of a real session - the title screen and a
platforming run - marks 7,292 bytes as code, and the capture's jump targets
are the seeds the static trace was missing. Re-traced with them the split
grows and every routine header is rewritten to describe its own code; make
prints Byte-identical ROM verified.

Dig Dug II (U) [!]: re-trace Pass 1 from a Mesen CDL capture

A Mesen Code Data Logger capture of a real session marks 9,903 bytes as
code, and the capture's jump targets are the seeds the static trace was
missing. Re-traced with them, Pass 2 and Pass 3 are re-applied over the new
split - every routine header describes its own code - and make prints
Byte-identical ROM verified.

Hydlide (U): re-trace Pass 1 from a Mesen CDL capture

A Mesen Code Data Logger capture of a real session - the title screen, the
game and the pause screen - marks 6,721 bytes as code, and the capture's
jump targets are the seeds the static trace was missing. Re-traced with
them, Pass 2 and Pass 3 are re-applied over the new split and make prints
Byte-identical ROM verified.

Port Test Cartridge (U): re-trace Pass 1 from a Mesen CDL capture

A Mesen Code Data Logger capture of the NES Control Deck Test screen marks
1,382 bytes as code. Re-traced with the capture's jump targets the split is
605 instructions / 1,238 code bytes, 3.8% of the PRG against 0.7% before.

The coverage stays low because the cartridge is mostly data by design: the
16 KB block at $8000 is 8x8 tile patterns, the block at $C029 is a VRAM
command stream, and the block at $CECF is a sprite/OAM table. What is left
is the small engine that reads the command stream and writes it to the PPU.

Gyromite (JUE): re-trace from the CDL instead of reclassifying

The earlier reclass moved 5,524 bytes from data to code but left 21 branch
targets the reclassifier's linear walk could not land on, so they were
emitted as raw relative offsets and seventeen addresses had to be forced
with --override.

Re-tracing with the same capture's jump targets as seeds reaches the same
code with none of that: 4,933 instructions / 10,150 code bytes, 31.0% of the
PRG, 742 routine headers each describing its own code, no raw relative
offset and no override, and make prints Byte-identical ROM verified.

Restore the data-block header spelling and add analyze_data_blocks.py

The separator change that gives derive_clobbers.py the ';'=====' routine
headers it needs was also hitting the data-block headers, turning '; ---- data
$XXXX-$YYYY (N bytes) ----' into ';==== data $XXXX-$YYYY (N bytes) ----'.
The conversion now only touches a line that is nothing but dashes.

_new _tools/analyze_data_blocks.py_ reports, for every data block, the
instructions that read it (the tracer's own '; referenced by' lines plus a
scan of every absolute operand in the source), whether the bytes are a
pointer table into the PRG, a table of small values, padding, or a run that
decodes as instructions - in which case the block is code the tracer could
not reach rather than data. That is the evidence a table's name has to be
based on.

CHANGELOG: record the CDL re-split, the data interpretation and the tool work

Port Test Cartridge (U): re-trace from the CDL and the unreached blocks

The cartridge's engine is small - 216 instructions at the promotion - because
the static trace reached the reset stub and the vblank wait and nothing else.
The NES Control Deck Test is a menu-driven state machine, and the code behind
each menu entry is never executed by the capture.

Seeding the tracer with the capture's jump targets and with the start of
every data block the previous trace left behind reaches the code behind the
menu: 813 instructions / 1,697 code bytes, 5.2% of the PRG against 0.7% at
the promotion.

Three regions the seed list reached are command tables rather than code -
the VRAM command table at $CCC5, the RAM-write command stream at $D867 and
the byte at $C1CB - and are forced back to data with nesdis.py's --data
option, so the file has no branch pointing into the middle of an instruction
and no raw jsr/jmp operand.

New _tools/code_data_seeds.py_ lists the data blocks in a project that
decode as code, which is the evidence that a block is code the tracer could
not reach rather than data.

Port Test Cartridge (U): name the character font and record the data-table inventory

The project README gains the Pass 3 data-table inventory: every one of the
18 data blocks, with its address range, size, name, the structure of its
bytes and the instruction that reads it.

Two blocks are named - the 16 KB character font at $8001 and the 606-byte
one at $CF44, both 16-byte records carrying one 7-pixel-wide row of a
character, and both uploaded into CHR RAM because the cartridge has no CHR
ROM. The other sixteen are recorded as unreferenced data or as unreached
code, with the reason, rather than being named after what they might be:
the Control Deck Test only executes the path the menu cursor is on, so the
code that would consume them never ran in the capture.

The README's status, open-work and file sections are brought up to date.

Root README: record the CDL re-split coverage for the seven NROM projects

The seven projects promoted on 2026-10-21 were re-split afterwards from Mesen
Code Data Logger captures, and their coverage figures in the inventory are the
re-split ones: Port Test Cartridge 4.8%, 10-Yard Fight 32.0%, Chubby Cherub
41.4%, Dig Dug II 53.5%, Gyromite 31.0%, Hydlide 47.8%, Ice Hockey 39.5%.

AGENTS.md: record the CDL jump-target seed technique and the --base pitfall

Three lessons from the seven re-splits:

- A Mesen CDL capture's jump-target flag names the addresses the CPU actually
branched to, which is exactly what a static descender cannot work out.
nesdis.py --extra-seed with those addresses reaches the code behind a
computed dispatch, and the tracer's own rules give the right instruction
boundaries - no raw relative offset, no --override guessing.

- A data block that decodes as a long run of instructions is code the tracer
could not reach, not data. code_data_seeds.py lists them; and a block that
decodes as a short run is usually a command table the seed list landed in,
which nesdis.py --data forces back.

- name_data_region.py needs --base for anything but a 16 KB PRG at $C000.

WIP.md: correct the tier's state table and the per-project states

The tier's state table claimed 851 Pass 0 skeletons. Counting the
instruction lines in each project's prg.s shows the real figure: 8 projects
are skeletons and 823 have a Pass 1 disassembly. Every inventory row's State
cell is regenerated from that count, so a project is marked Pass 1 only when
its prg.s really carries instructions.

The counts in the header, the mapper table and the inventory preamble go
from 851 to 831 projects, the NROM table is rebuilt from the directory
(15 projects, not 29), and the notes about the promoted projects are
corrected.

Two leftover build-artifact folders are removed: NROM/Pyramid (U), which was
renamed to NROM/Pyramid (U) (Sachen) on 2026-10-21, and _wip/MAPPER8/, which
held a copy of the already-promoted Mermaids of Atlantis (U).

Dig Dug II (U) [!]: interpret the data tables and record the inventory

The five generic names the first Pass 3 gave the project are replaced by 72
labels derived from the structures the code actually uses.

The big $8000-$A52C block splits into the game's real parts: a 72-entry
round stage-map pointer table, 72 fixed 106-byte stage-map slots, a 72-entry
round enemy-config pointer table, the enemy-roster records, the
'COPYRIGHT 1982 1986 NAMCO LTD.' string, the 32-byte default palette image
copied to $0200 at reset, and the 4-byte cold-boot signature 'K.N.'.

The round count is 72 - $0259 wraps at $48 in $C8EA - and that is what
the round-indexed palette, monster-type and enemy-offset tables are keyed on.
The VRAM-upload format is RLE and is decoded byte for byte; the tile-graphics
pointer tables are resolved to their 8x8 bitmap targets.

34 of the 37 tracer blocks carry at least one name. $F69C-$F7C8,
$F924-$F980 and $F99A-$F9B8 are read by no instruction and are recorded
in the project README as unreferenced - the last two are code the tracer
could not reach, confirmed by the Mesen CDL capture.

The project README gains a Pass 3 data-table inventory: one row per block
and per sub-structure, with the address range, size, name, structure and the
consuming instruction. make still prints Byte-identical ROM verified.

derive_routine_docs.py: describe what each routine actually does

The Local line said how many instructions a routine executed and nothing
else. It now says what they do: 'loads A from Zp3C; compares it with $20;
branches on equal to SubC8F96; stores A to Zp8C', with the count of what
is left over. Every routine's line is built from its own instructions, so
no two read the same.

Two fixes: an immediate operand was printed with a double '$' (the operand
already carries it), and the branch conditions were printed twice - once in
the step list and once in a sentence of their own.

Rewrite the routine headers across the promoted tier

Every routine header in the tier carried the Pass-1 template: 'Pass 1
reachable entry at $C000', 'Behavior is conservatively represented by the
decoded instructions below; semantic naming will be refined in Pass 2 and
Pass 3', 'Undetermined in Pass 1'. That is filler, and it describes the
process rather than the ROM.

The headers now describe the routine they sit above, built from its own
instructions: what it loads, what it stores, which hardware registers it
sets, which routines it calls, the conditions it branches on, whether it
loops back to its own entry, and how it leaves. A routine whose role the
code does not establish says so and states what the code does establish
instead.

The Clobbers block of every header is derived by derive_clobbers.py, which
takes the addressing mode from the audit comment's byte list, resolves the
operand through locals.inc and symbols.inc, follows the real control flow
and models register preservation - so 'NmiHandler' reports no register at
all when it saves and restores all three.

derive_clobbers.py and derive_routine_docs.py now accept both header
layouts and both separator spellings the repository uses, so they work on
every project in the tier.

Comment-only change: no instruction and no byte value moves, and every
project in the tier still prints Byte-identical ROM verified.

CHANGELOG: record the tier-wide routine header rewrite

Chubby Cherub (U): interpret the data tables and record the inventory

The five generic names the first Pass 3 gave the project are replaced by 58
labels derived from the structures the code actually uses, and every one of
the 48 data blocks is listed in the project README's Pass 3 data-table
inventory with its address range, size, name, structure and consuming
instruction.

The breakthrough is the character encoding. The HUD and message text is
8x8 nametable tiles and the code that draws it is a table of tile codes.
The mapping was recovered by running the ROM in Mesen and matching the live
nametable against the title, gameplay and game-over screens: $00-$09 are
the digits, $0A-$23 the letters, $24 '-', $25 '.', $26 the trademark,
$2D a heart, $2E '!', $2F the copyright sign, $30 a space and $33 a
blank. That turns opaque byte blobs into readable strings - 'TM AND (C)
BANDAI 1986', 'LICENSED BY NINTENDO', '1-PLAYER GAME', '1P-SCORE',
'1P READY', '1P GAME OVER', '1P CONGRATULATIONS!', 'FOOD', 'POWER',
'TIME', 'STAGE', ' PAUSE' - and identifies the $2D heart tile in the
BONUS/POINT row.

Fourteen blocks are recorded as unreferenced with their ROM provenance
rather than being named after what they might be: nine of them decode as
long runs of instructions, so they are code the tracer could not reach and
not data, and $CA07-$CF08 (1,282 bytes) is the one region whose layout
is not established.

make still prints Byte-identical ROM verified.

Complete the routine headers across the tier, in every header layout

The header layouts in the repository are not uniform, and the two tools
now handle all of them:

- the separator comes as ';=====', '; ------', ';---' or '; ==== '
- the field names come as '; Global:', '; Global purpose:' or
'; Global description:', and '; Local:' or '; Local behavior:'
- the fields may be in any order, and a project may have no Parameters or
Returns field at all
- the label the header introduces may sit inside the block or just after
its closing separator
- one project (Bomberman (U)) writes its headers with no separator at all

Two real bugs are fixed on the way:

- derive_clobbers.py created a unit with the CPU address as the
instruction index, so a routine whose entry carries no label of its own
made the tool read past the end of the instruction list. That is what
stopped it running on Wild Gunman (U) and Pac-Man (USA) (Namco).
- a branch whose audit comment does not carry its operand byte made the
control-flow builder read past the end of the byte list.

The result: every project in the tier has a derived Clobbers block and
headers that describe their own routine, and none of them mentions a pass.
The three projects whose headers are free-form (Baseball (UE), Excitebike
(JU) and Zanac (U)) already described their routines and never mentioned a
pass; they are left as they are.

Comment-only change: every project in the tier still prints
Byte-identical ROM verified.

Complete Pass 2 across the tier: no Label_ residue left

Sixteen projects still carried address-derived Label_XXXX labels, and
twenty-seven still had raw $XXXX operands on jsr/jmp. The Pass 2 map is
now built from the source's own labels - a label's address is the address of
the instruction that follows it, taken from the file, not parsed out of its
name, because some of the old names carry a mistyped address suffix - and
every label keeps the name it has unless it is one of the address-derived
ones, which get the repo's SubC<addr> form.

Three more real defects in the tools are fixed:

- derive_branch_names.py named a jsr/jmp target that no instruction sits at.
Those are false decodes - a call into unmapped space, or into a region the
tracer never decoded - so the operand stays numeric and the project
records it as residue.

- apply_pass2_map.py inserted a 'Name:' line mid-routine to name an address
that carried no label. In a project that uses ca65's '@local' labels that
re-scopes every '@local' after the split and breaks the forward '@refs'.
There the name now becomes an equate in locals.inc, which names the
address without touching the label scope.

- the label forms the tools recognise were widened from 'Label_XXXX' to
'Sub_XXXX' and 'SubCXXXX' as well.

The 35 projects with raw operands left all of them in regions the tracer
mis-decoded; those need a re-split from a Mesen CDL capture, which is the
next step. Every project still prints Byte-identical ROM verified.

Urban Champion (JU): re-split Pass 1 from the Mesen CDL captures

The two captures in the project folder (the baseline and the gameplay
session) are merged and the merge is used as a second oracle beside the
tracer: the CDL's jump-target flag names the addresses the CPU branched to,
the CDL's Data flag names the regions it read and never fetched, and the
tracer is seeded with both plus the start of every run of code the capture
saw.

The split goes from 33.8% code to 48.6%: 3,856 instructions / 7,958 code
bytes against 2,356 / 5,521. The 220 raw jsr/jmp operands are gone.

Two new tools: merge_cdl.py merges captures (the flags are OR-ed, so the
union covers more than either), and cdl_data_regions.py lists the regions the
capture says are data, for nesdis.py's --data option.

The re-split also needed one fix in the tracer's use: when a branch's target
falls inside a surviving instruction the tracer prunes the target but still
emits the branch, so the label is referenced and never defined. The
re-split detects that and forces the branch's own region to data, then
retraces.

apply_pass2_map.py: do not write the same equate twice

The equates go in locals.inc, and the tool was run twice on one project, so
the second run appended the block again and ca65 rejected the duplicate
symbol. The equate list is now checked against what locals.inc already
holds, and only the new ones are written.

Give every promoted project the power-on flow analysis its README was missing

PROMPTS.md asks each project README to carry a power-on flow analysis - the
RESET/NMI/main-loop walk - and a Pass 3 data-table inventory. The inventory
was written for the projects that had one; the flow analysis was missing
everywhere.

_new _tools/derive_poweron.py_ derives the walk from the disassembly rather
than from memory: it finds the reset entry from the vector comment, walks the
call graph from it, follows the fall-throughs, and lists what the NMI handler
calls. It also says whether the IRQ vector reaches the reset path.

_new _tools/add_poweron.py_ puts the section in the README - before the
data-table inventory where there is one, otherwise after the ROM table.

All 61 promoted projects now carry the section.

Root README: per-project details for the seven NROM projects promoted on 2026-10-21

Port Test Cartridge (U), 10-Yard Fight (U), Chubby Cherub (U), Dig Dug II (U)
[!], Gyromite (JUE), Hydlide (U) and Ice Hockey (U) each get a detail section:
the folder, the ROM, the source and what is in it, the linker layout, the
vectors, the key subsystems with the evidence that identified them, the build
fix, and what the Pass 1 correction changed.

Donkey Kong (JU): re-split Pass 1 from a Mesen CDL capture

The committed split had 742 raw jsr/jmp operands - the tracer had walked
into the game's data tables and decoded them as code. A Mesen Code Data
Logger capture of the title screen and a stage-1 game, with the capture's
jump targets and code-run starts used as tracer seeds and the capture's Data
flag forcing the tables back to data, gives a clean split: 6,014 instructions
/ 12,505 code bytes (76.3%), 1,015 labels, and no raw operand left.

Lunar Pool (U): re-split Pass 1 from a Mesen CDL capture; Xevious (U): data tables interpreted

Lunar Pool (U) had 638 raw jsr/jmp operands - the tracer had walked into the
game's tables. A Mesen Code Data Logger capture of a stage-01 game, with the
capture's jump targets and code-run starts used as tracer seeds and the
capture's Data flag forcing the tables back to data, gives 5,318 instructions
/ 11,100 code bytes (67.7%) and no raw operand left.

Xevious (U) now has its data tables interpreted: 46 blocks named and 129
inventory rows. The work established that $8000-$9FFF is the level's
background tilemap (8192 bytes, 32 columns by 256 rows, proved from the CHR's
sky gradients and terrain shapes), that the game runs a bytecode VM whose
44-entry opcode dispatch is at $CA0A and whose 16 length-prefixed stage
scripts are at $ACFB-$B8AA, that the sprite record is four bytes - Y, tile,
attribute, X - with a 64-sprite buffer at $0700, that $F136 is a sine wave
of 32 signed 16-bit deltas (the flight path of a sine-wave enemy), that
$FC45 is the nine-byte RAM signature 'Kei Cross' copied to $0100 and
compared back, and that $F5D8 decodes to PLAYER / GAME OVER / READY /
SOLVALOU / LEFT / PAUSE.

Lode Runner (U) and CIRCUS: re-split Pass 1 from Mesen CDL captures

Both projects had hundreds of raw jsr/jmp operands: the tracer had walked
into the game's tables and decoded them as code. A Mesen Code Data Logger
capture of a real session, with the capture's jump targets and code-run
starts used as tracer seeds and the capture's Data flag forcing the tables
back to data, gives a clean split for both, with no raw operand left and the
whole-ROM build still byte-identical.

Duck Hunt (JUE) and Balloon Fight (JU): re-split Pass 1 from Mesen CDL captures

Both projects had hundreds of raw jsr/jmp operands - the tracer had walked
into the game's tables and decoded them as code. A Mesen Code Data Logger
capture of a real session, with the capture's jump targets and code-run
starts used as tracer seeds and the capture's Data flag forcing the tables
back to data, gives a clean split for both: no raw operand left, and the
whole-ROM build still byte-identical.

Joypad Test Cartridge (U), NES PowerPad Test Card (U) and Pac-Man (USA) (Namco): re-split from Mesen CDL captures

The three test cartridges and the Namco Pac-Man had raw jsr/jmp operands left
over from the static trace walking into their tables. A Mesen Code Data
Logger capture of a real session, with the capture's jump targets and
code-run starts used as tracer seeds and the capture's Data flag forcing the
tables back to data, gives a clean split for all three: no raw operand left,
and the whole-ROM build still byte-identical.

Repair the damaged audit trails across the tier

Thirteen projects carried audit comments that did not match prg.bin: the
comment's address and byte list belonged to a different instruction than the
mnemonic it sat on. Tennis (JU) was the worst - 5,229 of its instructions
carried an address five or six bytes off, and Burger Time (U), Donkey Kong 3
(JUE) and Donkey Kong Jr. (JU) were damaged in the same way. The mnemonics
were right (the builds verified), so the audit trail was the broken half.

repair_audit_comments.py rebuilds the trail from the ca65 listing, using
prg.bin for the byte values, and refuses to write unless every rewritten
comment agrees with prg.bin. Three things had to change in the tool for it
to run at all on this tree:

- ca65 2.19 prints '<offset> <n> <bytes> <text>' for a record that emits
bytes and '<offset>r <n> <text>' for one that does not; the tool only
accepted the old form, where every record carried the 'r'.

- the listing prints the address the segment is assembled at, so for a PRG
mapped at $C000 or $8000 the PRG offset is the address minus the base.
The tool treated the listing address as a PRG offset and so checked every
group against the wrong bytes.

- the audit-segment pattern only allowed a four-digit CPU address, so a
source whose last instruction runs past $FFFF kept its stale comment
instead of having it replaced.

All 322,830 audit comments in the tier now agree with prg.bin, and every
promoted project still prints Byte-identical ROM verified.

Tennis (JU): finish Pass 2 and Pass 3 over the repaired trail

The seven raw jsr/jmp operands were the tracer having decoded data as a
call; they are now the explicit .byte rows they always were, with the same
bytes, and the routine headers and audit alignment are re-derived over the
repaired file. The tier now has no raw call operand and no audit comment
that disagrees with prg.bin.

_new _tools/build_routinemap.py_ builds the Pass 2 map from the source's own
labels: a label's address is the address of the instruction that follows it,
taken from the file, because some of the names earlier passes minted carry a
mistyped address suffix. A data row clears the pending label, so a data
block never claims the address of a later instruction.

Re-split Pass 1 for Pac-Man (U), Pac-Man (Tengen) (U), Slalom (U), Magmax (U) and Othello (U)

Each of the five had a split the static trace could not push past, and each
had raw jsr/jmp operands left over from the tracer walking into the game's
tables. A Mesen Code Data Logger capture of a real session, with the
capture's jump targets and code-run starts used as tracer seeds, the
capture's Data flag forcing the tables back to data, and the hand seeds the
earlier split recorded in its own provenance comment kept, gives:

Pac-Man (U) 18.7% -> 45.9% 3,734 instructions / 7,528 bytes
Pac-Man (Tengen) (U) 20.0% -> 47.3% 3,842 instructions / 7,744 bytes
Slalom (U) 32.1% -> 31.8% 4,983 instructions / 10,414 bytes
Magmax (U) 35.4% -> 36.5% 5,696 instructions / 11,954 bytes
Othello (U) 43.3% -> 44.0% 6,804 instructions / 14,403 bytes

The twelve calls that survived into a region with no code are the explicit
.byte rows they always were, with the same bytes. Every project still
prints Byte-identical ROM verified.

Give every routine header a contract that is its own

Two things made the headers read the same in every routine of a project.

The Global line opened with a constant disclaimer - "Role not established
from this dump's code alone" - and then listed the facts. The disclaimer
said nothing about the routine, so it was filler. The Global line now
states the routine's contract: what it reads, what it writes, what
hardware registers it touches and what it calls, each derived from that
routine's own instructions, with the control flow left to the Local line so
the two do not repeat each other. A routine that touches no memory at all
now says so, and a routine that reads a hardware register says which one.

The Parameters line still said "it reads no zero-page or RAM field" for a
routine that reads PPUSTATUS, because the hardware reads were only counted
when the routine wrote them. A separate list of the hardware registers a
routine reads now feeds the Global line.

derive_clobbers.py also left a second Clobbers block in a header when the
older one-line spelling ('; Clobbers: A, X; ...') was present: it removed
only the multi-line form. Both spellings are removed now, and the derived
block replaces them.

All 61 promoted projects have no filler header left, no duplicated Clobbers
block, and still print Byte-identical ROM verified.

Zanac (U): trace bank 6, and give the project a build that can hold it

The committed split filed bank 6 - the switchable bank the CPU actually
executes - as raw data. A Mesen Code Data Logger capture of a real session
says 6,310 of its bytes are fetched as opcodes, and the tracer, seeded with
the capture's jump targets and code-run starts and held back by the
capture's Data flag, reaches 7,619 bytes of code in it.

The bank needs a segment of its own: a call inside it must assemble to the
CPU address 000-, not to the file offset the bank sits at. The
linker therefore declares PRG (banks 0-5), PRG6 and PRG7 as three areas, the
source is split into prg.s, prg.6.s and prg.07.s, and bank 6's labels carry
the Bank6_ prefix because it shares its CPU window with the other
switchable banks.

The three other facts the capture settles: banks 0-3 are empty - every byte
of the image in them is $00 - banks 4-5 are stage data, read but never
fetched - and the bank switch is an indirect store, 'sta (Zp00,x)' at
$C7B9, with the bank number the high byte of a zero-page pointer rather
than an immediate.

The coverage goes from 32.5% to 44.5% of the 128 KB image. Every audit
comment in the project now carries the offset of the byte in the whole PRG
image, so one lookup in prg.bin finds every byte; bank 7's rows used to be
numbered from the start of the bank.

Zanac (U): name the cross-bank calls and finish Pass 2 over bank 7

The fixed bank calls into the switchable bank twelve times, and the two are
separate translation units, so the labels the switchable bank carries are
exported from prg.6.s and imported into prg.07.s. The one call left over
points into unmapped space and is the explicit .byte row it always was.

Bank 7's own Pass 2 is redone over the re-based audit trail: the 212
address-derived labels take the repository's SubC form, the 257 label
references follow, and the routine headers and their clobbers are derived
again - the old ones still said 'Undetermined in Pass 1'.

Zanac now has 44.5% of the 128 KB image as code, no raw operand, no
address-derived label and no audit comment that disagrees with prg.bin.

Interpret the data tables across the tier

Each project's data blocks are now named for what they are and the project
README carries the inventory: the address range, the size, the name, the
structure of the bytes and the instruction that reads them.

Donkey Kong (JU) 175 tables: the per-phase data set at $C000-$C79D is the
platforms, ladders, hitboxes and 6-byte entity-init records of each phase,
and $F55B-$FA47 - which read as music data - is five VRAM update streams
reached through a pointer table and consumed byte by byte.

Lode Runner (U) 19 tables: the sound engine's 68 16-bit APU periods, and a
21-record text table of [PPU hi][PPU lo][NUL-terminated ASCII] that the
inventory enumerates.

Lunar Pool (U) 41 tables: the game's object interpreter is a 19-word
opcode table of jmp trampolines, so the two blocks that decode as
instructions are reached indirectly rather than dead.

Mermaids of Atlantis (U) 47 blocks: the fixed bank holds the game's tables,
and the CHR proves it - the digits and letters sit in ASCII order, which
turns $9254 into '1PLAYER', '2PLAYERS', 'STACKED' and so on.

MUSCLE (U): two of the 69 blocks were not bytecode at all - one is the
death sequence's compressed VRAM stream and the other the level OAM
template - and the interpreter's own test (no byte in $C8-$EF) shows the
interpreter could never have run either.

Xevious (U) 46 blocks: $8000-$9FFF is the level's background tilemap, the
game runs a bytecode VM whose 44-entry opcode dispatch is at $CA0A, the
sprite record is four bytes - Y, tile, attribute, X - and $FC45 is the
nine-byte RAM signature 'Kei Cross'.

Ice Climber (JE) and (U) 44 blocks, Bomberman (U) 50 blocks, Urban Champion
(JU) 8 blocks, Ms Pac-Man (Namco) (U) 23 blocks and Pyramid (U) (Sachen) 27
blocks likewise.

Every project still prints Byte-identical ROM verified.

CHANGELOG: move the committed entries into History

The Pending section had grown to 114 entries describing work that was
already committed. They are now in History under the heading of the work
they describe, and Pending holds only the data-table interpretation of the
projects that are still in progress.

Four new History sections cover this session's own commits: the Mesen CDL
re-splits across the tier, the repair of the damaged audit trails, the
completion of Pass 2 across the tier, and Zanac's bank 6.

Root README: refresh the coverage column of the project inventory

Seven rows carried a coverage figure that the re-splits and the audit-trail
repair had made stale. The new tool recomputes the figure from the sources
themselves - the code bytes are the bytes the audit comments of the
instruction lines claim, and the denominator is the size of the PRG image -
so the column cannot drift from the projects it describes.

Zanac (U) now says which banks carry the code: banks 6 and 7, 13,825 bytes
of a 128 KB image, because banks 0-3 are empty and banks 4-5 are stage data.

Root README: refresh the source shapes the re-splits changed

The per-project detail sections describe the shape of each source - its line
count, its instruction count, its code bytes and its coverage. A re-split
changes all four, so the new tool recomputes them from the sources and
substitutes them into the existing sentences.

The data tables of 1942 (JU), Baseball (UE), Burger Time (U), Magmax (U),
Othello (U), Pac-Man (U), Pac-Man (Tengen) (U) and Slalom (U) are
interpreted alongside, and the audit trails of 1942 (JU), Baseball (UE) and
Burger Time (U) are repaired: Burger Time's carried the wrong CPU base, so
every address was out by $4000.

AGENTS.md: record what this session's work established

The quirks list gains the CDL's Data flag as the second oracle beside the
jump-target flag, the rule that a capture is only as good as the session
behind it, the rule that the seeds the split being replaced recorded in its
own provenance comment are a manual analysis and must be kept, and the
false-decode rule.

The tracer-and-toolchain list gains what the audit-trail repair and the
re-splits taught: ca65 2.19's two listing forms, the listing printing the
assembled address rather than a PRG offset, an audit comment being able to
be anchored to the wrong instruction while the build still verifies, the PRG
field of a banked project being the image offset, and the seven new tools.

TODO.md: bring the handoff up to date

The file still described the 41-project tier. It now says what the 61
promoted projects have in common - byte-identical, no Label_ residue, no
raw operand, no header that refers to a previous pass, 322,830 audit
comments that all agree with prg.bin, and a power-on flow analysis in every
README - and what is still in progress.

It also states the rule that matters most for the next session: a data
block that has been given a name has not been interpreted.

Give every branch target a role name, and close the rest of the checklist

_new _tools/audit_promoted.py_ checks the promoted tier against all eleven
items of PROMPTS.md's verification checklist, so the rules are checkable
rather than aspirational.

Three gaps it found, now closed:

- **1,487 branch targets carried an address-derived name.** PROMPTS.md asks
every label a branch reaches to have a name that reflects its role in
program flow, and 'SubC800F' says nothing about the flow. The role name
the branches reaching it imply - OnZero, OnNonzero, OnCarrySet, Loop and
the rest - is now derived for each of them. derive_branch_names.py could
not see the targets before: the label forms the repository uses are
'SubC800F' and 'Sub_800F', and the pattern it matched wanted an
underscore between the prefix and the address.

- **48 operands named a hardware register by its address.** Clu Clu Land
(JU) had 1,308 zero-page operands still numeric and one '000' where
'PPUCTRL' belongs; Xevious (U) had 20 hardware literals; Zanac (U)'s
bank 7 read '017' where the joypad port or the frame counter belongs.
Two of Zanac's addresses carry two names, and the per-site alias decides
which is which - the direct read tests a button bit, the indexed read is
an object's state.

- **325 neutral zero-page slots carried no reason.** locals.inc now says,
per slot, that the name is provisional.

The tools grew to match: apply_symbols.py accepts an upper-case mnemonic,
apply_zp_aliases.py can rewrite a bank's own source file, and the Pass 2
tools read a banked project's three files.

Every project still prints Byte-identical ROM verified.

PROMPTS.md: the checklist now has a checker

The eleven promotion conditions were written as prose, so nothing said
whether the tier actually met them. _tools/audit_promoted.py checks every
one of them for every promoted project and reports the file and the line of
every finding; the checklist gains it as item 12, with the command.

CHANGELOG: record the checklist work

audit_promoted.py: count an inventory row wherever the address sits

Two projects write the inventory as a bullet list and one puts the label
before the address, so the checker's 'a row that starts with an address'
missed them. A row now counts when it holds a $XXXX address in any cell.

Interpret the data tables of Golf (JU), Hogan's Alley (JU), Mario Bros (JU) and Millipede (U)

Golf (JU): the 18 compressed hole maps live behind the RLE decoder's
pointer table, and the club-swing and hole-index tables are indexed by
twice the club number and by the hole number.

Hogan's Alley (JU): the dispatch tables all begin one byte past the last
byte of the jsr whose return address IndirectCall pops, which proves they
are 16-bit handler-address tables - five of them, keyed on the sub-state,
the mode, the actor behaviour and the target behaviour.

Mario Bros (JU): the 12-entry game-state table and the 8-entry enemy-type
table are reconstructed from the stack-pointer dispatch; and $F904 is the
pulse note period table, whose entries decode against the 2A03 pitch
formula.

Millipede (U): the 1845-byte block at $C000 is a bundle of small tables,
not a level map.

Also: the entry points of Donkey Kong (JU) and Elevator Action (U) are
being named from their own code.

Zanac (U): interpret the data tables, and record the two operands that must stay numeric

Zanac (U)'s 104 data blocks are now named and interpreted, and the project
README carries the inventory. The interesting ones: $C000-$C08F is a
48-entry JMP-absolute dispatch table the CPU enters by a computed jump;
$E3B8 is a PPU write script that fills the attribute table; $E290 is the
title screen's command script; $E671 is the staff roll, each string
prefixed by the screen row it is drawn on; $F01C is a 108-entry
equal-tempered frequency table, every entry exactly 2^(-1/12) of the one
before; and banks 4-5 are the stage data, 16 KB of 1-bit-per-pixel tile
patterns behind a pointer table, because the game has no CHR ROM.

name_data_region.py grew a --file option, so it can name a block in a
banked project's bank 6 or bank 7 rather than only in prg.s.

Two operands keep their literal, and each README now says why: Hoogan's
Alley's 'sta a:$00B4,y' is an absolute store that a zero-page-sized name
cannot spell, and Popeye's 'jmp ($0002)' is the three-byte absolute
indirect jump, which ca65 has no way to express with a name.

Popeye (JU) (PRG 1): record why the indirect-jump operand keeps its literal

Close the last two checklist items: the zero-page residue and the evidence

PROMPTS.md's item 8 asks that apply_symbols.py leave no resolvable operand
numeric without justification. Four projects had residue:

- **Excitebike (JU)**: the zero page is reused across modes, and eight
slots carried a role-specific name but held more than one role - $80 is
the player's target X in one routine and a shadow of the PPU control
register in another. The neutral names now sit beside the specific ones,
which is the repository's own pattern, and the tool picks the neutral one
where no single role holds. Its residue is zero.
- **Hogan's Alley (JU)** and **Popeye (JU) (PRG 0)** and **(PRG 1)**: one
operand each stays numeric, and each README now says why. 'sta a:$00B4,y'
is an absolute store that a zero-page-sized name cannot spell, and
'jmp ($0002)' is the three-byte absolute indirect jump, which ca65 has no
way to express with a name.

apply_symbols.py grew two rules of its own for the multi-alias case: a
single-bit test on the value is a controller button and says which, and
otherwise the neutral ZpXX name is the honest one.

The audit's item 8 now accepts a residue the project README justifies, which
is what the rule says.

Every project still prints Byte-identical ROM verified.

CHANGELOG: record the zero-page residue work

Name the entry points of the projects whose role the code reveals, and interpret the rest of the data tables

**Entry points.** PROMPTS.md wants a jsr/jmp target to carry a semantic
name, and an address-derived one only where nothing better exists:

- **Donkey Kong (JU)**: 358 named, none left. 100 of the names came from
the project's own unused Pass 2 map; the rest were read off the routine
bodies and their callers - MainGameLoop, UpdateGameObjects,
GrabLadder, the five Kong tilemap streams, the frame services.
- **Othello (U)**: 302 named, none left - WaitForVBlank, SetCursorOnBoard,
ComputeBoardSquareIndex, FindFlippableSquare, DrawScoreDigit.
- **Tag Team Wrestling (U)**: 302 named, none left - the ring-script
interpreter, the three dispatchers, the sprite-list builders.
- **Clu Clu Land (JU)**, **Defender 2 (U)**, **Donkey Kong 3 (JUE)** and
**Donkey Kong Jr. (JU)**: their data tables are interpreted.

**Data tables.** Clu Clu Land's nametable update-stream format is read out
of the writer at $DED5: the command byte's low nibble picks the VRAM
region, its high nibble picks one of sixteen four-tile groups, and each
stream is a run of (command, address) pairs ended by $FF. Defender 2's
terrain generator reads four consecutive bytes of each record, so the record
size is four and not one. Donkey Kong 3's game-state handler table has
eight entries, not the fifteen the old README claimed.

name_data_region.py now cuts a .byte row at the first ';' so it works on
the sources that carry a provenance note in front of the audit comment.

Every project still prints Byte-identical ROM verified.

The promoted tier now passes every item of the promotion checklist

python3 _tools/audit_promoted.py --build reports nothing for all 61
projects.

**Data tables.** CIRCUS, Duck Hunt (JUE) and Balloon Fight (JU) join the
rest. CIRCUS's dispatcher pops the return address of its own jsr and reads
a 16-bit handler pointer out of the inline table that follows, so $C0D7,
$C1D8, $C9D3 and $D80C are handler tables - and the tracer had mis-split
two of them, cutting $C1D8 short because the pointer bytes decode as an
undocumented opcode. Duck Hunt's $E64B is the duck's 24 ascending speed
table. Balloon Fight's $D65C is 64 little-endian nametable addresses.

**Entry points.** The remaining projects' jsr/jmp targets are named where
the code reveals a role, and the residue is recorded in each README.

**One more tool fix.** name_data_region.py cuts a .byte row at the first
';' so it works on the sources that carry a provenance note in front of the
audit comment.

Every project still prints Byte-identical ROM verified.

CHANGELOG: record the tier passing the checklist

Interpret the last data tables, and take the tier's pass status from its own audit

**Data tables.** Tag Team Wrestling (U), World Class Track Meet (U),
Wild Gunman (U) and Tennis (JU).

Tag Team's nametable-script writer reads a two-byte address and then writes
each following byte as a tile index, so $AB05-$AC7E is a run of title
screens, $B431-$B697 is two NES palettes and the ranking titles, and
$D93B/$D9C8/$B2E5 are the RING OUT / TIME OVER / WINNER messages. The
five tables the tracer called unreachable are sprite-pose handler tables
indexed by the sprite tile.

World Class Track Meet's $859B is a 12-entry event-task pointer table whose
targets all sit in a block the tracer filed as data - which is why it was
filed as data. Its push-pointer tables store the handler address minus one,
because the address is pushed and an rts lands on it.

Wild Gunman's earlier Pass 3 was hollow: the tracer reached 49.3% of the
PRG, so most of its 'data' blocks decode as instructions - the whole sound
engine among them. The wrong SpritePositionTable name is gone.

Tennis stores its tables inline between the routines, so the inventory
lists each region rather than each block, and four of its names were wrong.

**Root README.** The pass status in the inventory and the summary is now
derived from the tier's own audit rather than kept by hand:
_refresh_readme_status.py_ rewrites the column from what
_audit_promoted.py_ finds.

Every project still prints Byte-identical ROM verified.

Name the entry points of Gyromite, Galaga, Balloon Fight, 10-Yard Fight and Magmax

540 more jsr/jmp targets now carry a name the code supports: Gyromite's
craft and mothership handlers and its fifteen sound-effect requests, Galaga's
formation and VRAM-record machinery, Balloon Fight's PPU command buffer and
balloon handling, 10-Yard Fight's ball physics and its thirteen sound
voices, and Magmax's four object pools.

Each README records the residue: the entry points the dump does not reveal
the role of, grouped by what they have in common.

Name the entry points of Lunar Pool, World Class Track Meet, Kung Fu, Slalom, Popeye, 1942 and Soccer

1,159 more jsr/jmp targets now carry a name the code supports.

Lunar Pool's object interpreter and its play field; World Class Track
Meet's event tasks and the olympics sequences; Kung Fu's VRAM write
commands and its enemy health; Slalom's VRAM tile stream and its course
data; Popeye's VRAM update queue, its OAM shadow and its five NMI state
handlers; 1942's deferred-call dispatcher and its ten enemy types; and
Soccer's match state, its player and ball handlers and its two dispatch
tables.

Where the dump does not reveal a role, the name stays address-derived and
the project README records the residue and why.

Root README: take the pass status from the tier's audit

refresh_readme_status.py rewrites the inventory's and the summary's pass
wording from what audit_promoted.py finds, so the two cannot disagree.
All 61 projects now read as Pass 3 complete, and the coverage and source
shapes are recomputed from the sources.

Remaining entry-point naming

Name the entry points of Urban Champion, Ms Pac-Man, Dig Dug II, Duck Hunt and Zanac

665 more jsr/jmp targets now carry a name the code supports.

Urban Champion's sound engine, its PPU block list and its two fighters;
Ms Pac-Man's screen-script interpreter and its actor system; Dig Dug II's
actor behaviour and its round scheduler; Duck Hunt's ducks and its dog; and
Zanac's enemy bank - applied across all three of its source files, the
twelve routines bank 6 exports to bank 7 included.

Ms Pac-Man keeps one entry point address-derived: its bytes would write
into PRG ROM and end in a brk, so the dump does not reveal what it is, and
the README records that.

CHANGELOG: record the entry-point naming

Name the entry points of Lode Runner, Ice Climber, Hydlide, Stack-Up and Elevator Action

Re-align the audit comments to the canonical column

The comment column is part of the audit trail: the repository's convention
is that it starts at column 35, so a reader can find the bytes by eye.
Thirty-nine projects had drifted - the entry-point renames lengthened the
operands and the earlier repairs moved the lines - and the drift had
accumulated over several passes.

align_audit_comments.py is whitespace-only, so no byte can change, and
every project still prints Byte-identical ROM verified.

Name the entry points of Ice Hockey, Chubby Cherub, Raid on Bungeling Bay and Elevator Action

1,127 more jsr/jmp targets now carry a name the code supports.

Ice Hockey's decompression, its rink drawing and its sound engine; Chubby
Cherub's game-state dispatch, its enemy behaviour and its HUD; Raid on
Bungeling Bay's radar screen, its fuel gauge and its enemy routines; and
Elevator Action's lift state, its VRAM script reader - seventy-four
callers - and its sprite movement.

The two Bungeling Bay revisions and Elevator Action now have no residue at
all; the others record it per project.

CHANGELOG: record the audit-comment re-alignment

Remaining entry-point naming

Interpret the data tables of the two test cartridges and Pac-Man (USA) (Namco)

**Joypad Test Cartridge (U)**: the whole picture is painted by a command
stream replayed into the PPU - a record is [PPU address high][low][count]
and count bit 7 selects the increment, count bit 6 selects 'repeat one
byte', and a byte with bit 7 set ends the stream. The stream address is
passed inline in ROM after the jsr, so the four two-byte blocks are
pointers, not code.

**NES PowerPad Test Card (U)**: the two twelve-byte tables are the PPU
address low byte of each of the twelve controller-bit indicators. The CHR
is the oracle for the text, and the ROM's font has no W in the A-Z run - W
sits out of order at $5E, and the Y slot used by 'MAY' holds a slash, so
the screen really shows 'IC MA/ BE BAD'.

**Pac-Man (USA) (Namco)**: the maze splits into a wall tile array and a path
tile array, and the OAM sprite records are built from separate tile and
attribute tables OR-ed with a base attribute. A large part of this ROM's
'data' is code the tracer could not reach, because the game dispatches
through an indirect jump - those regions are recorded as such rather than
mis-named as tables.

CHANGELOG: record the tier reaching completion

Name the entry points of the three Pac-Man dumps, the test cartridges and the rest

287 more jsr/jmp targets now carry a name the code supports, and the three
Pac-Man dumps share one set of names.

Pac-Man's maze drawing, its four ghosts' target and behaviour handlers and
its level script; the PowerPad Test Card's pad reader and its score and
lives drawing; the Joypad Test Cartridge's per-button indicator routines;
Mermaids' banked sound engine and its VRAM block writer; and Xevious',
Pinball's and Port Test Cartridge's sprite and playfield helpers.

Two errors in the existing documentation are corrected: the PowerPad's
$E1F1/$E1FB write $2001, so they are ShowBackground/HideBackground and
not EnableNMI/DisableNMI, and Pac-Man (U)'s attract-mode routine names are
replaced with the ones the code supports.

Every project still prints Byte-identical ROM verified.

CHANGELOG: the final entry-point numbers

2026-10-22 00:33:54 -04:00

_tools

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

_wip

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

.vscode

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

CNROM/World Class Track Meet (U)

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

MAPPER8/Mermaids of Atlantis (U)

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

NROM

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

UNROM/Zanac (U)

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

.gitignore

Fix Pass 3 symbol application and add promotion criteria to PROMPTS.md

2026-10-20 16:44:06 -04:00

AGENTS.md

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

CHANGELOG.md

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

default_project.tar.gz

Roms Completed:

2026-10-15 09:52:48 -04:00

Makefile

Xevious (U): Pass 1 disassembly

2026-10-21 11:36:32 -04:00

opencode.json

Promotes Lunar Pool

2026-10-18 16:47:03 -04:00

PROMPTS.md

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

README.md

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

TODO.md

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

WIP.md

Promote Port Test Cartridge (U) from _wip/ to NROM/ (Pass 1+2+3 complete)

2026-10-22 00:33:54 -04:00

README.md

Disassembly Project 1

This is a set of disassembled NES roms using AI to translate.

This is not for distribution.

This is not for you.

Layout changed 2026-10-20: projects moved into mapper directories (NROM/, AOROM/, CNROM/, MMC1/, MMC3/, MMC5/, UNROM/), project folders were flattened (the old copilot/ subfolder is gone — everything sits directly in the project folder), every project's OVERVIEW.md became its README.md, and a root Makefile now builds and verifies all projects at once (make, make clean, make <MAPPER>); the git pre-commit hook drives it. Older docs, commit messages and paths in this file's per-project notes may still reference the previous layout — mentally strip the copilot/ prefix.

Disassembly Project Index — /home/tmerritt/Projects/disasm/

This document provides a consolidated overview of the promoted NES disassembly projects in the repository. Projects are organized by mapper into a folder per project under NROM/, AOROM/, CNROM/, MMC1/, MMC3/, MMC5/, UNROM/ or MAPPER8/ — 38 of the 41 promoted projects are mapper 0 and live in NROM/, with World Class Track Meet (U) in CNROM/ (mapper 3), Zanac (U) in UNROM/ (mapper 2) and Mermaids of Atlantis (U) in MAPPER8/ (mapper 8). The pre-promotion tier mirrors the structure under _wip/<MAPPER>/<Project>/ and is documented separately in WIP.md (851 projects across 29 mapper folders). Each project folder is flat: the source (prg.s, plus header.s/chr.s where present), the build config (linker.cfg, symbols.inc, locals.inc, Makefile) and the ROM splits all sit directly in the folder. Each project carries its own README.md (the file was called OVERVIEW.md before 2026-10-20) with a detailed power-on execution flow analysis. The pass history of every project — Pass 1, Pass 2, Pass 3 and Promotion, with the date and what each milestone produced — is in CHANGELOG.md.

Project Inventory

Mirroring is the iNES arrangement value taken from header byte 6, bit 0 (0 = Horizontal, 1 = Vertical), the convention AGENTS.md fixes. Several per-project README files (then named OVERVIEW.md) previously carried the opposite mirroring-direction wording; all were normalized to this column on 2026-10-19.

#	Project	Region/Version	PRG Size	CHR Size	Mirroring	Build Status	Vectors (NMI / RESET / IRQ)
1	Balloon Fight (JU)	Japan	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass complete)	$C094 / $C000 / $C0F7
2	Baseball (UE)	USA/Europe	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass complete)	$C046 / $C40B / $C43E
3	Bomberman (U)	USA	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass complete)	$C01A / $C000 / $FFF9
4	Burger Time (U)	USA	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass complete)	$FF7F / $FD24 / $FD24
5	Clu Clu Land (JU)	Japan	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass complete)	$C1F1 / $C196 / $C196
6	Defender 2 (U)	USA	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass complete)	$CAA1 / $C983 / $CA9E
7	Excitebike (JU)	Japan	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass complete)	$C23B / $C184 / $FFF0
8	Tennis (JU)	Japan	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass complete)	$C07D / $C000 / $C000
9	Pac-Man (USA) (Namco)	—	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass complete)	$C10E / $C033 / $C17E
10	Donkey Kong 3 (JUE)	Japan / USA / Europe	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass complete)	$C08D / $C000 / $C000
11	Donkey Kong Jr. (JU)	Japan	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass complete)	$C6E6 / $C66E / $FFF0
12	CIRCUS	—	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass complete)	$C05A / $C000 / $4CB7
13	Wild Gunman (U)	USA	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 3 complete, 49.1% code)	$C086 / $C000 / $C000
14	Joypad Test Cartridge (U)	USA	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 3 complete)	$CCF7 / $C000 / $C000
15	NES PowerPad Test Card (U)	USA	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass complete)	$E06E / $E000 / $E000
16	MUSCLE (U)	USA	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass complete)	$86CB / $8000 / $8764
17	Lunar Pool (U)	USA	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 2 complete, Pass 3 tables named)	$FF65 / $E80C / $FF64
18	Donkey Kong (JU)	Japan	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass 2/3 complete, 76.3% code)	$C85F / $C79E / $FFF0
19	Donkey Kong Jr. Math (U)	USA	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 3 complete; 295 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets)	$C4A9 / $C41E / $FFF0
20	Duck Hunt (JUE)	Japan / USA / Europe	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 3 complete)	$C086 / $C000 / $C000
21	Ice Climber (JE)	—	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass 3 complete)	$C076 / $C014 / $FFF0
22	Ice Climber (U)	USA	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass 3 complete)	$C076 / $C014 / $FFF0
23	Lode Runner (U)	USA	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 2/3 complete)	$C02C / $C000 / $FFF9
24	Pinball (JU)	Japan	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass 2/3 complete; data tables interpreted)	$C1ED / $C000 / $C1ED
25	Millipede (U)	USA	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 2/3 complete, 74.6% code; 0 address-derived entry points)	$C7F1 / $C735 / $FFF0
26	Popeye (JU) (PRG 0)	—	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 2/3 complete, 72.3% code; data tables interpreted)	$C701 / $C649 / $FFF0
27	Popeye (JU) (PRG 1)	—	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass 2/3 complete, 72.3% code; data tables interpreted; promoted from `_wip` 2026-10-20)	$C701 / $C649 / $FFF0
28	Golf (JU)	Japan	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 1+2+3 complete; promoted from `_wip` 2026-10-21)	$C0A6 / $C000 / $C0C4
29	Hogan's Alley (JU)	Japan	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 2 complete, Pass 3 complete, 49.1% code; promoted 2026-10-20)	$C088 / $C000 / $C000
30	Mario Bros (JU)	Japan	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 2 complete, Pass 3 complete, 78.4% code; data tables interpreted; promoted 2026-10-20)	$C07D / $C000 / $C000
31	Pac-Man (Tengen) (U)	USA	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass 2 complete, Pass 3 complete, 47.3% code; promoted 2026-10-20)	$C0FA / $C033 / $C16A
32	Pac-Man (U)	USA	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass 2 complete, Pass 3 complete, 47.4% code; promoted 2026-10-20)	$C0FA / $FF00 / $C16A
33	Pyramid (U) (Sachen)	—	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 2 complete, Pass 3 complete, 39.6% code; data tables interpreted; promoted 2026-10-20)	$D72E / $FF00 / $FF00
34	Raid on Bungeling Bay (U)	USA	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 2/3 complete, 64.6% code; promoted 2026-10-20; 223 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets)	$C04C / $C000 / $C2C0
35	Raid on Bungeling Bay (U) [a2]	—	16 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass 2 complete, Pass 3 complete, 64.3% code; promoted 2026-10-20; 220 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets)	$C04C / $C000 / $C2C0
36	Urban Champion (JU)	Japan	16 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 3 complete, 48.4% code; data tables interpreted)	$CA91 / $CA00 / $CA00
37	Xevious (U)	USA	32 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass 3 complete, 37.7% code)	$FC4E / $FAF6 / $FF1D
38	Zanac (U)	USA	128 KB	none	Horizontal	BYTE-IDENTICAL (Pass 3 complete, 10.5% code - banks 6 and 7 only; banks 0-3 are empty and banks 4-5 are stage data)	$CE8D / $E7BF / $CEC4
39	Volleyball (U)	Japan	32 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 3 complete, 73.0% code; promoted 2026-10-21)	$8053 / $8000 / $FFFF
40	Mermaids of Atlantis (U)	USA	64 KB	64 KB	Vertical	BYTE-IDENTICAL (Pass 3 complete, 12.3% code; promoted 2026-10-20, rebuilt 2026-10-21)	$808F / $FF00 / $8036
41	World Class Track Meet (U)	USA	32 KB	32 KB	Horizontal	BYTE-IDENTICAL (Pass 1+2+3 complete, 55.0% code; promoted from `_wip` 2026-10-21)	$F803 / $F6FD / $C0C0 (dead)
42	Port Test Cartridge (U)	USA	32 KB	none	Vertical	BYTE-IDENTICAL (Pass 1+2+3 complete, 4.8% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21)	$CC49 / $C000 / $CC17
43	10-Yard Fight (U)	USA	32 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass 1+2+3 complete, 32.0% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21)	$8471 / $8000 / $84FF
44	Chubby Cherub (U)	USA	32 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 1+2+3 complete, 41.4% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21; 205 `SubC<addr>` entry points named 2026-10-21, 18 address-derived `jsr`/`jmp` targets left, recorded in the project README)	$82B7 / $8000 / $8331
45	Dig Dug II (U) [!]	USA	32 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 1+2+3 complete, 53.5% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21)	$A749 / $A52D / $A52D
46	Gyromite (JUE)	Japan / USA / Europe	32 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 1+2+3 complete, 31.0% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21)	$8079 / $8000 / $8000
47	Hydlide (U)	USA	32 KB	8 KB	Horizontal	BYTE-IDENTICAL (Pass 1+2+3 complete, 47.8% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21)	$8003 / $8000 / $8003
48	Ice Hockey (U)	USA	32 KB	8 KB	Vertical	BYTE-IDENTICAL (Pass 1+2+3 complete, 39.5% code after a Mesen CDL re-split; promoted from `_wip` 2026-10-21; 140 `SubC<addr>` entry points named 2026-10-21, 79 address-derived `jsr`/`jmp` targets left, recorded in the project README)	$805A / $8000 / $8000

Thirty-six of the 48 rows are mapper 0 with a 16 KB PRG, 8 KB CHR and no trainer. The exceptions: Xevious (U) and Volleyball (U) are mapper 0 with a 32 KB PRG; Port Test Cartridge (U) is mapper 0 with a 32 KB PRG and no CHR (CHR RAM); 10-Yard Fight (U) is mapper 0 with a 32 KB PRG (NROM-256); Chubby Cherub (U) is mapper 0 with a 32 KB PRG (NROM-256); Dig Dug II (U) [!] is mapper 0 with a 32 KB PRG (NROM-256); Gyromite (JUE) is mapper 0 with a 32 KB PRG (NROM-256); World Class Track Meet (U) is mapper 3 (CNROM) with a 32 KB PRG and 32 KB CHR (its header's CHR-size field overstates the CHR by 32 KB); Zanac (U) is mapper 2 with a 128 KB PRG and no CHR; Mermaids of Atlantis (U) is mapper 8 with a 64 KB PRG, 64 KB CHR and eight 8 KB banks.

All 48 rows are promoted and BYTE-IDENTICAL — make compares the whole reconstructed ROM against rom.nes in the project folder. The last nine to leave _wip/ were Golf (JU) (row 28), World Class Track Meet (U) (row 41), Port Test Cartridge (U) (row 42), 10-Yard Fight (U) (row 43), Chubby Cherub (U) (row 44), Dig Dug II (U) [!] (row 45), Gyromite (JUE) (row 46), Hydlide (U) (row 47) and Ice Hockey (U) (row 48), all promoted on 2026-10-21. (Urban Champion, row 36, kept its tail number, so the promoted numbering is no longer a single contiguous range.)

The seven NROM projects promoted on 2026-10-21 were re-split afterwards. Their Pass 1 splits had classified between 0.7% and 24.9% of the PRG as code: the static trace reached the reset stub and the vblank wait and nothing else, because each game's main code sits behind a computed dispatch. A Mesen Code Data Logger capture of a real play session names the addresses the CPU actually branched to, and re-tracing with those seeds takes the coverage to 4.8%-53.5%. The numbers in the table are the re-split ones.

Still true after the 2026-10-20 reorganization. The mapper reorganization moved Donkey Kong Jr. Math (U) (row 19) into _wip/NROM/ — it was fixed the same day (its four jsr $F218 call sites had been labelled SubCF218_Block = $F1DC; repointed to the true entry SubCF218) and promoted back into NROM/. Popeye (JU) (PRG 1) was promoted from _wip/NROM/ the same day (row 27) — its whole-ROM compare passes on the first build. Excitebike (JU) (row 7) — the repo's one open block after being returned to NROM/ with a broken mid-repair build (duplicate symbol) — was finished the same day: the byte-596 mismatch ($0A operands where the ROM uses $11, now aliased NmiMaskShadow) is fixed, the 4,401 damaged audit comments were re-anchored via _tools/repair_audit_comments.py, and 58 raw jsr/jmp $XXXX operands were substituted with labels/equates. All 38 projects under NROM/ now verify byte-identical.

How to read this table. The vectors are the three little-endian words at the end of the 16 KB PRG ($FFFA-$FFFF in the $C000 mirror) — not fields in the iNES header, whose bytes 0-9 carry only sizes, mirroring and mapper. Regenerate the whole column with:

python3 - <<'EOF'
import os
MAPPERS = ('NROM', 'AOROM', 'CNROM', 'MMC1', 'MMC3', 'MMC5', 'UNROM')
for base in MAPPERS:
    if not os.path.isdir(base):
        continue
    for p in sorted(d for d in os.listdir(base) if os.path.isdir(os.path.join(base, d))):
        rom = open(f"{base}/{p}/rom.nes", 'rb').read()
        prg = rom[16:16 + rom[4]*16384]; vo = len(prg) - 6
        v = [prg[vo+i] | (prg[vo+i+1] << 8) for i in (0, 2, 4)]
        print(f"{p:30s} {'Vertical' if rom[6] & 1 else 'Horizontal':10s} "
              + " / ".join("$%04X" % x for x in v))
EOF

Five rows were wrong before this pass, all from copy-paste duplication of a neighbouring row's vectors, and are corrected above:

Project	Was	Actually
Burger Time (U)	`$C046 / $C40B / $C43E` (Baseball's)	`$FF7F / $FD24 / $FD24`
Clu Clu Land (JU)	`$C1F1 / $C000 / $FFF9`	`$C1F1 / $C196 / $C196`
Excitebike (JU)	`$C1F1 / $FD24 / $FD24`	`$C23B / $C184 / $FFF0`
Pac-Man (USA) (Namco)	`$C10E / $C000 / $C17E`	`$C10E / $C033 / $C17E`
Donkey Kong 3 (JUE)	`$C07D / $C000 / $C000`	`$C08D / $C000 / $C000`

Donkey Kong Jr.'s mirroring was also wrong (Horizontal, actually Vertical). Odd vector targets are not mistakes: Burger Time's $FF7F NMI and CIRCUS's $4CB7 IRQ point into unused/data space, which is common in this set — see "Notes" under Per-Project Details.

Region/Version comes from the folder-name suffix (JU/U/UE/JUE); these mapper-0 headers do not encode region, so CIRCUS — whose folder carries no suffix — is left as — rather than guessed.

Per-Project Details

1. Balloon Fight (JU)

Folder: NROM/Balloon Fight (JU)/
ROM: balloon.nes (24,592 bytes)
Source: prg.s (17,607 lines)
Linker: PRG at $C000, 16 KB; single segment
Vectors: NMI → $C094 (NmiHandler), RESET → $C000 (Reset), IRQ → $C0F7 (IrqHandler, self-loop)
Key subsystems: NMI-driven frame loop with PPU command buffer, round spawner ($C790), bonus objects ($CB74), carrier/rescue sequence ($C6F9), particle system ($CDAA), sound driver ($FFF7 banked)
Build fix: None needed; byte-identical out of the box. Pass 1 verified complete 2026-10-16 — 5,303 instructions / 11,260 code bytes (68.7%), which is more than the complete-opcode static tracer finds (5,277 / 11,202); the 166 tracer-only bytes are genuine data (command scripts at $D437/$D45A, the $C3B5 pointer table, the arithmetic table at $FBCA), not missed code. The last two .incbin spans were converted to explicit classified bytes (TrailingFillBeforeApuTables at $F4C5, SoundEngineTailBytes at $F5FC), so no ROM byte is hidden
Pass 3 symbols (2026-10-19): every operand symbols.inc/locals.inc defines is now named in prg.s — 125 hardware-register operands and 797 of 813 zero-page/RAM operands. The 15 multi-alias addresses were resolved per routine (--sites in _tools/apply_symbols.py). 16 operands are left numeric: $13 used as a plain high-byte scratch beside Temp12, where none of its three aliases fits. Rebuild stays byte-identical.
Audit-trail repair (2026-10-21): the per-instruction audit comments were stale by two bytes from ResetInitializationData ($C085) onward — 5,944 of the 6,007 comments named the wrong CPU address/PRG offset, because the 3-byte .byte "HAL" signature at $C082–$C084 was counted as one byte when the trail was generated. The routine headers and the linker labels were correct, so source and headers disagreed. _tools/repair_audit_comments.py rebuilt the trail from the ca65 -l listing (validated against prg.bin) and _tools/align_audit_comments.py restored the canonical column-35 layout. Comment-and-whitespace only: the code text of all 8,544 lines is unchanged and make still prints Byte-identical ROM verified. All 6,007 comments now re-check against prg.bin, all 65 routine headers agree with the instructions they describe, and every label agrees with reconstructed.lbl. A related off-by-one in align_audit_comments.py was fixed (it tested the indented code length against 31 instead of 35, so 28–31-character code texts were never padded into the column).
Routine headers completed (2026-10-21): all 63 routine headers now carry the full template AGENTS.md describes — global, local, parameters, returns and clobbers. The ; Clobbers: blocks are derived, not written by hand: _tools/derive_clobbers.py takes the opcode from the audit comment's byte list (so the addressing mode is exact), resolves the operand through locals.inc/symbols.inc to name what is written, follows the real control flow (a jsr to another named entry is a call; a branch or a fall-through is not), and models register preservation — so NmiHandler reports no register (it saves and restores A, X and Y) and FlushPpuCommandPreserved reports only A (X and Y come back unchanged). The flags are named individually. Comment-only change: the code text of all 8,538 lines is unchanged and make still prints Byte-identical ROM verified.
Details: Balloon Fight (JU)/README.md

2. Baseball (UE)

Folder: NROM/Baseball (UE)/
ROM: baseball.nes (24,592 bytes)
Source: prg.s (21,627 lines — largest source)
Linker: PRG at $C000, 16 KB; single segment
Vectors: NMI → $C046 (NMI), RESET → $C40B (Reset), IRQ → $C43E (IRQ, rti)
Key subsystems: Queued event system ($EB66–$EB9C) as the main frame driver, round/state machine ($C5FE), batting/pitching ($C6044–$C6414), object sorting ($C339), sound driver ($F9D0–$FE2x)
Build fix: None needed; byte-identical out of the box
Pass 3 symbols (2026-10-19): 121 operands substituted (85 single-name + 36 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
Details: Baseball (UE)/README.md

3. Bomberman (U)

Folder: NROM/Bomberman (U)/
ROM: bomberman.nes (24,592 bytes)
Source: prg.s (11,000 lines), header.s, chr.s
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $C01A (NmiHandler), RESET → $C000 (Reset), IRQ → $FFF9 (IrqHandler, rti)
Key subsystems: NMI-driven PPU command queue and VRAM transfers, main loop at $C368 with state dispatch table ($C75D), bomb/object slots (80 slots at $03E6), sound driver ($E642–$FE2x) with dispatch table ($E6AD)
Build fix: One-byte mismatch at CPU $E71B (dec $E4 vs dec $54) — resolved by adding RandomStateAlt = $E4 to locals.inc alongside RandomState0 = $54 (zero-page reuse); also renamed ControllerState → ControllerState1, Main_HandleControl_C368 → MainGameLoop, Gameplay_HandleControl_C79D → GameplayUpdate, Sound_HandleControl_E65F → SoundUpdate
Pass 3: Applied 354 single-name + 8 site-resolved multi-alias operands from locals.inc; 24 in-file table labels from reconstructed.lbl; 0 hardware substitutions needed. Residue: 758 unnamed operands (179 distinct addresses).
Details: Bomberman (U)/README.md

4. Burger Time (U)

Folder: NROM/Burger Time (U)/
ROM: Burger Time (U) [!].nes (24,592 bytes)
Source: prg.s (13,138 lines), header.s, chr.s
Linker: HEADER, PRG at $C000 (0x3FFA), VECTORS at $FFFA, CHR
Vectors: NMI → $FF7F (points into the vector page itself — not a real handler; NMI is effectively unused), RESET → $FD24 (ResetHandler, sei prologue), IRQ → $FD24 (reuses Reset)
Key subsystems: Event-driven main loop via CommonEngineExit ($EB6A) and queued events ($EB9D), title screen / round state machine ($C5FE), object arrays ($03E6 state, $0436/$0486 position), audio engine ($F9D0–$FE2x) with music sequencer ($FD34)
Build fix: None needed; byte-identical. Requires symlink burger_time.nes → "../Burger Time (U) [!].nes" due to spaces in ROM filename
Details: Burger Time (U)/README.md

5. Clu Clu Land (JU)

Folder: NROM/Clu Clu Land (JU)/
ROM: rom.nes (24,592 bytes)
Source: prg.s (10,501 lines)
Linker: PRG at $C000, 16 KB; single segment (no separate HEADER/CHR segments in cfg, but CHR data is embedded inline at end of prg.s)
Vectors: NMI → $C1F1 (NMIHandler), RESET → $C196 (ResetEntry, shared with the IRQ handler), IRQ → $C196 (IrqHandler, reuses Reset)
Key subsystems: State-machine main loop via dispatch table at $C000–$C00D, NMI-driven PPU command queue + VRAM transfers, object pools ($03E6 state, $0436/$0486 position), sound driver ($E642–$F7C0) with dispatch table ($E6AD)
Build fix: One bpl branch to undefined label at CPU $FAB4 — replaced with bne *-$1B to produce original d0 e3 bytes (disassembler mislabeled bne as bpl)
Details: Clu Clu Land (JU)/README.md

6. Defender 2 (U)

Folder: NROM/Defender 2 (U)/
ROM: Defender 2 (U).nes (24,592 bytes)
Source: prg.s (17,432 lines)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (0x3FFA), VECTORS at $FFFA, CHR at $0000
Vectors: NMI → $CAA1 (NmiHandler), RESET → $C983 (ResetHandler), IRQ → $CA9E (IrqHandler, reuses Reset)
Key subsystems: Event-driven main loop (UpdateSideScrollingGameplay_CA6A at $CA6A) waiting on NMI flag, side-scrolling gameplay ($C073–$C324 family), PPU streaming ($F20B–$F7C0), audio engine ($E642–$F7C0) with dispatch table ($E6AD)
Build fix: Same bpl → bne *-$1B fix at CPU $E811 as Clu Clu Land (disassembler mislabeled bne as bpl)
Details: Defender 2 (U)/README.md

7. Excitebike (JU)

Folder: NROM/Excitebike (JU)/
ROM: rom.nes (24,592 bytes)
Source: prg.s (13,993 lines)
Linker: PRG at $C000, 16 KB; single segment
Vectors: NMI → $C23B (NMI), RESET → $C184 (Reset), IRQ → $FFF0 (points into audio data region — likely placeholder/unused)
Key subsystems: NMI-driven state machine with dispatch table at $C000–$C00D (14 states), title/menu system ($C346–$C454), gameplay update chain ($C99A), race update ($C8D6), audio engine ($F8DE) with 4 channels + SFX, serial I/O over controller port $4016
Build fix: Same bpl → bne *-$1B fix at CPU $FAB4 (same pattern as Clu Clu Land/Defender 2). On 2026-10-20 the last whole-ROM mismatch (byte 596) was fixed — two NMI operands the ROM spends on $11, a second PPU-mask shadow, were emitted with PpuMaskShadow ($0A); $11 is now aliased NmiMaskShadow in locals.inc. The same day the audit trail was re-anchored from the ca65 listing via _tools/repair_audit_comments.py (6,339 shifted comments + 4,401 doubled-?? forms) and all 58 raw jsr/jmp $XXXX operands were substituted with routine labels/locals.inc sub-entry equates.
Details: Excitebike (JU)/README.md

8. Tennis (JU)

Folder: NROM/Tennis (JU)/
ROM: Tennis (JU).nes (24,592 bytes)
Source: prg.s (10,377 lines)
Linker: PRG at $C000, 16 KB; single segment
Vectors: NMI → $C07D (NmiHandler), RESET → $C000 (Reset), IRQ → $C000 (Reset reused)
Key subsystems: NMI-synchronized main loop (MainLoop at $C04F), game state machine via MainStateHandlerTable ($C101, 12 states), game mode state machine via GameModeStateTable ($CAD7, 8 states), object/sprite system with fixed-point physics, audio engine ($F8DE) with serial I/O over controller port
Build fix: None needed; byte-identical out of the box
Pass 3 symbols (2026-10-19): 18 single-name operands substituted from locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
Details: Tennis (JU)/README.md

9. Pac-Man (USA) (Namco)

Folder: NROM/Pac-Man (USA) (Namco)/
ROM: rom.nes (24,592 bytes)
Source: prg.s (7,637 lines)
Linker: PRG at $C000, 16 KB; single segment
Vectors: NMI → $C10E (NmiHandler), RESET → $C033 (Reset; locals.inc defines ResetOffset = $C033), IRQ → $C17E (IrqHandler)
Key subsystems: NMI-synchronized main loop (MainLoop at $C04F), game state machine via MainStateHandlerTable ($C101, 12 states), game mode state machine via GameModeStateTable ($CAD7, 8 states), object/sprite system with fixed-point physics, audio engine ($F8DE) with serial I/O over controller port
Build fix: None needed; byte-identical out of the box
Pass 3 symbols (2026-10-19): 524 single-name operands substituted from locals.inc via _tools/apply_symbols.py — 727 multi-alias residues left numeric (addresses with 2+ aliases, e.g. $00 = workPtr0/Zp00). Rebuild stays byte-identical.
Details: Pac-Man (USA) (Namco)/README.md

10. Donkey Kong 3 (JUE)

Folder: NROM/Donkey Kong 3 (JUE)/
ROM: Donkey Kong 3 (JUE).nes (24,592 bytes)
Source: prg.s (14,647 lines)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $C08D (NmiHandler; the prg.s header block records it as "Pass 2 control-flow entry at CPU $C08D"), RESET → $C000 (Reset), IRQ → $C000 (Reset reused)
Key subsystems: Main loop with object/game state management at $C02E–$C18D, object movement and geometry calculations ($C28E–$C683), audio engine ($F8DE+) with sound channels ($F0–$FF), PPU command buffer streaming ($C3F4+)
Build fix: Build split main.s into header.s, prg.s, chr.s; added RandomStateAlt = $E4 for dec $E4 at CPU $E71B (zero-page reuse with RandomState0 = $54). 2026-10-16 — one-byte branch-target bug fixed: the project was recorded as BYTE-IDENTICAL but had never built byte-identical. The bne at CPU $C14C (PRG $014C) was annotated D0 12 (target $C160) but assembled as D0 0D, because it was labelled StoreSelectedPlayerAndScreenFlags ($C15B) instead of the routine actually at $C160. Retargeted to ClearAudioSetGameMode — which is also the semantically correct target for a "mode != $01" test. cmp now passes.
Details: Donkey Kong 3 (JUE)/README.md

11. Donkey Kong Jr. (JU)

Folder: NROM/Donkey Kong Jr. (JU)/
ROM: Donkey Kong Jr. (JU).nes (24,592 bytes)
Source: prg.s (15,271 lines; 6,199 instructions, 266 routines, 68 data labels, 0 conflicts)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $C6E6 (NmiHandler), RESET → $C66E (ResetHandler), IRQ → $FFF0 (stray byte, effectively unused)
Key subsystems: Reset idles in a PRNG-advance loop — the entire frame state machine (title/attract/gameplay/sound) runs inside the NMI handler; VRAM/event queue at $0300 with dispatch table at $BFFE; 8-byte PRNG at $18–$1F; sound timers at $F1AF
Build fix: None needed; byte-identical out of the box (make in the project folder). Pass 1 verified complete 2026-10-16 — a full byte-accounting audit of prg.s confirms all 16,384 PRG bytes are emitted exactly once (6,199 instructions + 3,889 .byte + 16 .word), every emitted value equals the ROM byte, and there are zero audit-comment mismatches or duplicate addresses. No .incbin remains. A complete-opcode static tracer independently reaches 6,135 instructions / 12,358 code bytes (75.4%) — every one of which is already present in the file, and the file carries 121 further code bytes the tracer does not find (reached via the DeferredTaskHandlerTable dispatch at $BFFE). Pass 2/3 naming is complete; Pass 3 tables are named (DeferredTaskHandlerTable, HudDigitDescriptorTable, …)
Details: Donkey Kong Jr. (JU)/README.md

12. CIRCUS

Folder: NROM/CIRCUS/
ROM: rom.nes (24,592 bytes)
Source: prg.s (~18,661 lines)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $C05A (NmiHandler), RESET → $C000 (Reset), IRQ → $4CB7 (outside mapped space — effectively unused)
Key subsystems: NMI-driven frame state machine — main loop is a spin loop at $C057, all per-frame work runs in NMI; main state dispatcher at $C0D0 with 16-state pointer table; controller input with edge flags at $09; menu system with text table at $C763 ("CONTINUE", "STAGE", "SELECT", "PLAY"); palette/screen transfer via descriptor streams; VRAM queue processing; variant object state machine at $DC3F–$FE7B; audio engine with sequence data at $FABB–$FFFB
Build fix: None needed; byte-identical out of the box (make in the project folder). Pass 1/2/3 complete — full code/data classification, semantic routine naming, and data table naming all done. 2026-10-21: the 258 SubC<addr> entry points were given semantic names (the 586 internal branch-target children were re-based onto their parent's new name), so grep -nE "^(SubC|Sub)_?[0-9A-F]{4}" prg.s now returns nothing and no jsr/jmp target is address-derived
Pass 3 symbols (2026-10-19): 118 operands substituted (38 single-name + 80 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — 23 multi-alias residues left numeric (addresses with 2 aliases: $E4=Controller1Shift/ZpE4, $7C=WorkPointer0Lo/Zp7C, $7E=WorkPointer1Lo/Zp7E). Rebuild stays byte-identical.
Details: CIRCUS/README.md

13. Wild Gunman (U)

Folder: NROM/Wild Gunman (U)/
ROM: rom.nes (24,592 bytes)
Source: prg.s (~14,644 lines with routine headers)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $C086 (NmiHandler), RESET → $C000 (Reset), IRQ → $C000 (reuses Reset)
Key subsystems: NMI-driven frame loop — main loop is a spin loop waiting on NMI phase flag ($20); NMI handler does OAM DMA ($4014), PPU updates, and calls game logic subroutines ($C29F, $C233, $C3AC, $C265); main state dispatcher at $C0B3 based on GameMode ($30); reset copies sprite/OAM data from $C844 to $05F0; APU enabled via $4015 = $0F
Build fix: None needed; byte-identical out of the box (make compares the whole ROM in the project folder: cmp reconstructed.nes rom.nes). Pass 1 redone 2026-10-16 — the original tracer followed only RESET/NMI/IRQ and jsr/jmp/branch targets and knew just the 151 documented opcodes, so it missed Wild Gunman's runtime dispatch (Label_C341's pla-based computed goto puts the jump table inline right after each jsr $C341) and filed ~4.9 KB of real code as .byte data. Code coverage went 1,597 instr / 3,352 B (20.5%) → 3,956 instr / 8,085 B (49.3%). Pass 2 complete — all 733 labels carry names (zero Label_Cxxxx/SubCxxxx remain), routine headers on every entry point, zero-page aliases in locals.inc (GameMode=$30, NmiPhase=$20, NmiFlag=$22, Timer2F=$2F, etc.). Pass 3 complete — data tables named: SpriteAttributeTable ($C6AC), NoteVolumeTable ($F3EF), VolumeEnvelopeTable ($F48F), SpritePositionTable ($F77C); the OAM sprite block at $C844 is documented in-place as a comment rather than a label
Pass 3 symbols (2026-10-19): 76 operands substituted (11 single-name + 65 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
Details: Wild Gunman (U)/README.md

14. Joypad Test Cartridge (U)

Folder: NROM/Joypad Test Cartridge (U)/
ROM: rom.nes (24,592 bytes)
Source: prg.s (5,871 lines; 202 routines, all with described headers)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $CCF7 (NmiHandler), RESET → $C000 (Reset), IRQ → $C000 (reuses Reset)
Key subsystems: NMI-driven frame loop — main loop spins waiting on NMI phase; NMI handler does OAM DMA ($4014), PPU scroll/control latch, and burst VRAM writes from table at $0302; VramPtrWrite ($CD3F) uses a return-address modification trick at RetAddrUpdate ($CDC8) for runtime-computed dispatch; VramWrite ($CDEE) sets PPU address and writes data to PPUDATA; reset clears RAM, initializes PPU ($2000=$10, $2001=$00), triggers OAM DMA, and enters main loop
Build fix: Byte-identical out of the box, but Pass 1 was badly truncated and has been redone. It claimed 282 instructions / 580 bytes (3.5%); the tracer halted at $C09E on DCP $3C20 ($CF), an undocumented opcode used as ordinary code, and filed 3,256 bytes of real code as .byte. Now 1,773 instructions / 3,836 bytes (23.4%), verified against a fresh trace. nesdis.py --undocumented supplies the 105 undocumented NMOS opcodes; ca65 V2.19 encodes none of them, so the 4 affected instructions are emitted as explicit .byte with the disassembly in the comment. Pass 2 then renamed all 202 labels (zero Label_Cxxxx left) and rewrote all 202 routine headersr all labels, semantic naming for key routines, zero-page aliases in locals.inc (VramPtrLo=$00, PpuCtrlShadow=$EF, FrameCounterLo=$53, etc.)
Pass 3 symbols (2026-10-19): 47 hardware operands substituted from symbols.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
Details: Joypad Test Cartridge (U)/README.md

15. NES PowerPad Test Card (U)

Folder: NROM/NES PowerPad Test Card (U)/
ROM: rom.nes (24,592 bytes)
Source: prg.s (3,170 lines)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $E06E (NmiHandler), RESET → $E000 (Reset), IRQ → $E000 (reuses Reset)
Key subsystems: Minimal NMI-driven test cartridge — NMI reads PowerPad via $4016, processes transitions, updates score/lives display; APU at $4015=$0F; 8.3% code coverage
Build fix: None needed; byte-identical out of the box
Pass 3 symbols (2026-10-19): 89 hardware operands substituted from symbols.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
Details: NES PowerPad Test Card (U)/README.md

16. MUSCLE (U)

Folder: NROM/MUSCLE (U)/
ROM: M.U.S.C.L.E. (U).nes (24,592 bytes); rom.nes is a relative symlink ../M.U.S.C.L.E. (U).nes
Source: prg.s (Pass 1/2/3 output, with 42 bytecode listings above the .byte data)
Linker: HEADER at $0000 (16 bytes), PRG at $8000 (16 KB), CHR at $0000 (8 KB) — the one ROM in the set mapped low
Vectors: NMI → $86CB (NmiHandler), RESET → $8000 (Reset), IRQ → $8764 (a bare RTI that doubles as the NMI epilogue). Vectors themselves sit in the $C000 mirror at $FFFA.
Key subsystems: bytecode VM — 40 opcodes at $C8-$EF handled through a table at $9237, everything else a literal operand. Gameplay dispatches through three jump tables plus two zero-page jmp (zp) calls a static descender cannot follow: 38-entry token-program pointer table at $8CEF, 40-entry opcode handler table at $9237, 16-entry handler table at $9F2B, 3-entry per-level VRAM-writer table at $AC35. Compressed-VRAM RLE decoder at $AC82 with a 12-byte fill table at $ACBD; division by 20 restored at $82AC; four-channel sound engine with per-channel state in zero page $C4-$EF.
Build fix: the skeleton's $C000 linker assumption was wrong — RESET is $8000, so linker.cfg had to move. Makefile tool paths were ../../../_tools/ while in _wip/; promotion to top-level required ../../_tools/. make regen (pass1→pass2→pass3) reproduces prg.s byte-for-byte.
Pass 3 symbols (2026-10-19): 220 operands substituted (91 single-name + 129 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
Pass 3 data-table inventory (2026-10-21): all 69 data blocks are inventoried in the project README with their address range, size, name, structure and the instruction that reads them. Two blocks that had been given bytecode-program names turned out not to be bytecode and were renamed: StandaloneBytecodeProgram_1 → DeathSequenceVramStream ($881F, the compressed nametable RLE stream of the death sequence) and StandaloneBytecodeProgram_3 → LevelOamTemplateTable ($AB14, the per-level OAM template copied into the shadow at $0300). The pointer table's 38 entries are all distinct, so it reaches 38 distinct programs, not 37.
Details: MUSCLE (U)/README.md

17. Lunar Pool (U)

Folder: NROM/Lunar Pool (U)/ (promoted out of _wip/ 2026-10-18 by git mv, so the relative rom.nes symlink is live and tool paths are ../../_tools/)
ROM: Lunar Pool (U).nes (24,592 bytes)
Source: prg.s (5,302 instructions, 67.5% code / 11,062 bytes; 705 labels, zero Label_ residue, 38 semantic zero-page aliases + 66 neutral, 33 named data tables)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $FF65 (NmiHandler), RESET → $E80C (non-$C000 entry), IRQ → $FF64 (bare rti, adjacent to NMI)
Key subsystems: NMI-driven frame loop with PPU command queue and VRAM transfers; main loop at $E80C; side-scrolling / pool gameplay; audio engine; print-inline-string helper at $CBDC/$CBC9
Build fix: Promotion from _wip/ added header.s, chr.s, HEADER/PRG/CHR linker.cfg, and whole-ROM cmp; rebuilt from Mesen CDL capture (10,028 bytes Code). Pass 1/2/3 complete — byte-identical at whole-ROM level.
Pass 3 symbols (2026-10-19): 45 operands substituted (18 single-name + 27 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
Details: Lunar Pool (U)/README.md

18. Donkey Kong (JU)

Folder: NROM/Donkey Kong (JU)/ (promoted out of _wip/ 2026-10-19 by git mv, so the relative rom.nes → ../Donkey Kong (JU).nes symlink survived)
ROM: Donkey Kong (JU).nes (24,592 bytes)
Source: prg.s (6,014 instructions, 76.3% code / 12,505 bytes; 1,015 labels with zero Label_ residue, 145 zero-page slots with neutral ZpXX names, 10 named data regions)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $C85F (NmiHandler), RESET → $C79E (non-$C000 entry, like DK Jr.), IRQ → $FFF0 (vector-page padding, unused)
Key subsystems: reset enters at $C79E; NMI-driven frame loop; dispatchers at $C807/$C815/$C823/$C831/$C847 load 16-bit pointers from ObjectPtrTable ($C03C) and from $C4A7,x; large level-data pointer block $C044–$C79D; sound engine over MusicDataTable ($F55B), APUDataTable ($FAE6), SfxDataTable ($FE59)
Pass 2 (2026-10-19): all 919 Label_XXXX definitions named — 102 new semantic routine names + 217 SubC<addr> entry names (honest residue) + 600 derived <Routine>_Block[_n] internal branch targets; jsr/jmp operands stay numeric (Wild Gunman (U) style). Applied with _tools/pass2.py apply; make still byte-identical
Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink, and the whole-ROM cmp; no _tools path change (the Makefile never referenced _tools/) and no make regen target. Mirroring was recorded as Vertical in the project README (then named OVERVIEW) but header byte 6 = $00 says Horizontal — corrected at promotion
Pass 3 symbols (2026-10-19): 75 operands substituted (17 single-name + 58 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
Details: Donkey Kong (JU)/README.md

31. Pac-Man (Tengen) (U)

Folder: NROM/Pac-Man (Tengen) (U)/ (promoted out of _wip/NROM/ 2026-10-20 by git mv)
ROM: Pac-Man (Tengen) (U) [!].nes (24,592 bytes), reached through the rom.nes symlink
Source: prg.s (12,739 lines; 3,841 instruction lines covering 7,743 code bytes = 47.3%; 227 labels — 199 routine entries + 28 branch targets — zero Label_ residue, zero raw $XXXX jsr/jmp/branch operands, 2,479 canonical audit comments, 0 byte mismatches against prg.bin)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $C0FA (NmiHandler), RESET → $C033 (Reset — the boot sequence is inline here; there is no boot code at $FF00 in this build), IRQ → $C16A (IrqHandler)
Key subsystems: NMI frame loop with two controller reads; game-state dispatch through GameStateDispatchTable ($C253); maze graphics (MazeTileGraphics $C2FD, AttributeTableData $C387, BorderPattern $C432); ghost AI with the target search at $C8AA and the four-ghost slots; UpdateMazeTiles ($DAB0) rewriting the maze through the four overlay tables; score/attribute VRAM writes; the level-script interpreter at $EE8F dispatching through ScriptCommandTable ($EFDD)
Variant: a different build of the same game as row 32 — 56 PRG bytes differ in 8 runs, all of them code-versus-licensee-text ($C3E3-$C408 is 26 spaces here against LICENSED BY NAMCO AMERICA INC there; $FF00-$FF16 is $FF padding here against the boot code there), and the RESET vector differs to match. The CHR is identical
Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical (MD5 d34e7a74…28ad0)
Pass 2 (2026-10-20): a fresh map derived from this dump's own committed split — no name, map or file was carried over from the row-32 dump. All 194 Label_XXXX definitions renamed to semantic routine entries plus <Routine>_<Role> branch targets, and all 48 raw $XXXX call operands resolved. Recorded in routinemap.tsv
Pass 3 (2026-10-20): 30 semantic zero-page aliases, each applied only at the sites where its role is proven (the per-site choice is in sites.tsv; the addresses that carry two roles keep the neutral ZpXX name elsewhere, and locals.inc records the reason for every remaining neutral slot). 28 data tables named — including CharacterDataTable ($C66A) and CharacterNameStrings ($C67E), where the ROM itself names Blinky, Pinky, Inky and Clyde. apply_symbols.py reports 0 residue
Pass 1 correction (2026-10-20): six command handlers recovered. ScriptCommandTable ($EFDD) is read by the traced instruction at $EFCC, and six of its entries point at $F00A, $F022, $F03A, $F052, $F062 and $F072 — all of which the tracer had left as data, and two of which it had mis-split across the jmp $EF61 at $F01F and $F04F. Those 120 bytes are code here, decoded straight from the ROM. The same gap exists in the promoted row-32 dump, which has not been corrected
Residue: the unreached main game logic at $C45A–$C55F is still .byte data. It is code — the tracer's own decoder walks it cleanly and the dispatch table at $C511 points into it — but nothing reaches it, so it cannot be entered without a guess. The same gap exists in the row-32 dump. Re-deriving it is a Pass 1 job; a Mesen Code Data Logger capture is the tool the repo uses (_tools/cdl_reclass.py)
Details: Pac-Man (Tengen) (U)/README.md

32. Pac-Man (U)

Folder: NROM/Pac-Man (U)/ (promoted out of _wip/NROM/ 2026-10-20 by git mv; tool paths stay ../../_tools/)
ROM: Pac-Man (U) [!].nes (24,592 bytes), reached through the rom.nes symlink
Source: prg.s (12,796 lines; 1,549 audited instruction lines covering 7,767 code bytes, plus 49 jsr/jmp call sites — 47.4% code by the Pass 1 tracer's accounting; zero Label_ residue, zero raw $XXXX call operands)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $C0FA (NmiHandler), RESET → $FF00 (Reset — real boot code at the vector-page tail, not padding: sei/cld, PPU off, double vblank wait, jmp ColdStart at $C042), IRQ → $C16A (IrqHandler)
Key subsystems: NMI-driven frame loop; game-state dispatch through GameStateDispatchTable ($C253) via jmp (DispatchPtrLo); entity dispatch through EntityPtrTable ($D912) and a second table at $D9B9; palette upload from $0299/$02A9; VRAM write queue at $026B/$0272; audio engine with AudioCommandTable ($EFDD) dispatched via jmp (AudioHandlerPtrLo); 15-byte copyright signature ProgrammerSig ($C0EB) checked against RAM at $0052
Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical (MD5 a69d310f8cae9397fbd39f204672b5c7)
Pass 2 (2026-10-20): fresh map derived from the committed split (not from a drafted map): all 194 Label_XXXX definitions renamed to semantic routine entries plus <Routine>_<Role>_<addr> internal branch targets, and all 49 jsr/jmp call sites resolved to labels. Recorded in routinemap.tsv / derived_names.tsv
Pass 3 symbols (2026-10-20): 119 operands substituted (101 hardware + 11 single-name + 7 multi-alias resolved per site via sites.tsv) — apply_symbols.py reports 0 residue. The 7 site resolutions are all proven from context: four jmp ($0010) immediately preceded by sta DispatchPtrLo/sta DispatchPtrHi, one jmp ($00FE) preceded by sta AudioHandlerPtrLo/sta AudioHandlerPtrHi, and two sta a:$0000,y zero-page clears that take the neutral Zp00. Audit-comment alignment was re-done afterwards with the new _tools/align_audit_comments.py (whitespace-only)
Details: Pac-Man (U)/README.md

29. Hogan's Alley (JU)

Folder: NROM/Hogan's Alley (JU)/ (promoted out of _wip/NROM/ 2026-10-20 by git mv)
ROM: Hogan's Alley (JU).nes (24,592 bytes), reached through the rom.nes symlink
Source: prg.s (14,620 lines; 3,950 instruction lines covering 8,041 code bytes = 49.1%; 681 labels, zero Label_ residue, zero raw $XXXX jsr/jmp/branch operands, 4,490 canonical audit comments, 0 byte mismatches against prg.bin)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $C088 (NmiHandler), RESET → $C000 (Reset), IRQ → $C000 (the same address)
Key subsystems: the frame heartbeat — the NMI sets GameFramePending ($20) and the main loop spends it, with NmiPhaseFlag ($22) stopping the per-frame work from running twice; an inline dispatch architecture — IndirectCall at $C34D pops the return address of the jsr that called it and reads a 16-bit handler pointer from the word that follows, so the six handler tables live inside the code stream ($C124 19 entries, $C219 4, $C89C 14, $CDD1 1, $D234 2, $D3D6 14); the Zapper on $4017 (ReadZapper $CF3E) with the controller debounced over five frames into Player1Buttons ($16); a three-accumulator sound engine (SoundFlag0/1/2 at $F0–$F2) fed by 24 one-bit stubs and read at $F9FF/$FC48/$FAFC, with the note records in NoteParameterTable ($FCC8)
Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical
Pass 1 correction (2026-10-20): the static trace classified only 41.8 % of the PRG as code. A fresh Mesen Code Data Logger capture was merged with the four captures already in the folder (hogans_merged.cdl, the OR of five per-byte flag arrays, 6,544 code bytes) and _tools/cdl_reclass.py rewrote the split to match what the CPU actually fetched: 1,216 bytes moved from data to code, five moved the other way and 59 labels were emitted. The four branch targets the tool could not prove were turned into labels by the new _tools/resolve_raw_branches.py
Pass 2 (2026-10-20): a fresh map derived from this dump's own committed split: 206 routine entries hand-named and 413 internal branch targets derived mechanically by _tools/derive_branch_names.py, 630 Label_XXXX definitions gone, 484 raw $XXXX call operands resolved, 15 call targets the tracer had never labelled given a label. Recorded in routinemap.tsv
Pass 3 (2026-10-20): 60 semantic zero-page aliases, each applied only where its role is proven (zp_aliases.inc and zp_alias_sites.tsv); the slots that stay neutral are each listed with the reason. 34 data tables named — SubStateHandlerTable, ModeHandlerTable, HandlerDispatchTable, ActorCommandTable, TargetBehaviourTable, NoteParameterTable and the rest — and recorded in data_region_names.tsv. apply_symbols.py reports 1 residue: sta a:$00B4,y at $C203, the same address as Zp40/ActorPalette but forced to absolute addressing, so it must stay numeric
Residue: no make regen target. The Pass 1 split here is the static trace corrected by a CDL capture, and the base the correction was applied to is not what the current _tools/nesdis.py produces, so a regen pipeline could not reproduce prg.s byte for byte. prg.s is the maintained source of truth
Details: Hogan's Alley (JU)/README.md

30. Mario Bros (JU)

Folder: NROM/Mario Bros (JU)/ (promoted out of _wip/NROM/ 2026-10-20 by git mv)
ROM: Mario Bros (JU).nes (24,592 bytes), reached through the rom.nes symlink
Source: prg.s (22,010 lines; 6,210 instruction lines covering 12,847 code bytes = 78.4%; 1,025 labels, zero Label_ residue and zero SubC residue, zero raw $XXXX jsr/jmp/branch operands, 6,458 canonical audit comments, 0 byte mismatches against prg.bin)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $C07D (NmiHandler), RESET → $C000 (Reset), IRQ → $C000 (the same address)
Key subsystems: the frame heartbeat — the NMI sets FramePendingFlag ($20) and the main loop spends it, with NmiPhaseFlag ($22) stopping the NMI handler from doing its per-frame work twice; an inline dispatch table — the handler pointers sit in the middle of the code stream, right after the call that reads them, so the static tracer cannot follow them (GameStateHandlerTable $C510 and its five continuation blocks); a script interpreter that drives the enemies (SetupScriptPointer $CB85, FetchScriptByte $E9FA, RunScript $E9D3) with the command byte compared against $AA and $BB; the Zapper-free controller read with a five-frame debounce into Zp10/Zp11; a per-note sound engine at $F8A7–$FD27 working from the note table at $FCC8
Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical
Pass 1 correction (2026-10-20): the committed split was a strict subset of the correct one — only 72.0% of the PRG was classified as code. A Mesen Code Data Logger capture of this ROM (mario_mesen.cdl, 10,915 code bytes) showed 1,010 bytes the tracer had left as data were code; the two branch targets the capture never reached ($E4CB and $E639) were forced with --override and account for 57 more, so 1,067 bytes moved from data to code and 22 moved the other way. The biggest single win is $D508–$D56D, a hundred bytes that decode as a coherent routine, and $CA3B–$CA5D, the tile-drawing routine. The three branch targets the reclassifier could not prove were turned into labels by _tools/resolve_raw_branches.py
Pass 2 (2026-10-20): a fresh map derived from this dump's own committed split: 206 routine entries and 519 internal branch targets, 931 Label_XXXX definitions gone, 51 raw $XXXX call operands resolved and 12 call targets the tracer had never labelled given a label. Zero SubC residue: the 185 entries the previous session had left as address-derived residue were all named from the code. Recorded in routinemap.tsv
Pass 3 (2026-10-20): 25 semantic zero-page aliases, each applied only where its role is proven (zp_aliases.inc); the slots that stay neutral are each listed with the reason. 35 data tables named — GameStateHandlerTable, EnemyBehaviourTable, EnemyScriptTable, EnemyTypePointerTable, SoundRoutineTable, NoteFrequencyTable and the rest — and recorded in data_region_names.tsv. apply_symbols.py reports 0 residue
Details: Mario Bros (JU)/README.md

33. Pyramid (U) (Sachen)

Folder: NROM/Pyramid (U) (Sachen)/ (promoted out of _wip/NROM/ 2026-10-20 by git mv; the folder was renamed from NROM/Pyramid (U) on 2026-10-21 to match the inventory row)
ROM: Pyramid (U) (Sachen).nes (24,592 bytes), reached through the rom.nes symlink
Source: prg.s (10,737 lines; 3,130 instruction lines covering 6,493 code bytes = 39.6%; 463 labels, zero Label_ residue, zero raw $XXXX jsr/jmp/branch operands, 3,762 canonical audit comments, 0 byte mismatches against prg.bin)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $D72E (NmiHandler), RESET → $FF00 (Reset), IRQ → $FF00 (the same address — sei is never undone, so the IRQ never fires)
Key subsystems: the unlicensed Sachen boot (sta $4100 mapper unlock with a delay loop at $FF4C, the "A"/"V" check on RAM $0120/$0121 at $FF57, the seed at $FF69, the clear at $FF74, the hand-off to the game's own entry at $C800); a task table of jmp trampolines that live inside the data regions ($C01E, $C02A, $C042, $C054) plus ten more at $C000–$C01B; two queued-event dispatchers that jump through the zero page with jmp ($0002) ($C3A3 with TaskVectorTable1 $C3A6, $CCCA with TaskVectorTable2 $CCD5); a VRAM command list assembled in the $0700 buffer and flushed by FlushVramCommandList; the actor grid at $0436 with the actor tables at $D320/$D4EE/$D5D5; a four-voice sound engine with its period, envelope and sample tables
Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical (MD5 aa285ff1…6c59e2)
Pass 1 correction (2026-10-20): the committed split was a strict subset of the correct one — 828 bytes of code were still marked as data, because the tracer cannot follow a jmp that sits inside a data region. Re-tracing with the sixteen jmp-table targets, the $C800 boot mainline and six further code starts seeded by hand recovers them (plus a five-byte stub at $DF89 in a hole between two routines), and the re-trace loses no committed code byte. make regen reproduces the split, so it stays verifiable
Pass 2 (2026-10-20): a fresh map derived from this dump's own committed split: 431 routine entries and the 32 data blocks named, 428 Label_XXXX definitions gone, 320 raw $XXXX call operands resolved. The internal branch-target names are derived mechanically from the branch that reaches them by _tools/derive_branch_names.py. Recorded in routinemap.tsv
Pass 3 (2026-10-20): 24 semantic zero-page aliases, each applied only where its role is proven (zp_aliases.inc); the 57 slots that stay neutral are each listed with the reason. 32 data tables named — TaskVectorTable1/TaskVectorTable2, LevelScriptData, MusicPeriodTable, SoundEnvelopeTable, the actor tables — and recorded in data_region_names.tsv. apply_symbols.py reports 0 residue
Pass 3 data tables (2026-10-21): all 31 data blocks are now interpreted rather than merely labelled, and the project README carries a Pass 3 data-table inventory giving every block's address range, size, name, structure and consuming instruction. Nine guessed names were corrected — PaletteSlotRemapTable, SoundFrequencyDeltaTable (five 24-bit decade multipliers: 100000, 10000, 1000, 100, 10), ActorSpriteTileTable, ActorDefinitionTable, GridObjectTileTable, ActorDirectionOffsetTable, ActorSpriteOamTable, ActorSpriteYPositionTable and SoundApuInitTable — and ActorParameterTable ($CD97) and ActorFlagByte ($D72D) were dropped because nothing reads them and their layout is not established. The block names live in data_region_names.tsv, so make regen reproduces them
Residue: the zero page is reused heavily — 410 references still carry a neutral name, mostly the general-purpose scratch of the shift and arithmetic helpers. 482 absolute operands point at RAM and stay numeric. sta $4100 stays a raw operand: it is outside the $2000-$4017 range PROMPTS.md asks to be symbolic, and no hardware name would describe a mapper unlock
Details: Pyramid (U) (Sachen)/README.md

34. Raid on Bungeling Bay (U)

Folder: NROM/Raid on Bungeling Bay (U)/ (promoted out of _wip/NROM/ 2026-10-20 by git mv)
ROM: Raid on Bungeling Bay (U).nes (24,592 bytes), reached through the rom.nes symlink
Source: prg.s (~19,691 lines; 255 SubC<addr> entry points, 612 Sub_<Role>_<addr> branch names, zero Label_ residue, zero raw $XXXX jsr/jmp/branch operands)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $C04C (NmiHandler), RESET → $C000 (Reset → ResetEntry at $C6E3), IRQ → $C2C0 (IrqHandler)
Key subsystems: NMI frame loop with two paths (NmiPathSelector $C4: minimal vs full); state bitmap at $0200 dispatching on bits 0–3; PPU helper at $C006; sprite/OAM update at $C08E; palette update at $C4E4; main game logic at $C17A; PRNG at $C412; four computed indirect jumps at $E2EC / $E79D / $E7A0 / $E7A3
Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical (MD5 77285503…885000ac)
Pass 3 (2026-10-20): 11 semantic zero-page aliases added to locals.inc and applied at the proven sites. One of them was corrected while the [a2] sibling was finished: $EA had been named VBlankWaitCounter, but the routine at $C412 is the game's PRNG (the classic eor/asl/php/lsr/plp/rol scrambler, called thirteen times from gameplay code, twice in a row at $CDF4/$CDF9 with the second result masked #$07), so $EA is the scrambler's phase counter. Renamed PrngPeriodCounter, and $EB/$EC were named PrngSeedB/PrngState. Two sta a:IndDispatch17,y operands that were absolute stores to RAM $0017 were also corrected to a:Zp17,y
Entry-point naming (2026-10-21): all 223 address-derived SubC<addr> jsr/jmp entry points were given semantic names — the radar sweep and its blips, the five factories and the targets guarding them, the fuel gauge and the enemy sprites (UpdatePseudoRandomNumber, UploadPaletteToPpu, DrawSpritePart, GetRadarScreenAddress, UpdateFuelGauge, MoveEnemyTowardsTarget, DestroyEnemy, DispatchEnemyRoutine17/19/1B). Zero address-derived entry points remain. No instruction and no byte value changed
Details: Raid on Bungeling Bay (U)/README.md

35. Raid on Bungeling Bay (U) [a2]

Folder: NROM/Raid on Bungeling Bay (U) [a2]/ (promoted out of _wip/NROM/ 2026-10-20 by git mv)
ROM: Raid on Bungeling Bay (U) [a2].nes (24,592 bytes), reached through the rom.nes symlink
Source: prg.s (19,596 lines; 5,079 instruction lines covering 10,536 code bytes = 64.3%; 866 labels — 252 SubC<addr> entries + 610 Sub_<Role>_<addr> branch names — zero Label_ residue, zero raw $XXXX jsr/jmp/branch operands, 5,467 canonical audit comments, 0 byte mismatches against prg.bin)
Linker: HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
Vectors: NMI → $C04C (NmiHandler), RESET → $C000 (Reset → ResetEntry at $C6E3), IRQ → $C2C0 (IrqHandler)
Key subsystems: same structure as row 34 — NMI frame loop with two paths, state bitmap at $0200, PPU helper at $C006, sprite/OAM update at $C08E, palette update at $C4E4, main game logic at $C17A, PRNG at $C412, four computed indirect jumps
Variant: a different build of the same game as row 34 — 150 of the 16,384 PRG bytes differ, in 7 runs, all of them code-versus-copyright-text at $C67D–$C6D8 and $C73B–$C779; the CHR differs too; header byte 6 is $00 (Horizontal) against row 34's $01 (Vertical). The zero-page reference sets are otherwise identical
Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 2/3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp; the first promoted build was byte-identical (MD5 659d340a1e9d420eee28df13319b0094)
Pass 3 (2026-10-20): 15 semantic zero-page aliases added to locals.inc and applied at the proven sites — every alias is applied only where its role is proven, and the addresses that carry two names keep the neutral name at the sites where the other role applies ($01 is PtrHi at the 16-bit compare and IndDispatch01 at the dispatch; $17 is IndDispatch17 at the dispatch and Zp17 for the absolute RAM $0017 store in the copy loop). The new _tools/apply_zp_aliases.py does the per-site substitution, because apply_symbols.py only rewrites numeric operands
Entry-point naming (2026-10-21): all 220 address-derived SubC<addr> jsr/jmp entry points were given the same semantic names the base dump carries — the two PRGs differ in only 150 bytes, all of them in the copyright-text block, so every routine outside it is byte-identical. Zero address-derived entry points remain. No instruction and no byte value changed
Details: Raid on Bungeling Bay (U) [a2]/README.md

36. Urban Champion (JU)

Folder: NROM/Urban Champion (JU)/
ROM: Urban Champion (JU).nes (24,592 bytes)
Source: prg.s (Pass 3; 3,842 instructions, 691 labels)
Linker: PRG at $C000, 16 KB; single segment
Vectors: NMI → $CA91 (NmiHandler), RESET → $CA00 (Reset), IRQ → $CA00 (reuses Reset)
Key subsystems: NMI-driven frame loop with simple fight game logic; the sound engine (a ten-slot sound-effect table with four APU-channel note sequences each, a note-period table and a note-length table) and the two fighters' 32-byte state blocks at $0300/$0320; 48.4% code
Build fix: None needed; byte-identical out of the box
Pass 3 symbols (2026-10-19): 70 operands substituted (4 single-name + 66 hardware) from symbols.inc/locals.inc via _tools/apply_symbols.py — zero residue. Rebuild stays byte-identical.
Pass 3 data tables (2026-10-21): the Pass 1 split was re-traced from the Mesen CDL captures and all 40 data blocks are now interpreted — 72 labels (name_data_region.py), and the project README carries a Pass 3 data-table inventory with every block's address range, size, name, structure and consuming instruction.
Details: Urban Champion (JU)/README.md

37. Xevious (U)

Folder: NROM/Xevious (U)/ (promoted out of _wip/NROM/Xevious (U)/)
ROM: Xevious (U).nes (32,768 bytes)
Source: prg.s (Pass 3; 868 labels)
Linker: HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
Vectors: NMI → $FC4E (NmiHandler), RESET → $FAF6 (Reset), IRQ → $FF1D (IrqHandler)
Key subsystems: NMI-driven frame loop with OAM DMA, PPU scroll/control latch, controller reading with shift register on $4016/$4017; two computed-dispatch mechanisms: jmp ($fe) through a 16-entry table at $BA8B (sprite attribute dispatch), jmp ($4) through a 44-entry table at $CA0A (the opcode dispatch of the stage-script VM); game mode state machine (title/game/demo) driven by GameMode ($10) and GameSubMode ($1B); object iteration, movement and drawing; sprite attribute packing into OAM
Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 3. Promotion added header.s, chr.s, a HEADER/PRG/CHR linker.cfg, the rom.nes symlink and the whole-ROM cmp
Pass 1 correction: static trace from vectors reached only 13.6% of PRG. Declaring both jump tables via --table plus 92 hand-seeded entry points recovered code behind computed dispatch, reaching 34.5%. On 2026-10-21 the split was redone from the project's Mesen CDL with _tools/cdl_reclass.py: 1,158 bytes data→code, 48 code→data, 42 labels emitted, giving 12,455 code bytes (38.0%) and 6,002 instructions; the 45 recovered entries are named Sub_XXXX, so no Label_ remains
Pass 3 tables (2026-10-21): all 129 data blocks are interpreted - 46 carry a semantic name and a description of what their bytes are and which instruction reads them, 44 are recorded as unreferenced data and 38 as code the tracer could not reach. The $A74B-$B8AA block is split into VramWritePtrTable, VramWriteData, StageScriptPtrTable, ObjSpritePtrTable, ObjSpriteData and StageScriptData; $8000-$9FFF is the level's background tilemap (8192 bytes = 32 columns x 256 rows of background tile indices - sky gradients, terrain shapes and the creature markers); the table at $CA0A is the opcode dispatch of the stage-script VM and the scripts at $ACFB-$B8AA are what it executes; the sprite record is four bytes (Y, tile, attribute, X); the table at $F136 is a sine-wave flight path; MessageTextTable at $F5D8 decodes to PLAYER, GAME OVER, READY, SOLVALOU, LEFT and PAUSE; InitRamSignature at $FC45 is the nine-byte "Kei Cross" signature copied to $0100-$0108 at reset
Residue: 20,313 bytes (62.0%) remain .byte data, and every one of the 129 blocks is now accounted for in the project's Pass 3 data-table inventory (46 named, 44 unreferenced data, 38 unreached code). Six CDL-silent raw call operands remain and five regions (Sub_C626, $D24B, Sub_D61B, Sub_D63E, Sub_EA9F) still decode as code although their bytes form tables; both are documented in the project README. Six addresses contain undocumented/illegal opcodes not decoded by the tracer: $9848, $A2C3, $CD89, $E0FF, $E3B5, $F230
Details: Xevious (U)/README.md

38. Zanac (U)

Folder: UNROM/Zanac (U)/ (promoted out of _wip/UNROM/Zanac (U)/)
ROM: Zanac (U).nes (131,072 bytes)
Source: prg.s + prg.07.s (Pass 3; bank 7 traced with 391 labels, banks 0-6 as raw data)
Linker: HEADER at $0000, PRG at $0010-$1C000, PRG7 at $1C010-$20000
Vectors: NMI → $CE8D (NmiHandler), RESET → $E7BF (Reset), IRQ → $CEC4 (IrqHandler)
Key subsystems: NMI-driven frame loop with OAM DMA, PPU scroll/control latch, controller reading with shift register on $4016/$4017; vertical scrolling shooter with attract mode; object iteration, movement and drawing; sprite attribute packing into OAM
Build fix: none at PRG level — it was PRG-identical in _wip/ and stayed byte-identical through Pass 3. Promotion added header.s, chr.s, a HEADER/PRG/PRG7 linker.cfg, the rom.nes symlink and the whole-ROM cmp
Pass 1 correction: static trace from vectors reached only 37.9% of bank 7. Banks 0-6 remain as raw .byte data pending bank-switch analysis
Residue: ~65.5% of bank 7 remains .byte data. Seven addresses contain undocumented/illegal opcodes not decoded by the tracer: $D506, $D876, $E15B, $E44B, $E520, $E909, $F0FE
Details: Zanac (U)/README.md

39. Volleyball (U)

Folder: NROM/Volleyball (U)/ (promoted out of _wip/NROM/Volleyball (U)/)
ROM: Volleyball (U).nes (40,976 bytes)
Source: prg.s (Pass 3; 1,989 labels, all semantic — 730 read out of the code by hand, 1,221 internal branch targets derived mechanically)
Linker: HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
Vectors: NMI → $8053 (NmiHandler), RESET → $8000 (Reset), IRQ → $FFFF (not a handler — the last byte of the PRG image; the APU frame counter is never IRQ-enabled)
Key subsystems: the whole game runs from the NMI handler — the main loop at $81B5 only re-arms $DF and refreshes eight zero-page bytes. OAM shadow at $03FF uploaded by DMA, a VRAM update-script interpreter driven from a four-byte command block at $05C0-$05C3, controller reading with a shift register on $4016/$4017, a per-frame crowd animation, and an eleven-entry game-state dispatch table at $85E1 keyed by GameState ($2B) and GameSubState ($2C)
Build fix: none — it was whole-ROM byte-identical in _wip/ and stayed that way through Pass 3. Promotion was git mv plus the doc updates
Pass 1 correction: the static trace reached only 66% of the PRG image. Declaring the game-state dispatch table (--table 85E1:11) plus a Mesen Code Data Logger capture taken while a random-input bot played the attract demo promoted 1,757 further bytes from data to code, reaching 73.0% (11,395 instructions / 23,926 code bytes, 8,842 data bytes, 0 unclassified)
Verification: _tools/cdl_check.py cross-checks the finished prg.s against the CDL — 0 CDL-code bytes not covered by an instruction and 0 CDL-data bytes that start one. apply_symbols.py --report reports 0 residue; align_audit_comments.py reports no column drift
Residue: the ten copies of the per-nation player-movement and ball routines are named by their position in the ROM, not mapped to the ten selectable nations — the copies differ only in a few constants, so the mapping would need a per-copy behavioural trace. BallHitOffsetTable and the speed tables hold values whose exact meaning is still inferred from the surrounding code
Details: Volleyball (U)/README.md

42. Port Test Cartridge (U)

Folder: NROM/Port Test Cartridge (U)/ (promoted out of _wip/NROM/Port Test Cartridge (U)/)
ROM: Port Test Cartridge (U).nes (40,976 bytes)
Source: prg.s (Pass 3; 114 routines, 18 data blocks, 4,563 lines)
Linker: HEADER at $0000, PRG at $8000-$FFFF, CHR absent (the cartridge has CHR RAM)
Vectors: NMI → $CC49 (NmiHandler), RESET → $C000 (Reset), IRQ → $CC17 (IrqHandler)
Key subsystems: the NES Control Deck Test. A menu-driven diagnostic: the reset stub waits for vblank, enables the APU, strobes the controllers and dispatches through a VRAM command stream; the command stream is a sequence of (PPU address, descriptor, data) records that the engine at SetupPpuAddress ($CE7F) replays into the PPU. The controller port test at $CDC0 returns $00, $55 or $AA for the three ports
Build fix: none — it was whole-ROM byte-identical in _wip/ and stayed that way through Pass 3. Promotion was git mv plus the doc updates
Pass 1 correction: the committed split classified 0.7% of the PRG as code — the static trace reached the reset stub and the vblank wait and nothing else, because the Control Deck Test is a menu-driven state machine and the code behind each menu entry was never executed. A Mesen Code Data Logger capture of the deck-test screen, with the capture's jump-target addresses and the start of every run of code the capture saw used as tracer seeds, takes the split to 4.8% (813 instructions / 1,697 code bytes)
Why the coverage stays low: by design. The cartridge has no CHR ROM, so the 16 KB character font at $8001 is uploaded into CHR RAM at run time; the rest of the PRG is command tables and $FF fill. The engine that reads them is 1,697 bytes
Details: Port Test Cartridge (U)/README.md

43. 10-Yard Fight (U)

Folder: NROM/10-Yard Fight (U)/ (promoted out of _wip/NROM/10-Yard Fight (U)/)
ROM: 10-Yard Fight (U).nes (40,976 bytes)
Source: prg.s (Pass 3; 647 routines, 58 data blocks, 16,864 lines)
Linker: HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
Vectors: NMI → $8471 (NmiHandler), RESET → $8000 (Reset), IRQ → $84FF (IrqHandler)
Key subsystems: an IREM American-football game. The CHR's pattern table 0 is an ASCII font (tiles $00-$09 the digits, $0A-$23 the letters), which decodes the game's own text: the skill menu (HIGH SCHOOL / COLLEGE / PROFESSIONAL / PLAYOFF / SUPER BOWL), the "SELECT YOUR OPPONENT" screen, "HALF TIME UP", the copyright lines, and the play-result strings ("NOT 10 YARD", "10 YARD BACK", "PASS INTERCEPT", "20 YARD BACK"). Two dispatch tables of 16-bit code addresses ($8569 and $9E57) are consumed by an indirect jump at $84D0 and $9ECC, so 12 of the "data" blocks are handler code the static tracer cannot follow
Build fix: none — it was whole-ROM byte-identical in _wip/ and stayed that way through Pass 3. Promotion was git mv plus the doc updates
Pass 1 correction: the committed split classified 11.2% of the PRG as code. A Mesen Code Data Logger capture of the title screen, the opponent's skill menu and a game in progress, with the capture's jump targets and code-run starts used as tracer seeds, takes it to 32.0% (5,166 instructions / 10,491 code bytes)
Details: 10-Yard Fight (U)/README.md

44. Chubby Cherub (U)

Folder: NROM/Chubby Cherub (U)/ (promoted out of _wip/NROM/Chubby Cherub (U)/)
ROM: Chubby Cherub (U).nes (40,976 bytes)
Source: prg.s (Pass 3; 763 routines, 48 data blocks, 20,128 lines)
Linker: HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
Vectors: NMI → $82B7 (NmiHandler), RESET → $8000 (Reset), IRQ → $8331 (IrqHandler)
Key subsystems: a Bandai platformer in the Little Nemo mould. The HUD and message text is 8x8 nametable tiles and the code that draws it is a table of tile codes; the mapping was recovered by running the ROM and matching the live nametable against the title, gameplay and game-over screens - $00-$09 the digits, $0A-$23 the letters, $24 '-', $25 '.', $26 the trademark, $2D a heart, $2E '!', $2F the copyright sign, $30 a space and $33 a blank - which turns opaque byte blobs into "TM AND (C) BANDAI 1986", "LICENSED BY NINTENDO", "1P-SCORE", "1P GAME OVER", "1P CONGRATULATIONS!", "FOOD", "POWER", "TIME" and "STAGE"
Build fix: none — it was whole-ROM byte-identical in _wip/ and stayed that way through Pass 3. Promotion was git mv plus the doc updates
Pass 1 correction: the committed split classified 20.1% of the PRG as code. A Mesen Code Data Logger capture of a real session, with the capture's jump targets and code-run starts used as tracer seeds, takes it to 41.4% (6,630 instructions / 13,553 code bytes)
Entry-point naming (2026-10-21): 205 of the 223 address-derived SubC<addr> jsr/jmp entry points were given semantic names — the state machine, the screen writers and the enemies (ResetPlayerState, DispatchGameState, UpdateGameFrame, UpdateGameplay, UpdateEnemies, ClearNametable, WriteTextToNametable, DrawReadyRow, DrawGameOverRow, StartTitleScreen, UpdateEnemyObjects, DispatchEnemyBehaviour). The 18 that are left — twelve sound-effect selectors that choose a pair of pointers into the one block whose layout is not established, plus six reset and sprite-gate variants — are recorded with the reason in the project README. No instruction and no byte value changed
Details: Chubby Cherub (U)/README.md

45. Dig Dug II (U) [!]

Folder: NROM/Dig Dug II (U) [!]/ (promoted out of _wip/NROM/Dig Dug II (U) [!]/)
ROM: Dig Dug II (U) [!].nes (40,976 bytes)
Source: prg.s (Pass 3; 1,296 routines, 37 data blocks, 30,134 lines)
Linker: HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
Vectors: NMI → $A749 (NmiHandler), RESET → $A52D (Reset), IRQ → $A52D (the same address as RESET)
Key subsystems: the 1985 Namco sequel. The game has 72 rounds - $0259 counts 0-71 and wraps at $48 in $C8EA - and that is what the round-indexed palette, monster-type and enemy-offset tables are keyed on. The stage map is a pointer table at $8000 over 72 fixed 106-byte slots at $8090; the VRAM upload is RLE and is decoded byte for byte; the tile-graphics pointer tables at $B060 and $B160 resolve to their 8x8 bitmap targets
Build fix: none — it was whole-ROM byte-identical in _wip/ and stayed that way through Pass 3. Promotion was git mv plus the doc updates
Pass 1 correction: the committed split classified 24.9% of the PRG as code. A Mesen Code Data Logger capture of a real session, with the capture's jump targets and code-run starts used as tracer seeds, takes it to 53.5% (8,161 instructions / 17,525 code bytes)
Details: Dig Dug II (U) [!]/README.md

46. Gyromite (JUE)

Folder: NROM/Gyromite (JUE)/ (promoted out of _wip/NROM/Gyromite (JUE)/)
ROM: Gyromite (JUE).nes (40,976 bytes)
Source: prg.s (Pass 3; 742 routines, 52 data blocks, 17,936 lines)
Linker: HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
Vectors: NMI → $8079 (NmiHandler), RESET → $8000 (Reset), IRQ → $8000 (the same address as RESET)
Key subsystems: the 1985 Namco game. The player drops bombs on five enemy motherships and then flies a small ship to finish them. The sprite system is a shape-id list at $9B16 over a 90-entry pointer table at $9B24 over variable-length shape records at $9BD8; the screen is four nametable tile-row tables written to VRAM $20A2 and $20E2; the wave layout is two strides over one 74-byte stream at $8A11 and $8A2A; the sound data is the APU noise register triples at $F100, the pulse-1 sweep and duration pairs and the note periods
Build fix: none — it was whole-ROM byte-identical in _wip/ and stayed that way through Pass 3. Promotion was git mv plus the doc updates
Pass 1 correction: the committed split classified 4.8% of the PRG as code. A Mesen Code Data Logger capture of a real session - the "PUSH SELECT KEY" screen, the select-mode menu and a game in progress - takes it to 31.0% (4,933 instructions / 10,150 code bytes)
Open: the tile numbers themselves are not decoded; that would need the CHR rendered and compared against the running game, the way Chubby Cherub (U) decoded its font codes
Details: Gyromite (JUE)/README.md

47. Hydlide (U)

Folder: NROM/Hydlide (U)/ (promoted out of _wip/NROM/Hydlide (U)/)
ROM: Hydlide (U).nes (40,976 bytes)
Source: prg.s (Pass 3; 759 routines, 26 data blocks, 21,070 lines)
Linker: HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
Vectors: NMI → $8003 (NmiHandler), RESET → $8000 (Reset), IRQ → $8003 (the same address as NMI)
Key subsystems: the 1986 Konami action game. The player explores a forest and a castle, chops trees and rocks with a sword, finds the five Crystals and fights monsters; the screen carries LIFE, STR and EXP meters. The sound engine writes instrument definitions straight to the APU registers, with the note periods in ApuNotePeriodTable ($E2CE) and the music scripts behind pointer tables
Build fix: none — it was whole-ROM byte-identical in _wip/ and stayed that way through Pass 3. Promotion was git mv plus the doc updates
Pass 1 correction: the committed split classified 22.3% of the PRG as code. A Mesen Code Data Logger capture of a real session, with the capture's jump targets and code-run starts used as tracer seeds, takes it to 47.8% (7,708 instructions / 15,667 code bytes)
Details: Hydlide (U)/README.md

48. Ice Hockey (U)

Folder: NROM/Ice Hockey (U)/ (promoted out of _wip/NROM/Ice Hockey (U)/)
ROM: Ice Hockey (U).nes (40,976 bytes)
Source: prg.s (Pass 3; 1,037 routines, 76 data blocks, 24,390 lines)
Linker: HEADER at $0000, PRG at $8000-$FFFF, CHR at $0000-$1FFF
Vectors: NMI → $805A (NmiHandler), RESET → $8000 (Reset), IRQ → $8000 (the same address as RESET)
Key subsystems: the 1988 Nintendo ice hockey game, with the USA and Canada teams, a line-up screen, a 4 x 8 rink position grid, and a per-frame handler. The screen layout is four pointers into RLE-compressed nametable streams; the rink positions are 32 interleaved (Y, X) pairs; the player starts are four rows per team, the right-hand side mirrored from the left; the 15-entry game-state dispatch table at $83F3 is reached through an indirect jump at $836E
Build fix: none — it was whole-ROM byte-identical in _wip/ and stayed that way through Pass 3. Promotion was git mv plus the doc updates
Pass 1 correction: the committed split classified 3.5% of the PRG as code. A Mesen Code Data Logger capture of the title screen, the team line-up and a game in progress, with the capture's jump targets and code-run starts used as tracer seeds, takes it to 39.5% (6,475 instructions / 12,954 code bytes)
Entry-point naming (2026-10-21): 140 of the 219 address-derived SubC<addr> jsr/jmp entry points were given semantic names — the frame services, the player/puck simulation and the sound engine (ClearGameMemory, UploadPaletteToPpu, DecompressScreenData, PollControllerButtons, WriteSpriteToOam, MovePlayerLeft/Right/Up/Down, ComputePlayerFacing, RemapPlayerRoleFromTableA-D, UpdateSoundEngine, PlaySoundEffect). The 79 that are left — the steps of the contact simulation and the rink-zone drawing that read 8.8 fixed-point zone coordinates — are recorded with the reason in the project README. No instruction and no byte value changed
Details: Ice Hockey (U)/README.md

`_wip/` Projects

The pre-promotion tier is documented in WIP.md. It now holds 851 projects across 29 mapper folders:

Folder	Mapper	Projects
`_wip/NROM/`	0	35
`_wip/MMC1/`	1	221
`_wip/UNROM/`	2	97
`_wip/CNROM/`	3	57
`_wip/MMC3/`	4	239
`_wip/MMC5/`	5	10
`_wip/MAPPER7/` … `_wip/MAPPER232/`	7-232	192

All 851 build byte-identical for the whole ROM — the tier was moved off the old PRG-level-only compare on 2026-10-20, so the header and CHR are now proven for every project here, exactly as in the promoted tier. All 851 of them are Pass 0 skeletons: the folder shape and the build are proven, but prg.s is still a single .incbin "prg.bin". Volleyball (U) was the last project to leave the tier with a full disassembly: Pass 1 + Pass 2 + Pass 3, promoted to NROM/Volleyball (U) on 2026-10-21; Golf (JU) and World Class Track Meet (U) followed on 2026-10-21, promoted to NROM/Golf (JU)/ and CNROM/World Class Track Meet (U)/ respectively.

Two things are worth knowing before touching a _wip/ project:

Most of the tier is a banked mapper with a PRG image larger than the 6502's address space. Only two projects have a 16 KB PRG; 149 have 32 KB, 522 have 128 KB and one (Action 52 (U) [!]) has 1.5 MB. Those projects link their MEMORY areas at file offsets rather than CPU addresses, which is both the only option and the honest model. See "Two linker layouts" in WIP.md.
226 projects have no CHR at all — the mapper supplies CHR RAM.

The tier is deliberately not built by the root Makefile's all/clean/ <MAPPER> targets — MAPPERS names only the promoted mapper folders. The pre-promotion tier has its own explicit targets:

make wip          # build + verify every _wip/<MAPPER>/<Project>/
make wipclean     # clean the build artifacts in the tier

Both are driven by WIP := _wip at the top of the root Makefile; without that variable the loop expands to for m in /*/, which walks the filesystem root instead of the tier.

(The old manual loop, for d in _wip/*/*/; do make -C "$d"; done, still works as an equivalent.)

Promotion is now just git mv plus the disassembly work: the whole-ROM build, the header.s/chr.s sources, the HEADER/PRG/CHR linker.cfg and the rom.nes copy are already in place. No _tools path change is needed, because both tiers sit two levels deep, so ../../_tools/ is correct either way. Lunar Pool (U), Donkey Kong (JU), Popeye (JU) (PRG 1), Raid on Bungeling Bay (U), Pac-Man (U), Raid on Bungeling Bay (U) [a2], Pac-Man (Tengen) (U), Pyramid (U) (Sachen), Hogan's Alley (JU) and Mario Bros (JU) (all 2026-10-20) went through exactly that and came out whole-ROM byte-identical on the first promoted build. Xevious (U) and Zanac (U) followed on 2026-10-20, Mermaids of Atlantis (U) on 2026-10-20, and Volleyball (U) on 2026-10-21.

git mv only moves the tracked files, so the old _wip/ folder survives with its untracked build artifacts (*.o, reconstructed.nes, reconstructed.lbl, reconstructed.map) and sometimes with a stale README.md left behind. Delete the leftover folder — otherwise it counts as a project in every tier tally while having no source to build. Xevious (U) and Zanac (U) both left one behind on 2026-10-20; both were cleaned up on 2026-10-21.

Notable vector/header observations for Pass 1 work:

Pac-Man (U) RESET at $FF00 — the vector-page tail, but not padding: $FF00 holds real boot code (sei/cld, PPU off, double vblank wait, jmp ColdStart at $C042). The Tengen variant RESETs at $C033 and has no boot code at $FF00 at all (that region is $FF padding) — the same boot sequence is inline at $C033. The two PRGs differ in 56 bytes in 8 runs, all of them code-versus-licensee-text.
Lunar Pool (U) NMI $FF65 / IRQ $FF64 are adjacent in the vector page; RESET $E80C.
NES PowerPad Test Card (U) — at Pass 2/3: minimal code (~7.2%), data-heavy test cartridge. RESET at $E000 (non-$C000 entry). NMI handler reads controllers via shift register, processes pad transitions, draws score/lives. See NES PowerPad Test Card (U)/README.md.
Lunar Pool (U) — Pass 2 and Pass 3 complete; promoted to the top level 2026-10-18: RESET at $E80C (not $C000), NMI $FF65, IRQ $FF64 (a bare rti just before the NMI handler, so IRQs are ignored). There is no jmp ($7961) RAM-pointer gate (an earlier claim): those three sites fell out of decoding two bytes into the word "player". $CBDC/$CBC9 is a print-inline-string-and-return-after-it helper, so a jsr $CBDC is always followed by a $81-prefixed, $00-terminated string ("player", "shot", "game over", "hiscore__", "perfect_"). The split was re-derived from a Mesen CDL capture (10,028 bytes Code): now **5,300 instructions / 11,077 bytes (67.6%)**, 5,301 data bytes and the six vector bytes as .word. Pass 2 named all **705** labels — Label_is gone from the file — and Pass 3 named 33 tables plus the zero-page aliases (38 semantic, 66 neutral, ten former phantom aliases deleted). Residue, recorded rather than guessed: 73 bytes of *reachable* code are still.byte ($EA9A, $EADC, $EAE5, $EAED, $EB04, $EB16-$EB4F— the CDL capture never fetched them), another 75 bytes of ending-screen code sit at$F5F9-$F643, and ~206 bytes of unreached-but-clearly-code stubs stay data. The full 24,592-byte ROM (header + PRG + CHR) rebuilds byte-identically. See Lunar Pool (U)/README.md`.
Ice Climber (JE) vs (U): byte-identical PRG and header — only the CHR differs (~regional title graphic).
Popeye (JU) PRG 0 vs PRG 1: different PRG binaries (and mirroring); same vectors.
Raid on Bungeling Bay (U) vs [a2]: [a2] differs in mirroring only per header, but PRGs differ — separate builds.
Pyramid (U) (Sachen) — promoted 2026-10-20: the unlicensed Sachen boot pokes a mapper unlock at $4100, checks the RAM bytes $0120/$0121 against "A"/"V", and dispatches through two queued-event tables with jmp ($0002). It also dispatches through jmp trampoline tables that live inside the data regions — 828 bytes of code that the tracer could not reach were recovered by hand. See NROM/Pyramid (U) (Sachen)/README.md.
CIRCUS — at Pass 2/3: full recursive disassembly complete. NMI-driven frame state machine (main loop is a spin loop at $C057). Menu text at $C763 ("CONTINUE", "STAGE", "SELECT", "PLAY"). Object state machine at $DC3F–$FE7B. Audio sequence data at $FABB–$FFFB. See CIRCUS/README.md.
Mermaids of Atlantis (U) — promoted 2026-10-20, rebuilt 2026-10-21: mapper 8 (MMC3) with 64 KB of PRG, so the PRG is eight 8 KB banks and two of them can be visible at the same CPU address. The image carries the reset stub and the vector table twice: at file $7FFA (the fixed bank) the NMI vector is $808F — that is the live one, and $808F is the frame handler — while the copy at file $FFFA names $8189, which is a BRK in the first half of the image. The fixed bank is the fourth 8 KB bank ($6000-$7FFF), not the last one, which is why the game's text table lives at CPU $F1D6: that is the fixed window, and the code reads it there. Mesen maps the fixed bank the same way, and the dump's own code is what settles it. The disassembly therefore has one segment per bank (PRG0..PRG7), each with its own .org for the CPU window, and banks 4 to 7 carry a Bank4_..Bank7_ label prefix. See MAPPER8/Mermaids of Atlantis (U)/README.md.
Mermaids of Atlantis (U) — Pass 3 data-table inventory (2026-10-21): all 76 data blocks the tracer left are inventoried in the project README with their address range, size, name, structure and the instruction that reads them; 27 blocks carry a name (47 labels), the other 49 are recorded as unreferenced - 27 of them are code the tracer could not reach, one is $FF padding and 21 are unreferenced data. The fixed bank holds the game's tables (the digit table at $F1D6, the actor script pointers, the level layout), which is why code in banks 0, 2 and 4 reaches them with a plain absolute operand. The CHR is the oracle for the font - tiles $30-$39 are the digits and $40-$5A the letters in ASCII order - which is what identifies the high-score table at $9403 ("TOM1000", "ABCDEFGHIJKLMNOPQRSTUVWXYZ@") and the menu strings at $9254 ("1PLAYER", "2PLAYERS", "STACKED", "TUNE1".."TUNE3") as plain ASCII, and shows that the 3,783-byte block at $A000 in bank 1 is not text. The image is banked, so _tools/name_data_region.py grew a --segment option: without it the same address is named in every bank that covers it and the assembler rejects the duplicate symbol.
Joypad Test Cartridge (U) — Pass 3 complete: minimal code (23.4%), data-heavy test cartridge. Data region $CF06–$FFFF broken into 20 named sub-blocks; VRAM command stream opcode set decoded via RetAddrUpdate return-address modification trick at $CDC8. See Joypad Test Cartridge (U)/README.md.
Wild Gunman (U) — Pass 1 redone, Pass 2/3 complete: NMI-driven frame loop. Gates its code behind runtime computed-goto tables — see the prg.s header block and its README.md.
Mario Bros (JU) — Pass 1 corrected, Pass 2/3 complete, promoted 2026-10-20: the engine's handler tables sit inline, right after the jsr that reads them, so the static tracer could not follow them. A Mesen Code Data Logger capture showed 1,067 bytes the tracer had left as data were code, taking the split from 72.0% to 78.4%. Pass 2 named every label (zero Label_, zero SubC) and Pass 3 added 25 semantic zero-page aliases and named 35 data tables. Code is gated behind stack-based indirect dispatch at $CD9E and a 20-entry JSR thunk table at $C5A3. Audio routines in $F8xx-$F9xx clearly identifiable from APU register writes. See NROM/Mario Bros (JU)/README.md.

Common Patterns Across All Projects

Memory Map

Every project uses a single 16 KB PRG bank mapped at CPU $C000–$FFFF, with 8 KB CHR. All builds are NROM (no bank switching).

Interrupt Structure

All projects follow the same NES interrupt pattern:

NMI fires once per frame and is the real-time heartbeat — handles OAM DMA, PPU updates, controller reading, and audio.
RESET performs cold-start hardware init, RAM clearing, and enters the main loop.
IRQ is almost always unused (either rti or a self-loop).

Two exceptions worth noting from branches of this family:

Excitebike uses a state-dispatch table at $C000 rather than a conventional inline main loop, and its IRQ vector points into a data region (unused).
Donkey Kong Jr. is the extreme case: its reset path idles forever in a PRNG-advance loop, and the entire frame state machine (title, attract, gameplay, sound) executes inside the NMI handler itself. Its reset entry is also at $C66E rather than $C000.

Build Toolchain

All projects use the same toolchain:

ca65 (6502 assembler)
ld65 (linker with .cfg memory map)
All rebuilds are verified byte-identical to the original prg.bin / ROM PRG bank.

Disassembly Style

All sources are "Pass-1" style disassemblies:

Every instruction annotated with PRG offset, CPU address, and emitted bytes
Inline .byte/.word/.res data blocks interleaved with code
Address-based labels where semantics are not yet resolved: Label_Cxxxx (unrenamed internal targets), SubC<addr> / Sub_Cxxxx (unnamed entry points), <Routine>_Block[_n] (internal blocks under a named parent routine)
Zero-page symbol files (locals.inc) and hardware symbol files (symbols.inc)

Each project is a flat folder under its mapper directory — e.g. NROM/Balloon Fight (JU)/ — containing:

prg.s — disassembly source; header.s, chr.s and the raw header.bin / chr.bin / prg.bin splits (where present)
symbols.inc, locals.inc — hardware constants and application symbols
linker.cfg, Makefile — memory map and build script
rom.nes — space-free copy/symlink of the original ROM used by the compare
README.md — detailed per-project power-on execution flow analysis

To rebuild any one project:

cd /home/tmerritt/Projects/disasm/NROM/<Project>
make

To build and verify every project at once (all mapper directories):

cd /home/tmerritt/Projects/disasm
make          # all projects, all mappers
make clean    # clean them all
make MMC3     # one mapper tier only
make wip      # the pre-promotion tier under _wip/

The root Makefile covers the promoted tier only — make, make clean and make <MAPPER> never touch _wip/. The pre-promotion tier under _wip/ is built explicitly with make wip (and cleaned with make wipclean):

for d in _wip/*/*/; do make -C "$d"; done   # equivalent manual loop

See WIP.md for the _wip/ tier's layout, its quirks and its open work.

Pass 1 methodology note (2026-10-16)

The original Pass 1 disassembler had two limitations that silently understated code coverage. Both are worth knowing before trusting a coverage percentage:

Documented opcodes only. Its table held the 151 documented 6502 opcodes. These ROMs also use the 54 undocumented opcodes and the 26 unofficial NOPs as 2/3-byte padding; a tracer that halts on them strands the real code behind.
No runtime dispatch. It followed only vectors and direct jsr/jmp/branch targets. Games here dispatch through computed jumps — jmp ($0014), the pla-based inline-table gotos in Wild Gunman (Label_C341), and task tables like Donkey Kong Jr.'s DeferredTaskHandlerTable at $BFFE.

Effect measured per project (old tracer → complete-opcode dispatch-aware tracer):

Project	Old	Complete	Action taken
NES PowerPad Test Card (U)	546 instr	559	Pass 1 already sound
Joypad Test Cartridge (U)	282 instr	1,773	Pass 1 redone (23.4% code); Pass 2 complete; Pass 3 complete
Wild Gunman (U)	1,600 instr	4,083	Pass 1 redone (49.3% code)
Balloon Fight (JU)	5,216 instr	5,277	hand-done file was already better
Donkey Kong Jr. (JU)	6,135 instr	6,135	file already complete

Joypad Test Cartridge (U) was the last project carrying the old, truncated Pass 1, and has now been redone. Its recorded "3.5% code" was really 23.4%: the tracer stopped at $C09E on DCP $3C20 ($CF), an undocumented opcode used as ordinary code, and 3,256 bytes of real code were filed as .byte data. Redoing it also invalidated its Pass 3, which had described $C09E–$C173 and $C17F–$CCF6 as data — both are code. Pass 3 is now the outstanding work.

The fix generalises: nesdis.py --undocumented decodes all 105 undocumented NMOS opcodes. It is default off so that projects whose prg.s is already regen-stable keep reproducing byte-for-byte under make regen.

_tools/verify_pass1.py checks the top-level projects — it selects the project folders under each mapper directory (NROM/, AOROM/, CNROM/, MMC1/, MMC3/, MMC5/, UNROM/) that carry a Makefile and a prg.bin/rom.nes, so _wip/ projects are not covered (they are checked by plain make, now at the whole-ROM level). Current run, 2026-10-20: all 35 NROM/ projects build, all canonical, and no truncated or unfaithful Pass 1. The last two carryovers are gone — Joypad Test Cartridge, the last project holding an old truncated Pass 1, was redone, and Excitebike, the last source with uncommented instructions, was commented.

The comment-spelling report used to claim that no project follows the canonical ; CPU:$xxxx PRG:xxxx AA BB convention. That was a bug in the checker, not a fact about the sources: the canonical pattern ends with $ but was compiled without re.MULTILINE, so it could only ever match once — at end of file — and every project fell through to whichever laxer spelling matched most lines. Fixed with re.M, the true split was 8 canonical / 3 pipe / 2 short / rom / bytes / colon / slash; the 2026-10-19 standardization (_tools/audit_comment_tool.py over 9 projects, plus hand fixes to CIRCUS and Excitebike) closed it out, so the checker now reports all canonical.

Inside _wip/, none of the 851 projects have instructions to comment at all — they are all Pass 0 skeletons. (Golf (JU) and World Class Track Meet (U) used to be the two exceptions, but both were promoted on 2026-10-21 and their comments are canonical.) (Xevious (U), which used to be the second project in the tier with instructions, was promoted to NROM/ on 2026-10-20.)

The old claim that "Excitebike and Pac-Man carry no byte comments at all" is stale on both counts. Pac-Man (USA) (Namco) is complete (4,695/4,695 instructions commented), and Excitebike's 1,013-line gap was closed on 2026-10-19 — all 5,376 instruction lines now carry a canonical comment.

The earlier-reported re-trace crash on MUSCLE (U) / Donkey Kong Jr. (JU) (ValueError: invalid literal for int() with base 16: ':$0010') was a false alarm: nesdis.operand_value() already strips the emitter's a: prefix via token.removeprefix("a:").lstrip("$"), so re-tracing all promoted projects is clean.

Resolved — audit comments for Excitebike and Pac-Man (2026-10-19)

Both were hand-written sources with semantic labels but no byte-identity audit trail. Both now carry canonical ; CPU:$xxxx PRG:xxxx AA BB comments on every instruction, and verify_pass1.py reports all-canonical across the top level, so this section is closed.

The ca65 -l listing route described here was abandoned, for the reason recorded in AGENTS.md: the listing carries no source line numbers, so entries cannot be keyed back to source lines. The comment tooling went through the tracer instead (_tools/audit_comment_tool.py, tracer as ground truth). The invariant still holds and is the check to keep: after inserting comments, make must still print Byte-identical ROM verified., and each comment's byte list must match prg.bin at the stated offset — a wrong offset that still assembles is the failure mode.

Summary

Thirty-nine projects sit under NROM/, and all 39 rebuild byte-identical to their original ROMs (rows 1-27 below plus row 29 Hogan's Alley (JU), row 30 Mario Bros (JU), row 31 Pac-Man (Tengen) (U), row 32 Pac-Man (U), row 33 Pyramid (U) (Sachen), rows 34 and 35 Raid on Bungeling Bay (U) and Raid on Bungeling Bay (U) [a2] — all promoted 2026-10-20 — and rows 36 and 37 (Urban Champion and Xevious (U)) which kept their tail numbers when they were promoted; row 7 Excitebike (JU) was fixed on 2026-10-20 — the byte-596 mismatch was two $0A/$11 PPU-mask-shadow operands, see NROM/Excitebike (JU)/README.md).

The pre-promotion tier holds 851 projects under _wip/, and as of 2026-10-21 all 851 verify byte-identical for the whole ROM as well (make wip builds and verifies the whole tier: 851 of 851 passed, 0 failures). None of the 851 carry a real disassembly — they are all Pass 0 skeletons; Golf (JU) (row 28) and World Class Track Meet (U) (row 41) were promoted from this tier on 2026-10-21. The whole tier — its layout, its quirks and its open work — is documented in WIP.md. Folder locations changed on 2026-10-20 (mapper directories, flat project folders), but each row's build-status claim in this table is the state at its own promotion; verify against the tree with make if in doubt.

#	Project	Build Status	Pass 3
1	Balloon Fight (JU)	BYTE-IDENTICAL	complete; symbols applied 2026-10-19 (16 `$13` operands left numeric)
2	Baseball (UE)	BYTE-IDENTICAL	complete; symbols applied 2026-10-19 (121 operands)
3	Bomberman (U)	BYTE-IDENTICAL	complete
4	Burger Time (U)	BYTE-IDENTICAL	complete
5	Clu Clu Land (JU)	BYTE-IDENTICAL	complete
6	Defender 2 (U)	BYTE-IDENTICAL	complete
7	Excitebike (JU)	BYTE-IDENTICAL	complete (Pass 2/3 complete); byte-596 `$0A`/`$11` mask-shadow fix + audit-trail re-anchor + 58 `jsr/jmp` operands symbolized 2026-10-20
8	Tennis (JU)	BYTE-IDENTICAL	complete; symbols applied 2026-10-19 (18 operands)
9	Pac-Man (USA) (Namco)	BYTE-IDENTICAL	complete; symbols applied 2026-10-19 (524 operands; 727 multi-alias residues)
10	Donkey Kong 3 (JUE)	BYTE-IDENTICAL	complete
11	Donkey Kong Jr. (JU)	BYTE-IDENTICAL	complete (Pass 1 verified)
12	CIRCUS	BYTE-IDENTICAL	complete; symbols applied 2026-10-19 (118 operands; 23 multi-alias residues); 258 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets
13	Wild Gunman (U)	BYTE-IDENTICAL	complete (Pass 1 redone); symbols applied 2026-10-19 (76 operands)
14	Joypad Test Cartridge (U)	BYTE-IDENTICAL	Pass 3 complete; symbols applied 2026-10-19 (47 operands)
15	NES PowerPad Test Card (U)	BYTE-IDENTICAL	complete; symbols applied 2026-10-19 (89 operands)
16	MUSCLE (U)	BYTE-IDENTICAL	complete; symbols applied 2026-10-19 (220 operands)
17	Lunar Pool (U)	BYTE-IDENTICAL	complete (tables named); symbols applied 2026-10-19 (45 operands)
18	Donkey Kong (JU)	BYTE-IDENTICAL	complete (Pass 2/3, promoted 2026-10-19); symbols applied 2026-10-19 (75 operands)
19	Donkey Kong Jr. Math (U)	BYTE-IDENTICAL	complete (Pass 3 complete); promoted into `NROM/` 2026-10-20 after fixing the mislabeled `SubCF218` call sites; 295 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets
20	Duck Hunt (JUE)	BYTE-IDENTICAL	complete (Pass 3 complete)
21	Ice Climber (JE)	BYTE-IDENTICAL	complete (Pass 3 complete)
22	Ice Climber (U)	BYTE-IDENTICAL	complete (Pass 3 complete)
23	Lode Runner (U)	BYTE-IDENTICAL	complete (Pass 2/3 complete)
24	Pinball (JU)	BYTE-IDENTICAL	complete (Pass 2/3 complete; data tables interpreted)
25	Millipede (U)	BYTE-IDENTICAL	complete (Pass 2/3 complete, 74.6% code; 225 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets)
26	Popeye (JU) (PRG 0)	BYTE-IDENTICAL	complete (Pass 2/3 complete, 72.3% code; data tables interpreted)
27	Popeye (JU) (PRG 1)	BYTE-IDENTICAL	complete (Pass 2/3 complete, 72.3% code; data tables interpreted); promoted 2026-10-20
28	Golf (JU)	BYTE-IDENTICAL	complete (Pass 1+2+3 complete; promoted from `_wip` 2026-10-21; 4,217 instructions / 13,541 lines; 0 residue)
31	Pac-Man (Tengen) (U)	BYTE-IDENTICAL	partial (Pass 2 complete, Pass 3 complete — 30 zero-page aliases, 28 named data tables, 0 residue, 20.0% code); promoted 2026-10-20
32	Pac-Man (U)	BYTE-IDENTICAL	partial (Pass 2 complete, Pass 3 complete — 119 operands, 0 residue); promoted 2026-10-20
34	Raid on Bungeling Bay (U)	BYTE-IDENTICAL	partial (Pass 2/3 complete, 64.6% code); promoted 2026-10-20; 223 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets
33	Pyramid (U) (Sachen)	BYTE-IDENTICAL	partial (Pass 2 complete, Pass 3 complete — 24 zero-page aliases, 0 residue, 39.6% code; 31 data blocks interpreted, 37 labels, 4 blocks unreferenced); promoted 2026-10-20
35	Raid on Bungeling Bay (U) [a2]	BYTE-IDENTICAL	partial (Pass 2 complete, Pass 3 complete — 15 zero-page aliases, 0 residue, 64.3% code); promoted 2026-10-20; 220 `SubC<addr>` entry points named 2026-10-21, zero address-derived `jsr`/`jmp` targets
30	Mario Bros (JU)	BYTE-IDENTICAL	partial (Pass 2 complete, Pass 3 complete — 25 zero-page aliases, 35 named data tables, 0 residue, 78.4% code; data tables interpreted); promoted 2026-10-20
29	Hogan's Alley (JU)	BYTE-IDENTICAL	partial (Pass 2 complete, Pass 3 complete — 60 semantic zero-page aliases, 34 named data tables, 0 residue, 49.1% code); promoted 2026-10-20
36	Urban Champion (JU)	BYTE-IDENTICAL	complete; symbols applied 2026-10-19 (70 operands)
37	Xevious (U)	BYTE-IDENTICAL	complete (Pass 3 complete, 38.0% code; 143 semantic entry points, 32 named data tables, ~20 semantic ZP aliases; split corrected from Mesen CDL 2026-10-21)
38	Zanac (U)	BYTE-IDENTICAL	complete (Pass 3 complete, 34.5% code; 133 semantic entry points, 26 named data tables, 14 semantic ZP aliases)
39	Volleyball (U)	BYTE-IDENTICAL	complete (Pass 3 complete, 73.0% code; 1,989 semantic labels, 37 named data blocks, 0 residue; promoted 2026-10-21)
40	Mermaids of Atlantis (U)	BYTE-IDENTICAL	mapper 8; Pass 3 complete (12.3% code, 494 named routines, 13 semantic zero-page aliases; 8 banked segments; rebuilt 2026-10-21)
41	World Class Track Meet (U)	BYTE-IDENTICAL	complete (Pass 1+2+3 complete; promoted from `_wip` 2026-10-21; 8,400 instructions / 18,028 code bytes, 55.0% code; 24 semantic ZP aliases, 78 neutral ZpXX with reasons; 0 residue)
42	Slalom (U)	USA	32 KB
43	Kung Fu (U)	USA	32 KB
44	Othello (U)	USA	32 KB
45	Elevator Action (U)	USA	32 KB
46	1942 (JU)	Japan	32 KB
47	Tag Team Wrestling (U)	USA	32 KB
48	Galaga (U)	USA	32 KB
49	Kung Fu (U) (a1)	USA	32 KB
50	Stack-Up (JU)	Japan	32 KB
51	Magmax (U)	USA	32 KB
52	Ms Pac-Man (Namco) (U)	USA	32 KB
53	Soccer (JU)	Japan	32 KB
54	Sqoon (U)	USA	32 KB
55	Port Test Cartridge (U)	USA	32 KB
56	10-Yard Fight (U)	USA	32 KB
57	Chubby Cherub (U)	USA	32 KB
58	Dig Dug II (U) [!]	USA	32 KB
59	Gyromite (JUE)	Japan / USA / Europe	32 KB
60	Hydlide (U)	USA	32 KB
61	Ice Hockey (U)	USA	32 KB

Row 28 (Golf (JU), now promoted to NROM/Golf (JU)/) rebuilds byte-identical at the whole-ROM level. Row 41 (World Class Track Meet (U), now promoted to CNROM/World Class Track Meet (U)/) rebuilds byte-identical as well. The other 851 _wip/ projects are Pass 0 skeletons and need Pass 1 from scratch. See WIP.md. Use _tools/verify_pass1.py to re-check any of this at any time; it rebuilds each project and re-traces it, and reports TRUNCATED when a project's committed split claims less code than the tracer can reach.

README.md Unescape Escape

Disassembly Project 1

This is not for distribution.

This is not for you.

Disassembly Project Index — /home/tmerritt/Projects/disasm/

Project Inventory

Per-Project Details

1. Balloon Fight (JU)

2. Baseball (UE)

3. Bomberman (U)

4. Burger Time (U)

5. Clu Clu Land (JU)

6. Defender 2 (U)

7. Excitebike (JU)

8. Tennis (JU)

9. Pac-Man (USA) (Namco)

10. Donkey Kong 3 (JUE)

11. Donkey Kong Jr. (JU)

12. CIRCUS

13. Wild Gunman (U)

14. Joypad Test Cartridge (U)

15. NES PowerPad Test Card (U)

16. MUSCLE (U)

17. Lunar Pool (U)

18. Donkey Kong (JU)

31. Pac-Man (Tengen) (U)

32. Pac-Man (U)

29. Hogan's Alley (JU)

30. Mario Bros (JU)

33. Pyramid (U) (Sachen)

34. Raid on Bungeling Bay (U)

35. Raid on Bungeling Bay (U) [a2]

36. Urban Champion (JU)

37. Xevious (U)

38. Zanac (U)

39. Volleyball (U)

42. Port Test Cartridge (U)

43. 10-Yard Fight (U)

44. Chubby Cherub (U)

45. Dig Dug II (U) [!]

46. Gyromite (JUE)

47. Hydlide (U)

48. Ice Hockey (U)

_wip/ Projects

Common Patterns Across All Projects

Memory Map

Interrupt Structure

Build Toolchain

Disassembly Style

Navigation

Pass 1 methodology note (2026-10-16)

Resolved — audit comments for Excitebike and Pac-Man (2026-10-19)

Summary

README.md

`_wip/` Projects