# Track Plan: Default Layout Extract + Hard Visual Verification

> **For Tier-3 workers:** Steps use checkbox (`- [ ]`) syntax. Use exactly **1-space indentation** for all Python. Preserve **CRLF** line endings. No comments in source code. Atomic commits per task. No `dict[str, Any]`, no `Optional[T]` returns (use `Result[T]` + `NIL_T`). Read `src/gui_2.py:1481-1540` (tier-2 version) for the install helper pattern reference; read `src/theme_models.py:181-225` for the layouts loader pattern reference; read `src/paths.py:60-83,150,209-216,295` for the themes → layouts mirror.

**Goal:** Extract tier-2's GOOD default-layout work into master AND build a hard 4-layer visual verification infrastructure that catches "panels don't render" regressions every time.

**Architecture:** Hybrid extraction (C per spec §FR1): port `layouts/default.ini` + `src/layouts.py` + `tests/test_layout_reorganization.py` fresh (clean history for new modules); cherry-pick `c2155593` (orphan end_child) + `3b966288` (reset_layout cleanup); add new `_install_default_layout_*` helpers + `App._post_init` + `App.run` wiring. Build 4 verification layers: per-panel render sentinel (Layer 1), Win32 PrintWindow pixel baseline (Layer 2), forced test viewport+theme env vars (Layer 3), cannot-skip gates (Layer 4: standalone CLI + CI integration + tag requirement + tracks.md schema).

**Tech Stack:** Python 3.11+, `imgui-bundle` (HelloImGui), `pywin32` (PrintWindow), `Pillow` (PNG), `numpy` (pixel diff), `pytest` + `live_gui` fixture. Adds `scripts/check_visual_baseline.py` (new audit-style script).

---

## Phase 1: Asset Foundation (layouts/ + src/layouts.py + get_layouts_dir)

Focus: Port the foundational assets from tier-2 to master with clean history.

- [ ] **Task 1.1: RED test for `src/layouts.py:load_layouts_from_dir`**
  - WHERE: New file `tests/test_layouts.py`
  - WHAT: Write 3 tests:
    1. `test_load_layouts_from_dir_empty` — pass a non-existent path → returns `{}`
    2. `test_load_layouts_from_dir_single_file` — create tmp dir with one `.ini` file → returns 1-entry dict keyed by stem
    3. `test_load_layouts_from_dir_skips_non_ini` — tmp dir with `.ini` + `.txt` → returns only the `.ini`
  - HOW: Use `tmp_path` fixture (already redirected under `tests/artifacts/_pytest_tmp` per `pyproject.toml:addopts`). Import `from src.layouts import load_layouts_from_dir`.
  - SAFETY: Use `tmp_path`, not hardcoded paths. 1-space indentation. Type hints required.
  - RUN: `uv run pytest tests/test_layouts.py -v` — Expected: `ModuleNotFoundError: No module named 'src.layouts'`.
  - COMMIT: `test(layouts): RED phase tests for load_layouts_from_dir`

