docs(claude): layout-read timing doctrine + behavioral guidelines

- Add the read-timing rule to Key Conventions: layout-forcing reads
  (getComputedStyle / getBoundingClientRect / offset* / scroll* / client*) run
  post-layout via `dom.measure` (or a `dom.raf` callback), NEVER synchronously
  after a write; a theme token → concrete colour via `eidos.resolveToken`, not a
  `getComputedStyle` probe; `uix.perf` detects violations at runtime.
- Also lands a pre-existing uncommitted behavioral-guidelines preamble
  (Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CLAUDE.md

@@ -1,5 +1,59 @@
 # CLAUDE.md
 
+1. Think Before Coding
+Don't assume. Don't hide confusion. Surface tradeoffs.
+
+Before implementing:
+
+State your assumptions explicitly. If uncertain, ask.
+If multiple interpretations exist, present them - don't pick silently.
+If a simpler approach exists, say so. Push back when warranted.
+If something is unclear, stop. Name what's confusing. Ask.
+2. Simplicity First
+Minimum code that solves the problem. Nothing speculative.
+
+No features beyond what was asked.
+No abstractions for single-use code.
+No "flexibility" or "configurability" that wasn't requested.
+No error handling for impossible scenarios.
+If you write 200 lines and it could be 50, rewrite it.
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+3. Surgical Changes
+Touch only what you must. Clean up only your own mess.
+
+When editing existing code:
+
+Don't "improve" adjacent code, comments, or formatting.
+Don't refactor things that aren't broken.
+Match existing style, even if you'd do it differently.
+If you notice unrelated dead code, mention it - don't delete it.
+When your changes create orphans:
+
+Remove imports/variables/functions that YOUR changes made unused.
+Don't remove pre-existing dead code unless asked.
+The test: Every changed line should trace directly to the user's request.
+
+4. Goal-Driven Execution
+Define success criteria. Loop until verified.
+
+Transform tasks into verifiable goals:
+
+"Add validation" → "Write tests for invalid inputs, then make them pass"
+"Fix the bug" → "Write a test that reproduces it, then make it pass"
+"Refactor X" → "Ensure tests pass before and after"
+For multi-step tasks, state a brief plan:
+
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+
+
+
+
+
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 > **Branch note (`active-uix`):** the legacy layers `src/lib/`, `src/uix/terra/`,
@@ -147,6 +201,17 @@ this to detect drift between the morfo contract and the eidos rules.
   active-dom's `targetWindow`; the bare functions fall back to the
   global `document` / `window`, which is wrong in iframe / popup /
   happy-dom-test contexts.
+- **Layout reads run post-layout, never sync-after-write**: layout-forcing reads
+  (`getBoundingClientRect`, `getComputedStyle`, `offset*`, `scroll*`, `client*`)
+  flush pending style + layout, so calling one synchronously right after a DOM /
+  style write forces a reflow mid-turn — the "[Violation] Forced reflow while
+  executing JavaScript" class of bug. Defer them: `dom.measure(read, node?)`
+  queues the read in a coalesced animation frame (the sanctioned vehicle), or run
+  it from a `dom.raf` callback. It's a *timing* rule, not an ownership one — a bare
+  deferred read complies; only the sync-after-write ordering is forbidden. The
+  dev-only `uix.perf` detector (opt-in `reflowDetector`) names violators at runtime
+  via Long Animation Frames. To turn a theme token into a concrete colour, use
+  `eidos.resolveToken(token)` (config + `$color`) — never a `getComputedStyle` probe.
 
 ## Critical Rules