refactor(effects): introduce WgslEffect for shader-only post-process effects

Replace boilerplate .h/.cc pairs for simple single-pass effects with a
generic WgslEffect base class that takes a shader string + optional
WgslEffectParams (binding 3). Port Flash, Passthrough, Heptagon, Scratch,
and GaussianBlur to thin header-only wrappers — no .cc files, no CMake
entries needed. Removes 5 .cc files (-243 lines).

Update EFFECT_WORKFLOW.md, CONTRIBUTING.md, and AI_RULES.md to document
the WgslEffect (Path A) vs full class (Path B) workflow. Doc cleanup:
fix stale GaussianBlurParams/PostProcessEffect references and test counts.

handoff(Claude): WgslEffect landed; 5 effects ported; docs updated.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

1 files changed, 14 insertions, 4 deletions

diff --git a/doc/AI_RULES.md b/doc/AI_RULES.md
index 1a4ee78..5500a9a 100644
--- a/doc/AI_RULES.md
+++ b/doc/AI_RULES.md
@@ -10,17 +10,27 @@
 
 **IMPORTANT:** When adding new visual effects, follow the complete workflow in `doc/EFFECT_WORKFLOW.md`.
 
-**Required steps (must complete ALL):**
+**Simple post-process (WgslEffect path — no .cc, no CMake):**
+1. Create `src/effects/<name>.wgsl`
+2. Add shader to `workspaces/main/assets.txt`
+3. Create `src/effects/<name>_effect.h` as thin wrapper over `WgslEffect`
+4. Add extern to `shaders.h` / `shaders.cc`
+5. Include header in `src/gpu/demo_effects.h`
+6. Add to test list in `src/tests/gpu/test_demo_effects.cc`
+7. Add to timeline with `EFFECT +` (priority modifier REQUIRED)
+8. Build and verify: `cmake --build build -j4 && cd build && ./test_demo_effects`
+
+**Complex effects (custom uniforms / 3D / compute — full class):**
 1. Create effect files (.h, .cc, .wgsl)
 2. Add shader to `workspaces/main/assets.txt`
-3. Add `.cc` to CMakeLists.txt GPU_SOURCES (BOTH sections: headless and normal)
+3. Add `.cc` to `cmake/DemoSourceLists.cmake` COMMON_GPU_EFFECTS
 4. Include header in `src/gpu/demo_effects.h`
-5. Add to timeline with `EFFECT +` (priority modifier is REQUIRED)
+5. Add to timeline with `EFFECT +` (priority modifier REQUIRED)
 6. Add to test list in `src/tests/gpu/test_demo_effects.cc`
 7. Build and verify: `cmake --build build -j4 && cd build && ./test_demo_effects`
 
 **Common mistakes to avoid:**
 - Missing priority modifier in timeline (`EFFECT` must be `EFFECT +`, `EFFECT =`, or `EFFECT -`)
-- Adding `.cc` to only one CMakeLists.txt section (need BOTH headless and normal)
+- Adding `.cc` to CMake for WgslEffect thin wrappers (not needed)
 - Wrong asset ID (check assets.txt entry name → `ASSET_SHADER_<NAME>`)
 - Forgetting to add to test file