docs(preset-api): hook ordering + Phase A summary

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).

.sisyphus/notepads/rule-variants/learnings.md

@@ -240,7 +240,54 @@ All 4 hooks landed on master:
 - A.1: 4d05473 — getRoyalPieces + engine royal dispatch
 - A.2: db8145f — filterLegalMoves
 - A.3: f9475e9 — shouldAdvanceTurn + HalfMovesThisTurn
-- A.4: (next commit) — overridePieceMoves
+- A.4: 1a11491 — overridePieceMoves
 
 Remaining in Phase A: A.5 — verification gate + PRESET-API.md
 hook-ordering doc + phase summary.
+
+## [2026-04-20 20:40] Task: A.5 — Phase A verification gate + PRESET-API.md
+
+**Shipped**:
+- `packages/chess/docs/PRESET-API.md` extensively updated:
+  - Movement section now leads with a 7-step dispatch diagram
+    covering both per-piece and aggregate stages. Each of the 4
+    new hooks references its step explicitly.
+  - New hook reference entries: `overridePieceMoves`,
+    `filterLegalMoves`, `getRoyalPieces` (new "Royalty" section),
+    `shouldAdvanceTurn` (new "Turn flip" section). Every entry
+    includes a concrete code example + canonical-user callout.
+  - "Hook firing order" in Design Notes split into two sequences:
+    LEGAL-MOVE QUERY (1-4) + MOVE APPLICATION (1-11). The
+    application sequence now correctly reflects
+    `HalfMovesThisTurn += 1` → `shouldAdvanceTurn` poll → flip or
+    veto path, and documents that `onTurnStart` is gated on
+    actual flip.
+  - Scope-aware table extended with the 4 new hooks.
+
+**Verification**:
+- `bun run check` green at every Phase A commit.
+- Full Playwright regression ran 80/80 passed after all 4 hooks
+  landed. No behavioural changes observed in any existing e2e.
+
+**Phase A closed.**
+- Total test delta: 1417 → 1448 (+31 new unit tests across 4 test
+  files: royal-pieces.test.ts, filter-legal-moves.test.ts,
+  turn-advance.test.ts, override-piece-moves.test.ts).
+- Zero lint / type errors.
+- Zero regressions (unit + e2e).
+- Master @ (about to be) the A.5 commit.
+
+**Next**: Phase B — Tier 1 presets. B.1-B.4 can run concurrently
+now. Recommended order per plan:
+  - B.1 (knightmate-rules) — simplest, getRoyalPieces only.
+    Unblocks immediately.
+  - B.2 (double-move) — shouldAdvanceTurn straightforward.
+  - B.3 (monster-rules) — scope-aware shouldAdvanceTurn. Depends
+    on A.3 only; can run parallel with B.2.
+  - B.4 (first-promotion-wins) — needs no new hooks, composes
+    existing onAfterMove + onCheckGameResult + shouldFilterSelfCheck.
+
+Before firing B.1-B.4 in parallel: confirm disjoint file sets
+(each preset = 1 file + 1 test file + maybe 1 layout update). Each
+delegation should be 1 preset per agent per the T3-learned tool-cap
+rule.