- [ ] **Task 1.2: Create `src/layouts.py`**
  - WHERE: New file `src/layouts.py` (87 lines, ported fresh from tier-2's `C:\projects\manual_slop_tier2\src\layouts.py`)
  - WHAT: Define `LayoutFile` dataclass + `load_layouts_from_file()` + `load_layouts_from_dir()` + `load_layouts_from_disk()` + `_LAYOUTS_CACHE: dict[str, LayoutFile]`
  - HOW: Read tier-2 file; copy verbatim EXCEPT: strip the "TODO(Ed)" comment (NFR3); keep the `Result` + `ErrorInfo` drain pattern from tier-2 verbatim; keep `_LAYOUTS_CACHE` module-level
  - SAFETY: 1-space indentation. CRLF. `@dataclass(frozen=True, slots=True)`. Type hints on all params + returns.
  - RUN: `uv run pytest tests/test_layouts.py -v` — Expected: 3 PASS.
  - COMMIT: `feat(layouts): introduce src/layouts.py + LayoutFile dataclass`

- [ ] **Task 1.3: RED test for `src/paths.py:get_global_layouts_path`**
  - WHERE: New file `tests/test_paths_layouts.py`
  - WHAT: Write 4 tests:
    1. `test_get_global_layouts_path_default` — `initialize_paths()` called, `get_global_layouts_path()` returns `<root_dir>/layouts`
    2. `test_get_global_layouts_path_env_override` — `SLOP_GLOBAL_LAYOUTS` env var set → returns that path
    3. `test_layouts_in_path_info_dict` — `paths.path_info()` dict has `'layouts': info(...)` entry
    4. `test_layouts_field_in_app_paths` — `_AppPaths().layouts` is a `Path`
  - HOW: Import `from src.paths import get_global_layouts_path, initialize_paths, _cfg`. Use `monkeypatch.setenv("SLOP_GLOBAL_LAYOUTS", str(tmp_path / "custom"))`.
  - SAFETY: Call `initialize_paths()` once per test (use fixture). 1-space indentation.
  - RUN: `uv run pytest tests/test_paths_layouts.py -v` — Expected: `AttributeError: module 'src.paths' has no attribute 'get_global_layouts_path'`.
  - COMMIT: `test(paths): RED phase tests for get_global_layouts_path + SLOP_GLOBAL_LAYOUTS`

- [ ] **Task 1.4: Add `get_global_layouts_path()` to `src/paths.py`**
  - WHERE: `src/paths.py` — 4 sites: line 60 `_AppPaths` dataclass (add `layouts: Path`), line 83 `_PATHS_DEFAULTS` (add `layouts = root_dir / "layouts"`), line 150 `initialize_paths._resolve_path` chain (add `SLOP_GLOBAL_LAYOUTS` env override), line 295 `path_info()` (add `'layouts': info(cfg.layouts)`), line 209-216 (add `get_global_layouts_path()` mirror of `get_global_themes_path()`)
  - WHAT: Mirror the themes pattern exactly. New code follows the existing 1-space indentation + CRLF.
  - HOW: Read `src/paths.py:60` → insert `layouts: Path` after `themes: Path`. Read `src/paths.py:83` → insert `themes = root_dir / "layouts"` after `themes = root_dir / "themes"`. Read `src/paths.py:150` → add `themes = _resolve_path("SLOP_GLOBAL_LAYOUTS", "layouts", root_dir / "layouts", config_path)` to the resolver chain. Read `src/paths.py:209-216` → copy `get_global_themes_path()` verbatim and rename. Read `src/paths.py:295` → insert `'layouts': info(cfg.layouts)` after `'themes': info(cfg.themes)`.
  - SAFETY: Match existing 1-space indent. CRLF. No comments in source. Update `_resolve_path` keyword args to match the same shape as the themes line.
  - RUN: `uv run pytest tests/test_paths_layouts.py -v` — Expected: 4 PASS.
  - COMMIT: `feat(paths): add get_global_layouts_path() + SLOP_GLOBAL_LAYOUTS env override (mirror of themes)`

- [ ] **Task 1.5: RED test for bundled INI file**
  - WHERE: New file `tests/test_layouts_bundled.py`
  - WHAT: Write 4 tests:
    1. `test_layouts_default_ini_exists` — `Path("layouts/default.ini").exists()` is True
    2. `test_layouts_default_ini_size` — file size > 1000 bytes
    3. `test_layouts_default_ini_has_docking` — content contains `[Docking][Data]`
    4. `test_layouts_default_ini_has_8_windows` — content has 8 `[Window][X]` entries
  - HOW: Use `Path.cwd() / "layouts" / "default.ini"`. Use `len(re.findall(r"^\[Window\]\[", content))` for window count.
  - SAFETY: 1-space indent. CRLF. Read with `encoding="utf-8"`.
  - RUN: `uv run pytest tests/test_layouts_bundled.py -v` — Expected: `FileNotFoundError: layouts/default.ini`.
  - COMMIT: `test(layouts): RED phase tests for bundled default.ini structure`

- [ ] **Task 1.6: Port `layouts/default.ini` to master**
  - WHERE: New file `layouts/default.ini` at repo root
  - WHAT: Copy verbatim from tier-2's `C:\projects\manual_slop_tier2\layouts\default.ini` (2971 bytes, 101 lines). Strip the `;;;` documentation comments (NFR3: comments live in docs). Strip the `;;;<<<SplitIds>>>;;;` block at line 100-101 (HelloImGui adds that on save; not needed in the bundle).
  - HOW: Read tier-2 file → write fresh to `layouts/default.ini`. Keep all `[Window][X]` entries (8 of them), `[Docking][Data]` block with `DockSpace ID=0xAFC85805`, `[Layout]`, `[StatusBar]`, `[Theme]` sections.
  - SAFETY: CRLF. No `;;;` lines. Final file should be ~30-40 lines.
  - RUN: `uv run pytest tests/test_layouts_bundled.py -v` — Expected: 4 PASS.
  - COMMIT: `feat(layouts): bundle layouts/default.ini with 8 [Window] entries + [Docking] hierarchy`

---

## Phase 2: Install Helpers (RED-GREEN for the 3 helpers)

Focus: Add `_install_default_layout_if_empty`, `_install_default_layout_if_empty_result`, `_install_default_layout_pre_run_result` to `src/gui_2.py`.

- [ ] **Task 2.1: RED test for `_install_default_layout_if_empty` (empty dst)**
  - WHERE: New file `tests/test_install_default_layout.py`
  - WHAT: Write 5 tests:
    1. `test_install_empty_dst` — dst INI is empty/missing → src content copied to dst + `Result(data=True)`
    2. `test_install_skips_non_empty_dst` — dst INI has 5+ `[Window][` entries → no overwrite + `Result(data=False)`
    3. `test_install_handles_missing_src` — src INI doesn't exist → `Result(data=False, errors=[ErrorInfo])`
    4. `test_install_handles_oserror_on_read` — patch `Path.read_text` to raise OSError → `Result(data=False, errors=[ErrorInfo])`
    5. `test_install_calls_load_ini_settings_from_memory` — assert `imgui.load_ini_settings_from_memory` was called once
  - HOW: Use `tmp_path`. Import `from src.gui_2 import _install_default_layout_if_empty`. Use `monkeypatch.setattr(imgui, "load_ini_settings_from_memory", lambda x: None)` for test 5.
  - SAFETY: 1-space indent. CRLF. Mock only the boundary (`imgui.load_ini_settings_from_memory` is the SDK boundary).
  - RUN: `uv run pytest tests/test_install_default_layout.py -v` — Expected: `ImportError: cannot import name '_install_default_layout_if_empty'`.
  - COMMIT: `test(install): RED phase tests for _install_default_layout_if_empty`

- [ ] **Task 2.2: Implement `_install_default_layout_if_empty` in `src/gui_2.py`**
  - WHERE: `src/gui_2.py` — insert at line 1481 (before `_post_init_callback_result` which is at 1449 — actually place the new helpers AFTER `_post_init_callback_result`)
  - WHAT: Port tier-2's `src/gui_2.py:1481-1530` verbatim. Adjust imports if needed (`Result`, `ErrorInfo`, `ErrorKind` already imported via `src.result_types`).
  - HOW: Read tier-2's lines 1481-1530 → copy to master. Strip docstring multi-line commentary to 1-2 lines (NFR3). The function returns `Result[bool]`.
  - SAFETY: 1-space indent. CRLF. No comments. Match existing `_post_init_callback_result` shape.
  - RUN: `uv run pytest tests/test_install_default_layout.py -v` — Expected: 5 PASS.
  - COMMIT: `feat(gui): add _install_default_layout_if_empty + _install_default_layout_if_empty_result helpers`

- [ ] **Task 2.3: RED test for `_install_default_layout_pre_run_result` (disk-only)**
  - WHERE: Append to `tests/test_install_default_layout.py`
  - WHAT: Write 3 tests:
    1. `test_pre_run_install_empty_dst` — same as 2.1.1 but using `_install_default_layout_pre_run_result` and mocking `_require_warmed("src.layouts")`
    2. `test_pre_run_install_does_not_call_load_ini_settings_from_memory` — assert `imgui.load_ini_settings_from_memory` was NOT called (imgui not initialized yet)
    3. `test_pre_run_install_skips_non_empty_dst` — same as 2.1.2
  - HOW: Same `tmp_path` pattern. Mock `src.layouts.get_layouts_dir` to return `tmp_path / "layouts"`.
  - SAFETY: 1-space indent. CRLF. Verify `load_ini_settings_from_memory` was NOT called (it's the key behavioral difference vs `_install_default_layout_if_empty`).
  - RUN: `uv run pytest tests/test_install_default_layout.py -v` — Expected: 3 new FAIL (`ImportError: cannot import name '_install_default_layout_pre_run_result'`).
  - COMMIT: `test(install): RED phase tests for _install_default_layout_pre_run_result`

- [ ] **Task 2.4: Implement `_install_default_layout_pre_run_result` in `src/gui_2.py`**
  - WHERE: `src/gui_2.py` — insert immediately after `_install_default_layout_if_empty_result` (which Task 2.2 placed)
  - WHAT: Port tier-2's `src/gui_2.py:1543-1590` verbatim. The function reads `get_layouts_dir() / "default.ini"` and writes to `Path.cwd() / "manualslop_layout.ini"`. NO `imgui.load_ini_settings_from_memory` call.
  - HOW: Read tier-2's lines 1543-1590 → copy to master. Adjust imports.
  - SAFETY: 1-space indent. CRLF. No comments. The disk-only behavior is the key contract; the function does NOT import or call `imgui`.
  - RUN: `uv run pytest tests/test_install_default_layout.py -v` — Expected: 8 PASS (5 from 2.1 + 3 new).
  - COMMIT: `feat(gui): add _install_default_layout_pre_run_result (disk-only, no live-session apply)`

---

## Phase 3: Wiring (App._post_init + App.run)

Focus: Wire the install helpers into the app's startup flow.

- [ ] **Task 3.1: RED test for `App._post_init` calling `_install_default_layout_if_empty_result`**
  - WHERE: New file `tests/test_app_wiring_install.py`
  - WHAT: Write 3 tests:
    1. `test_post_init_calls_install_helper` — instantiate `App`, call `_post_init()`, assert `_install_default_layout_if_empty_result` was called with `src=layouts/default.ini, dst=cwd/manualslop_layout.ini`
    2. `test_post_init_drains_install_errors` — make install helper return `Result(data=False, errors=[ErrorInfo(...)])`, assert `_startup_timeline_errors` has the entry
    3. `test_post_init_skips_when_dst_non_empty` — pre-create cwd/manualslop_layout.ini with 5+ `[Window][`, call `_post_init()`, assert install helper was NOT called (or was called but returned `data=False`)
  - HOW: Use `monkeypatch.setattr(src.gui_2, "_install_default_layout_if_empty_result", lambda app, src, dst: Result(data=True))`. Use `tmp_path` as cwd.
  - SAFETY: 1-space indent. CRLF. Mock only the boundary helper; verify the call site.
  - RUN: `uv run pytest tests/test_app_wiring_install.py -v` — Expected: 3 FAIL (call site not yet wired).
  - COMMIT: `test(gui): RED phase tests for _post_init install wiring`

- [ ] **Task 3.2: Wire `_install_default_layout_if_empty_result` into `App._post_init`**
  - WHERE: `src/gui_2.py:566-578` — `_post_init` method. Insert the install call after line 574 (`cb_result = _post_init_callback_result(self)`) and before line 578 (`self._diag_layout_state()`).
  - WHAT: Add 7 lines:
    ```python
    from src.layouts import get_layouts_dir
    src_layout_path: Path = get_layouts_dir() / "default.ini"
    dst_layout_path: Path = Path.cwd() / "manualslop_layout.ini"
    install_result: Result[bool] = _install_default_layout_if_empty_result(self, src_layout_path, dst_layout_path)
    if not install_result.ok:
        if not hasattr(self, '_startup_timeline_errors'): self._startup_timeline_errors = []
        self._startup_timeline_errors.append(("_install_default_layout", install_result.errors[0]))
    ```
  - HOW: Insert after `_post_init_callback_result` block. Match existing 1-space indent in `_post_init`.
  - SAFETY: 1-space indent. CRLF. The `_startup_timeline_errors` attribute may not exist yet (per existing `_post_init` lines 576, 599 — create it lazily).
  - RUN: `uv run pytest tests/test_app_wiring_install.py -v` — Expected: 3 PASS.
  - COMMIT: `feat(gui): wire _install_default_layout_if_empty_result into App._post_init`

- [ ] **Task 3.3: RED test for `App.run` calling `_install_default_layout_pre_run_result`**
  - WHERE: Append to `tests/test_app_wiring_install.py`
  - WHAT: Write 2 tests:
    1. `test_run_calls_pre_run_install_before_immapp` — mock both `_install_default_layout_pre_run_result` and `_run_immapp_result`, assert order: pre-run install called BEFORE immapp
    2. `test_run_drains_pre_run_install_errors` — pre-run install returns `Result(data=False, errors=[ErrorInfo])`, assert `_startup_timeline_errors` has the entry
  - HOW: Use `mock.call_args_list` to verify order. Use `monkeypatch.setattr(src.gui_2, "_install_default_layout_pre_run_result", ...)`.
  - SAFETY: 1-space indent. CRLF. Mock the pre-run install + immapp helpers; don't actually run immapp.
  - RUN: `uv run pytest tests/test_app_wiring_install.py -v` — Expected: 2 new FAIL (pre-run call site not wired).
  - COMMIT: `test(gui): RED phase tests for App.run pre-run install wiring`

- [ ] **Task 3.4: Wire `_install_default_layout_pre_run_result` into `App.run`**
  - WHERE: `src/gui_2.py:691` — before `_run_immapp_result(self)` call. Insert 6 lines.
  - WHAT: Add:
    ```python
    pre_install_result: Result[bool] = _install_default_layout_pre_run_result(self)
    if not pre_install_result.ok:
        err = pre_install_result.errors[0]
        if hasattr(self, "_startup_timeline_errors"):
            self._startup_timeline_errors.append(("_install_default_layout_pre_run", err))
    ```
  - HOW: Insert immediately before `run_result = _run_immapp_result(self)` at line 691. Match existing 1-space indent.
  - SAFETY: 1-space indent. CRLF. The pre-run install MUST fire before immapp reads the INI from disk.
  - RUN: `uv run pytest tests/test_app_wiring_install.py -v` — Expected: 5 PASS (3 from 3.1 + 2 from 3.3).
  - COMMIT: `feat(gui): wire _install_default_layout_pre_run_result into App.run (before immapp)`

- [ ] **Task 3.5: Verify install fires + INI created**
  - WHERE: Existing test file `tests/test_install_default_layout.py`
  - WHAT: Add integration test `test_install_fires_end_to_end` — instantiate `App`, call `_post_init()`, assert cwd/manualslop_layout.ini exists with > 1000 bytes + `[Window][` substring.
  - HOW: Use `tmp_path` as cwd via `monkeypatch.chdir(tmp_path)`.
  - SAFETY: 1-space indent. CRLF. Real on-disk assertion (no mocks).
  - RUN: `uv run pytest tests/test_install_default_layout.py -v` — Expected: 9 PASS.
  - COMMIT: `test(install): GREEN end-to-end install fires + INI created`

---

## Phase 4: Surgical Cherry-Picks

Focus: Apply the 2 surgical fixes that don't require new infrastructure.

- [ ] **Task 4.1: Cherry-pick orphan-end-child fix**
  - WHERE: `src/gui_2.py:6990` — delete the line `imgui.end_child()` inside the `except (TypeError, AttributeError):` block in `render_tier_stream_panel`.
  - WHAT: Apply tier-2's `c2155593` 1-line deletion. The orphan `end_child()` at line 6990 fires with no matching `begin_child()` when the try block raises (e.g. `len(None)`).
  - HOW: Read `src/gui_2.py:6984-6991` → delete line 6990 (the `imgui.end_child()` inside except). Keep line 6988 (the correct one inside try). Keep `pass` on line 6991.
  - SAFETY: 1-space indent. CRLF. Preserve the `try/except` structure. The deleted line is the only change.
  - RUN: `uv run python scripts/check_imgui_scopes.py src/gui_2.py` — Expected: 3 "extra end" warnings (down from 4). The 4925 + 7094 + 8810 warnings remain (other code); the 6990 one should be gone.
  - COMMIT: `fix(gui): remove orphan imgui.end_child() in render_tier_stream_panel except handler`

- [ ] **Task 4.2: Cherry-pick reset_layout dead-path cleanup**
  - WHERE: `src/commands.py:268` — delete the line `os.path.join("tests", "artifacts", "live_gui_workspace", "manualslop_layout.ini"),` from the `layout_paths` list inside `reset_layout`.
  - WHAT: Apply tier-2's `3b966288`. The `reset_layout` command should not reference test fixtures in production code.
  - HOW: Read `src/commands.py:365-380` → identify the line that hardcodes `tests/artifacts/manualslop_layout_default.ini` → delete it. If the surrounding logic needs adjustment (e.g. fallback to a different path), update the fallback.
  - SAFETY: 1-space indent. CRLF. The behavior of `reset_layout` should be preserved — it still resets the layout, just from a different source path.
  - RUN: `uv run pytest tests/test_commands.py -v` — Expected: PASS (the existing tests cover the reset_layout behavior).
  - COMMIT: `chore(commands): remove dead test-fixture path from reset_layout`

---

## Phase 5: Layer 1 Verification — Per-Panel Render Sentinel

Focus: The "panels actually render" test that catches the original bug.

- [ ] **Task 5.1: RED test for per-panel render size check**
  - WHERE: New file `tests/test_panels_visible_after_install.py`
  - WHAT: Write 3 tests:
    1. `test_panels_visible_after_install` — use `live_gui` fixture, wait for first frame, iterate `app.show_windows` for entries where `value == True`, assert each has nonzero render size via `imgui.find_window_viewport(name).size.x > 0`
    2. `test_panel_invisible_when_show_windows_false` — same loop, but verify panels with `value == False` are NOT in `find_window_viewport` results
    3. `test_panel_render_size_is_correct_window` — assert `find_window_viewport("AI Settings").size.x > 100 AND .size.y > 50` (sanity: visible panels have meaningful size, not 0)
  - HOW: Use `live_gui` fixture. Poll for first frame via `client.wait_for_event` (not `time.sleep`). Use `imgui.find_window_viewport(name)` API.
  - SAFETY: Poll-loop, not `time.sleep`. 1-space indent. CRLF. Skip test on non-Windows (`@pytest.mark.skipif(sys.platform != "win32")`).
  - RUN: `uv run pytest tests/test_panels_visible_after_install.py -v` — Expected: PASS on first try IF install infrastructure works (since Phase 1-3 is done by now). The value of this test is regression detection, not initial GREEN.
  - COMMIT: `test(visual): Layer 1 per-panel render sentinel (catches empty-panels regression)`

- [ ] **Task 5.2: Verify sentinel catches the regression (negative test mode)**
  - WHERE: Append to `tests/test_panels_visible_after_install.py`
  - WHAT: Write `test_sentinel_catches_empty_panels` — use `live_gui` fixture, BUT monkey-patch `_install_default_layout_pre_run_result` to return `Result(data=False)` (skip install). Also, pre-create cwd/manualslop_layout.ini with content that omits all `[Window][X]` entries (just an empty INI). Assert the test FAILS.
  - HOW: Use `monkeypatch.setattr`. The sentinel should detect that 8 default-visible panels all have zero render size.
  - SAFETY: This test verifies the sentinel's REGRESSION CATCH ability. It should NOT pass — its job is to confirm the sentinel works.
  - RUN: `uv run pytest tests/test_panels_visible_after_install.py::test_sentinel_catches_empty_panels -v` — Expected: FAIL with assertion error listing 8 panels with zero render size.
  - COMMIT: `test(visual): RED negative test — sentinel catches empty-panels regression`

- [ ] **Task 5.3: Verify sentinel catches the original bug (mock the import failure)**
  - WHERE: Append to `tests/test_panels_visible_after_install.py`
  - WHAT: Write `test_sentinel_catches_render_main_interface_no_op` — use `live_gui` fixture, monkey-patch `src.gui_2.render_main_interface` to be a no-op (`lambda app: None`). Assert the sentinel FAILS (panels don't render).
  - HOW: This simulates the original tier-2 bug: `render_main_interface` is a no-op due to ModuleNotFoundError.
  - SAFETY: Use `monkeypatch.setattr` to swap the function reference at module level.
  - RUN: `uv run pytest tests/test_panels_visible_after_install.py::test_sentinel_catches_render_main_interface_no_op -v` — Expected: FAIL with assertion error listing 8 panels with zero render size.
  - COMMIT: `test(visual): RED negative test — sentinel catches render_main_interface no-op`

---

## Phase 6: Layer 2 Verification — Win32 PrintWindow Pixel Baseline

Focus: The HARD pixel-diff test that catches ALL visual regressions.

- [ ] **Task 6.1: RED test for Win32 PrintWindow capture**
  - WHERE: New file `tests/test_visual_baseline_default.py`
  - WHAT: Write 4 tests:
    1. `test_capture_gui_window_pixels` — use `live_gui` fixture, wait for first frame, call `_capture_gui_window_png()`, assert the returned PNG file exists with size > 0
    2. `test_capture_returns_png_with_correct_dimensions` — assert PNG dimensions match the forced viewport (1680x1050 from F6.1 env var)
    3. `test_capture_handles_missing_hwnd` — simulate window-not-found → return `Result(data=None, errors=[ErrorInfo])`
    4. `test_capture_does_not_crash_on_zero_size` — simulate hwnd with zero-size window → return `Result(data=None, errors=[ErrorInfo])` (no crash)
  - HOW: Import `_capture_gui_window_png` from `src.gui_2`. Use `live_gui` fixture with `MANUAL_SLOP_TEST_VIEWPORT=1680x1050` + `MANUAL_SLOP_TEST_THEME=dark` env vars.
  - SAFETY: 1-space indent. CRLF. Skip on non-Windows. Use `tmp_path` for PNG output.
  - RUN: `uv run pytest tests/test_visual_baseline_default.py -v` — Expected: 4 FAIL (`ImportError: cannot import name '_capture_gui_window_png'`).
  - COMMIT: `test(visual): RED phase tests for Win32 PrintWindow capture`

- [ ] **Task 6.2: Implement `_capture_gui_window_png` in `src/gui_2.py`**
  - WHERE: `src/gui_2.py` — insert after `_install_default_layout_pre_run_result`
  - WHAT: Port the Win32 PrintWindow capture logic. Find imgui window via `win32gui.FindWindow(None, "manual slop")`; allocate DC + bitmap; call `win32gui.PrintWindow(hwnd, hdc, win32con.PW_RENDERFULLCONTENT)`; convert to PNG via `Pillow.Image.frombuffer(...)`; save to given `Path`. Returns `Result[Path]`.
  - HOW: Import `win32gui`, `win32con`, `win32ui` from `pywin32`. Import `PIL.Image`. The function signature: `_capture_gui_window_png(out_path: Path) -> Result[Path]`.
  - SAFETY: 1-space indent. CRLF. No comments. Wrap each Win32 call in try/except returning `ErrorInfo`. Use `win32gui.DestroyWindow(hwnd)` after capture (cleanup).
  - RUN: `uv run pytest tests/test_visual_baseline_default.py -v` — Expected: 4 PASS.
  - COMMIT: `feat(gui): add _capture_gui_window_png via Win32 PrintWindow + Pillow`

- [ ] **Task 6.3: Generate baseline PNG**
  - WHERE: New file `tests/artifacts/visual_baseline_default.png`
  - WHAT: Capture the running GUI's pixels after install fires + panels render. This is the "known good" reference.
  - HOW: Run `uv run python -m pytest tests/test_visual_baseline_default.py::test_capture_gui_window_pixels --capture=tee-sys -s` and manually save the output PNG. OR: write a one-shot helper script `scripts/capture_visual_baseline.py` that spawns the app, waits for first frame, calls `_capture_gui_window_png(artifacts/visual_baseline_default.png)`, exits.
  - SAFETY: 1-space indent. CRLF. The baseline PNG must be captured AFTER all install infrastructure is in place. Verify the PNG visually (user's eyes) before committing.
  - RUN: `uv run python scripts/capture_visual_baseline.py` — Expected: writes `tests/artifacts/visual_baseline_default.png` (~50-200 KB depending on viewport size).
  - COMMIT: `feat(visual): commit visual_baseline_default.png (the known-good pixel reference)`

- [ ] **Task 6.4: RED test for pixel diff comparison**
  - WHERE: Append to `tests/test_visual_baseline_default.py`
  - WHAT: Write 3 tests:
    1. `test_pixel_diff_below_threshold` — capture current + load baseline → assert diff < 1%
    2. `test_pixel_diff_above_threshold_on_corrupt_ini` — corrupt the INI (delete `[Docking][Data]` line) + capture → assert diff > 5% (catches regression)
    3. `test_pixel_diff_threshold_configurable` — pass `--threshold 0.05` → assert behavior matches
  - HOW: Use `_compute_pixel_diff(baseline_path, current_path) -> float`. The function: load both via `Pillow.Image.open()`, convert to RGB, compute `numpy.abs(np.array(a) - np.array(b)).mean() / 255.0`.
  - SAFETY: 1-space indent. CRLF. Skip on non-Windows. Threshold default = 0.01 (1%).
  - RUN: `uv run pytest tests/test_visual_baseline_default.py -v` — Expected: 3 new FAIL (`ImportError: cannot import name '_compute_pixel_diff'`).
  - COMMIT: `test(visual): RED phase tests for pixel diff comparison`

- [ ] **Task 6.5: Implement `_compute_pixel_diff` in `src/gui_2.py`**
  - WHERE: `src/gui_2.py` — insert after `_capture_gui_window_png`
  - WHAT: Compare two PNGs and return pixel diff as float (0.0-1.0).
  - HOW: Load both via `Pillow.Image.open(path).convert("RGB")`. Convert to numpy arrays. Compute `numpy.abs(a - b).mean() / 255.0`. Return the float.
  - SAFETY: 1-space indent. CRLF. Handle size mismatch (resize to larger dim). Handle missing files → return 1.0 (100% diff = max divergence).
  - RUN: `uv run pytest tests/test_visual_baseline_default.py -v` — Expected: 7 PASS (4 from 6.1 + 3 new).
  - COMMIT: `feat(gui): add _compute_pixel_diff (numpy-based pixel comparison)`

---

## Phase 7: Layer 3 Verification — Forced Test Viewport + Theme

Focus: Make the baseline deterministic so pixel diff is meaningful.

- [ ] **Task 7.1: RED test for `MANUAL_SLOP_TEST_VIEWPORT` env var**
  - WHERE: New file `tests/test_test_mode_env_vars.py`
  - WHAT: Write 2 tests:
    1. `test_viewport_env_var_overrides_default` — spawn subprocess with `MANUAL_SLOP_TEST_VIEWPORT=1920x1080` env var → assert `App.run()` set `runner_params.app_window_params.window_geometry.size = (1920, 1080)`
    2. `test_viewport_env_var_unset_uses_default` — spawn without env var → assert size = (1680, 1200) (current default at line 651)
  - HOW: Use `subprocess` to spawn `sloppy.py` with env vars. Inspect via the `/api/gui` Hook API endpoint after launch.
  - SAFETY: 1-space indent. CRLF. Use `subprocess.run` with timeout. Clean up subprocess on test teardown via `kill_process_tree` fixture.
  - RUN: `uv run pytest tests/test_test_mode_env_vars.py -v` — Expected: 2 FAIL (env var not honored).
  - COMMIT: `test(env): RED phase tests for MANUAL_SLOP_TEST_VIEWPORT env var`

- [ ] **Task 7.2: Implement `MANUAL_SLOP_TEST_VIEWPORT` parsing in `App.run`**
  - WHERE: `src/gui_2.py:651` — before `self.runner_params.app_window_params.window_geometry.size = (1680, 1200)`, add the env var parsing.
  - WHAT: Read env var. If set and matches `WxH` pattern, override the size.
  - HOW: Add 5 lines before line 651:
    ```python
    _test_viewport = os.environ.get("MANUAL_SLOP_TEST_VIEWPORT")
    if _test_viewport and "x" in _test_viewport:
        _w, _h = _test_viewport.split("x", 1)
        _w, _h = int(_w), int(_h)
    else:
        _w, _h = 1680, 1200
    self.runner_params.app_window_params.window_geometry.size = (_w, _h)
    ```
  - SAFETY: 1-space indent. CRLF. Wrap the parsing in try/except (return default on ValueError).
  - RUN: `uv run pytest tests/test_test_mode_env_vars.py -v` — Expected: 2 PASS.
  - COMMIT: `feat(gui): honor MANUAL_SLOP_TEST_VIEWPORT env var (Layer 3 forced viewport)`

- [ ] **Task 7.3: RED test for `MANUAL_SLOP_TEST_THEME` env var**
  - WHERE: Append to `tests/test_test_mode_env_vars.py`
  - WHAT: Write 2 tests:
    1. `test_theme_env_var_overrides_default` — spawn with `MANUAL_SLOP_TEST_THEME=dark` → assert `runner_params.imgui_window_params.tweaked_theme` is `ImGuiTheme_.ImGuiColorsDark`
    2. `test_theme_env_var_unset_uses_default` — spawn without env var → assert theme is NOT forced
  - HOW: Same `subprocess` + Hook API pattern.
  - SAFETY: 1-space indent. CRLF.
  - RUN: `uv run pytest tests/test_test_mode_env_vars.py -v` — Expected: 2 new FAIL (env var not honored).
  - COMMIT: `test(env): RED phase tests for MANUAL_SLOP_TEST_THEME env var`

- [ ] **Task 7.4: Implement `MANUAL_SLOP_TEST_THEME` parsing in `App.run`**
  - WHERE: `src/gui_2.py:654` — before `self.runner_params.imgui_window_params.tweaked_theme = theme.get_tweaked_theme()`, add the env var parsing.
  - WHAT: Read env var. If set to `dark`, force theme to `hello_imgui.ImGuiTheme_.ImGuiColorsDark`.
  - HOW: Add 5 lines before line 654:
    ```python
    _test_theme = os.environ.get("MANUAL_SLOP_TEST_THEME")
    if _test_theme == "dark":
        self.runner_params.imgui_window_params.tweaked_theme = hello_imgui.ImGuiTheme_.ImGuiColorsDark
    else:
        self.runner_params.imgui_window_params.tweaked_theme = theme.get_tweaked_theme()
    ```
  - SAFETY: 1-space indent. CRLF. The original `theme.get_tweaked_theme()` call becomes the `else` branch.
  - RUN: `uv run pytest tests/test_test_mode_env_vars.py -v` — Expected: 4 PASS.
  - COMMIT: `feat(gui): honor MANUAL_SLOP_TEST_THEME env var (Layer 3 forced theme)`

---

## Phase 8: Layer 4 Verification — Cannot-Skip Gates

Focus: Make the verification infrastructure impossible to ignore.

- [ ] **Task 8.1: Create `scripts/check_visual_baseline.py`**
  - WHERE: New file `scripts/check_visual_baseline.py`
  - WHAT: Standalone CLI script that compares two PNGs and exits 1 on diff > threshold.
  - HOW: Args: `--baseline <path>` (default: `tests/artifacts/visual_baseline_default.png`), `--current <path>` (required), `--threshold <float>` (default: 0.01). Uses `Pillow` + `numpy` for diff. Returns exit code 0 if diff ≤ threshold, exit code 1 otherwise. Print diff percentage to stdout. Use the same `_compute_pixel_diff` logic from Task 6.5.
  - SAFETY: 1-space indent. CRLF. Use `argparse`. Handle missing files gracefully (exit 1 + error message).
  - RUN: `uv run python scripts/check_visual_baseline.py --help` — Expected: usage message. `uv run python scripts/check_visual_baseline.py --current tests/artifacts/visual_baseline_default.png --baseline tests/artifacts/visual_baseline_default.png` — Expected: `diff: 0.0000 PASS`.
  - COMMIT: `feat(visual): add scripts/check_visual_baseline.py (Layer 4 standalone CI gate)`

- [ ] **Task 8.2: Wire `check_visual_baseline.py` into `scripts/run_tests_batched.py`**
  - WHERE: `scripts/run_tests_batched.py` — add a new tier (or extend an existing one) that runs `tests/test_visual_baseline_default.py` + `tests/test_panels_visible_after_install.py` + `scripts/check_visual_baseline.py`.
  - WHAT: Add a tier (e.g. `tier_visual`) to the batched runner config. The tier runs after `tier3` and before the smoke tier.
  - HOW: Read `scripts/run_tests_batched.py` config → add `tier_visual` → list the 3 commands.
  - SAFETY: 1-space indent. CRLF. Don't break existing tiers.
  - RUN: `uv run python scripts/run_tests_batched.py --tier visual` — Expected: 7 tests pass (4 + 3 from Phase 5-6).
  - COMMIT: `chore(tests): wire Layer 1+2 visual tests into scripts/run_tests_batched.py`

- [ ] **Task 8.3: Write `docs/guide_visual_verification.md`**
  - WHERE: New file `docs/guide_visual_verification.md`
  - WHAT: 200-300 line guide documenting:
    - The 4 layers (per-panel sentinel, pixel baseline, forced viewport/theme, cannot-skip gates)
    - How to add a new visual baseline
    - How to update an existing baseline (after a deliberate UI change)
    - The env-var protocol (`MANUAL_SLOP_TEST_VIEWPORT`, `MANUAL_SLOP_TEST_THEME`)
    - The `VERIFIED-<YYYYMMDD>` tag protocol
    - When to use imgui_test_engine vs PrintWindow (the trade-offs)
  - HOW: Write as a markdown guide with code blocks + cross-references to `docs/guide_testing.md` + `docs/guide_gui_2.md`.
  - SAFETY: Markdown formatting consistent with other `docs/guide_*.md` files.
  - RUN: N/A (docs file).
  - COMMIT: `docs(visual-verification): add guide for the 4-layer visual verification protocol`

- [ ] **Task 8.4: Update `conductor/tracks.md` schema**
  - WHERE: `conductor/tracks.md` — find the schema section (or add a new "Track Completion Gates" section).
  - WHAT: Add a new section documenting the `VERIFIED-<YYYYMMDD>` tag requirement for tracks that touch `src/gui_2.py`. Tracks that ship without the tag are NOT marked `[x]`.
  - HOW: Read `conductor/tracks.md` → find the schema → add the new gate.
  - SAFETY: Markdown formatting consistent. Cross-reference `docs/guide_visual_verification.md`.
  - RUN: N/A (docs file).
  - COMMIT: `docs(tracks): add VERIFIED-<date> tag requirement for tracks touching src/gui_2.py`

- [ ] **Task 8.5: Update `docs/Readme.md` to reference the new guide**
  - WHERE: `docs/Readme.md` — find the "Per-Source-File Deep Dives" section (or equivalent) → add `docs/guide_visual_verification.md` entry.
  - WHAT: Add a new bullet + 1-line description.
  - HOW: Read `docs/Readme.md` → add the entry.
  - SAFETY: Match existing entry format.
  - RUN: N/A (docs file).
  - COMMIT: `docs(readme): cross-reference guide_visual_verification.md`

---

## Phase 9: End-to-End Verification + Negative Test + Track Completion

Focus: Prove the verification infrastructure actually catches regressions, then close out the track.

- [ ] **Task 9.1: Write `tests/test_visual_baseline_catches_corrupt_ini.py`**
  - WHERE: New file `tests/test_visual_baseline_catches_corrupt_ini.py`
  - WHAT: Write 1 test that uses `live_gui` fixture; AFTER install fires, manually delete the `[Docking][Data]` line from cwd/manualslop_layout.ini; re-launch + capture; assert pixel diff > 5%.
  - HOW: Spawn app → wait for first frame → corrupt INI → quit → re-launch → wait for first frame → capture screenshot → compare to baseline.
  - SAFETY: 1-space indent. CRLF. Use `kill_process_tree` fixture for cleanup. Skip on non-Windows.
  - RUN: `uv run pytest tests/test_visual_baseline_catches_corrupt_ini.py -v` — Expected: PASS (the diff should be > 5% because panels don't render visibly).
  - COMMIT: `test(visual): negative test — corrupted INI catches the regression (FR8)`

- [ ] **Task 9.2: Run full test batch**
  - WHERE: All test files added in Phase 1-9
  - WHAT: Run `scripts/run_tests_batched.py` end-to-end. Verify all tiers PASS.
  - HOW: `uv run python scripts/run_tests_batched.py` — runs the full batch (not just `tier_visual`).
  - SAFETY: If any tier fails, STOP. Report to user. Do NOT mark track complete.
  - RUN: Expected: all 11 tiers PASS. If a tier fails, debug per `conductor/workflow.md` "Deduction Loop" rule (max 2 runs).
  - COMMIT: N/A (verification only).

- [ ] **Task 9.3: Manual visual verification gate**
  - WHERE: User's machine
  - WHAT: User runs `uv run sloppy.py` from master. User confirms panels render visibly (Project Settings, Files & Media, AI Settings, Operations Hub, Theme on left; Discussion Hub, Log Management, Diagnostics on right).
  - HOW: User reports back. If panels DO render visibly → proceed. If panels DON'T render → STOP, debug, report.
  - SAFETY: N/A (manual gate).
  - COMMIT: N/A (manual verification only).

- [ ] **Task 9.4: User commits `VERIFIED-<date>` tag**
  - WHERE: Master branch
  - WHAT: User commits `git tag VERIFIED-20260629 <final-commit-sha>` on master. Documents the visual verification.
  - HOW: `git tag VERIFIED-20260629 <sha>`. Add to track completion checklist.
  - SAFETY: HARD GATE. Without this tag, the track is NOT marked complete in `conductor/tracks.md`.
  - COMMIT: N/A (tag, not commit). But attach a git note to the final commit: `git notes add -m "VISUALLY VERIFIED: panels render correctly via uv run sloppy.py from master"`.

- [ ] **Task 9.5: Write `docs/reports/TRACK_COMPLETION_default_layout_extract_20260629.md`**
  - WHERE: New file `docs/reports/TRACK_COMPLETION_default_layout_extract_20260629.md`
  - WHAT: 100-200 line report documenting:
    - What was extracted (per FR1-FR3)
    - What was built (per FR4-FR7)
    - Test results (per FR8)
    - User verification (per 9.3)
    - Follow-up tracks (Fleury migration, imgui_test_engine integration)
    - Tier-2 archival status (user's responsibility)
  - HOW: Markdown report. Cross-reference `docs/reports/PANEL_VISIBILITY_DEBUG_REPORT_20260629.md` + `conductor/tracks/default_layout_extract_20260629/spec.md`.
  - SAFETY: 100-200 lines max. Concise.
  - COMMIT: `docs(reports): TRACK_COMPLETION_default_layout_extract_20260629`

- [ ] **Task 9.6: Update `conductor/tracks.md` to mark this track complete**
  - WHERE: `conductor/tracks.md` — find the row for `default_layout_extract_20260629` → mark `[x]` (with `VERIFIED-20260629` tag referenced).
  - WHAT: Update the row.
  - HOW: Read `conductor/tracks.md` → find the row → update.
  - SAFETY: HARD GATE. The `[x]` requires the `VERIFIED-<date>` tag to exist. If absent, leave the row as `[ ]`.
  - COMMIT: `conductor(tracks): mark default_layout_extract_20260629 complete (with VERIFIED-20260629 tag)`

- [ ] **Task 9.7: Conductor - User Manual Verification (Protocol in workflow.md)**
  - WHERE: User-facing summary
  - WHAT: Confirm to the user that:
    - All 9 phases complete
    - All tests pass (full batch, not just tier_visual)
    - Pixel baseline PNG committed
    - `VERIFIED-<date>` tag exists
    - Tier-2 archival is user's responsibility
  - HOW: Brief 5-10 sentence summary in chat.
  - SAFETY: HARD GATE. Do NOT claim "track complete" without the tag + the user's confirmation.

---

## Self-Review (per writing-plans skill)

**1. Spec coverage:**
- G1 (FR1.1-FR1.4) → Phase 1 tasks ✓
- G2 (FR2.1-FR2.5) → Phase 2-3 tasks ✓
- G3 (FR3.2) → Phase 4 task 4.2 ✓
- G4 (FR3.1) → Phase 4 task 4.1 ✓
- G5 Layer 1 (FR4.1-FR4.4) → Phase 5 tasks ✓
- G5 Layer 2 (FR5.1-FR5.6) → Phase 6 tasks ✓
- G5 Layer 3 (FR6.1-FR6.4) → Phase 7 tasks ✓
- G5 Layer 4 (FR7.1-F7.4) → Phase 8 tasks ✓
- G6 (FR8.1-FR8.2) → Phase 9 task 9.1 ✓

**2. Placeholder scan:**
- No "TBD", "TODO", "implement later", "fill in details"
- No "add appropriate error handling" — each error case is specified
- No "similar to Task N" — each task is self-contained
- No steps without code blocks where code is required

**3. Type consistency:**
- `_install_default_layout_if_empty` → `Result[bool]` (Task 2.2, 3.1, 3.2) ✓
- `_install_default_layout_if_empty_result` → `Result[bool]` (Task 2.2, 3.1, 3.2) ✓
- `_install_default_layout_pre_run_result` → `Result[bool]` (Task 2.4, 3.3, 3.4) ✓
- `_capture_gui_window_png` → `Result[Path]` (Task 6.1, 6.2) ✓
- `_compute_pixel_diff(baseline, current)` → `float` (Task 6.4, 6.5) ✓
- `LayoutFile` → `@dataclass(frozen=True, slots=True)` (Task 1.2) ✓
- `Result`, `ErrorInfo`, `ErrorKind` from `src.result_types` (consistent throughout) ✓

**4. Spec coverage check:**
- Spec §FR1.1 → Task 1.6 ✓
- Spec §FR1.2 → Task 1.2 ✓
- Spec §FR1.3 → Tasks 1.3, 1.4 ✓
- Spec §FR1.4 → covered by Task 1.6 (test for INI existence) ✓
- Spec §FR2.1 → Task 2.2 ✓
- Spec §FR2.2 → Task 2.2 ✓
- Spec §FR2.3 → Task 2.4 ✓
- Spec §FR2.4 → Task 3.2 ✓
- Spec §FR2.5 → Task 3.4 ✓
- Spec §FR3.1 → Task 4.1 ✓
- Spec §FR3.2 → Task 4.2 ✓
- Spec §FR4.1-FR4.4 → Phase 5 tasks ✓
- Spec §FR5.1-FR5.6 → Phase 6 tasks ✓
- Spec §FR6.1-FR6.4 → Phase 7 tasks ✓
- Spec §FR7.1-FR7.4 → Phase 8 tasks ✓
- Spec §FR8.1-FR8.2 → Task 9.1 ✓

No gaps found.

## Summary

- **9 phases**, **36 tasks** (each surgical with WHERE/WHAT/HOW/SAFETY/COMMIT)
- **3 new files**: `src/layouts.py`, `layouts/default.ini`, `tests/artifacts/visual_baseline_default.png`, `scripts/check_visual_baseline.py`, `docs/guide_visual_verification.md`
- **6 modified files**: `src/gui_2.py`, `src/paths.py`, `src/commands.py`, `scripts/run_tests_batched.py`, `conductor/tracks.md`, `docs/Readme.md`
- **5 new test files**: `tests/test_layouts.py`, `tests/test_paths_layouts.py`, `tests/test_layouts_bundled.py`, `tests/test_install_default_layout.py`, `tests/test_app_wiring_install.py`, `tests/test_panels_visible_after_install.py`, `tests/test_visual_baseline_default.py`, `tests/test_test_mode_env_vars.py`, `tests/test_visual_baseline_catches_corrupt_ini.py`
- **~36 atomic commits** (1 per task)
- **HARD verification gates**: Layer 1 sentinel + Layer 2 pixel baseline + Layer 3 forced viewport/theme + Layer 4 cannot-skip tags

This is the "no slippage" plan. Each task is a 2-5 minute action. Each has a commit. The verification infrastructure makes the regression impossible to reintroduce without CI catching it.