c64-kb 0.17.0

package/templates/hello/Makefile

@@ -0,0 +1,38 @@
+# hello: the minimal starter. Every target comes from the harness:
+#   make            build build/hello.prg (after the PLAN.md gate)
+#   make run        windowed VICE, joystick in port 2
+#   make shot       headless PAL and NTSC exit screenshots of the autopilot build
+#   make check      grade shots/pal.png and shots/ntsc.png against expect.json
+#   make selftest   prove check fails on the FORCE_FAULT=1 build
+#   make disk       build/hello.d64
+#   make claims     c64-kb's claims-watch over the autopilot build, when available
+#   make clean
+NAME     := hello
+C_MAIN   := src/main.c
+KICK_SRC := src/sprite.asm
+
+# Pinned after the script's 144 play frames and the grade at frame 150. From
+# then on nothing on the screen changes, so the pin can land anywhere in the
+# frame: 7,000,000 and 8,000,000 cycles gave byte-identical PAL pictures,
+# 8,000,000 and 12,000,000 identical NTSC ones (VICE x64sc 3.10, windowless).
+SHOT_CYCLES_PAL  := 8000000
+SHOT_CYCLES_NTSC := 8000000
+
+# What the program may write, for make claims (claims-watch's own grammar).
+# zero_page $02-$55: Oscar64's fixed registers start at BC_REG_WORK_Y ($02)
+# and each function's temporaries run from BC_REG_TMP ($43) up by its own
+# temp count, past BC_REG_TMP_SAVED ($53), so the top depends on the program.
+# Measured, not assumed: `make zp` lists what this build's code touches ($43
+# to $55 here), and claims-watch saw stores to $53-$55. An earlier version
+# claimed $02-$52 and failed make claims with 309 stores to $53-$55. IRQ is
+# declared because the KERNAL's IRQ handler runs and writes its own zero page.
+# The meter's one $DD0D store ($01: mask timer A only) is listed under
+# cia2_timer_b and cia2_tod too, because claims-watch maps any $DD0D store
+# to every CIA2 source; so all three are declared as harness.
+CLAIMS_ARGS := --claim 'sprite_0, cia1_port_a, zero_page $$02-$$55' --kernal IRQ --range 'screen=$$0400-$$07FF,colour=$$D800-$$DBFF,spritedata=$$0340-$$037F,result=$$02FF' --harness 'cia2_timer_a, cia2_timer_b, cia2_tod'
+
+# The harness sits beside the starter in c64-kb (../_harness) or is vendored
+# into ./harness when the starter is copied out on its own.
+HARNESS ?= $(firstword $(wildcard harness) ../_harness)
+$(if $(wildcard $(HARNESS)/harness.mk),,$(error No harness at '$(HARNESS)'. Copy c64-kb's templates/_harness to ./harness, or make the project with npm run new-project in c64-kb))
+include $(HARNESS)/harness.mk

package/templates/hello/PLAN.md

@@ -0,0 +1,200 @@
+# Plan: hello
+
+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
+sprite registers are written by a KickAssembler routine that C calls, and the
+frame's work is timed by the harness meter. 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 | 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 194 cycles, typical (the median) 172, 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-$0880` Oscar64 startup; `$0900-$0FFF` the KickAssembler blob
+  (`src/sprite.asm`, 31 bytes now); `$1000` up, Oscar64's code, data and stack.
+- `$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
+
+- The KickAssembler routine takes its arguments in its own bytes
+  (`ASM_SPR_X`, `ASM_SPR_Y`), not Oscar64's zero page, which the compiler owns.
+- `SEI` at start: no KERNAL interrupt lands inside the meter's bracket.

package/templates/hello/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/src/main.c

@@ -0,0 +1,161 @@
+// hello: the minimal starter. One sprite moved by joystick port 2 and placed
+// by a KickAssembler routine called from C, with the frame meter around the
+// frame's work. AUTOPILOT=1 replaces the port with a script and grades the
+// end position; FORCE_FAULT=1 starts the sprite one pixel off, so both the
+// program's own grade and the screenshot checks must fail.
+#include <c64/vic.h>
+#include <c64/cia.h>
+#include "asm.h"            // generated from src/sprite.asm by the harness
+#include "frame_meter.h"    // templates/_harness/meter
+
+#ifndef AUTOPILOT
+#define AUTOPILOT 0
+#endif
+#ifndef FORCE_FAULT
+#define FORCE_FAULT 0
+#endif
+
+// ---- the KickAssembler blob at its own address ------------------------------
+// ASM_ORG comes from the blob; main moves up to $1000 to leave it room. A blob
+// that outgrows $1000 fails the link with "Could not place object"; one that
+// starts below $0880, over Oscar64's startup code, stops at the #error that
+// asm.h carries.
+#pragma section( asmcode, 0 )
+#pragma region( asmreg, ASM_ORG, 0x1000, , , { asmcode } )
+#pragma region( main, 0x1000, 0xa000, , , { code, data, bss, heap, stack } )
+#pragma data( asmcode )
+__export const char asm_blob[] = {
+#embed "asm.bin"
+};
+#pragma data( data )
+
+#define SPR_X   (*(volatile unsigned *)ASM_SPR_X)   // parameters live in the blob
+#define SPR_Y   (*(volatile char *)ASM_SPR_Y)
+
+#define SCREEN  ((char *)0x0400)
+#define COLOUR  ((char *)0xd800)
+#define SPRITE_BLOCK 13                             // $0340, the tape buffer
+#define RESULT  (*(volatile char *)0x02ff)          // $01 pass, $02 fail, $00 not reached
+
+#define JOY_UP    0x01
+#define JOY_DOWN  0x02
+#define JOY_LEFT  0x04
+#define JOY_RIGHT 0x08
+#define JOY_FIRE  0x10
+
+#define START_X (100 + FORCE_FAULT)                 // the fault build ends 1 pixel off
+#define START_Y 100
+#define PLAY_FRAMES 144                             // the script's length; the meter records these
+#define VERDICT_FRAME 150                           // after the script
+
+#if AUTOPILOT
+// { frames, port byte }, active low as $DC00 reads it: right 64, down 40,
+// fire 16 (one press: yellow to cyan), up and right 24. Every frame plays.
+static const char script[4][2] = {
+    { 64, 0xf7 }, { 40, 0xfd }, { 16, 0xef }, { 24, 0xf6 }
+};
+static char ap_index, ap_used;
+// End state by arithmetic on the script: x 100 + 64 + 24, y 100 + 40 - 24.
+#define EXPECT_X 188
+#define EXPECT_Y 116
+#define EXPECT_COLOUR VCOL_CYAN
+
+static char port_read(void)
+{
+    char out = 0xff;
+    if (ap_index < 4) {
+        out = script[ap_index][1];
+        if (++ap_used == script[ap_index][0]) { ap_used = 0; ap_index++; }
+    }
+    return out;
+}
+#else
+static char port_read(void)
+{
+    return cia1.pra;                                // control port 2, active low
+}
+#endif
+
+static void put_text(char row, char col, const char *s, char colour)
+{
+    char *p = SCREEN + 40 * row + col;
+    char *q = COLOUR + 40 * row + col;
+    while (*s) {
+        char c = *s++;
+        *p++ = (c >= 'a' && c <= 'z') ? c - 'a' + 1 : c;
+        *q++ = colour;
+    }
+}
+
+// frame_sync_loop: line 250 is below the last badline ($F7) on PAL and NTSC
+// and occurs once a frame, so the 8-bit compare needs no ninth bit.
+static void wait_frame(void)
+{
+    while (vic.raster == 250) ;
+    while (vic.raster != 250) ;
+}
+
+int main(void)
+{
+    __asm { sei }                                   // no KERNAL IRQ inside the meter's bracket
+    cia1.pra = 0xff;                                // no keyboard column selected
+
+    for (unsigned i = 0; i < 1000; i++) {
+        SCREEN[i] = 0x20;
+        COLOUR[i] = VCOL_WHITE;
+    }
+    vic.color_border = VCOL_BLACK;
+    vic.color_back = VCOL_BLACK;
+    put_text(1, 1, "hello harness", VCOL_WHITE);
+
+    char *img = (char *)(SPRITE_BLOCK * 64);
+    for (char i = 0; i < 63; i++)
+        img[i] = 0xff;                              // a solid 24 x 21 block
+    SCREEN[0x3f8] = SPRITE_BLOCK;
+    vic.spr_color[0] = VCOL_YELLOW;
+    vic.spr_enable = 0x01;
+
+    unsigned x = START_X;
+    char y = START_Y, colour = VCOL_YELLOW, prev = 0xff;
+    unsigned frame = 0;
+
+    meter_init(0x0400, 24, 20, VCOL_WHITE, PLAY_FRAMES);
+
+    for (;;) {
+        wait_frame();
+        METER_START;
+
+        char joy = port_read();
+        if (!(joy & JOY_LEFT)  && x > 24)  x--;
+        if (!(joy & JOY_RIGHT) && x < 320) x++;
+        if (!(joy & JOY_UP)    && y > 50)  y--;
+        if (!(joy & JOY_DOWN)  && y < 229) y++;
+        if (!(joy & JOY_FIRE) && (prev & JOY_FIRE))   // a new press
+            colour = colour == VCOL_YELLOW ? VCOL_CYAN : VCOL_YELLOW;
+        prev = joy;
+
+        SPR_X = x;
+        SPR_Y = y;
+        __asm { jsr ASM_PUT_SPRITE }                // the KickAssembler routine
+        vic.spr_color[0] = colour;
+
+        METER_STOP;                                 // the frame's own work ends here
+
+#if AUTOPILOT
+        // Grading is the harness's bookkeeping, not the program's work: it
+        // runs after METER_STOP, so it is not in the worst frame.
+        if (frame == VERDICT_FRAME) {
+            char ok = vic.spr_pos[0].x == (char)EXPECT_X
+                   && (*(volatile char *)0xd010 & 1) == (EXPECT_X >> 8)
+                   && vic.spr_pos[0].y == EXPECT_Y
+                   && (vic.spr_color[0] & 15) == EXPECT_COLOUR;
+            RESULT = ok ? 0x01 : 0x02;
+            vic.color_border = ok ? VCOL_GREEN : VCOL_RED;
+            put_text(22, 1, ok ? "result 01 pass" : "result 02 fail", VCOL_WHITE);
+        }
+#endif
+        meter_print();
+        frame++;
+    }
+    return 0;
+}

package/templates/hello/src/sprite.asm

@@ -0,0 +1,27 @@
+// sprite.asm: the KickAssembler half of hello. The harness assembles it to
+// build/asm.bin (raw bytes from $0900) and build/asm.h, which gives C
+// ASM_ORG, ASM_END and ASM_<LABEL> for every top-level label below.
+//
+// Calling convention (this file's own, not Oscar64's): C writes the
+// parameters into this blob's own bytes, then `jsr ASM_PUT_SPRITE` from an
+// __asm block. The routine uses A and X and no zero page, so it cannot
+// collide with Oscar64's registers.
+
+* = $0900 "asm"
+
+// Sprite 0 to (spr_x, spr_y). spr_x is 9-bit: its high byte sets bit 0 of $D010.
+put_sprite:
+        lda spr_x
+        sta $d000
+        lda $d010
+        and #$fe
+        ldx spr_x+1
+        beq !+
+        ora #$01
+!:      sta $d010
+        lda spr_y
+        sta $d001
+        rts
+
+spr_x:  .word 0
+spr_y:  .byte 0

package/templates/hello-kick/.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/hello-kick/.mcp.json

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

package/templates/hello-kick/CLAUDE.md

@@ -0,0 +1,100 @@
+# 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: hello-kick
+
+hello in KickAssembler alone: `src/main.asm` runs the loop, moves sprite 0
+and uses the meter's macros (`#import "frame_meter.asm"`). Start a pure
+KickAssembler program from it with `npm run new-project -- hello-kick <dir>`
+in c64-kb. `PLAN.md` here is a plan filled from real tool output;
+new-project keeps it as `PLAN-hello-kick-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).

package/templates/hello-kick/Makefile

@@ -0,0 +1,17 @@
+# hello-kick: hello in KickAssembler alone, on the same harness targets as
+# hello (make, run, shot, check, selftest, disk, claims, clean).
+NAME     := hello-kick
+KICK_SRC := src/main.asm
+
+# Pinned as in hello: 7,000,000 and 8,000,000 cycles gave identical PAL
+# pictures, 8,000,000 and 12,000,000 identical NTSC ones.
+SHOT_CYCLES_PAL  := 8000000
+SHOT_CYCLES_NTSC := 8000000
+
+# What the program may write, for make claims (claims-watch's own grammar).
+# See hello's Makefile for why cia2_timer_b and cia2_tod are listed as harness.
+CLAIMS_ARGS := --claim 'sprite_0, cia1_port_a' --range 'screen=$$0400-$$07FF,colour=$$D800-$$DBFF,spritedata=$$0340-$$037F,result=$$02FF' --harness 'cia2_timer_a, cia2_timer_b, cia2_tod'
+
+HARNESS ?= $(firstword $(wildcard harness) ../_harness)
+$(if $(wildcard $(HARNESS)/harness.mk),,$(error No harness at '$(HARNESS)'. Copy c64-kb's templates/_harness to ./harness, or make the project with npm run new-project in c64-kb))
+include $(HARNESS)/harness.mk