systemic-game-design-course/docs/HANDOFF.md

# Handoff: state of the course after the v2 extensions

Written 2026-11-11. This records what the two revision rounds changed, the
decisions made along the way that the spec and plan do not show, and what is
still open. The code, lessons and commit history are the record of *what*
exists; this file is the record of *why* and *what next*.

## Where things stand

`main` is at `85959ba` and contains everything below. Two branches fed it and
still exist on the remote:

- `revise/edge-cases-and-sources` (round 1): bug fixes, ordering tests,
  fact-checking, a "Stress it" beat in every lesson, the closing module, the
  level solver.
- `extend/course-v2` (round 2, built on round 1): Modules 11 and 12, engine
  extensions in Modules 2, 4, 5, 9 and 10, seven new levels, new tools, the
  playable site page, three CI jobs.

Design documents:

- `docs/superpowers/specs/2026-11-11-course-v2-extensions-design.md` (spec)
- `docs/superpowers/plans/2026-11-11-course-v2-extensions.md` (plan)

**The code departs from the spec and plan text in a few places.** Those
documents were not updated afterwards. Where they disagree with the code, the
code is right; see "Rulings" below.

Verification at the time of the merge: `npm run check` ok; 93 tool tests and
13 site tests pass; `verify-references` and `--expansion` ok for Modules
01–12; coupling audit ok; all 10 level proofs hold; all 13 mutants killed;
the Rust and TypeScript tracks agree over the fuzz seeds; the site builds
(20 pages).

## Round 1: what was found

Three bugs in the reference engines, all with every test green at the time:

- **Deathrattle summon position.** The Death Event remembered a board index,
  which went stale when a minion further left died in the same step. It now
  remembers the surviving right-hand neighbour by id.
- **Negated conversion lost to a group noun.** `ALL IS ROCK` plus
  `BABA IS NOT ROCK` turned Baba into a rock.
- **A pulled `YOU` object moved twice.** A key that was `YOU` and `PULL`
  behind Baba was dragged one tile, then took its own step.

Six ordering decisions that no test pinned were found by mutating the
engines' order lists: two turn-phase reorderings, a dropped final parse, two
hazard reorderings, and a live aura scan in place of the snapshot. Each now
fails a named test.

Fact-check results:

- Two Branns: the lesson said the sources do not say how they combine. The
  wiki does ("Brann's effect does not stack with itself"). Fixed.
- The rulebook's Acolyte of Pain example predates the 2023 change from 3 to
  4 Health (Patch 27.2.0.183876). The card data was right; the example is
  flagged as stale.
- HearthSim's mirror of the game's tag names has `EXTRA_DEATHRATTLES_BASE`
  next to `EXTRA_DEATHRATTLES_ADDITIONAL`, which looks like the same split as
  Module 4's `stacking` field. The lesson presents this as a reading of the
  names, not a documented rule.
- Level 1 cannot be solved without `DEATHRATTLE IS DOUBLE`, and Level 3 has
  no solution on the naive-timing engine (both by exhaustive search).

Decisions made in round 1:

- Module 9 requires the Module 7 Expansion Drop (`ALL`), the way Module 4
  already requires earlier drops. Without it the conversion bug has no test.
- An object steps at most once per move, and a stepped object does not block
  a later mover. This keeps stacked `YOU AND PUSH` objects together. It is
  the course's rule; no source covers it.
- Two dying neighbours summon their tokens in order of play, even if that
  reverses their board order. Unsourced, and labelled so.
- Module 9 went from 8 tests to 14.
- "Stress it" is a new optional lesson beat.

## Round 2: where each idea landed

| Idea | Result |
|---|---|
| Differential fuzzing of the two tracks | `tools/diff-tracks.mjs`. No divergence in 5,000 seeds. Three real track differences were found by reading side by side and fixed: the TypeScript `registerAssembled`, and two CLI parsing differences. |
| Replacement effects | Module 4: `DAMAGE_STEPS = [redirect, armor]`, the `damageRedirect` aura, the `ArmorLost` event, the card Bolf Ramshield. |
| Nesting guard and Death Phase cap | Module 5: a resolving stack in `World`; `DEATH_PHASE_LIMIT = 64`. |
| Well-formed Assemble | Module 5: `wellFormed` / `well_formed`. |
| Conditions | Module 11: `NOUN ON NOUN IS …`, evaluated per object at use; `NEAR` is the drop. |
| Fourth SpellGrid seam | Module 10: a summoned minion with a noun enters the grid (`Summoned.by`); cards Clay Golem and Clay Shard. |
| Combat and turns | Module 12: `orderAttack`, `canAttack`, `endTurn`, Taunt, defender-first as a queue priority; Bonechewer Brawler is the drop. |
| More levels, solver-verified | Levels l4–l10 with `course/10-spellgrid/levels/proofs.json` and `tools/verify-levels.mjs`. |
| Log tree printer | `logTree()` / `log_tree()` from Module 2; both SpellGrid CLIs print it. |
| Designer capstone | `course/10-spellgrid/designer-capstone.md`, `designer-example/`, `tools/run-scenario.mjs`. |
| CI | Three new jobs (`diff-tracks`, `mutation-check`, `verify-levels`). Never run on a real runner; see "Open items". |
| Interactive site | `/play/` runs the Module 12 TypeScript reference unmodified in the browser. |
| Undo | `undo()` on the grid engine from Module 9. SpellGrid deliberately reports it as not supported. |
| Solver position key | Age-aware, via `stackAt`. |
| Leftovers from round 1 | The Lesson 8 quote and the `count > 1` summon order are fixed. |

