Audit comment standardization + new tool (2026-10-19)

Standardized all 18 top-level projects to canonical audit comment format:
  ; CPU:$XXXX PRG:XXXX AA BB

Changes per project:
- CIRCUS: fixed 4,427 comments (CPU:XXXX -> CPU:$XXXX)
- Excitebike (JU): fixed 48 double-semicolon comments (; state $XX  ; CPU:...)
- 9 projects received canonical comments via new audit_comment_tool.py:
  Balloon Fight, Baseball, Bomberman, Burger Time, Clu Clu Land,
  Defender 2, Donkey Kong 3, Donkey Kong Jr., Tennis

New tool: _tools/audit_comment_tool.py
- Uses nesdis.py tracer as ground truth for instruction bytes/addresses
- Parses source while tracking PRG offset, emits canonical comments
- Handles .byte/.word/.dword directives, instruction comments (short format)
- Carves PRG from rom.nes when prg.bin missing

Documentation updates:
- TODO.md: Updated current state, item 3 (tool built), repo conventions, tool list
- AGENTS.md: Added audit_comment_tool.py to _tools/, updated audit convention

Verification: verify_pass1.py reports all 18 projects byte-identical with 'canoni' format.

Excitebike (JU)/copilot/locals.inc

@@ -8,11 +8,15 @@ Zp03 = $03
 Zp04 = $04
 Zp05 = $05
 Zp06 = $06
+SerialBitCountLo           = $08
+SerialBitCountHi           = $09
 PpuCtrlShadow = $09
 PpuMaskShadow = $0A
 Zp0C = $0C
 Zp0D = $0D
+SerialBlockLength          = $0D
 Zp0E = $0E
+SerialBlockPtr             = $0E
 Zp10 = $10
 Zp11 = $11
 MathOperandLo = $12
@@ -77,6 +81,7 @@ Player1XSubpixel = $61
 Player1XPosition = $62
 Player1YSubpixel = $63
 Player1YPosition = $64
+Player2MotionControl = $65
 Player2XSubpixel = $66
 Player2XPosition = $67
 Player2YSubpixel = $68
@@ -168,6 +173,7 @@ SoundEffectPhase = $F4
 Pulse2EffectTimer = $F5
 PitchAdjustment = $F6
 AudioSequencePtrLo = $F7
+AudioSequencePtrHi = $F8
 AudioSequenceIndex = $F9
 AudioSequenceOffset = $FA
 AudioStreamPosition = $FB
@@ -176,6 +182,85 @@ AudioRequestFlags1 = $FD
 AudioRequestFlags2 = $FE
 AudioRequestFlags3 = $FF
 
-; Additional traced fields
-Player2MotionControl = $65
-AudioSequencePtrHi = $F8
+
+
+
+
+MENU_HORIZONTAL_COUNT=$05
+MENU_VERTICAL_COUNT=$06
+MENU_ACTION_NONE=$00
+MENU_ACTION_ACCEPTED=$04
+NMI_SYNC_PENDING=$FF
+NMI_SYNC_COMPLETE=$01
+RESET_MAGIC_1=$A5
+RESET_MAGIC_2=$5A
+PPUCTRL_NMI_ENABLE=$80
+
+WorkingBuffer = $05E0
+PERSISTENT_BUFFER_SIZE = $0100
+
+StateTargetCA85 = $CA85
+
+; Serial I/O helpers using JOY1 (verified structure; peripheral identity unknown)
+WriteSerialTiming    = $C62D
+WaitSerialPulse      = $C639
+TransmitPulseShort   = $C64E
+TransmitPulseLong    = $C653
+TransmitByte         = $C66E
+IncrementSerialCount = $C68A
+ReceiveSerialBit     = $C691
+ReceiveByte          = $C6A5
+
+; Block protocol helpers
+TransmitRuntimeData        = $C6C8
+TransmitDataBlock          = $C6D1
+SetupTransmitRamBlock      = $C716
+SetupTransmitWorkingBuffer = $C726
+SetTransmitPreambleCounts  = $C734
+ReceiveRuntimeData         = $C739
+ReceiveDataBlock           = $C792
+
+; App Specific Variables
+TMP00 = $00
+TMP01 = $01
+
+
+; App Specific Magic Values
+RIDER_MOTION_DISABLED = $01
+RIDER_MOTION_ACTIVE = $02
+RIDER_MOTION_TRANSITION = $03
+RIDER_MOTION_COMPLETE = $04
+
+; Variables
+PpuControlShadow = $10
+Controller1Held = $14
+Controller1Pressed = $15
+Controller2Held = $16
+Controller2Pressed = $17
+ControllerState = Controller1Held
+NmiDispatchMode = $40
+NmiState = $41
+MenuSelectionIndex = $42
+NmiSequenceStep = $44
+NmiSyncState = $48
+InputActionLatch = $49
+OamBuffer = $0200
+PersistentRecord0 = $0580
+PersistentRecord1 = $05A3
+ResetMagic1 = $05CE
+ResetMagic2 = $05CF
+PersistentBuffer = $06E0
+RiderMotionState = $A4
+
+PAD_MENU_INPUT=PAD_SELECT|PAD_START|PAD_VERTICAL
+PAD_HORIZONTAL=PAD_LEFT|PAD_RIGHT
+PAD_VERTICAL=PAD_UP|PAD_DOWN
+PAD_RIGHT=$01
+PAD_LEFT=$02
+PAD_DOWN=$04
+PAD_UP=$08
+PAD_START=$10
+PAD_SELECT=$20
+PAD_B=$40
+PAD_A=$80
+PAD_DPAD=PAD_HORIZONTAL|PAD_VERTICAL

