docs+test: pin alive-first ordering in planAi human guard

BugBot review on PR #4 flagged that the !me.alive early-return preempts the
isHuman throw, "undermining the fail-fast guard." This is intentional design,
documented in the Task 5 plan ("dead humans return [] — same as dead AI"), but
not previously visible in the code. Add a 5-line comment to ai/index.ts
explaining the ordering rationale, plus a regression test asserting the dead-
human path returns [] (locks the ordering against future reorderings).

No behaviour change. 161/161 tests; typecheck clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: emp3thy

src/engine/ai/index.ts

@@ -13,6 +13,11 @@ const DIFFICULTY_RANDOM_PCT: Record<Difficulty, number> = {
 
 export function planAi(state: GameState, leaderId: LeaderId, difficulty?: Difficulty): Order[] {
   const me = state.leaders[leaderId];
+  // Alive-check first by design: dead leaders (AI or human) return [] — same shape,
+  // same caller contract. The human throw below catches misroutes for ALIVE humans
+  // (Phase 3 UI-orchestrator bug), not eliminated humans whose lifecycle handling
+  // should mirror eliminated AI. Reordering would create asymmetric semantics
+  // (dead AI = []; dead human = throw) for no benefit.
   if (!me || !me.alive) return [];
   if (isHuman(leaderId)) {
     throw new Error(

tests/engine/ai/dispatcher.test.ts

@@ -60,12 +60,26 @@ describe('planAi dispatcher', () => {
     }
   });
 
-  it('throws when called for a human player slot', () => {
+  it('throws when called for an alive human player slot', () => {
     const s = initialState({
       cast: ['player1', 'chump'],
       difficulty: 'normal',
       seed: 'planAi-human',
     });
     expect(() => planAi(s, 'player1')).toThrow(/planAi.*human/i);
   });
+
+  it('returns [] (does not throw) when called for an eliminated human player slot', () => {
+    // Dead AI returns []; dead human must mirror that — Phase 3 callers iterate
+    // the cast and rely on planAi(state, deadId) === [] without special-casing.
+    // The "throw on human" guard is for ALIVE-human routing bugs only.
+    const s = initialState({
+      cast: ['player1', 'chump'],
+      difficulty: 'normal',
+      seed: 'planAi-dead-human',
+    });
+    s.leaders.player1.alive = false;
+    s.leaders.player1.population = 0;
+    expect(planAi(s, 'player1')).toEqual([]);
+  });
 });