c64-kb 0.17.0

package/templates/hello-kick/PLAN.md

@@ -0,0 +1,199 @@
+# Plan: hello-kick
+
+hello in KickAssembler alone, to prove the harness's pure-KickAssembler
+path and the KickAssembler frame meter. The minimal starter. It exists to prove the harness end to end, so its plan
+is small. The tool output below was produced on 2026-09-23 by c64-kb 0.13.0
+(KB data 756) and pasted whole.
+
+## Concept
+
+One hardware sprite, moved by joystick port 2, fire toggles its colour. The
+frame's work is timed by the harness meter's KickAssembler macros. PAL and
+NTSC.
+
+## Briefing
+
+No briefing was run for hello: its techniques were chosen to exercise the
+harness, not proposed by a brief. A real starter runs
+`npx tsx src/cli.ts game-briefing "<concept>" --archetype <name>` here.
+
+## Techniques
+
+| Technique | Why | Recipe it starts from | Pitfalls read (`pitfalls-for`) |
+|---|---|---|---|
+| frame_sync_loop | one pass of the loop a frame, synced on raster line 250 | oscar64-frame-sync-loop (ported) | badline_cycle_loss, d012_wrap_around, raster_line_count_difference, vic_colour_register_upper_nibble_reads_set, and the rest of its list |
+| joystick_edge_detect | fire toggles the colour once per press, not once per frame | oscar64-joystick-input, oscar64-headless-verify (the autopilot) | cia1_ddr_cleared_kills_keyboard, colour_ram_index_past_last_cell_hits_cia1, joystick2_scan_phantom_press |
+| raster_profile_bars | the frame meter is its CIA-timed half, on CIA2 timer A | oscar64-raster-profile-bars | badline_cycle_loss, vic_bus_takeover_on_dma, vic_colour_register_upper_nibble_reads_set |
+
+## Compatibility
+
+Command: `npx tsx src/cli.ts check-compatibility frame_sync_loop joystick_edge_detect raster_profile_bars`
+
+```text
+# Compatibility: frame_sync_loop + joystick_edge_detect + raster_profile_bars
+
+**Verdict:** WARNINGS
+
+Unit claims are stated for 1 of 3 techniques; a unit conflict cannot be ruled out for: frame_sync_loop, raster_profile_bars. The zero-page bytes and interrupt vectors a recipe chooses are not checked yet (issue #22, step 8).
+
+## shared_register (soft): frame_sync_loop × raster_profile_bars
+**Shared:** EXTCOL
+Both techniques touch register(s) EXTCOL. This says they write the same registers, not that they fight: keep each one's writes in its own raster region, or have one of them own the register and the other read a shadow copy.
+
+
+## Shared Infrastructure (info)
+- **CLRCHN** (KernalRoutine) shared via recipe(s): oscar64-platformer-scaffold
+- **CHKOUT** (KernalRoutine) shared via recipe(s): oscar64-platformer-scaffold
+- **CHKIN** (KernalRoutine) shared via recipe(s): oscar64-platformer-scaffold
+- **CLOSE** (KernalRoutine) shared via recipe(s): oscar64-platformer-scaffold
+- **OPEN** (KernalRoutine) shared via recipe(s): oscar64-platformer-scaffold
+- **SETNAM** (KernalRoutine) shared via recipe(s): oscar64-platformer-scaffold
+- **SETLFS** (KernalRoutine) shared via recipe(s): oscar64-platformer-scaffold
+- **DC0F** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **DC07** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **DC06** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **SP6COL** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **SP5COL** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **SP4COL** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **SP3COL** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **SP2COL** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **SP1COL** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **SP0COL** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **BGCOL0** (Register) shared via recipe(s): oscar64-platformer-scaffold, oscar64-falling-blocks
+- **EXTCOL** (Register) shared via recipe(s): oscar64-platformer-scaffold, oscar64-falling-blocks
+- **IRQMSK** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **VICIRQ** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **SPENA** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **RASTER** (Register) shared via recipe(s): oscar64-platformer-scaffold, oscar64-falling-blocks
+- **SCROLY** (Register) shared via recipe(s): oscar64-platformer-scaffold, oscar64-falling-blocks
+- **MSIGX** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **M0Y** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **M0X** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **RANDOM** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **SIGVOL** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **SUREL3** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **ATDCY3** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **VCREG3** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **PWHI3** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **PWLO3** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **FREHI3** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **FRELO3** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **SUREL2** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **ATDCY2** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **VCREG2** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **PWHI2** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **PWLO2** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **FREHI2** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **FRELO2** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **SUREL1** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **ATDCY1** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **VCREG1** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **DC03** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **DC02** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **PWHI1** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **PWLO1** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **FREHI1** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **FRELO1** (Register) shared via recipe(s): oscar64-platformer-scaffold
+- **READST** (KernalRoutine) shared via recipe(s): oscar64-platformer-scaffold
+- **DC00** (Register) shared via recipe(s): oscar64-platformer-scaffold, oscar64-falling-blocks
+- **CHRIN** (KernalRoutine) shared via recipe(s): oscar64-platformer-scaffold
+- **CHROUT** (KernalRoutine) shared via recipe(s): oscar64-platformer-scaffold
+- **DC0E** (Register) shared via recipe(s): oscar64-falling-blocks
+- **DC05** (Register) shared via recipe(s): oscar64-falling-blocks
+- **DC04** (Register) shared via recipe(s): oscar64-falling-blocks
+- **raster_discipline**: Multiple raster-discipline techniques present. Verify IRQ stack ordering and timing budget.
+```
+
+What the warnings mean for this program:
+
+- EXTCOL shared by frame_sync_loop and raster_profile_bars: hello uses no
+  border bars; only the verdict writes `$D020`, once.
+- The shared-infrastructure list comes from another recipe
+  (platformer-scaffold) that uses these techniques; hello calls no KERNAL
+  routine after `SEI`.
+
+## Budget
+
+Command: `npx tsx src/cli.ts plan-budget frame_sync_loop joystick_edge_detect raster_profile_bars --region both --sprites 1 --sprite-lines 21`
+
+```text
+# Budget plan: undetermined
+
+Techniques: frame_sync_loop, joystick_edge_detect, raster_profile_bars
+
+## play (PAL, 19656 cycles a frame): undetermined
+
+Range 467 + 1180 fixed cycles; floor 1180; weakest basis measured-vice; IRQ slots 0.
+
+Summed:
+- raster_profile_bars: 467 (measured-vice, on oscar64-raster-profile-bars (worst frame, screen blanked))
+
+To measure:
+- frame_sync_loop: the Cost line has no cycles_per_frame (nor cycles_per_line with lines_active); measure it on oscar64-frame-sync-loop
+- joystick_edge_detect: no **Cost:** line; measure it on oscar64-attract-replay
+
+Notes:
+- Fixed losses 1180 cycles (badlines 25 × 43 = 1075, lines 51-243 every eighth with YSCROLL 3, sprite DMA 105; arithmetic) charged because raster_profile_bars is not stated as measured with the screen on. A stall takes its cycles wherever the code runs, so the charge is exact: no summed figure already holds a stall.
+- Unknown is not zero: frame_sync_loop, joystick_edge_detect have no cycles figure, so the verdict cannot be fits.
+
+## play (NTSC, 17095 cycles a frame): undetermined
+
+Range 467 + 1180 fixed cycles; floor 1180; weakest basis measured-vice; IRQ slots 0.
+
+Summed:
+- raster_profile_bars: 467 (measured-vice, on oscar64-raster-profile-bars (worst frame, screen blanked))
+
+To measure:
+- frame_sync_loop: the Cost line has no cycles_per_frame (nor cycles_per_line with lines_active); measure it on oscar64-frame-sync-loop
+- joystick_edge_detect: no **Cost:** line; measure it on oscar64-attract-replay
+
+Notes:
+- Fixed losses 1180 cycles (badlines 25 × 43 = 1075, lines 51-243 every eighth with YSCROLL 3, sprite DMA 105; arithmetic) charged because raster_profile_bars is not stated as measured with the screen on. A stall takes its cycles wherever the code runs, so the charge is exact: no summed figure already holds a stall.
+- Unknown is not zero: frame_sync_loop, joystick_edge_detect have no cycles figure, so the verdict cannot be fits.
+- Cycles per frame are the pages' figures, most measured on PAL; the same code takes about the same cycles on NTSC, against a 17,095-cycle frame.
+
+## Bytes
+
+No member states a byte figure that can be summed.
+- frame_sync_loop: 985 bytes left out, the whole program, not the technique
+
+## Assumptions
+
+- Region PAL and NTSC: PAL 19656, NTSC 17095 cycles a frame.
+- Screen on: unless every summed figure says it was measured with the screen on, the 25 badlines × 43 cycles outside any band charge are charged.
+- Low end: each member's cycles_per_frame_typical where the page states one (a common frame, or a real run's worst frame), else its worst frame. It is not a floor. Over is judged on the floor: band and per-line charges, which run every frame, plus the badline loss no summed figure can already hold.
+- Each figure is the technique's own Cost line, measured on the recipe it names: another implementation can cost more or less.
+- Claims, zero page and memory are not judged here; c64_check_compatibility judges claims and zero page.
+- Sprites: 1 a line on 21 lines, (3 + 2 × 1) × 21 = 105 cycles of DMA a frame (3 + 2n measured in VICE x64sc for sprites numbered without gaps).
+```
+
+Measured by the meter (`make shot check`, VICE x64sc 3.10, the script's 144
+play frames): worst 178 cycles, typical (the median) 154, the same on PAL and
+NTSC. The bracket starts on raster line 250, below the last badline ($F7),
+and the sprite is on lines 117 to 137, so no badline and no sprite DMA lands
+in it; the plan's 1,180 fixed cycles are real but fall outside the bracket.
+The grading at frame 150 runs after the bracket and is not in either figure.
+
+## Memory and screen
+
+- `$0340-$037E` sprite 0's image (block 13, the tape buffer).
+- `$0801` up: the program, then the meter's code and variables
+  (`FrameMeterCode`, no zero page).
+- `$0400` screen, power-on character set. Row 24, columns 20 to 39: the meter.
+- `$02FF` the verdict byte. CIA2 timer A: the meter.
+
+## Autopilot and checks
+
+Script (frames, port byte): 64 right, 40 down, 16 fire, 24 up and right: 144
+frames, every one playing, then idle. The meter records exactly those 144.
+End state by arithmetic: sprite X 188, Y 116, cyan. Frame 150, after the
+meter's bracket, reads the sprite registers back, stores the verdict at
+`$02FF` and sets the border. FORCE_FAULT starts the sprite at X 101, so it
+ends at 189: the verdict and the sprite checks fail together. `expect.json`
+checks the border, the title and verdict text, the sprite's bounding box and
+that it is solid, the pixel left of it, rows 0 to 23 identical on PAL and
+NTSC, and the meter (144 frames recorded, worst within one frame).
+
+## Decisions and open questions
+
+- `SEI` at start: no KERNAL interrupt lands inside the meter's bracket.

