F4 scope-fidelity audit flagged a plan-text vs implementation count
drift. Only three trigger primitives existed before Wave 2
(on-turn-start, on-capture, on-damaged) plus one non-trigger
conditional primitive, NOT four trigger primitives. Wave 2 added
seven more, so the correct total is 10 trigger primitives, not 11.
This commit corrects the RULES.md intro paragraph from
11 trigger primitives (4 existing + 7 added in Wave 2)
to
10 trigger primitives (3 existing + 7 added in Wave 2)
matching the actual file-system count under
packages/chess/src/modifiers/primitives/on-*.ts. No structural docs
reorganization needed (the section already tabulates the 3 existing
triggers under Existing triggers (pre-Wave 2) and the 7 new ones
under New triggers (Wave 2) individually).
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.
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.)
