From 973b0c7807d64b21d0e18a570a11a96b690037ab Mon Sep 17 00:00:00 2001
From: Kawa <us.fame.sq@gmail.com>
Date: Mon, 13 Apr 2026 11:12:05 +0200
Subject: [PATCH] docs(phase-09): complete phase execution

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .planning/STATE.md                            |   2 +-
 .../09-VERIFICATION.md                        | 173 ++++++++++++++++++
 2 files changed, 174 insertions(+), 1 deletion(-)
 create mode 100644 .planning/phases/09-ux-tech-debt-closure/09-VERIFICATION.md

diff --git a/.planning/STATE.md b/.planning/STATE.md
index aa8b806..81f9b1b 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -4,7 +4,7 @@ milestone: v1.1
 milestone_name: Hardening & Validation
 status: Pending (roadmap approved, plans not yet drafted)
 stopped_at: Completed 09-02-playwright-port-autofill-PLAN.md
-last_updated: "2026-04-13T08:58:40.338Z"
+last_updated: "2026-04-13T09:11:50.029Z"
 last_activity: 2026-04-13 — v1.1 roadmap created, 15/15 requirements mapped across Phases 8–11
 progress:
   total_phases: 4
diff --git a/.planning/phases/09-ux-tech-debt-closure/09-VERIFICATION.md b/.planning/phases/09-ux-tech-debt-closure/09-VERIFICATION.md
new file mode 100644
index 0000000..70c6ac3
--- /dev/null
+++ b/.planning/phases/09-ux-tech-debt-closure/09-VERIFICATION.md
@@ -0,0 +1,173 @@
+---
+phase: 09-ux-tech-debt-closure
+verified: 2026-04-13T00:00:00Z
+status: human_needed
+score: 11/11 must-haves verified
+human_verification:
+  - test: "Start app, open /printers, upload a real driver ZIP via the inline Upload Driver button — do NOT press F5 after upload"
+    expected: "The driver dropdown refreshes automatically (HTMX OOB swap) and the newly uploaded driver is selected in the list without any page reload"
+    why_human: "Automated OOB contract tests verify the HTTP response shape (hx-swap-oob, auto-select option). Only a live browser confirms the actual DOM swap fires correctly and the UX criterion of 'no manual page reload' is met."
+  - test: "Run: pytest tests/e2e/test_port_autofill.py -v --headed — observe the chromium window"
+    expected: "A visible chromium window opens /printers, typing 192.168.1.100 in IP Address causes port_name to auto-populate as IP_192_168_1_100 in real time"
+    why_human: "ROADMAP.md success criterion explicitly requires the behaviour 'observed live in a real browser'. The headless test is permanent regression evidence; the --headed run is the human-visible live confirmation required by UX-02."
+  - test: "Start app, open the printer detail page for a printer with a driver assigned, click each of the 3 download buttons: Download Install Script, Download Uninstall Script, Download Detect Script"
+    expected: "Each click triggers a file download named install.ps1 / uninstall.ps1 / detect.ps1 respectively, with non-empty PowerShell content"
+    why_human: "Integration tests verify the HTTP routes and template link presence. Only a real browser confirms the browser download dialog opens and the downloaded file is correctly named and readable."
+---
+
+# Phase 9: UX Tech Debt Closure Verification Report
+
+**Phase Goal:** The three carried-over UX defects are fixed and live-verified in a real browser so the rolled-out build is the polished one.
+**Verified:** 2026-04-13
+**Status:** human_needed — all automated checks VERIFIED; 3 items require live browser confirmation per ROADMAP.md success criteria
+**Re-verification:** No — initial verification
+
+---
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | POST /drivers/upload never returns HTTP 500 for a valid driver ZIP | VERIFIED | `test_upload_500_regression` (parametrized: plain UTF-8 + BOM UTF-16 LE) in `tests/test_driver_upload.py` |
+| 2 | Uploading a driver from the printer form refreshes the driver select via HTMX OOB swap without a page reload | VERIFIED | `test_upload_returns_oob_when_called_from_form` + `test_upload_oob_autoselects_new_driver` in `tests/test_driver_upload.py` |
+| 3 | The newly uploaded driver is auto-selected in the refreshed select | VERIFIED | `test_upload_oob_autoselects_new_driver` — asserts `<option value="{new_id}" selected` via regex |
+| 4 | Uploading from the standalone /drivers page still returns only the #driver-list fragment (no OOB noise) | VERIFIED | `test_upload_no_oob_from_standalone_drivers_page` — asserts "hx-swap-oob" not in response |
+| 5 | A headless chromium browser loads the printer form, types an IP, and observes port_name auto-populate | VERIFIED | `tests/e2e/test_port_autofill.py::test_port_autofill[chromium]` — 1 passed in 6.76s (commit 322fc20) |
+| 6 | The Playwright test file path is the cited evidence for UX-02 in 09-VALIDATION.md | VERIFIED | 09-VALIDATION.md Wave 0 row `09-02-02` references `pytest tests/e2e/test_port_autofill.py -v` with status green |
+| 7 | The e2e suite runs in isolation from unit tests via --ignore path and has its own live server fixture | VERIFIED | `tests/e2e/conftest.py` provides session-scoped `live_server` fixture; e2e package isolated at `tests/e2e/` |
+| 8 | GET /printers/{id}/scripts/install.ps1 returns 200 with Content-Disposition attachment and non-empty PowerShell body | VERIFIED | `tests/test_script_download.py::TestPs1Routes::test_install_ps1_route` asserts status + header + "Add-Printer" or "$PSScriptRoot" |
+| 9 | GET /printers/{id}/scripts/uninstall.ps1 returns 200 with attachment disposition and uninstall content | VERIFIED | `test_uninstall_ps1_route` asserts "Remove-Printer" in body |
+| 10 | GET /printers/{id}/scripts/detect.ps1 returns 200 with attachment disposition and detect content | VERIFIED | `test_detect_ps1_route` asserts "Get-Printer" in body |
+| 11 | printer_detail.html renders three direct download links for install/uninstall/detect in addition to existing package export buttons | VERIFIED | `tests/test_packages.py::TestCommandPreview::test_detail_page_shows_script_links` asserts all three `.ps1` hrefs; Export section preserved untouched at lines 59-61 of `printer_detail.html` |
+
+**Score:** 11/11 truths verified by automated checks
+
+---
+
+## Required Artifacts
+
+### Plan 09-01 (UX-01)
+
+| Artifact | Status | Evidence |
+|----------|--------|----------|
+| `tests/test_driver_upload.py` | VERIFIED — substantive, wired | Contains `test_upload_500_regression`, `test_upload_returns_oob_when_called_from_form`, `test_upload_oob_autoselects_new_driver`, `test_upload_no_oob_from_standalone_drivers_page` |
+| `imptune/api/drivers.py` | VERIFIED — substantive, wired | Contains `caller: str = Form("")` parameter, branch on `caller == "printer_form"`, full OOB response path; `new_driver, _created = Driver.get_or_create(...)` captured and used |
+| `imptune/templates/partials/driver_upload_with_oob.html` | VERIFIED — substantive, wired | Contains `hx-swap-oob="true"`, `id="printer-form-driver-select"`, `{% if item.driver.id == new_driver_id %}selected{% endif %}` |
+| `imptune/templates/partials/printer_form.html` | VERIFIED — substantive, wired | Contains `id="printer-form-driver-select"` on the select, sibling `<form hx-post="/drivers/upload">` with `name="caller" value="printer_form"`, outside the printer form |
+| `tests/test_printer_form.py` | VERIFIED — substantive, wired | `test_printer_form_has_inline_driver_upload` checks stable select id, caller sentinel, and asserts upload form is NOT nested inside printer form |
+
+### Plan 09-02 (UX-02)
+
+| Artifact | Status | Evidence |
+|----------|--------|----------|
+| `requirements-dev.txt` | VERIFIED | Contains `pytest-playwright` and `playwright` |
+| `tests/e2e/conftest.py` | VERIFIED — substantive, wired | Session-scoped `live_server` fixture: uvicorn thread, free port, /health readiness poll, isolated tmp data dir |
+| `tests/e2e/test_port_autofill.py` | VERIFIED — substantive, wired | `test_port_autofill` function: navigates to `/printers`, fills `ip_address`, waits for Alpine, asserts `port_name == "IP_192_168_1_100"` |
+| `tests/e2e/__init__.py` | VERIFIED | File exists as package marker |
+
+### Plan 09-03 (UX-03)
+
+| Artifact | Status | Evidence |
+|----------|--------|----------|
+| `imptune/api/scripts.py` | VERIFIED — substantive, wired | Contains `scripts/install.ps1`, `scripts/uninstall.ps1`, `scripts/detect.ps1` route aliases backed by shared `_install_response`, `_uninstall_response`, `_detect_response` helpers |
+| `imptune/templates/printer_detail.html` | VERIFIED — substantive, wired | Contains `scripts/install.ps1`, `scripts/uninstall.ps1`, `scripts/detect.ps1` hrefs inside `{% if has_driver %}` guard; existing Export section preserved |
+| `tests/test_script_download.py` | VERIFIED — substantive, wired | Contains `test_install_ps1_route`, `test_uninstall_ps1_route`, `test_detect_ps1_route`, `test_ps1_routes_missing_printer`, `test_ps1_routes_no_driver` |
+| `tests/test_packages.py` (addition) | VERIFIED | `test_detail_page_shows_script_links` present in `TestCommandPreview` |
+
+---
+
+## Key Link Verification
+
+### Plan 09-01
+
+| From | To | Via | Status |
+|------|----|-----|--------|
+| `printer_form.html` | `POST /drivers/upload` | Sibling `<form hx-post="/drivers/upload">` with `name="caller" value="printer_form"` | WIRED — pattern confirmed at lines 87-97 of `printer_form.html` |
+| `imptune/api/drivers.py upload_driver` | `partials/driver_upload_with_oob.html` | `TemplateResponse` when `caller == "printer_form"` | WIRED — branch at lines 113-122 of `drivers.py` |
+| `partials/driver_upload_with_oob.html` | `printer_form.html #printer-form-driver-select` | `hx-swap-oob="true"` on `<select id="printer-form-driver-select">` | WIRED — line 3 of `driver_upload_with_oob.html` |
+
+### Plan 09-02
+
+| From | To | Via | Status |
+|------|----|-----|--------|
+| `tests/e2e/test_port_autofill.py` | `imptune.main:app` (uvicorn thread) | `live_server` fixture yields `http://127.0.0.1:<port>` | WIRED — fixture in `tests/e2e/conftest.py`; test uses `live_server` parameter |
+| `tests/e2e/test_port_autofill.py` | `printer_form.html` Alpine `@input` handler | `page.fill("input[name='ip_address']", ...)` then assert on `port_name` input value | WIRED — `page.fill` + `page.wait_for_function` + `page.input_value("input[name='port_name']")` |
+
+### Plan 09-03
+
+| From | To | Via | Status |
+|------|----|-----|--------|
+| `printer_detail.html` | `GET /printers/{id}/scripts/{install,uninstall,detect}.ps1` | `<a href="/printers/{{ printer.id }}/scripts/install.ps1" role="button">` | WIRED — lines 49-57 of `printer_detail.html` |
+| `imptune/api/scripts.py (.ps1 aliases)` | `render_install`, `render_uninstall`, `render_detect` | Delegation via shared `_install_response`, `_uninstall_response`, `_detect_response` helpers | WIRED — helpers imported and called in each route handler |
+
+---
+
+## Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|-------------|-------------|-------------|--------|----------|
+| UX-01 | 09-01 | After a new driver is uploaded on the printer form, the DriverDesc dropdown refreshes automatically (no manual page reload) | SATISFIED | OOB contract tests green; HTMX OOB wiring verified in template and handler |
+| UX-02 | 09-02 | PRNT-03 Alpine.js IP→port auto-derivation is verified live in a real browser session, with the verification recorded in VALIDATION.md | SATISFIED (automated) / NEEDS HUMAN (live browser per ROADMAP) | Headless Playwright test green (commit 322fc20); live --headed run pending |
+| UX-03 | 09-03 | The printer detail page exposes direct download links for each generated script (install / uninstall / detect) in addition to the package export buttons | SATISFIED | Template links verified; integration tests green; Export section untouched |
+
+All three phase requirements (UX-01, UX-02, UX-03) accounted for. No orphaned requirements.
+
+---
+
+## Anti-Patterns Found
+
+No anti-patterns detected across the modified files:
+
+- `imptune/api/drivers.py` — no TODO/FIXME, no empty implementations, no stub returns
+- `imptune/api/scripts.py` — no TODO/FIXME, no empty implementations
+- `imptune/templates/partials/driver_upload_with_oob.html` — functional template, no placeholders
+- `imptune/templates/partials/printer_form.html` — fully wired, no placeholders
+- `imptune/templates/printer_detail.html` — no TODO/FIXME, no placeholders
+- All test files — substantive assertions, no pass-only or comment-only stubs
+
+**Notable observation:** `09-VALIDATION.md` task status rows were not updated post-execution — Wave 0 checkboxes for 09-01 tasks (driver upload tests) and 09-03 tasks (script download tests) remain `⬜ pending`. This is a documentation gap only, not a code gap. The actual tests exist and are substantive.
+
+---
+
+## Human Verification Required
+
+### 1. UX-01 Live Browser OOB Swap
+
+**Test:** Start the app (`uvicorn imptune.main:app --reload`), navigate to `/printers`, open the "Upload New Driver" section inside the printer form, upload a real driver ZIP. Do NOT press F5.
+
+**Expected:** The driver dropdown refreshes in-place (HTMX OOB swap replaces the select element) and the newly uploaded driver appears pre-selected in the list.
+
+**Why human:** ROADMAP.md success criterion 1 states "sees the new DriverDesc appear in the dropdown without manually reloading the page." Automated tests verify the HTTP response contains the OOB swap markup (`hx-swap-oob="true"`, auto-select option). Only a live browser confirms the DOM swap fires correctly in a real rendering engine and that no page reload occurs.
+
+### 2. UX-02 Live Browser Port Auto-fill
+
+**Test:** Run `pytest tests/e2e/test_port_autofill.py -v --headed` and observe the chromium window that opens.
+
+**Expected:** A visible chromium window opens `/printers`, types `192.168.1.100` into the IP Address field, and the Port Name field auto-populates with `IP_192_168_1_100` in real time without any page action.
+
+**Why human:** ROADMAP.md success criterion 2 requires this "observed live in a real browser and recorded in VALIDATION.md." The headless test is the permanent regression guard; the `--headed` run is the live confirmation. The 09-VALIDATION.md Manual-Only Verifications section explicitly calls for this step.
+
+### 3. UX-03 Live Browser Script Downloads
+
+**Test:** Start the app, navigate to a printer detail page for a printer with a driver assigned, click "Download Install Script," "Download Uninstall Script," and "Download Detect Script" in turn.
+
+**Expected:** Each click triggers a browser file download. The downloaded files are named `install.ps1`, `uninstall.ps1`, and `detect.ps1` respectively and contain non-empty PowerShell script content.
+
+**Why human:** ROADMAP.md success criterion 3 states "can click direct download links for the install, uninstall, and detect scripts individually." Integration tests verify the HTTP routes return 200 with attachment headers and the template renders the hrefs. Only a live browser confirms the download dialog opens and the file content is correct when triggered from the UI.
+
+---
+
+## Gaps Summary
+
+No automated gaps. All 11 must-have truths are VERIFIED by code inspection and test coverage. All key links are WIRED. All three requirements (UX-01, UX-02, UX-03) are mapped and satisfied by implementation evidence.
+
+The phase goal — "three carried-over UX defects are fixed and live-verified in a real browser" — is satisfied on the code and automated-test side. The "live-verified in a real browser" portion of the goal explicitly requires the three human browser confirmations listed above, per ROADMAP.md success criteria.
+
+**Documentation gap (non-blocking):** `09-VALIDATION.md` task status rows for 09-01 and 09-03 tasks remain `⬜ pending` despite the plans completing. The tests exist and pass. Updating the VALIDATION.md status cells is cosmetic housekeeping, not a code gap.
+
+---
+
+_Verified: 2026-04-13_
+_Verifier: Claude (gsd-verifier)_