# ISphereWinHelper First Phase 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 (`- [x]`) syntax for tracking.

**Goal:** Build the first C# read-only Windows helper for `version`, `self_check`, `scan_windows`, and `dump_uia` using the agreed Go/C# JSON boundary.

**Architecture:** The helper is a one-shot CLI process. Go will later send one JSON request on stdin and read one JSON response from stdout. This phase implements only read-only desktop/UIA probing and a PowerShell build script.

**Tech Stack:** C# .NET Framework, `csc.exe`, Windows UI Automation, Python `unittest` wrapper tests.

---

### Task 1: Contract and build test

**Files:**
- Create: `tests/test_win_helper.py`
- Create: `scripts/build-win-helper.ps1`
- Create: `native/ISphereWinHelper/Program.cs`
- Create: `native/ISphereWinHelper/HelperProtocol.cs`
- Create: `native/ISphereWinHelper/WindowScanner.cs`
- Create: `native/ISphereWinHelper/UiaDumper.cs`

- [x] Write a Python unittest that expects `scripts/build-win-helper.ps1` to build `runs/win-helper/ISphereWinHelper.exe`.
- [x] Run the test and verify it fails because the build script/helper does not exist yet.
- [x] Add the minimal C# helper and build script.
- [x] Run the build test and verify it passes.

### Task 2: JSON operation tests

**Files:**
- Modify: `tests/test_win_helper.py`
- Modify: `native/ISphereWinHelper/*.cs`

- [x] Add tests for `version`, `self_check`, `scan_windows`, invalid JSON, and unsupported op.
- [x] Run tests and verify they fail for missing behavior.
- [x] Implement JSON request/response handling and the four first-phase operations.
- [x] Run tests and verify they pass.

### Task 3: Verification

**Files:**
- No new production files.

- [x] Run `python -m unittest discover -s tests -p test_win_helper.py -v`.
- [x] Run `python -m compileall -q tests`.
- [x] Run `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\build-win-helper.ps1`.
- [x] Run direct `version`, `scan_windows`, and dedicated WinForms `dump_uia` JSON requests against the helper.