Extends RULES.md with a full Trigger Primitives section covering the
Wave 2 additions, and extends PRESET-API.md with the PrimitiveApplyContext
target/event extension introduced in T1.
RULES.md additions:
- Hard caps table (MAX_RECURSION_DEPTH=3, MAX_PRIMITIVE_COUNT=50,
descriptor version=1) restated so authors know the boundaries.
- Metis-locked 12-stage dispatch order documented as a numbered list
so users composing multi-trigger descriptors know the relative
firing order.
- Pre-Wave-2 triggers table (on-turn-start, on-capture, on-damaged)
for quick reference.
- Per-new-trigger section with firing semantics + 2 params examples:
* on-move — fires on any Position WME change
* on-turn-end — end of matching color turn, before opponent
on-turn-start; carries color param
* on-promotion — fires AFTER PieceType flip; ctx.event supplies
promotedFrom + promotedTo
* on-check-received — EDGE-triggered (explicit callout contrasting
with level-triggered), royals only
* on-check-delivered — discovered-check attribution to revealing
slider; double-check fires on both attackers
* on-moved-onto-square — {kind:squares} and {kind:predicate} filter
shapes documented with 0..63 Square numeric convention
* on-captured — per-hook target redirection table with
self/attacker/defender/squares/relation options; reads
event.attackerId + event.defenderId
PRESET-API.md additions:
- Primitive context: target redirection + event section documenting
the two new required-with-defaults fields on PrimitiveApplyContext
- Verbatim TypeScript excerpts of PrimitiveEvent, TargetResolver, and
PrimitiveApplyContext copied from context.ts/types.ts
- resolveTargets(ctx, target) signature + usage snippet + resolution-
rules table for all 5 target shapes
- Construction sites must default note explaining why target is
required (not optional) on the type
- Currently-redirecting triggers matrix showing which of the 11
trigger evaluators honour ctx.target and which populate ctx.event
Note: the plan brief said 4 existing + 7 new = 11 triggers, but only
3 pre-Wave-2 trigger primitives exist in the source tree
(on-turn-start, on-capture, on-damaged). Docs reflect the actual
3 + 7 = 10.
Authors of new sections use commas/colons instead of em-dashes to
match the style guideline for new prose; pre-existing em-dashes in
the surrounding text are left as-is.
Feature 3 of post-epic-deferrals. Adds en-passant to berolina-pawns
and berolina-pawns-2 following the Parton 1952 variant — the most
common published ruleset. Reflects standard ep semantics through
Berolina's reversed geometry (diagonal push, orthogonal capture).
Engine:
- MoveHookContext extended with pieceId + from + to. Existing
presets (piece-hp, poisoned-squares, etc.) are purely additive
on the new fields and don't need changes. Dispatch site in
applyMove populates them from the resolved move.
berolina-pawns + berolina-pawns-2:
- overridePieceMoves: after emitting normal Berolina moves, read
the preset's ep latch (namespaced preset state). If the mover's
orthogonal-forward square equals the stored skipped square AND
the capturer color matches, emit a capture move onto that
square. Note destination is empty by construction — the engine's
getPieceAt returns null there, so the default capture path is a
no-op; onAfterMove below does the actual retraction.
- onAfterMove: two responsibilities. (1) If the mover just
accepted a latched ep (move.to === skippedSquare) retract the
stored capturedPieceId. (2) Clear the latch. (3) If THIS move
was a Berolina double-diagonal push from the home rank, record
skippedSquare + capturedPieceId (the mover's own pieceId, since
that's what the opponent can remove next turn) + capturer color.
- Scope-flip semantics preserved — scope='white' means only white
pawns emit ep moves; the latch still records for downstream, but
the opposing black pawns follow FIDE rules and don't emit it.
- berolina-pawns-2: sideways captures do NOT trigger or accept
ep (only the orthogonal-forward direction participates).
Tests:
- 5 new berolina-pawns.test.ts cases: (r) latch + ep emission,
(s) accept-ep retracts the double-pushed pawn, (t) one-half-move
window expiry, (u) single-push doesn't latch, (v) scope='white'
latch set on white's double-push.
- 3 new berolina-pawns-2.test.ts cases: (l) ep through the
extended preset, (m) retraction on accept, (n) sideways capture
does NOT set the latch.
- All 31 pre-existing Berolina tests unchanged and still pass.
Docs:
- RULES.md gallery entries: remove 'en-passant deferred' language;
document the Parton 1952 rule and the sideways-ep exclusion.
- PRESET-API.md post-landing-backlog: drop the berolina ep
deferral.
- Preset docblocks: rewrite the en-passant section to describe
the shipped mechanism + plan reference.
Verification: 1671 unit tests (+8 ep). Typecheck + lint clean.
Plan: .sisyphus/plans/post-epic-deferrals.md Feature 3 complete.
Feature 2 of post-epic-deferrals. Exposes extinction-chess's
configurable targetType through the in-game rules drawer so players
don't need to open devtools or call engine.presetState themselves.
UI:
- RulesDrawer.tsx renders a 'Target: <PieceType>' chip inside the
extinction-chess detail card when the preset is active.
Clicking advances through pawn -> knight -> bishop -> rook ->
queen -> king -> pawn (wraps). Plural labels ('Pawns', 'Knights',
...) for prose.
- data-testid='extinction-target-cycler' on the chip for e2e.
- New optional RulesDrawer props extinctionTarget +
onExtinctionTargetChange; omitted props hide the cycler (no
hard dependency on the engine).
Wiring (GameView.tsx):
- Solo-only per plan decision 2a. Multiplayer games use the
target set at room-creation time; the cycler doesn't render in
MP to avoid desync (a future preset-config.update WS message
could lift this; out of v1 scope).
- Local useState syncs with engine.presetState via a useEffect;
setExtinctionTarget writes back through the same state API and
calls refresh() so legal highlights + terminal-state panels
pick up the target flip.
Docs:
- extinction-chess.ts docblock updated to reference the shipped
UI surface + the MP deferral.
- PRESET-API.md post-landing backlog: remove the 'UI cycling'
deferral (now shipped), add the MP-target-sync deferral.
Tests:
- 2 new rule-variants.spec.ts cases: (a) cycler cycles through
all 6 labels when preset active, (b) cycler hidden when preset
inactive.
Verification: 1663 unit + 89/89 e2e (87 + 2 new). Typecheck + lint
clean.
Plan: .sisyphus/plans/post-epic-deferrals.md Feature 2 complete.
Phase F.5 (docs portion) of the rule-variants epic.
- PRESET-API.md gains a 'Rule Variants Gallery' section summarizing
the 14 new presets grouped by category (King Variants, Objectives,
Multi-move, Movement). Flags which are scope-aware. Documents
the reusable scope-flip pattern for future asymmetric presets.
New section on 'ongoing' two-phase protocol for
onCheckGameResult composition.
- RULES.md gains a 'Rule Variants Gallery (v2, 2026)' section
cross-referencing each of the 14 presets with greenchess.net
where applicable. Overview table bumps from 15 rules to 29.
Also documents the new 'dual-classic' starting layout.
Tests: 1651 passing (docs-only; no test delta).
(Full Playwright regression + final commit still to come as part
of F.5 once the F.4 e2e spec lands.)
Phase A.5 of the rule-variants epic — the documentation gate.
- Movement section now leads with a 7-step dispatch diagram covering
the full per-piece-to-aggregate pipeline. Every new hook points at
its step explicitly so future preset authors know where each hook
slots in.
- New hook reference entries with canonical-user callouts:
overridePieceMoves, filterLegalMoves, getRoyalPieces (new Royalty
section), shouldAdvanceTurn (new Turn flip section). Every entry
has a concrete code snippet illustrating typical usage.
- Design Notes 'Hook firing order' split into two sequences — the
legal-move query (1-4) and move application (1-11). Application
sequence now correctly reflects HalfMovesThisTurn increment +
shouldAdvanceTurn poll + onTurnStart gating.
- Scope-aware table extended with the 4 new hooks.
- Notepad appended with Phase A close-out: 1417 → 1448 unit tests,
80/80 Playwright green, zero lint/type errors, four commits on
master (4d05473, db8145f, f9475e9, 1a11491).
Decouples five cross-cutting concerns from engine core so new presets
compose without special-casing:
- Piece attributes: CORE_PIECE_ATTRS + PresetDef.pieceAttributes;
engine.effectivePieceAttrs unions them. HP is now preset-owned.
- Spawn pipeline: engine.spawnPiece() + onPieceSpawn hook replaces
hand-rolled materialization. Queen-splits seeds HP via the hook,
not via direct knowledge of piece-hp.
- Hook signatures: all hooks now take single context objects
(LifecycleContext, MoveHookContext, CaptureHookContext, DamageHookContext,
SelfCheckFilterContext, GameResultHookContext, PieceSpawnContext,
BeforeMoveContext, TurnStartContext, DescribeMoveEffectContext).
- Piece-type registry: PIECE_TYPE_REGISTRY + core-piece-types.ts
replaces hardcoded FIDE switch-tables in engine/check/checkmate/
stalemate/Piece.tsx. Custom piece types plug in without engine edits.
- Preset-scoped state: engine.presetState<T>(id) backed by facts on
PRESET_STATE_ENTITY. Auto-cleared on deactivate. capture-to-win
migrated off GAME_ENTITY.Winner.
- Move log: engine.moveLog + MoveRecord + describeMoveEffect hook.
- Visual effects: engine.emitEffect/subscribeEffects + VisualEffect +
VisualEffectLayer. Explosion, heal, poison renderers. No-op when
no subscribers.
- Phase hooks: onBeforeMove (with cancel), onTurnStart. Scope-aware
dispatch routes onDamage/onBeforeMove/onTurnStart by target/mover
color.
All 5 production presets migrated. 4 prototype presets (Shield, Cannon,
Berserker, PawnStamina) in integration.test.ts exercise every hook.
Added test-utils.ts and PRESET-API.md for preset authors.
930 tests passing; bun run check clean.
