docs: implementation plan for mouse post-processing rework

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/superpowers/plans/2026-07-09-mouse-postprocess-quality.md

@@ -0,0 +1,624 @@
+# Mouse Post-Processing Quality Rework Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Remove the endpoint artifacts (vertical walls, hooks, start kinks) in generated mouse trajectories by reworking the post-processing pipeline, and reduce sampling jitter by switching 10-step Euler to 10-step Heun.
+
+**Architecture:** Three new pure-numpy functions in `src/ai_mouse/_postprocess.py` (`soften_forward`, `damp_start`, `warp_endpoints`) replace the three hard-clamping functions (`enforce_forward_monotonic`, `smooth_start`, `snap_endpoints`). `mouse.py` wires them in a new order (soft-monotonic → start damping → smoothing both axes → global endpoint correction) and replaces the Euler ODE loop with Heun predictor-corrector. Golden regression baselines are re-captured (intentional behavior change).
+
+**Tech Stack:** Python 3.12+, numpy, onnxruntime, pytest. Package manager: `uv`.
+
+**Spec:** `docs/superpowers/specs/2026-07-09-mouse-postprocess-quality-design.md`
+
+## Global Constraints
+
+- `src/ai_mouse/` is wheel content: NEVER import torch/fastapi/scipy/matplotlib there (CI `library` job installs runtime deps only).
+- All new post-processing functions are pure (no I/O, no global state), matching the existing `_postprocess.py` convention.
+- Public API (`generate()` signature and return shape, exact endpoint hit) must not change.
+- Scroll subsystem and `golden_scroll.npz` are untouched.
+- Run library tests with: `uv run pytest tests/unit` (add `-v` per test as noted).
+- All commits end with `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.
+
+---
+
+### Task 1: `soften_forward` — soft monotonic with overshoot compression
+
+Replaces the hard `clip(0,1)` + strict monotonicity of `enforce_forward_monotonic`. Tolerates small backtracking (real hands micro-correct), allows natural overshoot past 1.0, and soft-compresses extreme overshoot with tanh so the path never flies far past the target.
+
+**Files:**
+- Modify: `src/ai_mouse/_postprocess.py` (add function; do NOT delete old ones yet — removal happens in Task 4)
+- Test: `tests/unit/test_postprocess.py`
+
+**Interfaces:**
+- Produces: `soften_forward(forward: np.ndarray, backtrack_tol: float = 0.02, overshoot_span: float = 0.08) -> np.ndarray` — returns a new array; Task 4 calls it with defaults.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/unit/test_postprocess.py`:
+
+```python
+from ai_mouse._postprocess import soften_forward
+
+
+def test_soften_forward_tolerates_small_backtrack() -> None:
+    # A 0.01 dip is within the 0.02 tolerance and must survive untouched.
+    f = np.array([0.0, 0.30, 0.29, 0.60, 1.0])
+    out = soften_forward(f)
+    assert np.isclose(out[2], 0.29)
+
+
+def test_soften_forward_limits_large_backtrack() -> None:
+    # A 0.30 dip is noise; it gets pulled up to prev - tol.
+    f = np.array([0.0, 0.50, 0.20, 0.70, 1.0])
+    out = soften_forward(f)
+    assert np.isclose(out[2], 0.50 - 0.02)
+
+
+def test_soften_forward_allows_moderate_overshoot() -> None:
+    # Overshoot past 1.0 is natural; small overshoot survives (compressed
+    # but strictly > 1.0).
+    f = np.array([0.0, 0.5, 0.9, 1.04, 1.0])
+    out = soften_forward(f)
+    assert out[3] > 1.0
+
+
+def test_soften_forward_compresses_extreme_overshoot() -> None:
+    # tanh compression: no output value may exceed 1 + overshoot_span.
+    f = np.array([0.0, 0.5, 1.30, 1.50, 1.0])
+    out = soften_forward(f)
+    assert out.max() <= 1.0 + 0.08 + 1e-9
+    assert out[2] > 1.0  # still an overshoot, not clipped flat
+
+
+def test_soften_forward_no_lower_clip() -> None:
+    # Small wind-up behind the start is allowed (warp_endpoints pins
+    # the first point later; interior may be slightly negative).
+    f = np.array([0.0, -0.01, 0.30, 0.70, 1.0])
+    out = soften_forward(f)
+    assert out[1] < 0.0
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `uv run pytest tests/unit/test_postprocess.py -k soften_forward -v`
+Expected: 5 failures/errors with `ImportError: cannot import name 'soften_forward'`
+
+- [ ] **Step 3: Write the implementation**
+
+Add to `src/ai_mouse/_postprocess.py` (after `enforce_forward_monotonic`):
+
+```python
+def soften_forward(
+    forward: np.ndarray,
+    backtrack_tol: float = 0.02,
+    overshoot_span: float = 0.08,
+) -> np.ndarray:
+    """Softly regularise the forward axis without destroying natural motion.
+
+    Real trajectories contain small backward corrections and overshoot
+    past the target; hard clipping turns both into visible artifacts
+    (stacked points, vertical walls). Instead:
+
+    - Backtracking is tolerated up to ``backtrack_tol``; larger dips are
+      raised to ``prev - backtrack_tol``.
+    - Values above 1.0 are compressed with tanh so they asymptote at
+      ``1 + overshoot_span`` (moderate overshoot survives, extremes
+      cannot fly far past the target).
+    - No lower clip: the endpoint warp pins the first point later.
+
+    Args:
+        forward: (T,) forward coordinates.
+        backtrack_tol: max allowed per-step regression.
+        overshoot_span: asymptotic max excess above 1.0.
+
+    Returns:
+        New (T,) array.
+    """
+    out = forward.copy()
+    for i in range(1, len(out)):
+        floor = out[i - 1] - backtrack_tol
+        if out[i] < floor:
+            out[i] = floor
+    over = out > 1.0
+    out[over] = 1.0 + overshoot_span * np.tanh((out[over] - 1.0) / overshoot_span)
+    return out
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest tests/unit/test_postprocess.py -k soften_forward -v`
+Expected: 5 passed
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ai_mouse/_postprocess.py tests/unit/test_postprocess.py
+git commit -m "feat: add soften_forward (backtrack tolerance + tanh overshoot compression)
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: `damp_start` — continuous start damping
+
+Replaces `smooth_start`, whose ×1/5-then-abrupt-release lateral damping creates start kinks. New version ramps damping with smoothstep so the weight approaches 1 continuously at the release boundary, and touches only lateral (forward regularisation is `soften_forward`'s job).
+
+**Files:**
+- Modify: `src/ai_mouse/_postprocess.py`
+- Test: `tests/unit/test_postprocess.py`
+
+**Interfaces:**
+- Produces: `damp_start(lateral: np.ndarray, n: int = 4) -> np.ndarray` — returns a new array; Task 4 calls it with defaults.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/unit/test_postprocess.py`:
+
+```python
+from ai_mouse._postprocess import damp_start
+
+
+def test_damp_start_dampens_early_lateral() -> None:
+    lat = np.full(16, 1.0)
+    out = damp_start(lat, n=4)
+    assert out[1] < out[2] < out[3] < out[4] < 1.0  # monotone ramp
+    assert np.all(out[5:] == 1.0)  # untouched past n
+
+
+def test_damp_start_no_release_jump() -> None:
+    # The weight at i=n must be close to 1 (continuous release):
+    # smoothstep(4/5) = 0.896, vs the old linear 4/5 = 0.8.
+    lat = np.full(16, 1.0)
+    out = damp_start(lat, n=4)
+    assert out[4] > 0.85
+
+
+def test_damp_start_short_input_safe() -> None:
+    lat = np.array([0.0, 0.5, 0.3])
+    out = damp_start(lat, n=4)  # n capped to len//4 = 0 → no-op
+    assert np.array_equal(out, lat)
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `uv run pytest tests/unit/test_postprocess.py -k damp_start -v`
+Expected: 3 failures with `ImportError: cannot import name 'damp_start'`
+
+- [ ] **Step 3: Write the implementation**
+
+Add to `src/ai_mouse/_postprocess.py`:
+
+```python
+def damp_start(lateral: np.ndarray, n: int = 4) -> np.ndarray:
+    """Dampen lateral oscillation over the first ``n`` points, continuously.
+
+    Weights follow smoothstep(i / (n+1)) so the damping releases smoothly
+    into the untouched region (the old linear blend jumped from 0.8 to
+    1.0 and left a visible kink).
+
+    Args:
+        lateral: (T,) lateral coordinates.
+        n: number of leading points to dampen (capped at len//4).
+
+    Returns:
+        New (T,) array.
+    """
+    out = lateral.copy()
+    n = min(n, len(out) // 4)
+    for i in range(1, n + 1):
+        t = i / (n + 1)
+        w = t * t * (3.0 - 2.0 * t)  # smoothstep
+        out[i] *= w
+    return out
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest tests/unit/test_postprocess.py -k damp_start -v`
+Expected: 3 passed
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ai_mouse/_postprocess.py tests/unit/test_postprocess.py
+git commit -m "feat: add damp_start (smoothstep lateral damping, no release kink)
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: `warp_endpoints` — global residual correction
+
+Replaces `snap_endpoints`. Instead of dragging the last 6 points toward (1,0) (which fights the trajectory's own direction and creates hooks), compute the first/last-point residuals and distribute the correction across the whole curve with smoothstep weights. Endpoints land exactly; local shape and approach direction are preserved.
+
+**Files:**
+- Modify: `src/ai_mouse/_postprocess.py`
+- Test: `tests/unit/test_postprocess.py`
+
+**Interfaces:**
+- Produces: `warp_endpoints(forward: np.ndarray, lateral: np.ndarray) -> tuple[np.ndarray, np.ndarray]` — returns new arrays with `forward[0]==0.0, lateral[0]==0.0, forward[-1]==1.0, lateral[-1]==0.0` exactly; Task 4 calls it last in the pipeline.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/unit/test_postprocess.py`:
+
+```python
+from ai_mouse._postprocess import warp_endpoints
+
+
+def test_warp_endpoints_exact_pin() -> None:
+    f = np.linspace(0.05, 1.10, 32)
+    l = np.linspace(0.03, -0.07, 32)
+    fo, lo = warp_endpoints(f, l)
+    assert fo[0] == 0.0 and lo[0] == 0.0
+    assert fo[-1] == 1.0 and lo[-1] == 0.0
+
+
+def test_warp_endpoints_identity_when_already_pinned() -> None:
+    f = np.linspace(0.0, 1.0, 32)
+    l = np.sin(np.linspace(0, np.pi, 32)) * 0.1
+    l[0] = l[-1] = 0.0
+    fo, lo = warp_endpoints(f.copy(), l.copy())
+    assert np.allclose(fo, f, atol=1e-12)
+    assert np.allclose(lo, l, atol=1e-12)
+
+
+def test_warp_endpoints_preserves_smoothness() -> None:
+    # Correcting a smooth curve must not introduce sharp local bends:
+    # the warp adds a smoothstep-weighted offset, so the second
+    # difference (discrete curvature proxy) stays small.
+    f = np.linspace(0.02, 1.08, 32)
+    l = np.full(32, 0.05)
+    fo, lo = warp_endpoints(f, l)
+    assert np.abs(np.diff(lo, 2)).max() < 0.01
+    assert np.abs(np.diff(fo, 2)).max() < 0.01
+
+
+def test_warp_endpoints_correction_local_to_each_end() -> None:
+    # A start-only residual should barely move the last quarter.
+    # (smoothstep weight at i=24/31 is ~0.13, so 0.08 residual leaves
+    # ~0.010 there — threshold 0.02 gives margin without losing meaning)
+    f = np.linspace(0.0, 1.0, 32) + 0.0
+    l = np.zeros(32)
+    f[0] = 0.08  # start residual only
+    fo, _ = warp_endpoints(f, l)
+    assert np.abs(fo[24:] - f[24:]).max() < 0.02
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `uv run pytest tests/unit/test_postprocess.py -k warp_endpoints -v`
+Expected: 4 failures with `ImportError: cannot import name 'warp_endpoints'`
+
+- [ ] **Step 3: Write the implementation**
+
+Add to `src/ai_mouse/_postprocess.py`:
+
+```python
+def warp_endpoints(
+    forward: np.ndarray,
+    lateral: np.ndarray,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Warp the whole curve so endpoints land exactly on (0,0) and (1,0).
+
+    Computes the residual of the first point vs (0, 0) and the last point
+    vs (1, 0), then subtracts each residual weighted by a smoothstep that
+    is 1 at its own end and 0 at the opposite end. Unlike tail-dragging,
+    this preserves the trajectory's local shape and approach direction.
+
+    Args:
+        forward: (T,) forward coordinates.
+        lateral: (T,) lateral coordinates.
+
+    Returns:
+        ``(forward, lateral)`` new arrays, endpoints pinned exactly.
+    """
+    t = np.linspace(0.0, 1.0, len(forward))
+    w_end = t * t * (3.0 - 2.0 * t)      # smoothstep: 0 at start → 1 at end
+    w_start = 1.0 - w_end                # mirrored
+
+    res_f0, res_l0 = forward[0] - 0.0, lateral[0] - 0.0
+    res_f1, res_l1 = forward[-1] - 1.0, lateral[-1] - 0.0
+
+    fo = forward - w_start * res_f0 - w_end * res_f1
+    lo = lateral - w_start * res_l0 - w_end * res_l1
+
+    fo[0], lo[0] = 0.0, 0.0
+    fo[-1], lo[-1] = 1.0, 0.0
+    return fo, lo
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest tests/unit/test_postprocess.py -k warp_endpoints -v`
+Expected: 4 passed
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ai_mouse/_postprocess.py tests/unit/test_postprocess.py
+git commit -m "feat: add warp_endpoints (global residual correction, shape-preserving)
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: Wire new pipeline into `mouse.py`; remove old functions
+
+Swap the pipeline in `MouseModel.generate` to the spec order (soft-monotonic → start damping → smooth both axes → global endpoint correction), then delete the three replaced functions and their tests. Golden tests will now fail — that is expected and fixed in Task 6; all other tests must pass.
+
+**Files:**
+- Modify: `src/ai_mouse/mouse.py:14-24` (imports), `src/ai_mouse/mouse.py:106-109` (pipeline)
+- Modify: `src/ai_mouse/_postprocess.py` (delete `snap_endpoints`, `smooth_start`, `enforce_forward_monotonic`; also update the stale `snap_endpoints` cross-reference in any remaining docstring)
+- Modify: `tests/unit/test_postprocess.py` (delete the 6 tests of the removed functions and their two mid-file import lines)
+
+**Interfaces:**
+- Consumes: `soften_forward(forward)` (Task 1), `damp_start(lateral)` (Task 2), `warp_endpoints(forward, lateral)` (Task 3), existing `gaussian_smooth(x, sigma)`.
+
+- [ ] **Step 1: Update `mouse.py` imports**
+
+Replace the import block at `src/ai_mouse/mouse.py:15-24` with:
+
+```python
+from ai_mouse._postprocess import (
+    build_timestamps,
+    damp_start,
+    gaussian_smooth,
+    resample_arc,
+    sample_duration,
+    soften_forward,
+    truncnorm_sample,
+    warp_endpoints,
+)
+```
+
+- [ ] **Step 2: Replace the pipeline**
+
+Replace `src/ai_mouse/mouse.py:106-109`:
+
+```python
+        forward, lateral = snap_endpoints(forward, lateral, self._seq_len)
+        forward, lateral = smooth_start(forward, lateral)
+        forward = enforce_forward_monotonic(forward)
+        lateral = gaussian_smooth(lateral, sigma=1.0)
+```
+
+with:
+
+```python
+        forward = soften_forward(forward)
+        lateral = damp_start(lateral)
+        forward = gaussian_smooth(forward, sigma=1.0)
+        lateral = gaussian_smooth(lateral, sigma=1.0)
+        forward, lateral = warp_endpoints(forward, lateral)
+```
+
+- [ ] **Step 3: Delete replaced functions and their tests**
+
+- In `src/ai_mouse/_postprocess.py`: delete `snap_endpoints` (lines 34-62), `smooth_start` (65-80), `enforce_forward_monotonic` (83-92).
+- In `tests/unit/test_postprocess.py`: delete `test_snap_endpoints_pins_first_and_last`, `test_snap_endpoints_preserves_middle`, `test_smooth_start_dampens_lateral`, `test_enforce_forward_monotonic_repairs_inversions`, `test_enforce_forward_monotonic_clips_to_unit_interval`, and the `from ai_mouse._postprocess import snap_endpoints` / `from ai_mouse._postprocess import enforce_forward_monotonic, smooth_start` import lines.
+
+- [ ] **Step 4: Run the unit suite (golden mouse failures expected)**
+
+Run: `uv run pytest tests/unit -v`
+Expected: everything passes EXCEPT `tests/unit/test_golden.py::test_mouse_golden[...]` cases, which may exceed the path envelope (behavior intentionally changed; re-baselined in Task 6). If anything else fails, fix before committing. In particular `test_mouse.py` (endpoint snap, seed reproducibility, shape) must pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ai_mouse/mouse.py src/ai_mouse/_postprocess.py tests/unit/test_postprocess.py
+git commit -m "feat: rework mouse post-processing pipeline (soft monotonic, global endpoint warp)
+
+Golden mouse baselines temporarily failing; re-captured in follow-up commit.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: Euler → Heun sampling
+
+Second-order predictor-corrector at the same 10 steps (NFE 10 → 20; each call is a small d_model=128 transformer, ~1-2 ms CPU). Reduces integration error and sampling jitter.
+
+**Files:**
+- Modify: `src/ai_mouse/mouse.py:27` (constant), `src/ai_mouse/mouse.py:93-97` (ODE loop)
+
+**Interfaces:**
+- Consumes: the existing ONNX session I/O contract `session.run(["v"], {"x_t", "t", "cond"})` — unchanged.
+
+- [ ] **Step 1: Replace the ODE loop**
+
+Rename the constant at `src/ai_mouse/mouse.py:27`:
+
+```python
+_N_ODE_STEPS = 10
+```
+
+Replace the loop at `src/ai_mouse/mouse.py:93-97`:
+
+```python
+        dt = 1.0 / _N_EULER_STEPS
+        for step in range(_N_EULER_STEPS):
+            t = np.full((1,), step * dt, dtype=np.float32)
+            v = self._session.run(["v"], {"x_t": x, "t": t, "cond": cond})[0]
+            x = x + v * dt
+```
+
+with:
+
+```python
+        # Heun (2nd-order predictor-corrector): same step count as the old
+        # Euler loop but far lower integration error for 2x NFE.
+        dt = 1.0 / _N_ODE_STEPS
+        for step in range(_N_ODE_STEPS):
+            t0 = np.full((1,), step * dt, dtype=np.float32)
+            v1 = self._session.run(["v"], {"x_t": x, "t": t0, "cond": cond})[0]
+            x_pred = (x + v1 * dt).astype(np.float32)
+            t1 = np.full((1,), (step + 1) * dt, dtype=np.float32)
+            v2 = self._session.run(["v"], {"x_t": x_pred, "t": t1, "cond": cond})[0]
+            x = x + (v1 + v2) * (dt / 2.0)
+```
+
+- [ ] **Step 2: Run the unit suite (same expectation as Task 4)**
+
+Run: `uv run pytest tests/unit -v`
+Expected: all pass except `test_mouse_golden` envelope cases (still pending re-baseline). `test_mouse.py::test_mouse_model_seed_reproducibility` must pass — Heun adds no new randomness.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/ai_mouse/mouse.py
+git commit -m "feat: switch flow ODE sampling from Euler to Heun (10 steps, NFE 20)
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 6: Quality regression test, golden re-baseline, CHANGELOG, visual verification
+
+Add a numeric guard against the two artifact classes (sharp turns near the endpoint, vertical walls), re-capture `golden_mouse.npz` from the new implementation (documented procedure in `tests/unit/test_golden.py` docstring), and verify visually.
+
+**Files:**
+- Test: `tests/unit/test_mouse.py` (append)
+- Modify: `tests/unit/data/golden_mouse.npz` (re-captured binary)
+- Modify: `CHANGELOG.md`
+
+**Interfaces:**
+- Consumes: `generate(start, end, *, seed, click)` public API.
+
+- [ ] **Step 1: Write the quality regression test (fails on OLD pipeline, passes on new)**
+
+Append to `tests/unit/test_mouse.py` (note: this file has no module-level
+`numpy`/`generate` imports — the test is self-contained):
+
+```python
+def test_no_sharp_turns_or_walls_near_endpoint() -> None:
+    """Guard against the two endpoint artifact classes:
+
+    - sharp turns (>90°) between consecutive substantial segments in the
+      final approach (the old tail-drag created hooks);
+    - vertical walls: many points stacked at the target's forward
+      position (the old clip(0,1) stacked overshoot at forward=1).
+    """
+    import math
+
+    import numpy as np
+
+    from ai_mouse import generate
+
+    cases = [((100, 300), (900, 350)), ((100, 100), (700, 600)),
+             ((800, 200), (150, 550))]
+    for (start, end) in cases:
+        for seed in range(6):
+            pts = generate(start, end, seed=seed, click=False)
+            arr = np.array([(x, y) for x, y, _ in pts], dtype=float)
+            tail = arr[-12:]
+            seg = np.diff(tail, axis=0)
+            lens = np.linalg.norm(seg, axis=1)
+            # Only consider substantial segments: integer-pixel staircase
+            # on 1-2 px steps produces spurious 90° angles.
+            keep = lens >= 3.0
+            headings = np.arctan2(seg[keep][:, 1], seg[keep][:, 0])
+            if len(headings) >= 2:
+                turns = np.abs(np.diff(np.unwrap(headings)))
+                max_turn = math.degrees(turns.max())
+                assert max_turn < 90.0, (
+                    f"{start}->{end} seed={seed}: {max_turn:.0f}° turn "
+                    f"in final approach"
+                )
+            # Vertical wall: >=4 consecutive tail points within 2 px of
+            # the target x while spanning >10 px of y.
+            near_x = np.abs(tail[:, 0] - end[0]) <= 2.0
+            run = 0
+            for i, flag in enumerate(near_x[:-1]):  # exclude final point
+                run = run + 1 if flag else 0
+                assert run < 4 or np.ptp(tail[near_x][:, 1]) <= 10.0, (
+                    f"{start}->{end} seed={seed}: vertical wall at target x"
+                )
+```
+
+- [ ] **Step 2: Run the new test**
+
+Run: `uv run pytest tests/unit/test_mouse.py::test_no_sharp_turns_or_walls_near_endpoint -v`
+Expected: PASS (the new pipeline removed the artifacts). If it fails, treat it as a real defect in Tasks 1-5 — do not loosen the thresholds; investigate which pipeline step reintroduces the artifact.
+
+- [ ] **Step 3: Re-capture the mouse golden baseline**
+
+Write a throwaway script (scratchpad or temp path, NOT committed):
+
+```python
+# recapture_golden.py — regenerate golden_mouse.npz from new implementation
+import numpy as np
+from ai_mouse import generate
+
+CASES = [
+    ((100, 200), (900, 400)), ((500, 500), (500, 100)),
+    ((200, 600), (800, 200)), ((100, 100), (130, 110)),
+    ((50, 50), (1500, 900)), ((400, 300), (500, 300)),
+    ((300, 300), (700, 700)), ((600, 400), (200, 100)),
+]
+out = {}
+for ci, (s, e) in enumerate(CASES):
+    for seed in range(4):
+        pts = generate(s, e, seed=seed)
+        out[f"case{ci}_seed{seed}"] = np.array(pts, dtype=np.int64)
+np.savez_compressed("tests/unit/data/golden_mouse.npz", **out)
+print(f"wrote {len(out)} golden traces")
+```
+
+Run: `uv run python <path>/recapture_golden.py`
+Expected: `wrote 32 golden traces`
+
+- [ ] **Step 4: Full unit suite must be green**
+
+Run: `uv run pytest tests/unit -v`
+Expected: ALL pass, including all 32 `test_mouse_golden` and all 32 `test_scroll_golden` cases (scroll goldens untouched — if any scroll test fails, something leaked outside mouse scope; stop and investigate).
+
+- [ ] **Step 5: Update CHANGELOG**
+
+Add under the top of `CHANGELOG.md` (after the intro, before `## [0.2.0]`):
+
+```markdown
+## [Unreleased]
+
+### Changed
+
+- Mouse post-processing pipeline reworked to remove endpoint artifacts:
+  hard forward clip → backtrack-tolerant soft monotonic with tanh
+  overshoot compression (`soften_forward`); tail-drag endpoint snapping →
+  whole-curve smoothstep residual correction (`warp_endpoints`); abrupt
+  start damping → continuous smoothstep damping (`damp_start`);
+  gaussian smoothing now applied to both axes.
+- Flow ODE sampling switched from 10-step Euler to 10-step Heun
+  (predictor-corrector); ~2x model calls per trajectory, still ~40 ms CPU.
+- `tests/unit/data/golden_mouse.npz` re-baselined against the new
+  pipeline (intentional behavior change; scroll goldens unchanged).
+```
+
+- [ ] **Step 6: Visual verification (diagnostic plot + Web UI)**
+
+1. Re-run the diagnostic script from the investigation (same 4 cases × 6 seeds; it lives in the session scratchpad as `diag_traj.py`) and visually compare against the "before" plot: no vertical walls in end zoom, no hooks, no start kinks; `turns>45deg` counts in the numeric output should drop sharply vs the before-values (3-8 per trace).
+2. Start the Web UI: `uv run python tools/serve.py`, open the verify page, and have the user visually approve. **This is the final acceptance gate** — post-processing is Python-side, so no ONNX re-export is needed, but the server must be (re)started to pick up the new library code.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add tests/unit/test_mouse.py tests/unit/data/golden_mouse.npz CHANGELOG.md
+git commit -m "test: quality guard for endpoint artifacts; re-baseline mouse goldens
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+## Acceptance summary (from spec)
+
+- [ ] No vertical wall / hooks / start kinks in diagnostic plots (Task 6 step 6)
+- [ ] `turns>45°` count drops sharply vs baseline (was 1-8 per trace)
+- [ ] `uv run pytest tests/unit` fully green, goldens re-baselined
+- [ ] User approves Web UI verify page visually
+- [ ] Out of scope confirmed untouched: scroll subsystem, training code, ONNX assets