# Track Specification: Default Layout Extract + Hard Visual Verification

## Overview

Extract tier-2's GOOD work on the default layout setup (the `layouts/` directory, the install-on-empty-INI helpers, the pre-run install timing fix, and the orphan-end-child cleanup) into `master`, and replace the previous tier-2 "fake" verification (INI content assertions only) with a HARD 4-layer visual verification protocol that catches the "panels don't render" regression every time it occurs.

## Current State Audit (as of commit `466d2656` on master)

### Branch State Warning

The main working tree at `C:\projects\manual_slop` is currently on branch `tier2/post_module_taxonomy_de_cruft_20260627` (NOT master). This track targets `master`. All line numbers below are from `master` (verified via `git show master:src/gui_2.py`). The cruft-elimination tracks (`module_taxonomy_refactor_20260627` + `post_module_taxonomy_de_cruft_20260627`) are NOT merged to master — they live on tier-2 branches only. This track does NOT depend on those cruft tracks; it depends only on `cruft_elimination_20260627` (which IS merged to master) + the themes infrastructure in `src/paths.py` (which is on master). A separate master worktree exists at `C:\projects\manual_slop_master` for editing on the master branch without disturbing the cruft-branch working tree.

### Already Implemented on Master

- `src/paths.py:60,83,150,209-216` — themes infrastructure (the pattern to mirror for layouts): `themes: Path` field in `_AppPaths`, default `root_dir / "themes"`, env override `SLOP_GLOBAL_THEMES`, getters `get_global_themes_path()` and `get_project_themes_path(project_root)`, plus the path info dict entry at line 295.
- `src/theme_2.py:340-346` + `src/theme_models.py:181-225` — themes loader pair (the pattern to mirror for layouts): `load_themes_from_disk()` calls `get_global_themes_path()` then `load_themes_from_dir(path, scope)`; the latter iterates children, parses, builds typed `@dataclass(frozen=True, slots=True)` records, drains errors via `Result + ErrorInfo`.
- `src/gui_2.py:1776` — `from src.command_palette import render_palette_modal`. **MASTER WORKS**: `src/command_palette.py` EXISTS (165 lines, has `Command`, `ScoredCommand`, `CommandRegistry`, `render_palette_modal`). Tier-2 broke because they deleted `src/command_palette.py` in `module_taxonomy_refactor_20260627` (commit `3dd153f7`, NOT merged to master).
- `src/gui_2.py:580-611` — `_diag_layout_state` (one-shot startup diagnostic that logs `show_windows` count + INI file size + stale window name warnings). Used as the install verification hook.
- `src/gui_2.py:619-703` — `App.run`. Calls `_run_immapp_result(self)` at line 691. HelloImGui reads `runner_params.ini_filename` ("manualslop_layout.ini") from cwd at load_user_pref time, BEFORE `callbacks.post_init` fires.
- `src/gui_2.py:566-578` — `App._post_init`. Calls `_post_init_callback_result` and `_diag_layout_state`. Fires AFTER HelloImGui has loaded the INI from disk.
- `src/gui_2.py:1449-1470` — `_post_init_callback_result` (drain-aware wrapper for `App._post_init`). The pattern Tier-2's `_install_default_layout_if_empty_result` and `_install_default_layout_pre_run_result` follow.
- `src/gui_2.py:1658-1660` — orphan-end-child bug was refactored OUT of `_tier_stream_scroll_sync_result` (the helper that was previously buggy). The orphan at line 6990 (in `render_tier_stream_panel`'s except block) STILL exists on master.
- `src/gui_2.py:6981-6991` — `render_tier_stream_panel` has the latent orphan-end-child bug: `try: ... imgui.end_child()` at line 6988; `except (TypeError, AttributeError): imgui.end_child()` at line 6990. When the try block raises (e.g. `len(None)`), the second `end_child()` fires with no matching `begin_child()` and ImGui emits "In window 'MainDockSpace': Missing End()". Currently latent because `len(content)` rarely raises.
- `tests/conftest.py:700-712` — pre-baked `tests/artifacts/manualslop_layout_default.ini` shipped to fresh test workspaces. Hardcoded path (cwd-relative test fixture) — violates "production code uses cwd-relative paths only" rule.
- `src/commands.py:248-275` — `reset_layout` command with hardcoded `tests/artifacts/live_gui_workspace/manualslop_layout.ini` path at line 268 (dead code in production; references a test-fixture path that doesn't exist in production cwd).
- `conductor/tracks/default_layout_install_20260629/` — Tier-1 track scaffolding from this session. States the user's intent.
- `conductor/tracks/default_layout_install_followup_20260629/` — Tier-1 followup track that supersedes Tier-2's wrong-theory `e9654518` strip-docking fix.

### Already Implemented on Tier-2 Branch (NOT on master)

- `layouts/default.ini` (2971 bytes, 101 lines) — bundled INI with full `[Docking][Data]` hierarchy (DockSpace ID=0xAFC85805 + DockNode 0x00000001 + DockNode 0x00000002 + 8 per-window `DockId=...` entries). Comments document the runtime-generated ID semantics.
- `src/layouts.py` (3178 bytes, 88 lines) — `LayoutFile` dataclass + `load_layouts_from_file()` + `load_layouts_from_dir()` + `load_layouts_from_disk()` (mirrors `src/theme_models.py:181-225` shape exactly).
- `src/gui_2.py:1481-1540` — `_install_default_layout_if_empty` + `_install_default_layout_if_empty_result` (drain-aware wrapper). The function: reads dst INI; if empty (<1000 bytes OR no `[Window][`), reads bundled src INI, writes to dst, calls `imgui.load_ini_settings_from_memory(src_text)` to apply to live session.
- `src/gui_2.py:1543-1590` — `_install_default_layout_pre_run_result`. Same logic but disk-only (no `load_ini_settings_from_memory`) because imgui is not yet initialized before `immapp.run()`. This is the timing fix Tier-2 added after the post-init version was too late for the first session.
- `src/gui_2.py:701-706` — `App.run` wiring: calls `_install_default_layout_pre_run_result(self)` BEFORE `_run_immapp_result(self)`. Drains errors to `_startup_timeline_errors`.
- `src/gui_2.py:579-582` — `App._post_init` wiring: calls `_install_default_layout_if_empty_result(self, src_layout_path, dst_layout_path)`. Drains errors.
- `tests/test_layout_reorganization.py` (66 lines) — RED tests for the install-on-empty-INI behavior (per tier-2 claim "17/17 PASSED"; tests check INI content, not visible panels).

### Gaps to Fill (This Track's Scope)

| Gap | Severity | Layer |
|---|---|---|
| `layouts/` directory + `layouts/default.ini` + `src/layouts.py` missing on master | High | (the assets themselves) |
| `_install_default_layout_if_empty` + `_install_default_layout_pre_run_result` helpers missing on master | High | (the install behavior) |
| `App._post_init` and `App.run` wiring missing on master | High | (the install triggers) |
| `get_layouts_dir()` in `src/paths.py` missing on master | High | (the path resolver; mirrors themes) |
| `reset_layout` command still references dead `tests/artifacts/manualslop_layout_default.ini` path | Medium | cleanup |
| Orphan `imgui.end_child()` at `src/gui_2.py:6990` (latent; fires when tier-stream try-block raises) | Medium | cleanup |
| **No hard verification that panels actually render visually** | Critical | verification infrastructure |

### Tier-2's "Bullshit" We're NOT Extracting

| Commit | Why Skip |
|---|---|
| `e9654518` "strip stale dockspace IDs" | Wrong theory (superseded by `2afb0126`; that one we DO extract) |
| `13ad9d3e` "idk" | Meaningless commit message; bulk-edited `manualslop_layout.ini` |
| `28527851` "artifacts" | Meaningless commit; bulk-edited artifacts |
| `9437af6c` "archive 27 diagnostic scripts" | 27 throwaway scripts not needed in master |
| `4acf8b15`, `b80e5afb`, `c42a7599`, `cf5244b1`, `b1632f46`, `06476c56`, `519e1340`, `cf6a2e20`, `4bf5ecd6`, `5e53d477`, `d4116f19`, `7d5a5492`, `15cd1262`, `23566da8` | Tier-2 internal track-marking commits; we write our own |
| `71028dad` "drop stale `from src.command_palette import`" | Tier-2 specific: master has `src/command_palette.py` so the import WORKS on master. The stale import bug only exists on tier-2 because they deleted the module. **We do not cherry-pick this.** |

### Why the User Wants This Track

The tier-2 track was marked "SHIPPED" based on:
- 17/17 install/layout tests PASS (which only check INI content, not visible panels)
- Manual launch produces a 3072-byte INI with correct structure (content check, not visible check)
- "the imgui core loader rejected the literal IDs from the bundled INI because the runtime IDs didn't match" — claim contradicted by post-fix INI matching runtime IDs

**None of those commits empirically verified visible panels after install.** The user wants this regression to never happen again. The previous tier-2 "fake" verification must be replaced by a HARD one.

## Goals

**G1.** Master has `layouts/default.ini` + `src/layouts.py` + `get_layouts_dir()` so the app boots with a non-empty INI on first launch.

**G2.** Master has `_install_default_layout_if_empty` + `_install_default_layout_pre_run_result` wired into `App._post_init` + `App.run` so empty-INI detection + install-on-empty works at both phases (live session + first session).

**G3.** Master has `reset_layout` cleaned up to remove the dead test-fixture path (no more `tests/artifacts/...` in production code).

**G4.** Master has the orphan `imgui.end_child()` at `src/gui_2.py:6990` removed.

**G5.** Master has a HARD 4-layer visual verification infrastructure:
- **Layer 1 (Per-Panel Sentinel)**: a `tests/test_panels_visible_after_install.py` test that asserts every `show_windows[k]==True` panel has nonzero render size after first frame.
- **Layer 2 (Win32 PrintWindow Pixel Baseline)**: a `tests/test_visual_baseline_default.py` test that captures the running GUI window's pixels via Win32 `PrintWindow` API and compares against `tests/artifacts/visual_baseline_default.png` with <1% pixel-diff tolerance. Catches ALL visual regressions (empty workspace, wrong INI, missing panels, overlap, theme corruption).
- **Layer 3 (Forced Test Viewport + Theme)**: `MANUAL_SLOP_TEST_VIEWPORT=1680x1050` + `MANUAL_SLOP_TEST_THEME=dark` env vars honored at startup. Forces fixed viewport + known theme so the baseline PNG is deterministic.
- **Layer 4 (Cannot-Skip Gates)**: `scripts/check_visual_baseline.py` (exits 1 if pixel diff > 1%); wire into `scripts/run_tests_batched.py`; require `git tag VERIFIED-<YYYYMMDD>` on the merge commit; `conductor/tracks.md` schema update so `[x]`-completion requires the tag.

**G6.** A regression test demonstrates that the verification infrastructure catches the original "panels don't render" bug (negative test: corrupt the installed INI, verify the sentinel + pixel baseline both fail).

## Functional Requirements

### FR1. Tier-2 Asset Extraction (Hybrid Approach C)
- F1.1. Port `layouts/default.ini` fresh from tier-2's `C:\projects\manual_slop_tier2\layouts\default.ini` (2971 bytes, 101 lines) to `layouts/default.ini` at master repo root. Rationale: clean history for new asset; user-facing content.
- F1.2. Port `src/layouts.py` fresh from tier-2's `C:\projects\manual_slop_tier2\src\layouts.py` (88 lines). Mirrors `src/theme_models.py:181-225` shape. Rationale: clean history for new module; matches `src/theme_2.py` + `src/theme_models.py` pair.
- F1.3. Add `get_layouts_dir()` to `src/paths.py` mirroring `get_global_themes_path()` at line 209. Add `layouts: Path` field to `_AppPaths` (line 60), default `root_dir / "layouts"` (line 83), env override `SLOP_GLOBAL_LAYOUTS` (line 150), path info dict entry (line 295). User explicitly authorized "make a layouts directory similar to the themes directory" in the prior session.
- F1.4. Port `tests/test_layout_reorganization.py` fresh from tier-2 (66 lines). Rationale: tests for the install helpers.

### FR2. Install Helpers + Wiring
- F2.1. Add `_install_default_layout_if_empty(src_ini: Path, dst_ini: Path) -> Result[bool]` to `src/gui_2.py` (per tier-2 line 1481). Reads dst; if empty (<1000 bytes OR no `[Window][`), copies src→dst and calls `imgui.load_ini_settings_from_memory(src_text)` to apply to live session.
- F2.2. Add `_install_default_layout_if_empty_result(app: "App", src: Path, dst: Path) -> Result[bool]` (per tier-2 line 1530). Drain-aware passthrough wrapper.
- F2.3. Add `_install_default_layout_pre_run_result(app: "App") -> Result[bool]` (per tier-2 line 1543). Disk-only install (no `load_ini_settings_from_memory`); imgui isn't initialized yet.
- F2.4. Wire `_install_default_layout_if_empty_result` into `App._post_init` (line 566-578). Source path: `get_layouts_dir() / "default.ini"`. Dst path: `Path.cwd() / "manualslop_layout.ini"`. Drain errors to `_startup_timeline_errors`.
- F2.5. Wire `_install_default_layout_pre_run_result` into `App.run` (line 619-703, insert before line 691 `_run_immapp_result(self)`). Drain errors to `_startup_timeline_errors`.

### FR3. Surgical Cherry-Picks
- F3.1. Cherry-pick `c2155593 fix(gui): remove orphan imgui.end_child() in render_tier_stream_panel except handler`. Apply the 1-line deletion to `src/gui_2.py:6990`. Tier-2 verified this fixes an imgui "Missing End()" error in MainDockSpace when the tier-stream try-block raises. Latent on master but real.
- F3.2. Cherry-pick `3b966288 chore(commands): remove dead test-fixture path from reset_layout`. Apply the deletion to `src/commands.py:268` (the `tests/artifacts/live_gui_workspace/manualslop_layout.ini` hardcoded path in the `layout_paths` list).

### FR4. Layer 1 — Per-Panel Render Sentinel
- F4.1. New test file `tests/test_panels_visible_after_install.py`. Imports `live_gui` fixture from `tests/conftest.py`.
- F4.2. RED: assert that for each `show_windows[k]==True` entry, after first frame, `imgui.find_window_viewport(k).size.x > 0 AND .size.y > 0`. Test should fail on the current baseline (we don't have the install helpers yet) — confirms sentinel catches the regression.
- F4.3. GREEN: with the install helpers in place (FR2), test passes.
- F4.4. Test must use poll-loop (not `time.sleep`) per `conductor/workflow.md` "Async Setters Need Poll-For-State".

### FR5. Layer 2 — Win32 PrintWindow Pixel Baseline
- F5.1. New test file `tests/test_visual_baseline_default.py`. Imports `live_gui` fixture.
- F5.2. Capture: import `win32gui` from `pywin32`; find imgui window HWND via `win32gui.FindWindow(None, "manual slop")`; allocate DC + bitmap; call `win32gui.PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT)`; convert bitmap to PNG via `Pillow` (already a dep); save to `tests/artifacts/<test_session>_<date>.png`.
- F5.3. Baseline: commit `tests/artifacts/visual_baseline_default.png` (the "known good" reference). Generated AFTER F5.1 + F5.2 are GREEN against the new install infrastructure.
- F5.4. Compare: load baseline + current via `Pillow.Image.open(...)`; convert to RGB; compute pixel diff via `numpy.abs(np.array(a) - np.array(b)).mean() / 255.0`. Threshold: 0.01 (1%). Fail if > 1%.
- F5.5. RED: with the install infrastructure removed, the test must fail. Confirms the test catches the regression.
- F5.6. Test must poll for first frame + capture screenshot AT MOST ONCE (don't spam captures).

### FR6. Layer 3 — Forced Test Viewport + Theme
- F6.1. Add `MANUAL_SLOP_TEST_VIEWPORT=1680x1050` env var support to `App.run` (line 619). If set, override `self.runner_params.app_window_params.window_geometry.size` to the env-var value (parsed as `WxH`).
- F6.2. Add `MANUAL_SLOP_TEST_THEME=dark` env var support to `App.run` (line 619). If set, force `self.runner_params.imgui_window_params.tweaked_theme = ImGuiTheme_.ImGuiColorsDark` (the default dark theme).
- F6.3. RED: write `tests/test_test_mode_env_vars.py` that asserts both env vars are honored when set (via `live_gui` fixture with env vars).
- F6.4. GREEN: implement the env-var parsing in `App.run`.

### FR7. Layer 4 — Cannot-Skip Gates
- F7.1. New file `scripts/check_visual_baseline.py`. Imports `live_gui` (no — too heavy for a CLI script). Instead, accepts `--baseline <path>` + `--current <path>` + `--threshold <float>` CLI args. Uses `Pillow.Image.open()` + `numpy.abs(...).mean()` to compute diff. Exits 1 if diff > threshold.
- F7.2. Add `scripts/check_visual_baseline.py` to `scripts/run_tests_batched.py` tier-2 test list (or a new tier dedicated to visual regression).
- F7.3. Document the `VERIFIED-<YYYYMMDD>` git-tag requirement in `conductor/tracks.md` schema section. Tracks that touch `src/gui_2.py` MUST carry the tag for `[x]`-completion.
- F7.4. New doc `docs/guide_visual_verification.md` (200-300 lines). Documents the 4 layers, how to add a new visual baseline, how to update an existing baseline, the env-var protocol, the tag protocol.

### FR8. Negative Test (Regression Catch Demonstration)
- F8.1. New test file `tests/test_visual_baseline_catches_corrupt_ini.py`. Uses `live_gui` fixture; AFTER the install infrastructure has run, manually corrupt the installed INI (delete `[Docking][Data]` line). Re-launch + capture screenshot. Verify pixel diff > 5% (the corrupted INI shows empty workspace, baseline shows full panels).
- F8.2. Negative test must run in a separate `pytest` session (not pollute `live_gui` state).

## Non-Functional Requirements

### NFR1. Atomic Per-Task Commits
Every Phase task results in exactly ONE atomic commit. No batched commits. Per `AGENTS.md` "Critical Anti-Patterns" — "Do not batch commits - commit per-task for atomic rollback".

### NFR2. TDD Red-First
Every implementation task has a preceding RED test task. Per `conductor/workflow.md` "Standard Task Workflow" §4.

### NFR3. No Comments in Source Code
Per `AGENTS.md` "Critical Anti-Patterns" — "Do not add comments to source code; documentation lives in /docs".

### NFR4. No Diagnostic Noise in Production
Per `AGENTS.md` "Critical Anti-Patterns" — diag stderr goes to `tests/artifacts/*.diag.log` or `/tmp`, NOT `src/*.py`.

### NFR5. 1-Space Indentation
Per `conductor/workflow.md` "Code Style (MANDATORY - Python)" — exactly 1 space per level for ALL Python code.

### NFR6. CRLF Line Endings on Windows
Per `conductor/workflow.md` "Code Style (MANDATORY - Python)" — preserve CRLF.

### NFR7. Type Hints Required
Per `conductor/product-guidelines.md` "AI-Optimized Compact Style" — strict type hints on all parameters, return types, globals.

### NFR8. No `dict[str, Any]` / `Optional[T]` in Non-Boundary Code
Per `conductor/code_styleguides/data_oriented_design.md` §8.5 + `python.md` §17. Typed `@dataclass(frozen=True, slots=True)` + `Result[T]` + `NIL_T`.

### NFR9. ImGui Defer Patterns
Per `conductor/code_styleguides/python.md` — use `imscope` context managers over manual `imgui.begin/end` pairs (where applicable). Existing manual pairs in `src/gui_2.py` are unchanged.

### NFR10. Manual Slop MCP Tools Only
Per the system prompt — use `manual-slop_*` MCP tools, NOT native `read`/`edit`/`grep` (where the MCP equivalents are available). When MCP tools aren't available (which is the case for this Tier-1 track creation), native `read`/`edit`/`grep`/`write` are the fallback.

## Architecture Reference

- **`docs/guide_gui_2.md`** §"App class lifecycle" + §"_post_init + App.run" — current rendering flow; where the install helpers slot in.
- **`docs/guide_architecture.md`** §"Thread domains, event system" — confirms main thread owns `App.run`; install helpers run on main thread (no thread-safety concerns).
- **`docs/guide_testing.md`** §"`live_gui` fixture" + §"Puppeteer pattern" + §"Structural Testing Contract" — the live_gui fixture is the test harness for FR4-FR8.
- **`conductor/code_styleguides/data_oriented_design.md`** §8.5 — the Python Type Promotion Mandate. Bound by NFR8.
- **`conductor/code_styleguides/error_handling.md`** — `Result[T]` + `ErrorInfo` + `ErrorKind` usage. The install helpers return `Result[bool]` per this styleguide.
- **`conductor/code_styleguides/type_aliases.md`** — `Metadata = TrackMetadata` etc. The new `LayoutFile` dataclass follows the typed-record pattern from this styleguide.
- **`conductor/code_styleguides/feature_flags.md`** — "delete to turn off" (file presence) for the bundled INI. If `layouts/default.ini` is deleted, `_install_default_layout_if_empty` returns `Result(data=False)` (no install).
- **`docs/guide_visual_verification.md`** (NEW, FR7.4) — the documentation deliverable.

## Out of Scope

1. **Fleury declarative view-constructs migration** (`PANELS: tuple[PanelDef, ...]`). Logged in `default_layout_install_20260629/metadata.json` `deferred_to_followup_tracks[0]`. Requires its own track.
2. **imgui_test_engine integration** (`test_engine_integration_20260627`). Provides pixel-level diff via `ctx.capture_screenshot_window()`. Our Win32 PrintWindow approach is simpler + works without test engine. The two approaches are complementary; layering them is a future task.
3. **Reverting tier-2's working tree state**. User's responsibility per the Inherited-Cruft rule. Tier-2's `git status` shows uncommitted `manual_slop.toml` + `manual_slop_history.toml` deletions; user must explicitly handle those.
4. **Cross-platform pixel diff** (Linux/macOS). Win32 PrintWindow is Windows-only. The track ships Windows-only; CI on Linux/macOS would skip FR5 (marked `@pytest.mark.skipif(sys.platform != "win32")`).
5. **Pre-baked test INI shipped from `tests/conftest.py:700-712`**. Replaced by FR5.3 baseline PNG.
6. **`render_persona_editor_window` bug** at `src/gui_2.py:3433+` (opens + immediately closes the Persona Editor window when not embedded). Pre-existing; unrelated to panel visibility. Logged for followup.

## Coordination with Pending Tracks

- **`default_layout_install_20260629/`** — supersedes. Tier-1 scaffolding for this work. The plan.md tasks here replace `conductor/tracks/default_layout_install_20260629/plan.md`.
- **`default_layout_install_followup_20260629/`** — supersedes. The followup plan assumed tier-2's `e9654518` INI strip was the right fix; this track's plan supersedes that with the hybrid extraction.
- **`test_engine_integration_20260627`** — independent. Not blocked by, does not block this track. May consume the env-var protocol (FR6.1 + F6.2) once integrated.
- **`panel_defs_fleury_migration_20260629`** (deferred) — future. Will consume `LayoutFile` + `get_layouts_dir()` from this track.

## Verification Criteria (Track Completion Gates)

- [ ] All Phase 1-9 tasks committed (atomic per-task)
- [ ] `tests/test_panels_visible_after_install.py` passes (Layer 1 sentinel)
- [ ] `tests/test_visual_baseline_default.py` passes (Layer 2 pixel diff < 1%)
- [ ] `tests/test_test_mode_env_vars.py` passes (Layer 3 env vars honored)
- [ ] `tests/test_visual_baseline_catches_corrupt_ini.py` passes (FR8 negative test)
- [ ] `scripts/check_visual_baseline.py --help` works; `--strict` mode exits 1 on diff > 1%
- [ ] `scripts/run_tests_batched.py` includes the visual verification tests
- [ ] `tests/artifacts/visual_baseline_default.png` is committed to master
- [ ] `docs/guide_visual_verification.md` is committed; cross-referenced from `docs/Readme.md`
- [ ] `conductor/tracks.md` schema updated to require `VERIFIED-<YYYYMMDD>` tag for `[x]`-completion of tracks touching `src/gui_2.py`
- [ ] **MANUAL GATE**: user runs `uv run sloppy.py` from master, confirms panels render visibly. User commits the `VERIFIED-<date>` tag.
- [ ] `docs/reports/TRACK_COMPLETION_default_layout_extract_20260629.md` committed
- [ ] Tier-2 branch status: marked for archival (user's responsibility per AGENTS.md "Inherited-Cruft")

## Scope Summary (per workflow.md "Tier 1 Track Initialization Rules")

- **Scope**: 9 phases, ~36 tasks
- **Files touched**: ~12 (3 new: `src/layouts.py`, `layouts/default.ini`, `tests/artifacts/visual_baseline_default.png`, `scripts/check_visual_baseline.py`, `docs/guide_visual_verification.md`; 6 modified: `src/gui_2.py`, `src/paths.py`, `src/commands.py`, `tests/test_layout_reorganization.py`, `tests/test_panels_visible_after_install.py` (new), `tests/test_visual_baseline_default.py` (new), `tests/test_test_mode_env_vars.py` (new), `tests/test_visual_baseline_catches_corrupt_ini.py` (new), `scripts/run_tests_batched.py`, `conductor/tracks.md`, `docs/Readme.md`)
- **Sites modified**: ~15 (in `_post_init`, `App.run`, `_install_default_layout_*`, `_diag_layout_state`, etc.)
- **Tasks**: ~36

## Risk Register

- **R1** — Win32 PrintWindow may fail for the imgui-bundle HelloImGui window (HWND lookup or print flags). **Mitigation**: pre-flight check `win32gui.IsWindow(hwnd)` before capture; fall back to `BitBlt` of the screen region.
- **R2** — Pixel baseline may be too sensitive (font hinting, GPU driver variations). **Mitigation**: tolerance is 1%; if false positives appear, raise to 2% and document.
- **R3** — Forced viewport env var may not work on multi-monitor systems. **Mitigation**: scope the env var to test fixtures only (`tests/conftest.py` sets it before spawning).
- **R4** — Tier-2 sandbox has uncommitted edits that may conflict when cherry-picking. **Mitigation**: cherry-pick to master directly (master is clean); tier-2 archival is user's responsibility.
- **R5** — User-visible panel rendering depends on `_install_default_layout_pre_run_result` firing BEFORE `immapp.run`. If the user's cwd already has a valid `manualslop_layout.ini`, the install is skipped. The pixel baseline test must run with cwd-deleted `manualslop_layout.ini` to exercise the install path. **Mitigation**: `live_gui` fixture already cleans cwd before spawning.