The closing module, "Break your own engine", was renumbered from 11 to 13.

## Rulings

Decisions made during round 2 that the spec and plan do not record, each with
what it costs if it was the wrong call.

1. **Worked on a branch in the main checkout, not a separate worktree.** No
   lasting cost.
2. **The CI jobs were validated by running their commands locally.** There is
   no runner. A workflow syntax error would only show on a real runner, and
   CI pins Rust 1.85.1 where the local runs used 1.99.
3. **The plan gave tests as scenario prose, not code in two languages.**
   Reviewers had to check tests against scenarios more carefully.
4. **The redirect test uses Armorsmith's reaction** as "the minion's damage
   trigger fires", since Bolf has no damage trigger.
5. **`wellFormed` is stricter than the spec's wording.** It also rejects an
   effect after an aura or keyword. A future card with a keyword between
   trigger and effect would be rejected.
6. **`Summoned.by` is set in `World.enter` from the innermost resolving
   trigger,** not threaded through the queue. A future summon outside a
   trigger block would have no summoner.
7. **The fuzzer's generator was extended for conditions** in the Module 11
   task, outside that task's file list. Earlier modules' cases are unchanged.
8. **The attack action is `orderAttack` / `order_attack`, not `attack`.**
   `attack(id)` has returned a character's Attack since Module 2. The spec
   and plan say `attack`.
9. **No course test for closing a trigger block on error.** It is covered by
   reference-only tests. Learners' engines are not asked to do it.

## Where the course knowingly differs from the real games

Both are stated in the lessons as the course's choice.

- **Nesting guard.** The course drops the skipped activations. Hearthstone's
  rulebook says: "Instead it works the skipped times as a compensation after
  all other consequences of it are resolved."
- **`ON ALL`.** The course means "any one other object". The Baba Is You wiki
  says "ALL in the noun2 part requires one of every object in ALL".

## Corrections made during round 2

Claims that were wrong in a draft and fixed before the merge. They are listed
because each is easy to reintroduce.

- Lesson 2: two Bombs do not "hit each other once each"; the correct count is
  six activations.
- Lesson 10: level 2 has 18,601 reachable positions, not "some 31,000".
- Lesson 11: a wiki page does cover `ON ALL` (see above).
- Lesson 12: several Hearthstone claims were not in the research log; they
  were re-fetched and logged in `docs/research/hearthstone.md`.
- Module 13: the mutation table's rows follow `tools/mutants.json`, and the
  survivor count is five in both places it appears.

The final whole-branch review found three important issues, all fixed in
`85959ba`:

- An engine error in the middle of a Sequence left a corrupt game in
  `run-scenario` and the TypeScript CLI. It is now fatal ("The Sequence did
  not finish, so the game cannot go on."), and trigger blocks close on error
  in Modules 2–12 (`try`/`finally`; `catch_unwind` in Rust).
- The nesting guard was presented as Hearthstone's rule. It is now labelled
  as the course's.
- The Node floor is 22.15, because the site's game test needs it.

## Changes to the learner contract

- Module 5 has a new test, `test_05_assemble_never_rewrites_an_earlier_card`.
- Module 9 requires the Module 7 drop (`ALL`).
- `package.json` `engines` is `>=22.15`.

## Open items

- **CI has never run on a real runner.** The Gitea workflow needs the
  `ubuntu-latest` label and access to GitHub for the actions it uses.
- **The deploy subdomain is not set** (`COURSE_HOST` in `deploy/.env`).
- The owner's read-through of the course is still to come.

## Known minor issues, deliberately deferred

- Level 9 is the weakest puzzle: its chain push is forced, not a decision.
- The solver, `verify-levels`, `play-spellgrid` and `run-scenario` stage the
  Module 10 engine, while the site, fuzzer and mutation check use Module 12.
  It is the same game for the shipped levels, and the lessons say so.
- The differential fuzzer rarely puts an Assembled minion on the grid and
  never draws Bolf.
- Play page: focus is lost after a tile click, and arrow keys are captured
  page-wide.
- No tests for: SpellGrid undo erroring, a conditional rule giving no aura,
  third-party defender priority, two Taunts.
- `site/scripts/sync-content.mjs` duplicates `cardDirs` from `tools/lib.mjs`.
- Lesson 11's hazard-board bullet has nested parentheses.
- From v1: the coupling audit flags PascalCase names and string-literal noun
  words; the chooser type in `course/harness.md` does not match the code; the
  `registerCards` test is weak.