flat-js

Use when planning or implementing Flat JS VM state serialization, execution snapshots, snapshot restore, host capability registries, serializable runtime records, iterator/collection/function/generator/async serialization support, serialization playground work, or updates to `plan/vm-state-serialization-plan.md`. Guides phased work, runtime boundaries, unsupported-state policy, and validation gates.

Use when confirming a Flat JS branch is truly working, green, ready, or target complete after compiler, runtime, protected-mode, loader, example, or browser-facing changes. Provides the checklist and completion gates to satisfy before claiming the branch is done.

Use when checking rebuilt Flat JS generated loader output, especially `example/opcode-kitchen-sink-loader.js`, for runtime-internal property names emitted as string properties, leaked bookkeeping fields, or cleanup regressions after runtime/compiler changes.

Use when fixing Flat JS bugs, regressions, unintended test failures, or behavior that broke after a recent change, especially in `src/compiler/**`, `src/runtime/**`, opcode work, or Test262-driven fixes. Enforces root-cause fixes: remove or narrow the regression-causing change first, and do not add workaround paths, new opcodes, special-case branches, sentinels, or duplicate semantics layers just to patch a newly introduced bug.

Use when adding or fixing ES2015+ language support in Flat JS, especially in `src/compiler/**`, `src/runtime/**`, opcode work, or syntax handlers. Enforces the project rule that newer JavaScript features must be implemented directly in compiler/runtime semantics rather than lowered into ES5-style helper code, synthetic AST rewrites, or userland compatibility shims.

Use when working on the Flat JS arena sim, debugger stepping, scan or lastMoveDistance barriers, TICKS_PER_SECOND semantics, or future multi-controller bot scheduling. Grounds changes in the current code so world ticks, raw VM steps, and user-visible highlight steps are not conflated.