From f6bef061c3a273425f77b268e72e9a827de59170 Mon Sep 17 00:00:00 2001
From: josh <josh@thewrightserver.net>
Date: Sat, 9 May 2026 02:57:15 -0400
Subject: [PATCH] revise(02-04): replace in-test compileAllInk() call with
 precondition check

Per W9: invoking the compiler from inside ink-loader.test.ts's beforeAll
creates a filesystem race against other concurrent tests because the
script wipes src/content/compiled-ink/ at start. Compile is already part
of the npm run ci chain (via npm run build); the test should only verify
the artefact exists and fail loudly with a fix-it message otherwise.
---
 .../02-04-lura-gate-beats-PLAN.md             | 22 ++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/.planning/phases/02-season-1-vertical-slice-soil/02-04-lura-gate-beats-PLAN.md b/.planning/phases/02-season-1-vertical-slice-soil/02-04-lura-gate-beats-PLAN.md
index 5744c45..4cef90f 100644
--- a/.planning/phases/02-season-1-vertical-slice-soil/02-04-lura-gate-beats-PLAN.md
+++ b/.planning/phases/02-season-1-vertical-slice-soil/02-04-lura-gate-beats-PLAN.md
@@ -587,14 +587,30 @@ export function bindGardenStateToInk(story: Story, snapshot: AppStoreShape): voi
 - `bindGardenStateToInk` does not throw on a story missing a declared var (the warn is silent).
 - Variable casing test (Pitfall 4): every key in `INK_VARIABLE_MAP` is snake_case. Programmatic assertion: `Object.keys(INK_VARIABLE_MAP).every(k => /^[a-z_]+$/.test(k))`.
 
-This test requires Ink JSON to be present, which requires `npm run compile:ink` to have run. Add a `beforeAll` that runs the compile script:
+This test requires Ink JSON to be present, which requires `npm run compile:ink` to have run BEFORE the suite. Per W9, do NOT call `compileAllInk()` from inside the test — invoking the compiler concurrently with other tests creates a filesystem race on `src/content/compiled-ink/` (the script wipes the directory at start). Instead, add a precondition check that fails loudly with a fix-it message:
 
 ```typescript
 import { beforeAll } from 'vitest';
-import { compileAllInk } from '../../scripts/compile-ink.mjs';
-beforeAll(async () => { await compileAllInk(); });
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const compiledExists = existsSync(
+  resolve(process.cwd(), 'src/content/compiled-ink/season1/lura-arrival.ink.json'),
+);
+beforeAll(() => {
+  if (!compiledExists) {
+    throw new Error(
+      'ink-loader.test.ts: compiled Ink JSON missing. Run `npm run compile:ink` (or `npm run build`) before this suite.',
+    );
+  }
+});
 ```
 
+The `npm run ci` chain already runs `compile:ink` as part of `npm run build`, so the local + CI flow is:
+  `npm run compile:ink` → `npx vitest run` (the test file's beforeAll just verifies the artefact exists).
+
+If you prefer Vitest's globalSetup, the equivalent lives in `vitest.config.ts` — but the precondition check above is simpler, faster, and surfaces a clearer error when the artefact is missing.
+
 **Step 9 — Update `src/content/index.ts`** to re-export ink-loader:
 ```typescript
 export { loadInkStory, bindGardenStateToInk, INK_VARIABLE_MAP } from './ink-loader';