c64-kb 0.17.0

package/templates/demo/src/verdict.asm

@@ -0,0 +1,179 @@
+// verdict.asm: AUTOPILOT only. Once the main part has frozen, the main loop
+// reads the demo's real state back and grades it against what the assembler
+// predicts from config.asm. $02FF = $01 and a green border on pass, $02 and
+// red on fail; "RESULT 01 PASS" or "RESULT 02 FAIL" on row 24.
+
+.const EXP_PX    = (FREEZE_UPDATES * CHAIN_SX) & 255   // the frozen phases
+.const EXP_PY    = (FREEZE_UPDATES * CHAIN_SY) & 255
+.const EXP_PB    = (FREEZE_UPDATES * BAR_SPEED) & 255
+.const EXP_SHIFTS = floor(FREEZE_UPDATES / 8)          // XSCROLL 7 - (k mod 8)
+.const EXP_XSCROLL = 7 - mod(FREEZE_UPDATES, 8)
+
+.function SinR(amp, step) { .return round(amp * sin(toRadians(step * 360 / 256))) }
+.function ExpX(n) { .return CHAIN_X0 + n * CHAIN_DX + SinR(CHAIN_AX, (EXP_PX + n * CHAIN_PX) & 255) }
+.function ExpY(n) { .return CHAIN_Y0 + SinR(CHAIN_AY, (EXP_PY + n * CHAIN_PY) & 255) }
+
+.var msb_bits = 0
+.for (var n = 0; n < 8; n++) {
+    .if (ExpX(n) > 255) .eval msb_bits = msb_bits | (1 << n)
+}
+.const exp_msb = msb_bits
+
+// A failed check jumps to vfail; the checks are too long for one branch.
+.macro FailNe() {
+        beq !+
+        jmp vfail
+!:
+}
+.macro FailEq() {
+        bne !+
+        jmp vfail
+!:
+}
+
+verdict:
+        jsr hard_cut                   // no part in the table names hard_cut, so the
+        bcs !+                         // verdict runs it: it must end a part (carry set)
+        jmp vfail
+!:
+        lda part                       // the transition happened: the main part plays,
+        cmp #MAIN_PART                        // the wipe cleared all 40 columns, the
+        FailNe()                     // title's teardown ran
+        lda seq_state
+        cmp #PLAY
+        FailNe()
+        lda tr_step
+        cmp #40
+        FailNe()
+        lda title_done
+        FailEq()
+        .for (var n = 0; n < 8; n++) {  // the chain against the sine formula
+            lda $d000 + 2 * n
+            cmp #<ExpX(n)
+            FailNe()
+            lda $d001 + 2 * n
+            cmp #ExpY(n)
+            FailNe()
+        }
+        lda $d010
+        cmp #exp_msb
+        FailNe()
+        lda xscroll                    // the scroller: phase, read pointer, row 22
+        cmp #EXP_XSCROLL
+        FailNe()
+        lda msg_read+1
+        cmp #<(message + MSG_START + EXP_SHIFTS)
+        FailNe()
+        lda msg_read+2
+        cmp #>(message + MSG_START + EXP_SHIFTS)
+        FailNe()
+        ldx #37
+!:      lda SCREEN + SCROLL_ROW * 40 + 1,x
+        cmp message + EXP_SHIFTS + 1,x
+        FailNe()
+        dex
+        bpl !-
+        ldx #BARS_LINES - 1            // the bar table the kernel draws
+!:      lda bar_colours,x
+        cmp exp_bars,x
+        FailNe()
+        dex
+        bpl !-
+        lda music_calls                // every frame slot played or (NTSC) skipped
+        clc
+        adc music_skips
+        tax
+        lda music_calls+1
+        adc music_skips+1
+        cmp frames+1
+        FailNe()
+        cpx frames
+        FailNe()
+        lda music_skips                // PAL never skips; NTSC skips one in six
+        ora music_skips+1
+        ldx model
+        beq !pal+
+        cmp #0
+        FailEq()
+        jmp !pass+
+!pal:   cmp #0
+        FailNe()
+!pass:
+        lda irq_late                   // every IRQ on its line, every chain whole,
+        ora irq_bad                    // every frame slot done before the next chain
+        ora frame_late
+        FailNe()
+        // The player's place against its call count: after c calls the
+        // tick is c mod STEP_FRAMES and the step (c div STEP_FRAMES) mod
+        // STEPS. Read together, with the IRQ that advances them held off.
+        sei
+        lda music_calls
+        sta v_calls
+        lda music_calls+1
+        sta v_calls+1
+        lda m_tick
+        sta v_tick
+        lda m_step
+        sta v_step
+        cli
+        ldx #0                         // v_calls div STEP_FRAMES, low byte in X
+!:      lda v_calls
+        sec
+        sbc #STEP_FRAMES
+        tay
+        lda v_calls+1
+        sbc #0
+        bcc !+
+        sta v_calls+1
+        sty v_calls
+        inx
+        jmp !-
+!:      lda v_calls                    // the remainder
+        cmp v_tick
+        FailNe()
+        txa
+        and #STEPS - 1
+        cmp v_step
+        FailNe()
+        lda #1
+        ldy #5
+        ldx #0
+        jmp !say+
+vfail:  lda #2
+        ldy #2
+        ldx #pass_end - pass
+!say:   sta RESULT
+        sty border_colour              // the bar kernel writes it after the last bar
+        sty $d020
+        ldy #0
+!:      lda pass,x
+        sta SCREEN + 24 * 40 + 1,y
+        lda #1
+        sta COLOUR + 24 * 40 + 1,y
+        inx
+        iny
+        cpy #pass_end - pass
+        bne !-
+        lda #1
+        sta verdict_done
+        rts
+
+// The bar table at the frozen phase, drawn as fill_bars draws it.
+.var expected = List()
+.for (var i = 0; i < BARS_LINES; i++) .eval expected.add(0)
+.for (var b = 0; b < 4; b++) {
+    .var top = BARS_CENTRE + SinR(BARS_AMP, (EXP_PB + b * BAR_STEP) & 255)
+    .for (var i = 0; i < BAR_H; i++) .eval expected.set(top + i, bar_ramps.get(b).get(i))
+}
+exp_bars:
+        .for (var i = 0; i < BARS_LINES; i++) .byte expected.get(i)
+
+.encoding "screencode_upper"
+pass:   .text "RESULT 01 PASS"
+pass_end:
+        .text "RESULT 02 FAIL"
+verdict_done: .byte 0
+v_calls: .word 0
+v_tick:  .byte 0
+v_step:  .byte 0
+