package/templates/hello-kick/expect.json

@@ -0,0 +1,20 @@
+{
+  "checks": [
+    { "name": "own verdict (border)", "type": "verdict" },
+    { "name": "title", "type": "text", "row": 1, "col": 1, "text": "HELLO HARNESS" },
+    { "name": "verdict line", "type": "text", "row": 22, "col": 1, "text": "RESULT 01 PASS" },
+    {
+      "name": "sprite where the script leaves it (X 188, Y 116: lines 117 to 137)",
+      "type": "sprite",
+      "colour": 3,
+      "vic_x": 188,
+      "line": 117,
+      "width": 24,
+      "height": 21
+    },
+    { "name": "sprite solid", "type": "rect", "colour": 3, "vic_x": 188, "line": 117, "width": 24, "height": 21 },
+    { "name": "left of the sprite", "type": "pixel", "vic_x": 187, "line": 117, "colour": 0 },
+    { "name": "display the same on both models", "type": "same", "cells": [0, 0, 23, 39] },
+    { "name": "frame meter, the script's 144 play frames", "type": "meter", "row": 24, "col": 20, "frames": 144 }
+  ]
+}

package/templates/hello-kick/src/main.asm

@@ -0,0 +1,233 @@
+// hello-kick: hello in KickAssembler alone. One sprite moved by joystick
+// port 2, fire toggles its colour, the frame meter around the frame's work.
+// -define AUTOPILOT replaces the port with a script and grades the end
+// position; -define FORCE_FAULT starts the sprite one pixel off, so both the
+// program's own grade and the screenshot checks must fail.
+#import "frame_meter.asm"              // templates/_harness/meter, via -libdir
+
+.const SCREEN   = $0400
+.const COLOUR   = $d800
+.const RESULT   = $02ff                // $01 pass, $02 fail, $00 not reached
+.const SPRITE_BLOCK = 13               // $0340, the tape buffer
+#if FORCE_FAULT
+.const START_X  = 101                  // the fault build ends 1 pixel off
+#else
+.const START_X  = 100
+#endif
+.const START_Y  = 100
+.const PLAY_FRAMES = 144               // the script's length; the meter records these
+.const VERDICT_FRAME = 150             // after the script
+.const EXPECT_X = 188                  // 100 + 64 + 24, by arithmetic on the script
+.const EXPECT_Y = 116                  // 100 + 40 - 24
+.const EXPECT_COLOUR = 3               // cyan: one fire press from yellow
+
+BasicUpstart2(start)
+
+start:
+        sei                            // no KERNAL IRQ inside the meter's bracket
+        lda #$ff
+        sta $dc00                      // no keyboard column selected
+        ldx #0
+!:      lda #$20
+        sta SCREEN,x
+        sta SCREEN+$100,x
+        sta SCREEN+$200,x
+        sta SCREEN+$2e8,x
+        lda #1
+        sta COLOUR,x
+        sta COLOUR+$100,x
+        sta COLOUR+$200,x
+        sta COLOUR+$2e8,x
+        inx
+        bne !-
+        lda #0
+        sta $d020
+        sta $d021
+        ldx #title_end - title - 1
+!:      lda title,x
+        sta SCREEN + 40*1 + 1,x
+        dex
+        bpl !-
+        ldx #62
+        lda #$ff                       // a solid 24 x 21 block
+!:      sta SPRITE_BLOCK*64,x
+        dex
+        bpl !-
+        lda #SPRITE_BLOCK
+        sta SCREEN + $3f8
+        lda #7
+        sta colour
+        sta $d027
+        lda #1
+        sta $d015
+        FrameMeterInit()
+
+loop:
+!:      lda $d012                      // frame_sync_loop on line 250: below the last
+        cmp #250                       // badline ($F7), once a frame, PAL and NTSC
+        beq !-
+!:      lda $d012
+        cmp #250
+        bne !-
+        FrameMeterStart()
+        jsr port_read                  // A = port byte, active low
+        sta joy
+        lda joy
+        and #$04                       // left, down to X 24
+        bne no_left
+        lda xpos+1
+        bne do_left
+        lda xpos
+        cmp #25
+        bcc no_left
+do_left:
+        lda xpos
+        bne !+
+        dec xpos+1
+!:      dec xpos
+no_left:
+        lda joy
+        and #$08                       // right, up to X 320
+        bne no_right
+        lda xpos+1
+        beq do_right
+        lda xpos
+        cmp #<320
+        bcs no_right
+do_right:
+        inc xpos
+        bne no_right
+        inc xpos+1
+no_right:
+        lda joy
+        and #$01                       // up
+        bne !+
+        lda ypos
+        cmp #51
+        bcc !+
+        dec ypos
+!:      lda joy
+        and #$02                       // down
+        bne !+
+        lda ypos
+        cmp #229
+        bcs !+
+        inc ypos
+!:      lda joy                        // fire: a new press toggles the colour
+        and #$10
+        bne !+
+        lda prev
+        and #$10
+        beq !+
+        lda colour
+        eor #7 ^ 3
+        sta colour
+!:      lda joy
+        sta prev
+        lda xpos                       // the sprite registers
+        sta $d000
+        lda $d010
+        and #$fe
+        ldx xpos+1
+        beq !+
+        ora #1
+!:      sta $d010
+        lda ypos
+        sta $d001
+        lda colour
+        sta $d027
+        FrameMeterStop()               // the frame's own work ends here
+#if AUTOPILOT
+        // Grading is the harness's bookkeeping, not the program's work: it
+        // runs after FrameMeterStop, so it is not in the worst frame.
+        lda frame+1
+        bne !+
+        lda frame
+        cmp #VERDICT_FRAME
+        bne !+
+        jsr verdict
+!:
+#endif
+        FrameMeterPrint()
+        inc frame
+        bne !+
+        inc frame+1
+!:      jmp loop
+
+#if AUTOPILOT
+// Reads the sprite registers back and grades them.
+verdict:
+        lda $d000
+        cmp #<EXPECT_X
+        bne fail
+        lda $d010
+        and #1
+        cmp #>EXPECT_X
+        bne fail
+        lda $d001
+        cmp #EXPECT_Y
+        bne fail
+        lda $d027
+        and #$0f                       // the upper nibble of a colour register reads set
+        cmp #EXPECT_COLOUR
+        bne fail
+        lda #1
+        sta RESULT
+        lda #5
+        sta $d020
+        ldx #0
+        jmp say
+fail:   lda #2
+        sta RESULT
+        sta $d020
+        ldx #pass_end - pass
+say:    ldy #0
+!:      lda pass,x
+        sta SCREEN + 40*22 + 1,y
+        inx
+        iny
+        cpy #pass_end - pass
+        bne !-
+        rts
+
+// { frames, port byte }: right 64, down 40, fire 16, up and right 24.
+// Every frame plays.
+port_read:
+        ldx ap_index
+        cpx #4
+        bcs idle
+        inc ap_used
+        lda ap_used
+        cmp script_frames,x
+        bne !+
+        lda #0
+        sta ap_used
+        inc ap_index
+!:      lda script_byte,x              // this frame's byte; X still names its entry
+        rts
+idle:   lda #$ff
+        rts
+script_frames: .byte 64, 40, 16, 24
+script_byte:   .byte $f7, $fd, $ef, $f6
+ap_index: .byte 0
+ap_used:  .byte 0
+pass:   .text "result 01 pass"
+pass_end:
+        .text "result 02 fail"
+#else
+port_read:
+        lda $dc00                      // control port 2, active low
+        rts
+#endif
+
+title:  .text "hello harness"
+title_end:
+xpos:   .word START_X
+ypos:   .byte START_Y
+colour: .byte 7
+joy:    .byte 0
+prev:   .byte $ff
+frame:  .word 0
+
+frame_meter:                           // the meter's macros jsr into this label
+        FrameMeterCode(SCREEN, 24, 20, 1, PLAY_FRAMES)

