feat(effects): add Scratch post-process effect with reusable scratch_lines snippet

- src/shaders/render/scratch_lines.wgsl: reusable WGSL snippet registered as
  "render/scratch_lines"; call scratch_lines(uv, resolution, time)->f32 from
  any effect. Uses hash_1f from math/noise; 8 lines/frame, ~24fps flicker.
- src/effects/scratch.{wgsl,h,cc}: thin Scratch effect wrapping the snippet.
- Applied to "intro" and "rotating_cube" sequences as the final step.
- 35/35 tests passing.

handoff(Gemini): Scratch effect added. render/scratch_lines snippet is reusable.

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

13 files changed, 141 insertions, 6 deletions

diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md
index 690b589..3b49bab 100644
--- a/PROJECT_CONTEXT.md
+++ b/PROJECT_CONTEXT.md
@@ -34,20 +34,20 @@
 - **Timing System:** **Beat-based timelines** for musical synchronization. Sequences defined in beats, converted to seconds at runtime. Effects receive both physical time (constant) and beat time (musical). Variable tempo affects audio only. See `doc/BEAT_TIMING.md`.
 - **Workspace system:** Multi-workspace support. Easy switching with `-DDEMO_WORKSPACE=<name>`. Organized structure: `music/`, `weights/`, `obj/`, `shaders/`. Shared common shaders in `src/shaders/`. See `doc/WORKSPACE_SYSTEM.md`.
 - **Audio:** Sample-accurate sync. Zero heap allocations per frame. Variable tempo. OLA-IDCT synthesis (v2 .spec): Hann analysis window, rectangular synthesis, 50% overlap, click-free. V1 (raw DCT-512) preserved for generated notes. .spec files regenerated as v2.
-- **Shaders:** Parameterized effects (UniformHelper, .seq syntax). Beat-synchronized animation support (`beat_time`, `beat_phase`). Modular WGSL composition with ShaderComposer. 24 shared common shaders (math, render, compute).
+- **Shaders:** Parameterized effects (UniformHelper, .seq syntax). Beat-synchronized animation support (`beat_time`, `beat_phase`). Modular WGSL composition with ShaderComposer. 25 shared common shaders (math, render, compute). Reusable render snippets: `render/scratch_lines`.
 - **3D:** Hybrid SDF/rasterization with BVH. Binary scene loader. Blender pipeline.
 - **Effects:** CNN post-processing: CNNEffect (v1) and CNNv2Effect operational. CNN v2: sigmoid activation, storage buffer weights (~3.2 KB), 7D static features, dynamic layers. Training stable, convergence validated.
 - **Tools:** CNN test tool operational. Texture readback utility functional. Timeline editor (web-based, beat-aligned, audio playback).
 - **Build:** Asset dependency tracking. Size measurement. Hot-reload (debug-only). WSL (Windows 10) supported: native Linux build and cross-compile to `.exe` via `mingw-w64`.
-- **Sequence:** DAG-based effect routing with explicit node system. Python compiler with topological sort and ping-pong optimization. 10 effects operational (Passthrough, Placeholder, GaussianBlur, Heptagon, Particles, RotatingCube, Hybrid3D, Flash, PeakMeter, Scene1). Effect times are absolute (seq_compiler adds sequence start offset). See `doc/SEQUENCE.md`.
-- **Testing:** **34/34 passing**.
+- **Sequence:** DAG-based effect routing with explicit node system. Python compiler with topological sort and ping-pong optimization. 12 effects operational (Passthrough, Placeholder, GaussianBlur, Heptagon, Particles, RotatingCube, Hybrid3D, Flash, PeakMeter, Scene1, Scene2, Scratch). Effect times are absolute (seq_compiler adds sequence start offset). See `doc/SEQUENCE.md`.
+- **Testing:** **35/35 passing**.
 
 ---
 
 ## Next Up
 
 **Active:** Spectral Brush Editor (procedural compression), CNN v2 quantization
-**Ongoing:** Test infrastructure maintenance (34/34 passing)
+**Ongoing:** Test infrastructure maintenance (35/35 passing)
 **Future:** Size optimization (64k target), 3D enhancements
 
 See `TODO.md` for details.