package/templates/demo/tools/audio.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Grade the tune by the stores it makes to the SID, from a VICE store trace.
+
+usage: audio.py --c64kb DIR --x64sc PATH [--cycles N] build/demo-auto.prg
+
+The demo cannot read its own sound back: under the harness's `+sound`,
+VICE returns values from $D41B and $D41C that do not follow the voice
+(measured here: they change with no SID write at all), so the verdict
+cannot hear a silent player. This check runs c64-kb's claims-watch over the
+AUTOPILOT PRG on PAL and counts the program's stores to each SID unit:
+
+- voice 2 (the arpeggio) is written twice every play call, and the tune is
+  played every PAL frame from the chain's start. So its stores, less the
+  twelve of init, over two, must match the frames from its first store to
+  the end of the trace, within SLACK (measured: 447 calls in 451 frames).
+- voice 1 (bass) and voice 3 (drums) change on steps, so each must have at
+  least one store per step of seven frames; the volume at least one.
+
+Exit 0 when all hold, 1 when one fails, 2 when the trace cannot be run.
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+
+PAL_FRAME = 19656
+STEP_FRAMES = 7
+INIT_V2 = 12                               # m_init: 7 in its clearing loop, 5 to set the voice up
+SLACK = 6                                  # frames between init and the first play call:
+                                           # measured 4 (the meter's calibration and the
+                                           # title's init run between them)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--c64kb", required=True)
+    ap.add_argument("--x64sc", required=True)
+    ap.add_argument("--cycles", type=int, default=12000000)
+    ap.add_argument("prg")
+    a = ap.parse_args()
+    with tempfile.TemporaryDirectory() as t:
+        out = os.path.join(t, "claims.json")
+        r = subprocess.run(
+            ["node", "scripts/claims-watch.ts", os.path.abspath(a.prg),
+             "--claim", "sid_voice_1, sid_voice_2, sid_voice_3, sid_filter_volume",
+             "--cycles", str(a.cycles), "--json", out],
+            cwd=a.c64kb, env={**os.environ, "X64SC_BIN": a.x64sc}, capture_output=True, text=True)
+        if not os.path.exists(out):
+            print(r.stdout[-2000:], r.stderr[-2000:])
+            print("audio: claims-watch wrote no trace")
+            return 2
+        with open(out) as f:
+            tallies = json.load(f)["tallies"]
+    units = {t["target"]: t for t in tallies if t["source"] == "program" and t["target"].startswith("sid_")}
+    ok = True
+    v2 = units.get("sid_voice_2")
+    if not v2:
+        print("FAIL audio: no store to voice 2 at all")
+        return 1
+    calls = (a.cycles - v2["first"]["clock"]) // PAL_FRAME + 1
+    played = (v2["count"] - INIT_V2) // 2
+    line = f"voice 2: {v2['count']} stores = {played} play calls; {calls} frames from its first store"
+    if abs(played - calls) > SLACK:
+        print(f"FAIL audio: {line}")
+        ok = False
+    else:
+        print(f"PASS audio: {line}")
+    for unit, least in (("sid_voice_1", calls // STEP_FRAMES), ("sid_voice_3", calls // STEP_FRAMES),
+                        ("sid_filter_volume", 1)):
+        n = units.get(unit, {}).get("count", 0)
+        print(f"{'PASS' if n >= least else 'FAIL'} audio: {unit}: {n} stores, want at least {least}")
+        ok = ok and n >= least
+    print("audio: " + ("the tune writes the SID every frame" if ok else "FAILED"))
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/demo/tools/gen_expect.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Write expect.json for the demo starter from src/config.asm.
+
+usage: python3 tools/gen_expect.py > expect.json      (or: make expect)
+
+The numbers (lines, amplitudes, speeds, the freeze) are read from the plain
+`.const NAME = number` lines of src/config.asm; the picture is computed here
+again, in Python, not taken from the assembler: where the eight sprites
+sit, which colour every bar line has, where row 22's ink falls at the
+frozen XSCROLL (from the character ROM).
+KickAssembler's round() is Java's Math.round, floor(x + 0.5), and so is
+rnd() below.
+"""
+import json
+import math
+import os
+import re
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+with open(os.path.join(HERE, "src", "config.asm")) as f:
+    CONFIG = f.read()
+C = {m.group(1): int(m.group(2), 0) for m in re.finditer(r"^\.const (\w+)\s*=\s*(\d+)\b", CONFIG, re.M)}
+
+# The ramps and the message, from their source lines.
+RAMPS = [[int(v) for v in m.group(1).split(",")]
+         for m in re.finditer(r"List\(\)\.add\(([\d, ]+)\)", CONFIG)]
+with open(os.path.join(HERE, "src", "tables.asm")) as f:
+    TABLES = f.read()
+MESSAGE = "".join(re.findall(r'\.text "([^"]*)"', TABLES[TABLES.index("message:"):]))
+SUBTITLE = re.search(r'subtitle:\s*\.text "([^"]*)"', TABLES).group(1)
+# scroll_colours: ".byte a, b, c / .fill n, v / .byte ..." read in order.
+SCROLL_COLOURS = []
+for kind, args in re.findall(r"\.(byte|fill) ([\d, ]+)", TABLES[TABLES.index("scroll_colours:"):TABLES.index(".encoding")]):
+    vals = [int(v) for v in args.split(",")]
+    SCROLL_COLOURS += vals if kind == "byte" else [vals[1]] * vals[0]
+
+# The power-on character set, for where the scroller's ink falls (the same
+# ROM check.py decodes text with).
+CHARGEN_PATHS = [
+    os.environ.get("C64_CHARGEN", ""),
+    "/opt/homebrew/opt/vice/share/vice/C64/chargen-901225-01.bin",
+    "/usr/local/share/vice/C64/chargen-901225-01.bin",
+    "/usr/share/vice/C64/chargen-901225-01.bin",
+    "/usr/lib/vice/C64/chargen-901225-01.bin",
+]
+
+BORDER_PASS = 5
+BLACK = 0
+
+
+def rnd(x):
+    return math.floor(x + 0.5)
+
+
+def sin256(amp, step):
+    return rnd(amp * math.sin(2 * math.pi * (step & 255) / 256))
+
+
+def sprites(k):
+    px, py = (k * C["CHAIN_SX"]) & 255, (k * C["CHAIN_SY"]) & 255
+    out = []
+    for n in range(8):
+        x = C["CHAIN_X0"] + n * C["CHAIN_DX"] + sin256(C["CHAIN_AX"], px + n * C["CHAIN_PX"])
+        y = C["CHAIN_Y0"] + sin256(C["CHAIN_AY"], py + n * C["CHAIN_PY"])
+        out.append((x, y, C["CHAIN_COL_A"] if n % 2 == 0 else C["CHAIN_COL_B"]))
+    return out
+
+
+def bar_lines(k):
+    pb = (k * C["BAR_SPEED"]) & 255
+    lines = [BLACK] * C["BARS_LINES"]
+    for b, ramp in enumerate(RAMPS):
+        top = C["BARS_CENTRE"] + sin256(C["BARS_AMP"], pb + b * C["BAR_STEP"])
+        lines[top:top + C["BAR_H"]] = ramp
+    return lines
+
+
+def screen_code(ch):
+    """KickAssembler's screencode_upper for the characters the message uses."""
+    return ord(ch) - 64 if "A" <= ch <= "Z" else ord(ch)
+
+
+def scroller_checks(k, rom):
+    """Row 22 at the freeze: 38 columns, XSCROLL 7 - (k mod 8), after k // 8 shifts.
+    For each visible cell, the leftmost ink pixel of its first inked glyph row
+    and the pixel just left of it. A missing or wrong $D016 write moves them."""
+    shifts, xs = k // 8, 7 - k % 8
+    row = MESSAGE[shifts:shifts + 40]
+    line0 = 51 + 8 * C["SCROLL_ROW"]
+
+    def colour_at(vic_x, r):
+        cell, bit = divmod(vic_x - 24 - xs, 8)
+        if not 0 <= cell < 40:
+            return BLACK
+        glyph = rom[screen_code(row[cell]) * 8 + r]
+        return SCROLL_COLOURS[cell] if glyph & (0x80 >> bit) else BLACK
+
+    out = []
+    for c in range(1, 38):
+        code = screen_code(row[c])
+        glyph = rom[code * 8: code * 8 + 8]
+        r = next((r for r in range(8) if glyph[r]), None)
+        if r is None:
+            continue
+        bit = next(b for b in range(8) if glyph[r] & (0x80 >> b))
+        x = 24 + 8 * c + xs + bit
+        for vx, what in ((x, "ink"), (x - 1, "left of it")):
+            out.append({"name": f"scroller cell {c} '{row[c]}', XSCROLL {xs}: {what} at X {vx}, line {line0 + r}",
+                        "type": "pixel", "vic_x": vx, "line": line0 + r, "colour": colour_at(vx, r)})
+    # 38 columns: the border covers X 24-30 and 335-343 on the scroller's lines only.
+    out.append({"name": "scroller in 38 columns: left border X 24-30", "type": "rect", "colour": BORDER_PASS,
+                "vic_x": 24, "line": line0, "width": 7, "height": 8})
+    out.append({"name": "scroller in 38 columns: right border X 335-343", "type": "rect", "colour": BORDER_PASS,
+                "vic_x": 335, "line": line0, "width": 9, "height": 8})
+    return out
+
+
+def main():
+    k = C["FREEZE_UPDATES"]
+    top = C["BARS_TOP"]
+    checks = [
+        {"name": "own verdict (border)", "type": "verdict"},
+        {"name": "verdict line", "type": "text", "row": 24, "col": 1, "text": "RESULT 01 PASS"},
+        {"name": "subtitle under the logo (row 5)", "type": "text", "row": 5, "col": 0, "text": SUBTITLE},
+    ]
+    # The logo: two cells of the D's stem and one gap, rows 0 to 4.
+    for row, colour in enumerate([4, 10, 7, 10, 4]):
+        checks.append({"name": f"logo row {row}: the D's stem", "type": "pixel", "row": row, "col": 7, "colour": colour})
+    checks.append({"name": "logo: the gap between D and E", "type": "pixel", "row": 2, "col": 13, "colour": BLACK})
+
+    for n, (x, y, colour) in enumerate(sprites(k)):
+        checks.append({
+            "name": f"sprite {n} at X {x}, Y {y} (lines {y + 1}-{y + 21}), from the sine formula",
+            "type": "sprite", "colour": colour, "vic_x": x, "line": y + 1, "width": 24, "height": 21,
+            "search": {"vic_x": x - 16, "line": y - 7, "width": 56, "height": 37},
+        })
+
+    # Every bar line, left border to right border, one colour: runs of equal
+    # colour become one rect each. The title card's rows 13, 15 and 17 lie in
+    # these lines, so these checks also prove the wipe cleared it.
+    lines = bar_lines(k)
+    i = 0
+    while i < len(lines):
+        j = i
+        while j + 1 < len(lines) and lines[j + 1] == lines[i]:
+            j += 1
+        checks.append({
+            "name": f"bar lines {top + i}-{top + j}: colour {lines[i]} across the whole line",
+            "type": "rect", "colour": lines[i], "vic_x": -8, "line": top + i, "width": 384, "height": j - i + 1,
+        })
+        i = j + 1
+    for line, what in ((top - 1, "above"), (top + len(lines), "below")):
+        checks.append({"name": f"line {line}, {what} the bars: border", "type": "rect", "colour": BORDER_PASS,
+                       "vic_x": -8, "line": line, "width": 32, "height": 1})
+        checks.append({"name": f"line {line}, {what} the bars: background", "type": "rect", "colour": BLACK,
+                       "vic_x": 24, "line": line, "width": 320, "height": 1})
+
+    rom = next(open(p, "rb").read() for p in CHARGEN_PATHS if p and os.path.exists(p))
+    checks += scroller_checks(k, rom)
+    checks.append({"name": "rows 0 to 23 the same on PAL and NTSC", "type": "same", "cells": [0, 0, 23, 39]})
+    checks.append({"name": f"frame meter, {C['HOLD']} frames: title, wipe and main part", "type": "meter",
+                   "row": 24, "col": 20, "frames": C["HOLD"]})
+    print(json.dumps({"checks": checks}, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/templates/demo/tools/probe.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Where the bar kernel's colour stores land, read off the PROBE build's shots.
+
+usage: probe.py probe-pal-*.png probe-ntsc-*.png   (at least 8 shots a model)
+
+The PROBE build delays the whole kernel by 20 cycles, so the second store
+of each line ($D021, the background) lands inside the visible line instead
+of in the horizontal blank. On every bar line whose colour differs from the
+line above, the first pixel of the new colour inside the display window is
+that store. One column on every line, in every shot, means the entry is
+stable and every badline chunk has the right length. Taking the 20 cycles
+(160 pixels) back off says how far the real stores sit from the visible
+edges: the $D020 store is 4 cycles (32 pixels) before the $D021 store.
+
+Exit 0 when each model shows one column, PROBE_COLUMN from config.asm,
+over all its shots, and the stores
+of every chunk fall in the horizontal blank without the probe; 1 otherwise.
+Geometry from c64-kb docs/runtime/vice-reference.md: row = line - 16 (PAL),
+line - 28 (NTSC); a PAL line is 504 pixels (63 cycles), an NTSC one 520.
+"""
+import os
+import re
+import sys
+
+from PIL import Image
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+with open(os.path.join(HERE, "src", "config.asm")) as f:
+    CONST = {m.group(1): int(m.group(2)) for m in re.finditer(r"^\.const (\w+)\s*=\s*(\d+)\b", f.read(), re.M)}
+SHIFT_PX = 20 * 8
+MIN_SHOTS = 8                          # the review saw wrong pads show one column in 16 of 16 single shots
+GREY_DOT = (205, 205, 205)             # light grey, the same triple on both models
+MODELS = {"pal": (16, 504), "ntsc": (28, 520)}
+
+
+def columns(path, offset):
+    """(line, x) of the first new-colour pixel in the display, per changing line."""
+    im = Image.open(path).convert("RGB")
+    top, n = CONST["BARS_TOP"], CONST["BARS_LINES"]
+    out = []
+    for line in range(top, top + n + 1):
+        y = line - offset
+        new, old = im.getpixel((383, y)), im.getpixel((0, y))
+        # VICE's PAL default, a C64C, draws the grey dot: one light grey pixel
+        # where a colour register changes. A change to or from light grey is
+        # skipped, so the column is always the first pixel of the new colour.
+        if new == old or GREY_DOT in (new, old):
+            continue
+        out.append((line, next((x for x in range(32, 352) if im.getpixel((x, y)) == new), None)))
+    return out
+
+
+def main():
+    shots = {"pal": [], "ntsc": []}
+    for path in sys.argv[1:]:
+        shots["ntsc" if "ntsc" in os.path.basename(path) else "pal"].append(path)
+    last_line = CONST["BARS_TOP"] + CONST["BARS_LINES"]
+    ok = True
+    for model, paths in shots.items():
+        offset, line_px = MODELS[model]
+        body, last = set(), set()
+        for p in paths:
+            for line, x in columns(p, offset):
+                (last if line == last_line else body).add(x)
+        print(f"{model}: {len(paths)} shot(s), $D021 store column(s) {sorted(body, key=str)}")
+        if len(paths) < MIN_SHOTS:
+            print(f"{model}: FAIL, {len(paths)} shot(s); a wrong SYNC_PAD can look right in fewer than {MIN_SHOTS}")
+            ok = False
+            continue
+        if len(body) != 1 or None in body:
+            print(f"{model}: FAIL, the stores do not line up")
+            ok = False
+            continue
+        if body != {CONST["PROBE_COLUMN"]}:
+            print(f"{model}: FAIL, the stores line up at x {next(iter(body))}, not PROBE_COLUMN "
+                  f"{CONST['PROBE_COLUMN']} (config.asm): the entry moved")
+            ok = False
+            continue
+        x2 = next(iter(body)) - SHIFT_PX     # the real $D021 store, relative to x = 0
+        x1 = x2 - 32                         # the $D020 store, four cycles earlier
+        # The last chunk's $D021 store writes black over black, so it never
+        # shows; it is two cycles later than the others by the code.
+        xl = x2 + 16
+        after = x1 + line_px - 383           # pixels past the line above's last visible pixel
+        print(f"{model}: without the probe, $D020 at x {x1} and $D021 at x {x2} (the last chunk's "
+              f"$D021 at {xl} by the code, not measured), x 0 being the line's first visible pixel; "
+              f"the $D020 store is {after} pixels after the line above leaves the picture")
+        if not (xl < 0 and after > 0):
+            print(f"{model}: FAIL, a store would land in the visible line")
+            ok = False
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

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

package/templates/hello/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
+
+The smallest program that uses every harness target. `src/main.c` (Oscar64)
+runs the loop; `src/sprite.asm` (KickAssembler) places sprite 0; the meter
+times each frame. Start a program from it with
+`npm run new-project -- hello <dir>` in c64-kb. `PLAN.md` here is a plan
+filled from real tool output; new-project keeps it as
+`PLAN-hello-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).