package/templates/platformer/.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "h=\"$CLAUDE_PROJECT_DIR/harness/hooks/plan-gate.py\"; [ -f \"$h\" ] || h=\"$CLAUDE_PROJECT_DIR/../_harness/hooks/plan-gate.py\"; exec python3 \"$h\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/platformer/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "c64-kb": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["../../dist/cli.js", "serve"],
+      "env": {}
+    }
+  }
+}

package/templates/platformer/CLAUDE.md

@@ -0,0 +1,125 @@
+# Rules for an agent working on this C64 program
+
+This program runs on a stock Commodore 64, PAL and NTSC. It is built on the
+c64-kb harness (`./harness`, vendored from c64-kb's `templates/_harness`).
+c64-kb is the reference: its pages give the registers, timings, techniques,
+pitfalls and recipes this program is built from. A wrong number becomes a torn
+screen or a crash, so every claim here is measured or says it is not.
+
+A new program starts in c64-kb with `npm run new-project -- <starter> <dir>`.
+That copies the starter and the harness, points `.mcp.json` and `local.mk`
+at the c64-kb checkout, proves the copy with `make shot check`, and leaves a
+blank `PLAN.md`.
+
+## This starter: platformer
+
+A side-scrolling platformer that plays: `README.md` has the file map, how a
+frame runs, the measured frame and the three most likely next steps. Rules
+this program depends on:
+
+- The scroll never shifts or redraws the page on display: it prepares a
+  third page five rows a frame (`src/view.c`), and only a flip shows it. A
+  taken coin's cells and the sprite pointers are the only writes to the
+  page on display (and a level restart redraws all three pages at a cut).
+  Keep the camera at 2 pixels a frame or less, or the slices fall behind.
+- It builds on the local Oscar64 and on v1.32.273. Keep `surface_at`
+  `__noinline` and the score written through `put_digits`: both work around
+  v1.32.273 faults (README, "Which Oscar64").
+- `NSLOT` is 5 because six live enemies overran an NTSC frame. After any
+  change to the enemies, run `make stage` (every slot live) as well as
+  `make shot check`.
+- The verdict's per-frame bits (`check_frame` in `src/verdict.h`) catch
+  faults that heal before the end: keep them when you change the rules.
+- `$D016` and `$D018` belong to the two IRQs in `src/engine.asm`. C
+  publishes the next picture's pair once a frame (`view_publish`).
+- `make tearcheck` after any change to the scroll, the camera, the level or
+  the art: `tools/tearcheck.py` renders the level from `src/` and matches
+  shots mid-play. It reads the `LEVEL`, `TILES`, `GLYPHS` and `GLYPH-ART`
+  blocks: keep their markers.
+- The autopilot is a timeline (`src/autopilot.h`); a changed level or
+  physics changes the run. Re-time it with `-dDEBUG_AT=n` builds, which
+  freeze at frame n and print the state on HUD row 21.
+- `-dPROF=n` meters one subsystem (see `src/main.c`).
+
+`PLAN.md` here is this starter's plan, filled from real tool output;
+new-project keeps it as `PLAN-platformer-example.md` and gives the new
+program a blank one.
+
+## Before any code
+
+1. Brief: `npx tsx src/cli.ts game-briefing "<concept>" --archetype <name>`
+   (or `demo-briefing`), in the c64-kb checkout. Read what it proposes.
+2. For each technique you keep: `technique-lookup <name>` and
+   `pitfalls-for <name>`. Start from the recipe it names (`recipe-lookup`).
+3. Fill `PLAN.md`: paste the whole output of `check-compatibility` and of
+   `plan-budget` (same techniques) into their sections, list every technique
+   in its table, and replace every `FILL:` line.
+
+Until `PLAN.md` passes, a hook blocks Edit and Write under `src/`, and every
+make target that builds stops (`make plan-gate` says what is missing). With
+C64KB set, `make` re-runs `check-compatibility` and wants the pasted Verdict.
+The gate cannot see writes made through a shell command, or outputs edited
+into shape by hand: do neither. `make PLAN_GATE=off` overrides it; say why in
+`PLAN.md` if you do.
+
+## The loop
+
+```bash
+make                  # build build/<name>.prg
+make shot check       # autopilot build, headless PAL and NTSC, graded by expect.json
+make selftest         # the FORCE_FAULT build must fail the same checks
+make disk             # build/<name>.d64
+make claims           # every store the program makes, against what it declares
+make run              # windowed VICE, for a human
+```
+
+## Rules
+
+- Build before claiming. Code that has not built is not done.
+- Measure screenshots with `check.py` through `expect.json`, never by eye.
+  Every visible claim gets a check. Add one before you trust a change.
+- PAL and NTSC: both shots pass, or it is not done.
+- Name the rung for every number: measured here (`make shot`, the meter, the
+  VICE monitor), taken from a c64-kb page (say which), arithmetic, or not
+  measured. Never call something verified that was not run.
+- Frame cost comes from the meter: CIA2 timer A, printed as
+  `F<frames> W<worst> T<typical>` at row 24, columns 20 to 39, in AUTOPILOT
+  builds. It records the first `hold` frames: make that the autopilot
+  script's play frames. Typical is the median of those frames, the KB's
+  `cycles_per_frame_typical`. Keep grading, logging and printing outside the
+  bracket; work split between the main loop and IRQs is summed with
+  `METER_PAUSE` / `METER_START`.
+- Do not invent a register, routine or address. Look it up:
+  `lookup-register`, `lookup-kernal`, `memory-map`.
+- Lint every source you change: `npx tsx src/cli.ts lint <file>`.
+- Commit named paths only. Never `git add -A` or `git add .`. `build/`,
+  `shots/` and `local.mk` are never committed.
+
+## Harness facts you will need
+
+- `AUTOPILOT=1` builds read a scripted joystick byte instead of `$DC00` and
+  grade themselves: `$02FF` = `$01` and a green border on pass, `$02` and red
+  on fail. `FORCE_FAULT=1` must turn the verdict red and move something a
+  screenshot check can see.
+- Screenshot geometry (c64-kb `docs/runtime/vice-reference.md`): PAL 384 x 272,
+  row = raster line - 16; NTSC 384 x 247, row = line - 28; x = VIC X + 8. A
+  sprite at Y register y is drawn from line y + 1.
+- `check.py` reads text in the ROM character set unless a check names a
+  `charset` file; the meter's cells need 0-9, F, W and T in the set on screen.
+- A KickAssembler part called from C is a raw blob at its own `* =` address,
+  `$0880` or above; `build/asm.h` gives C its labels as `ASM_<LABEL>`
+  (`ASM_<SCOPE>_<LABEL>` inside a scope). Pass arguments through bytes in the
+  blob, not Oscar64's zero page (`$02` up; the top depends on the program:
+  `make zp` lists what the build's code touches).
+- The meter takes CIA2 timer A. Do not open RS-232 (device 2) while it runs.
+- The KERNAL serial routines end in `CLI` (ROM bytes `58 60` / `58 18` at
+  `$EDAB`, `$EDB5`, `$EDDB`, `$EE82`). After any disk call, `SEI` again if
+  the program runs with the KERNAL IRQ off: otherwise that IRQ lands inside
+  the meter's brackets and rewrites `$DC00`.
+
+## Calling c64-kb
+
+- CLI, from the c64-kb checkout (`C64KB` in `local.mk`):
+  `npx tsx src/cli.ts <command>`; `npx tsx src/cli.ts --help` lists them.
+- MCP: `.mcp.json` starts `node <c64-kb>/dist/cli.js serve` (run
+  `npm run build` in c64-kb first).