diff --git a/cmake/DemoSourceLists.cmake b/cmake/DemoSourceLists.cmake
index 0c57ada..1aaef59 100644
--- a/cmake/DemoSourceLists.cmake
+++ b/cmake/DemoSourceLists.cmake
@@ -43,6 +43,7 @@ set(COMMON_GPU_EFFECTS
     src/effects/peak_meter_effect.cc
     src/effects/scene1_effect.cc
     src/effects/scene2_effect.cc
+    src/effects/scratch_effect.cc
     # TODO: Port CNN effects to v2 (complex v1 dependencies)
     # cnn_v1/src/cnn_v1_effect.cc
     # cnn_v2/src/cnn_v2_effect.cc
diff --git a/doc/COMPLETED.md b/doc/COMPLETED.md
index d72591f..5d8603f 100644
--- a/doc/COMPLETED.md
+++ b/doc/COMPLETED.md
@@ -29,6 +29,15 @@ Detailed historical documents have been moved to `doc/archive/` for reference:
 
 Use `read @doc/archive/FILENAME.md` to access archived documents.
 
+## Recently Completed (March 2026)
+
+- [x] **Scratch post-process effect**
+    - New `Scratch` effect overlays random horizontal film-scratch lines additively on top of any input buffer.
+    - Scratch logic extracted into reusable snippet `src/shaders/render/scratch_lines.wgsl` (registered as `"render/scratch_lines"`). Any effect can `#include "render/scratch_lines"` and call `scratch_lines(uv, resolution, time) -> f32`. Uses `hash_1f` from `math/noise`.
+    - Applied to first two timeline sequences ("intro", "rotating_cube") as the final post-process step.
+    - **Files:** `src/shaders/render/scratch_lines.wgsl` (new), `src/effects/scratch.wgsl` (new), `src/effects/scratch_effect.{h,cc}` (new), `assets.txt`, `DemoSourceLists.cmake`, `demo_effects.h`, `shaders.{h,cc}`, `test_demo_effects.cc`, `timeline.seq`
+    - **Tests:** 35/35 passing
+
 ## Recently Completed (March 2, 2026)
 
 - [x] **OLA-IDCT Synthesis — click-free .spec decoding**
diff --git a/src/effects/scratch.wgsl b/src/effects/scratch.wgsl
new file mode 100644
index 0000000..818202e
--- /dev/null
+++ b/src/effects/scratch.wgsl
@@ -0,0 +1,14 @@
+// Scratch effect - overlays film scratch lines on top of the input buffer
+#include "sequence_uniforms"
+#include "render/fullscreen_uv_vs"
+#include "render/scratch_lines"
+
+@group(0) @binding(0) var input_sampler: sampler;
+@group(0) @binding(1) var input_texture: texture_2d<f32>;
+@group(0) @binding(2) var<uniform> uniforms: UniformsSequenceParams;
+
+@fragment fn fs_main(in: VertexOutput) -> @location(0) vec4f {
+    let color = textureSample(input_texture, input_sampler, in.uv);
+    let s = scratch_lines(in.uv, uniforms.resolution, uniforms.time);
+    return vec4f(color.rgb + vec3f(s), color.a);
+}
diff --git a/src/effects/scratch_effect.cc b/src/effects/scratch_effect.cc
new file mode 100644
index 0000000..f49e601
--- /dev/null
+++ b/src/effects/scratch_effect.cc
@@ -0,0 +1,44 @@
+// Scratch effect - film scratch overlay post-process
+
+#include "effects/scratch_effect.h"
+#include "effects/shaders.h"
+#include "gpu/post_process_helper.h"
+#include "util/fatal_error.h"
+
+Scratch::Scratch(const GpuContext& ctx, const std::vector<std::string>& inputs,
+                 const std::vector<std::string>& outputs, float start_time,
+                 float end_time)
+    : Effect(ctx, inputs, outputs, start_time, end_time) {
+  HEADLESS_RETURN_IF_NULL(ctx_.device);
+
+  create_linear_sampler();
+
+  pipeline_.set(create_post_process_pipeline(ctx_.device,
+                                             WGPUTextureFormat_RGBA8Unorm,
+                                             scratch_shader_wgsl));
+}
+
+void Scratch::render(WGPUCommandEncoder encoder,
+                     const UniformsSequenceParams& params,
+                     NodeRegistry& nodes) {
+  WGPUTextureView input_view = nodes.get_view(input_nodes_[0]);
+  WGPUTextureView output_view = nodes.get_view(output_nodes_[0]);
+
+  pp_update_bind_group(ctx_.device, pipeline_.get(), bind_group_.get_address(),
+                       input_view, uniforms_buffer_.get(), {nullptr, 0});
+
+  WGPURenderPassColorAttachment color_attachment = {};
+  gpu_init_color_attachment(color_attachment, output_view);
+
+  WGPURenderPassDescriptor pass_desc = {};
+  pass_desc.colorAttachmentCount = 1;
+  pass_desc.colorAttachments = &color_attachment;
+
+  WGPURenderPassEncoder pass =
+      wgpuCommandEncoderBeginRenderPass(encoder, &pass_desc);
+  wgpuRenderPassEncoderSetPipeline(pass, pipeline_.get());
+  wgpuRenderPassEncoderSetBindGroup(pass, 0, bind_group_.get(), 0, nullptr);
+  wgpuRenderPassEncoderDraw(pass, 3, 1, 0, 0);
+  wgpuRenderPassEncoderEnd(pass);
+  wgpuRenderPassEncoderRelease(pass);
+}
diff --git a/src/effects/scratch_effect.h b/src/effects/scratch_effect.h
new file mode 100644
index 0000000..fb36a96
--- /dev/null
+++ b/src/effects/scratch_effect.h
@@ -0,0 +1,20 @@
+// Scratch effect - film scratch overlay post-process
+// Reads input buffer, additively blends scratch_lines() on top.
+
+#pragma once
+#include "gpu/effect.h"
+#include "gpu/wgpu_resource.h"
+
+class Scratch : public Effect {
+ public:
+  Scratch(const GpuContext& ctx, const std::vector<std::string>& inputs,
+          const std::vector<std::string>& outputs, float start_time,
+          float end_time);
+
+  void render(WGPUCommandEncoder encoder, const UniformsSequenceParams& params,
+              NodeRegistry& nodes) override;
+
+ private:
+  RenderPipeline pipeline_;
+  BindGroup bind_group_;
+};
diff --git a/src/effects/shaders.cc b/src/effects/shaders.cc
index c6a81d0..e4b9b25 100644
--- a/src/effects/shaders.cc
+++ b/src/effects/shaders.cc
@@ -51,6 +51,8 @@ void InitShaderComposer() {
   register_if_exists("ray_box", AssetId::ASSET_SHADER_RAY_BOX);
   register_if_exists("ray_triangle", AssetId::ASSET_SHADER_RAY_TRIANGLE);
 
+  register_if_exists("render/scratch_lines",
+                     AssetId::ASSET_SHADER_RENDER_SCRATCH_LINES);
   register_if_exists("render/fullscreen_vs",
                      AssetId::ASSET_SHADER_RENDER_FULLSCREEN_VS);
   register_if_exists("render/fullscreen_uv_vs",
@@ -97,6 +99,7 @@ const char* rotating_cube_wgsl =
 const char* flash_shader_wgsl = SafeGetAsset(AssetId::ASSET_SHADER_FLASH);
 const char* scene1_shader_wgsl = SafeGetAsset(AssetId::ASSET_SHADER_SCENE1);
 const char* scene2_shader_wgsl = SafeGetAsset(AssetId::ASSET_SHADER_SCENE2);
+const char* scratch_shader_wgsl = SafeGetAsset(AssetId::ASSET_SHADER_SCRATCH);
 
 // Compute shaders
 const char* gen_noise_compute_wgsl =
diff --git a/src/effects/shaders.h b/src/effects/shaders.h
index 5fc442a..76b5d96 100644
--- a/src/effects/shaders.h
+++ b/src/effects/shaders.h
@@ -16,6 +16,7 @@ extern const char* rotating_cube_wgsl;
 extern const char* flash_shader_wgsl;
 extern const char* scene1_shader_wgsl;
 extern const char* scene2_shader_wgsl;
+extern const char* scratch_shader_wgsl;
 
 // Compute shaders
 extern const char* gen_noise_compute_wgsl;
diff --git a/src/gpu/demo_effects.h b/src/gpu/demo_effects.h
index e1a9c17..ecc37df 100644
--- a/src/gpu/demo_effects.h
+++ b/src/gpu/demo_effects.h
@@ -28,6 +28,7 @@
 #include "effects/rotating_cube_effect.h"
 #include "effects/scene1_effect.h"
 #include "effects/scene2_effect.h"
+#include "effects/scratch_effect.h"
 
 // TODO: Port CNN effects
 // #include "../../cnn_v1/src/cnn_v1_effect.h"
diff --git a/src/shaders/render/scratch_lines.wgsl b/src/shaders/render/scratch_lines.wgsl
new file mode 100644
index 0000000..04ed6f8
--- /dev/null
+++ b/src/shaders/render/scratch_lines.wgsl
@@ -0,0 +1,35 @@
+// Horizontal film scratch lines utility
+// Returns scratch intensity [0,1] to additively overlay on a color buffer.
+//
+// Parameters:
+//   uv         - normalized texture coordinates [0,1]
+//   resolution - screen size in pixels (used for sub-pixel thickness)
+//   time       - physical time in seconds
+//
+// Simulates aged/damaged film: ~8 random horizontal lines per frame,
+// each with independent position, thickness, brightness and on/off state.
+// Time is quantized to 24 buckets/sec so scratches flicker like film frames.
+#include "math/noise"
+
+fn scratch_lines(uv: vec2f, resolution: vec2f, time: f32) -> f32 {
+    // Quantize to ~24fps to simulate film frame rate
+    let t = floor(time * 24.0);
+
+    var intensity = 0.0;
+    for (var i = 0; i < 8; i++) {
+        let seed = f32(i) * 17.3 + t;
+        // ~25% chance this scratch is visible this frame
+        let visible = step(0.75, hash_1f(seed + 3.1));
+        // Random vertical position [0, 1]
+        let y = hash_1f(seed + 7.9);
+        // Thickness in pixels [1, 4]
+        let thickness = hash_1f(seed + 13.5) * 3.0 + 1.0;
+        // Brightness [0.5, 1.0]
+        let brightness = hash_1f(seed + 21.7) * 0.5 + 0.5;
+        // Soft linear falloff from line center
+        let dy = abs(uv.y - y) * resolution.y;
+        let line = clamp(1.0 - dy / thickness, 0.0, 1.0);
+        intensity += line * brightness * visible;
+    }
+    return clamp(intensity, 0.0, 1.0);
+}
diff --git a/src/tests/gpu/test_demo_effects.cc b/src/tests/gpu/test_demo_effects.cc
index 5c4bffc..3aa6230 100644
--- a/src/tests/gpu/test_demo_effects.cc
+++ b/src/tests/gpu/test_demo_effects.cc
@@ -70,6 +70,9 @@ static void test_effects() {
       {"Scene2", std::make_shared<Scene2Effect>(
                      fixture.ctx(), std::vector<std::string>{"source"},
                      std::vector<std::string>{"sink"}, 0.0f, 1000.0f)},
+      {"Scratch", std::make_shared<Scratch>(
+                      fixture.ctx(), std::vector<std::string>{"source"},
+                      std::vector<std::string>{"sink"}, 0.0f, 1000.0f)},
   };
 
   int passed = 0;
diff --git a/workspaces/main/assets.txt b/workspaces/main/assets.txt
index 625dc22..1bcbcd0 100644
--- a/workspaces/main/assets.txt
+++ b/workspaces/main/assets.txt
@@ -91,6 +91,8 @@ CIRCLE_MASK_RENDER_SHADER, NONE, shaders/circle_mask_render.wgsl, "Circle mask r
 MASKED_CUBE_SHADER, NONE, shaders/masked_cube.wgsl, "Masked cube shader"
 SHADER_SCENE1, NONE, ../../src/effects/scene1.wgsl, "Scene1 effect shader"
 SHADER_SCENE2, NONE, ../../src/effects/scene2.wgsl, "Scene2 effect shader"
+SHADER_RENDER_SCRATCH_LINES, NONE, ../../src/shaders/render/scratch_lines.wgsl, "Film scratch lines snippet"
+SHADER_SCRATCH, NONE, ../../src/effects/scratch.wgsl, "Scratch effect shader"
 
 # --- Sequence Shaders ---
 SHADER_SEQUENCE_V2_UNIFORMS, NONE, ../../src/shaders/sequence_uniforms.wgsl, "Sequence Uniforms Snippet"
diff --git a/workspaces/main/timeline.seq b/workspaces/main/timeline.seq
index 6399bdf..e6ba4a5 100644
--- a/workspaces/main/timeline.seq
+++ b/workspaces/main/timeline.seq
@@ -3,11 +3,13 @@
 
 SEQUENCE 0.00 0 "intro"
   EFFECT + RotatingCube source -> temp1 0.00 4.00
-  EFFECT + GaussianBlur temp1 -> sink 0.00 4.00
+  EFFECT + GaussianBlur temp1 -> temp2 0.00 4.00
+  EFFECT + Scratch temp2 -> sink 0.00 4.00
 
 SEQUENCE 4.00 0 "rotating_cube"
   EFFECT + RotatingCube source -> temp1 0.00 4.00
-  EFFECT + Placeholder temp1 -> sink 1.00 4.00
+  EFFECT + Placeholder temp1 -> temp2 1.00 4.00
+  EFFECT + Scratch temp2 -> sink 1.00 4.00
 
 SEQUENCE 8.00 0 "scene 2"
   # Scene2 test