Excitebike (JU)/copilot/symbols.inc

@@ -1,85 +1,62 @@
-; PPU registers 
-PPUCTRL = $2000
-PPUMASK = $2001
-PPUSTATUS = $2002
-OAMADDR = $2003
-OAMDATA = $2004
-PPUSCROLL = $2005
-PPUADDR = $2006
-PPUDATA = $2007
-OAMDMA = $4014
-JOY1 = $4016
+;------------------------------------------------------------
+; NES hardware registers
+;------------------------------------------------------------
 
-; Variables
-PpuControlShadow = $10
-PpuMaskShadow = $11
-Controller1Held = $14
-Controller1Pressed = $15
-Controller2Held = $16
-Controller2Pressed = $17
-ControllerState = Controller1Held
-NmiDispatchMode = $40
-NmiState = $41
-MenuSelectionIndex = $42
-NmiSequenceStep = $44
-NmiSyncState = $48
-InputActionLatch = $49
-OamBuffer = $0200
-PersistentRecord0 = $0580
-PersistentRecord1 = $05A3
-ResetMagic1 = $05CE
-ResetMagic2 = $05CF
-PersistentBuffer = $06E0
-PAD_RIGHT=$01
-PAD_LEFT=$02
-PAD_DOWN=$04
-PAD_UP=$08
-PAD_START=$10
-PAD_SELECT=$20
-PAD_B=$40
-PAD_A=$80
-PAD_HORIZONTAL=PAD_LEFT|PAD_RIGHT
-PAD_VERTICAL=PAD_UP|PAD_DOWN
-PAD_DPAD=PAD_HORIZONTAL|PAD_VERTICAL
-PAD_MENU_INPUT=PAD_SELECT|PAD_START|PAD_VERTICAL
-MENU_HORIZONTAL_COUNT=$05
-MENU_VERTICAL_COUNT=$06
-MENU_ACTION_NONE=$00
-MENU_ACTION_ACCEPTED=$04
-NMI_SYNC_PENDING=$FF
-NMI_SYNC_COMPLETE=$01
-RESET_MAGIC_1=$A5
-RESET_MAGIC_2=$5A
-PPUCTRL_NMI_ENABLE=$80
+PPUCTRL        = $2000
+PPUMASK        = $2001
+PPUSTATUS      = $2002
+OAMADDR        = $2003
+OAMDATA        = $2004
+PPUSCROLL      = $2005
+PPUADDR        = $2006
+PPUDATA        = $2007
 
-WorkingBuffer = $05E0
-PERSISTENT_BUFFER_SIZE = $0100
+SQ1_VOL        = $4000
+SQ1_SWEEP      = $4001
+SQ1_LO         = $4002
+SQ1_HI         = $4003
 
-StateTargetCA85 = $CA85
+SQ2_VOL        = $4004
+SQ2_SWEEP      = $4005
+SQ2_LO         = $4006
+SQ2_HI         = $4007
 
-; Serial I/O helpers using $4016 (verified structure; peripheral identity unknown)
-WriteSerialTiming    = $C62D
-WaitSerialPulse      = $C639
-TransmitPulseShort   = $C64E
-TransmitPulseLong    = $C653
-TransmitByte         = $C66E
-IncrementSerialCount = $C68A
-ReceiveSerialBit     = $C691
-ReceiveByte          = $C6A5
+TRI_LINEAR     = $4008
+TRI_LO         = $400A
+TRI_HI         = $400B
 
-; Block protocol helpers
-TransmitRuntimeData        = $C6C8
-TransmitDataBlock          = $C6D1
-SetupTransmitRamBlock      = $C716
-SetupTransmitWorkingBuffer = $C726
-SetTransmitPreambleCounts  = $C734
-ReceiveRuntimeData         = $C739
-ReceiveDataBlock           = $C792
-SerialBlockLength          = $0D
-SerialBlockPtr             = $0E
-SerialBitCountLo           = $08
-SerialBitCountHi           = $09
+NOISE_VOL      = $400C
+NOISE_LO       = $400E
+NOISE_HI       = $400F
 
-; App Specific Variables
-TMP00 = $00
-TMP01 = $01
+OAMDMA         = $4014
+APUSTATUS      = $4015
+JOY1           = $4016
+JOY2           = $4017
+
+
+APUPC1BASE = $4000
+APUPC1SWEEP = $4001
+APUPC1TLOW = $4002
+APUPC1THIGH = $4003
+
+APUPC2BASE = $4004
+APUPC2SWEEP = $4005
+APUPC2LOW = $4006
+APUPC2HIGH = $4007
+
+APUTRIBASE = $4008
+APUTRILOW = $400A
+APUTRIHIGH = $400B
+
+APUNOISEBASE = $400C
+APUNOISELOOP = $400E
+APUNOISELENGTH = $400F
+
+APUDMABASE = $4010
+APUDMALOAD = $4011
+APUDMAADDR = $4012
+APUDMALEN = $4013
+
+APUCTRL = $4015
+APUFRAMECNT = $4017