typescript-sprite-wiring-judge-criterion

Answer

Root cause. The RR-VIS-001 criterion in .gitreins/tasks.yaml was written against a stale 8-cell-index mental model — it assumed the player's sprite-sheet cell index (0..7 across an 8-wide sheet) is the frame index. The engine does not address frames that way: it resolves frames via per-animation sequences (SUBJECT_TABLES.player.strips.<anim>.frames, playback index t mod sequence.length). The engine's mapping was correct (run[0-3] → run-1..4); the criterion was wrong and the judge failed a correct mapping.

The fix (two parts):

1. Verify the engine lookup convention first. The ground truth is animationToFrames (engine/sprites.ts), not the task-text indices:

// engine/sprites.ts — the contract to check BEFORE writing any criterion
export const SUBJECT_TABLES = {
  player: {
    cells: 8, // physical sheet width — NOT a frame index space
    strips: {
      idle: { row: 0, frames: ["idle-1", "idle-2", "idle-3", "idle-4"] },
      run:  { row: 1, frames: ["run-1", "run-2", "run-3", "run-4"] },
      jump: { row: 2, frames: ["jump-1", "jump-2"] },
      hurt: { row: 3, frames: ["hurt-1"] },
    },
  },
} as const;

export function animationToFrames(subject: Subject, animation: string): string[] {
  return SUBJECT_TABLES[subject]?.strips[animation]
    ? [...SUBJECT_TABLES[subject].strips[animation].frames] : [];
}

// runtime resolution: sequence index = t mod sequence length
export function frameAt(subject: Subject, animation: string, t: number): string {
  const frames = animationToFrames(subject, animation);
  if (frames.length === 0) throw new Error(`unknown animation "${animation}"`);
  return frames[((t % frames.length) + frames.length) % frames.length];
}

1. Edit the criterion in .gitreins/tasks.yaml to the real contract (before → after):

# BEFORE (stale 8-cell-index mental model — FAILED a correct mapping)
criterion:
  id: RR-VIS-001
  asserts:
    - expr: animationToFrames(player, run)
      expected: ["player-0", "player-1", "player-2", "player-3"]  # sheet cells 0..3 — WRONG

# AFTER (engine contract: run[0-3] -> run-1..4 via sequence index)
criterion:
  id: RR-VIS-001
  kind: sprite-frame-mapping
  subject: player
  asserts:
    - expr: animationToFrames(player, run)
      expected: ["run-1", "run-2", "run-3", "run-4"]
    - expr: frameAt(player, run, 4)
      expected: "run-1"   # index mod sequence length wraps
    - expr: frameAt(player, run, 7)
      expected: "run-4"
snapshot:
  files: [".gitreins/tasks.yaml", "level-config.ts"]

1. Re-run task complete only after the sibling worker commits. The judge refuses to run on a dirty tree (an uncommitted level config shifts the config snapshot and breaks determinism):

// judge/determinism.ts — fails fast on in-flight sibling edits
const dirty = execFileSync("git", ["status", "--porcelain"], { cwd: root, encoding: "utf8" });
const treeClean = dirty.trim().length === 0;          // false -> re-judge later
const drift = files.some(f => baseline[f] !== sha256(f)); // uncommitted config -> drift
// judge passes only when: all criterion assertions hold AND tree clean AND no drift

Full reproduction lives in /tmp/rr-vis-001 (engine, judge, .gitreins/tasks.yaml, tests).