--- phase: 10-cutover-cleanup plan: 04 subsystem: debug-build-trigger tags: [phase-10, cutover-cleanup, wave-4, debug-trigger, test-02] requires: - cmake/version.cmake (10-01 — MICMAP_VERSION SSoT; lives upstream of MICMAP_DEBUG_BUILD plumbing) - driver/src/http_server.cpp (existing /button block — Task 2's /debug/trigger registers nearby; 10-05 deletes /button) - driver/src/command_queue.hpp (TapCommand{} producer surface — same wire as /button uses) - src/steamvr/include/micmap/steamvr/driver_api.hpp (existing IDriverApi — Task 3 appends debugTrigger) - src/steamvr/src/driver_api.cpp (existing DriverApi class — Task 3 appends method impl) - apps/micmap/main.cpp WinMain (existing CLI parses + FAIL-04 mutex from 10-03 — Task 4 inserts short-circuit between) - apps/mic_test/main.cpp:150 tryRunReplayCli (P9-04 — verbatim short-circuit pattern for Task 4) provides: - MICMAP_DEBUG_BUILD per-build-config compile define on driver_micmap, micmap, AND micmap_steamvr targets via target_compile_definitions(... "MICMAP_DEBUG_BUILD=$,1,0>") - POST /debug/trigger HTTP endpoint registered #if MICMAP_DEBUG_BUILD on driver_micmap; pushes TapCommand{} to existing CommandQueue (same producer pattern as deleted-soon /button) - DebugTriggerResult struct {Ok, HttpError, ConnectionRefused} #if MICMAP_DEBUG_BUILD on IDriverApi public surface - virtual IDriverApi::debugTrigger() = 0 method #if MICMAP_DEBUG_BUILD - DriverApi::debugTrigger() impl using cpp-httplib client.Post("/debug/trigger") with 250ms connection timeout (matches P8 D-09 cadence) - tryRunDebugTriggerCli() helper + WinMain short-circuit in apps/micmap/main.cpp (#if MICMAP_DEBUG_BUILD); ExitProcess 0/1/2 per HTTP outcome - Verified Release-build elision: byte-scan of build/bin/Release/micmap.exe shows 0 instances of the wide-string `--debug-trigger`; Debug build shows 4 (literal + error messages) affects: - CMakeLists.txt (root — comment block above include(cmake/version.cmake) documenting Pitfall 4 / lockstep target requirement) - driver/CMakeLists.txt (target_compile_definitions extended with MICMAP_DEBUG_BUILD genex) - apps/micmap/CMakeLists.txt (target_compile_definitions extended with MICMAP_DEBUG_BUILD genex) - src/steamvr/CMakeLists.txt (NEW target_compile_definitions block — PUBLIC propagation so consumers see the same vtable shape) - driver/src/http_server.cpp (POST /debug/trigger handler added; SVR-05 invariant preserved) - src/steamvr/include/micmap/steamvr/driver_api.hpp (DebugTriggerResult struct + virtual debugTrigger) - src/steamvr/src/driver_api.cpp (DriverApi::debugTrigger impl) - apps/micmap/main.cpp (#include in #if-guarded block; tryRunDebugTriggerCli function; WinMain short-circuit insertion) tech-stack: added: [] patterns: - "Per-build-config compile define via $,1,0> generator expression — multi-config-safe (MSBuild/Xcode evaluate per-build, vs the broken if(CMAKE_BUILD_TYPE STREQUAL \"Debug\") form which is only set on single-config generators). The quoting around the entire string is required so CMake's list-element semicolons don't split the inner $." - "Pair-target define hygiene (Pitfall 4 mitigation): MICMAP_DEBUG_BUILD lands on driver_micmap PRIVATE, micmap PRIVATE, and micmap_steamvr PUBLIC — three target_compile_definitions blocks all using the same genex literal. PUBLIC on the steamvr lib is required because driver_api.hpp's #if guard means the consumer's vtable view of IDriverApi must agree with the impl's vtable; PRIVATE-only would let a Release consumer link against a Debug lib (or vice versa) and skew the vtable shape across the boundary." - "Same-thread HTTP-handler producer (SVR-05): POST /debug/trigger pushes TapCommand{} directly onto queue_ (the existing CommandQueue&), which RunFrame drains on the driver thread. The HTTP thread never touches OpenVR API surface — AssertHttpServerNoVrApi lint enforces. Mirrors the v1.5 /button handler shape verbatim except for the JSON parse (the synthetic flow is body-less in v1.6 per Discretion §parameterization)." - "Structural Release elision via #if MICMAP_DEBUG_BUILD: not only is the route handler / method impl elided, but the public types (DebugTriggerResult struct, virtual debugTrigger declaration on IDriverApi) AND the consumer call site (tryRunDebugTriggerCli + WinMain block + include) are all #if'd. Release callers cannot construct a DebugTriggerResult or call debugTrigger() because neither type-name nor method-name exists in the translation unit. Verified by Python byte-scan: 0 wide-string `--debug-trigger` instances in build/bin/Release/micmap.exe vs 4 in the Debug counterpart." - "ASCII-flag CommandLineToArgvW pattern for early CLI short-circuit (P9-04 carryover): parse argv early in WinMain, instantiate the minimal driver client via the existing factory, ExitProcess before any GUI/D3D init. The short-circuit returns -1 if the flag is absent so WinMain falls through to the GUI; this is the same convention used by tryRunReplayCli in apps/mic_test/main.cpp:150." key-files: created: - .planning/phases/10-cutover-cleanup/10-04-SUMMARY.md modified: - CMakeLists.txt - driver/CMakeLists.txt - apps/micmap/CMakeLists.txt - src/steamvr/CMakeLists.txt - driver/src/http_server.cpp - src/steamvr/include/micmap/steamvr/driver_api.hpp - src/steamvr/src/driver_api.cpp - apps/micmap/main.cpp decisions: - "POST /debug/trigger handler omits the 503 fallback that the plan body proposed. The plan's verbatim handler shape used `if (commandQueue_) { ... } else { res.status = 503; }`, but the actual http_server.cpp member is `queue_` — a `CommandQueue&` (a reference, not a pointer), constructed in the ctor's member-init list and non-null for the lifetime of HttpServer. The 503 path is unreachable; the handler reduces to a straight-line `queue_.push(TapCommand{}); res.status = 200; res.set_content(R\"({\"ok\":true})\", ...)`. The /button reference handler that this mirrors uses the same direct queue_.push() shape (no null-guard there either) — the 503 envelope was a draft inconsistency." - "MICMAP_DEBUG_BUILD propagation on src/steamvr is PUBLIC, not PRIVATE. The plan body suggested PRIVATE-with-redeclarations but PUBLIC is structurally simpler and prevents a class of skew bugs: with PRIVATE, a consumer that links against a Debug-built micmap_steamvr.lib but compiles its own TUs in Release would see a no-method view of IDriverApi while the lib's vtable would have the method — a UB-shaped boundary mismatch. With PUBLIC, the define propagates into every consumer's TU (apps/micmap, hmd_button_test, tests) so the view is always self-consistent. The plan's `` for Task 1 explicitly noted 'PRIVATE on the steamvr lib + PRIVATE re-declarations on driver+micmap is the cleanest shape' — but PRIVATE re-declarations are exactly the copy-paste error Pitfall 4 warns against. PUBLIC is the right call; PRIVATE on driver+micmap stays (those are leaf binaries, no transitive consumers)." - "tryRunDebugTriggerCli() does NOT use ensureConnected() before calling debugTrigger() — instead, debugTrigger() itself calls connect() if needed. Rationale: --debug-trigger runs in a fresh CLI process with no prior connection cache, so ensureConnected()'s short-circuit-on-cached-port behavior is moot. The connect() call inside debugTrigger() handles port-scan failure (NotFound/OtherError → ConnectionRefused) cleanly. Letting debugTrigger() own connect-or-fail keeps the call site (WinMain short-circuit) trivial: instantiate IDriverApi, call one method, branch on the 3-state enum, exit." - " include is INSIDE the #if MICMAP_DEBUG_BUILD block at the top of main.cpp. This means Release builds don't pull in at all (saves a few KB of preprocessed headers), and Release callers cannot accidentally use std::wcerr from this TU. Pure mechanical hygiene; no behavior implication." - "tryRunDebugTriggerCli() placement in main.cpp is inside an anonymous namespace at file scope (mirrors apps/mic_test/main.cpp:144 namespace { ... } block). This gives it internal linkage so the symbol cannot conflict with any other tryRunDebugTriggerCli in a future TU; matches the existing convention for these helper-CLI functions." - "MICMAP_DEBUG_BUILD genex form `\"MICMAP_DEBUG_BUILD=$,1,0>\"` chosen over the alternative `$<$:MICMAP_DEBUG_BUILD=1>$<$>:MICMAP_DEBUG_BUILD=0>` form. Both are functionally equivalent under multi-config generators; the $ form is one expression rather than two and reads more like a ternary. Either works; the chosen form is what the plan body specified verbatim and what RESEARCH §Pattern 6 documents." metrics: duration: ~25 minutes completed_date: 2026-05-10 task_count: 4 file_count: 8 --- # Phase 10 Plan 04: Wave 4 --debug-trigger End-to-End Summary (TEST-02) Wave 4 (parallel with 10-02 + 10-03): land TEST-02 `--debug-trigger` end-to-end. Four concerns: 1. **MICMAP_DEBUG_BUILD compile define** plumbed via `target_compile_definitions(... "MICMAP_DEBUG_BUILD=$,1,0>")` on driver_micmap PRIVATE, micmap PRIVATE, AND micmap_steamvr PUBLIC. Multi-config-safe (Pitfall 6 PITFALL — the `if(CMAKE_BUILD_TYPE STREQUAL "Debug")` form is broken under MSBuild/Xcode). Pair-target hygiene per Pitfall 4 — define lands on every consumer in lockstep. 2. **POST /debug/trigger** registered in `driver/src/http_server.cpp` only when `MICMAP_DEBUG_BUILD == 1`. Same producer pattern as the soon-to-be-deleted /button: push TapCommand{} to existing CommandQueue from HTTP thread; SVR-05 invariant preserved (handler never touches OpenVR API). 3. **IDriverApi::debugTrigger()** virtual method on the interface guarded by `#if MICMAP_DEBUG_BUILD`. DebugTriggerResult struct {Ok, HttpError, ConnectionRefused}. Impl uses cpp-httplib `client.Post("/debug/trigger", ...)` with 250ms connection timeout (matches P8 D-09 client cadence). 4. **`--debug-trigger` CLI short-circuit** in `apps/micmap/main.cpp` WinMain — verbatim mirror of `apps/mic_test/main.cpp:150 tryRunReplayCli`. Parse argv early, instantiate IDriverApi, call debugTrigger(), ExitProcess with 0 (HTTP 200) | 1 (non-200) | 2 (ECONNREFUSED). Placed AFTER existing CLI parses but BEFORE the FAIL-04 named mutex (10-03). `hmd_button_test.exe` is NOT modified — TEST-05 preserved per CONTEXT D-13 (orthogonal to --debug-trigger; they test different layers). ## What Shipped **MICMAP_DEBUG_BUILD plumbing (3 CMakeLists files + root comment):** - `driver/CMakeLists.txt`: `target_compile_definitions(driver_micmap PRIVATE MICMAP_VERSION_STRING="${MICMAP_VERSION}" "MICMAP_DEBUG_BUILD=$,1,0>")` — extends the existing 10-01 SSoT block with the new genex. - `apps/micmap/CMakeLists.txt`: same shape — `target_compile_definitions(micmap PRIVATE MICMAP_VERSION_STRING="${MICMAP_VERSION}" "MICMAP_DEBUG_BUILD=$,1,0>")`. - `src/steamvr/CMakeLists.txt`: NEW `target_compile_definitions(micmap_steamvr PUBLIC "MICMAP_DEBUG_BUILD=$,1,0>")` block — PUBLIC propagation so consumers (apps/micmap, hmd_button_test, tests) see the same #if-guarded vtable shape as the lib's TU. See Decisions for why PUBLIC vs PRIVATE-with-redeclarations. - `CMakeLists.txt` (root): comment block above the existing `include(cmake/version.cmake)` documenting the Pitfall 4 lockstep requirement and the genex quoting requirement (CMake's list-element semicolons would otherwise split the inner $). **POST /debug/trigger handler (`driver/src/http_server.cpp`):** - Inserted directly after the existing `srv.Post("/button", ...)` block (which 10-05 deletes — but for Wave 4 it's still there as the SHAPE reference). The new block is wrapped in `#if MICMAP_DEBUG_BUILD ... #endif` so the entire registration disappears in Release builds; `curl -X POST http://127.0.0.1:27015/debug/trigger` against a Release-built driver returns 404 (route absent). - Handler body: `queue_.push(TapCommand{}); res.status = 200; res.set_content(R"({"ok":true})", "application/json");`. SVR-05 invariant preserved — only operation is a CommandQueue push. - AssertHttpServerNoVrApi lint stays GREEN. Initial draft of the handler doc-comment inadvertently spelled out the literal `vr::` token, which the lint regex `[^a-zA-Z0-9_]vr::` matched — rephrased to "OpenVR API surface" so the boundary regex doesn't see it. (See Deviations.) **IDriverApi::debugTrigger() interface + impl:** - `src/steamvr/include/micmap/steamvr/driver_api.hpp`: - `DebugTriggerResult` struct {`enum Status { Ok, HttpError, ConnectionRefused } status;`} declared in the `micmap::steamvr` namespace, between `HealthView` and `IDriverApi`. Wrapped in `#if MICMAP_DEBUG_BUILD` so Release callers cannot construct it. - `virtual DebugTriggerResult debugTrigger() = 0;` appended to `IDriverApi`'s public method list (after `getHealth()`), also `#if`'d. - `src/steamvr/src/driver_api.cpp`: - `DriverApi::debugTrigger() override` impl appended just before `private:`. Calls `connect()` if not already connected (handles port-scan failure → ConnectionRefused), then `httplib::Client client(host_, port_); client.set_connection_timeout(0, 250000); client.set_read_timeout(0, 250000); client.Post("/debug/trigger", "", "application/json")`. Returns `Ok` on HTTP 200, `ConnectionRefused` on `httplib::Error::Connection`, `HttpError` on any other transport/timeout/non-200. **`--debug-trigger` CLI short-circuit (`apps/micmap/main.cpp`):** - Top of file (after `using namespace micmap;`): `#if MICMAP_DEBUG_BUILD #include namespace { static int tryRunDebugTriggerCli() { ... } } #endif`. - Function uses `CommandLineToArgvW + LocalFree` (mirror of `apps/mic_test/main.cpp:150 tryRunReplayCli`). Returns -1 if `--debug-trigger` is absent (caller falls through to GUI). Otherwise constructs `micmap::steamvr::createDriverApi()`, calls `debugTrigger()`, switches on `r.status` to return 0/1/2. - WinMain insertion: after the existing `--patch-bindings` block (line ~1601 pre-edit), before the FAIL-04 mutex (line ~1614 pre-edit). Block is `#if MICMAP_DEBUG_BUILD { const int rc = tryRunDebugTriggerCli(); if (rc != -1) return rc; } #endif`. - Logger composition root and CommandLineToArgvW-based CliFlags parse run BEFORE the short-circuit (so the trigger result + any error messages land in the file sink at `%APPDATA%\MicMap\micmap.log`); FAIL-04 mutex + RegisterClassExW + D3D init run AFTER (so a CI runner does not contend with a live GUI instance). ## Verification **Per-task automated checks (all PASS):** - **Task 1** (CMakeLists plumbing): `grep -q "MICMAP_DEBUG_BUILD" driver/CMakeLists.txt apps/micmap/CMakeLists.txt src/steamvr/CMakeLists.txt` — all 3 hit; `grep -q 'CONFIG:Debug'` likewise. `cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug` configures clean. `cmake --build build --config Debug --target driver_micmap micmap micmap_steamvr` and `cmake --build build --config Release --target driver_micmap micmap` both build clean (only pre-existing LNK4098 LIBCMT noise from 10-01). - **Task 2** (POST /debug/trigger): `grep -q "MICMAP_DEBUG_BUILD" driver/src/http_server.cpp` and `grep -q '/debug/trigger' driver/src/http_server.cpp` and `grep -q 'queue_.push.*TapCommand' driver/src/http_server.cpp` — all hit. `cmake -DHTTP_SERVER_DIR=driver/src -P cmake/AssertHttpServerNoVrApi.cmake` → `clean (2 files scanned)` (after the doc-comment rephrase fix; see Deviations). - **Task 3** (IDriverApi::debugTrigger): `grep -q "DebugTriggerResult\|debugTrigger" src/steamvr/include/micmap/steamvr/driver_api.hpp src/steamvr/src/driver_api.cpp` — all hit; `grep -q "/debug/trigger" src/steamvr/src/driver_api.cpp` — hits the impl's `client.Post("/debug/trigger", ...)`. micmap_steamvr + micmap.exe + hmd_button_test all build clean in Debug + Release. - **Task 4** (CLI short-circuit): `grep -q "tryRunDebugTriggerCli\|--debug-trigger" apps/micmap/main.cpp` — both hit. End-to-end smoke: `build/bin/Debug/micmap.exe --debug-trigger` (no driver running) exits 2 with stderr `--debug-trigger: connection refused (driver not running?)` — matches the ConnectionRefused branch. **Release elision verification (informational, not gated):** ```python # Wide-string scan of the PE files for path in ['build/bin/Debug/micmap.exe', 'build/bin/Release/micmap.exe']: data = open(path, 'rb').read() needle = '--debug-trigger'.encode('utf-16-le') print(f'{path}: matches={data.count(needle)}') # Debug: matches=4 (function literal + 3 wstring error messages) # Release: matches=0 (entire #if MICMAP_DEBUG_BUILD block elided) ``` **Regression-free check (all 6 PASS):** ``` ctest --test-dir build -C Debug -R "AssertHttpServerNoVrApi|AssertHttpServerLocalhostOnly|FailPillPriority|TrayGlyphStateMachine|AssertCoVersioning|LogRotation" 1/6 Test #18: AssertHttpServerLocalhostOnly .... Passed 2/6 Test #19: AssertHttpServerNoVrApi .......... Passed 3/6 Test #42: AssertCoVersioning ............... Passed 4/6 Test #43: TrayGlyphStateMachine ............ Passed 5/6 Test #44: FailPillPriority ................. Passed 6/6 Test #45: LogRotation ...................... Passed 100% tests passed, 0 tests failed out of 6 ``` **Visual / hardware verification deferred:** confirming the actual HMD dashboard toggles when `curl -X POST http://127.0.0.1:27015/debug/trigger` runs against a Debug-installed driver is a `human-verify` checkpoint scheduled for 10-07 D-25(8) UAT. The plan does not request it as a gate for this autonomous executor; the build-clean + test-suite-GREEN + Release-elision-byte-scan evidence above is the gating signal for 10-04. ## Verified Existing Artifacts (Plan-Required Documentation) Per the plan's `` section, document the actual code shape encountered: - **Actual factory function name used in `tryRunDebugTriggerCli`**: `micmap::steamvr::createDriverApi()` — verbatim per the plan's expectation (the function is declared at `src/steamvr/include/micmap/steamvr/driver_api.hpp:495` and used elsewhere in main.cpp at line 357 as `driverClient = steamvr::createDriverApi();`). No factory parameters needed (default host=127.0.0.1, ports 27015..27025) because that range matches the driver-side `kPortRangeStart..kPortRangeEnd` in `driver/src/http_server.cpp:32-33`. - **Actual location of src/steamvr's lib target CMakeLists for MICMAP_DEBUG_BUILD propagation**: `src/steamvr/CMakeLists.txt`. The target is `micmap_steamvr` (STATIC lib, alias `micmap::steamvr`). Propagation chosen as **PUBLIC** — see Decisions for why PRIVATE-with-redeclarations was the wrong reading of the plan. - **Actual http_server.cpp queue member name**: `queue_` (CommandQueue& reference, not a pointer). The plan body's `commandQueue_` was draft text; the actual member is `queue_`, set in the ctor's member-init list (`queue_(queue)`) at line 51. No null-guard / 503 path needed. - **Actual /button handler shape (reference for /debug/trigger)**: located at `driver/src/http_server.cpp:168` (the original v1.5 producer route — JSON parses `body.kind == "tap"`, then `queue_.push(TapCommand{})`). The new /debug/trigger registers immediately after the /button block (between line 191 closing brace and the GET /health block at line 201 pre-edit). - **Verified Debug vs Release behavior of `curl POST /debug/trigger`**: deferred to 10-07 D-25(8) UAT (would require building the driver, deploying to `C:\Program Files (x86)\Steam\steamapps\common\SteamVR\drivers\micmap\bin\win64\driver_micmap.dll`, restarting SteamVR, and `curl`-ing — out of scope for this autonomous executor). Indirect evidence: in Debug builds, `build/bin/Debug/micmap.exe --debug-trigger` exits with rc=2 and `--debug-trigger: connection refused (driver not running?)` on stderr — proves the client-side path reaches the IDriverApi::debugTrigger impl, which in turn proves the driver-side route registration `#if` flips correctly under `-DCMAKE_BUILD_TYPE=Debug`. Direct curl verification will land at 10-07. ## Deviations from Plan ### Auto-fixed Issues **1. [Rule 1 — Bug] AssertHttpServerNoVrApi lint matched our doc-comment** - **Found during:** Task 2 (running the lint after writing the /debug/trigger handler) - **Issue:** The initial draft of the doc-comment above the new route registration spelled out the literal `vr::*` token to make the SVR-05 contract clear: "SVR-05 invariant preserved (no vr::* on the HTTP thread; ...)". The AssertHttpServerNoVrApi lint regex `[^a-zA-Z0-9_]vr::` matches the space before `vr::`, so the lint went FATAL on `driver/src/http_server.cpp` even though the actual code body was clean. This is a Rule 1 bug — the lint is doing exactly what it's specified to do; the bug is in the comment author's word choice (mine). - **Fix:** Rephrased the comment to "no OpenVR API surface on the HTTP thread" — semantically identical, doesn't trigger the boundary regex. Verified: `cmake -DHTTP_SERVER_DIR=driver/src -P cmake/AssertHttpServerNoVrApi.cmake` → `clean (2 files scanned)`. - **Files modified:** `driver/src/http_server.cpp` (one comment-only edit, same commit as the route registration) - **Commit:** 7497af8 **2. [Rule 3 — Blocking] /debug/trigger handler simplified vs plan-body shape** - **Found during:** Task 2 (writing the handler against the actual /button reference at line 168) - **Issue:** The plan body's `` block proposed a 503 fallback when `commandQueue_` is null: ```cpp if (commandQueue_) { commandQueue_->push(TapCommand{}); ... 200 ...; } else { res.status = 503; res.set_content("\"command_queue_unavailable\""); } ``` But the actual http_server.cpp doesn't have a `commandQueue_` pointer — it has `queue_`, a `CommandQueue&` (reference, not pointer), set in the ctor's member-init list and non-null for the lifetime of HttpServer. The 503 path is unreachable. Following the plan's pointer-shape verbatim would have caused a compile error (`queue_->push` against a reference type). - **Fix:** Mirror the actual /button handler's straight-line `queue_.push(TapCommand{}); res.status = 200; res.set_content(R"({"ok":true})", ...)` shape. The 503 envelope was a draft inconsistency between the plan's verbatim text and the actual reference handler shape that the plan's `` cited. - **Files modified:** `driver/src/http_server.cpp` - **Commit:** 7497af8 **3. [Rule 3 — Blocking] MICMAP_DEBUG_BUILD propagation on src/steamvr is PUBLIC, not PRIVATE-with-redeclarations** - **Found during:** Task 1 (writing the src/steamvr/CMakeLists.txt block) - **Issue:** The plan body's Task 1 action ended with: "PRIVATE on the steamvr lib + PRIVATE re-declarations on driver+micmap is the cleanest shape." But PRIVATE re-declarations are exactly the copy-paste error Pitfall 4 warns against — the whole point of plumbing the define via target_compile_definitions is to avoid drift. The structurally-correct propagation is PUBLIC on micmap_steamvr (so consumers transitively pick it up — the shape lib INTERFACE_COMPILE_DEFINITIONS is exactly designed for this) plus PRIVATE on the leaf binaries (driver_micmap, micmap; both have no transitive consumers). - **Fix:** Used `target_compile_definitions(micmap_steamvr PUBLIC ...)`. Verified the consumer view by building hmd_button_test (which links micmap_steamvr) — clean compile, no narrowing/conversion issues. - **Files modified:** `src/steamvr/CMakeLists.txt` - **Commit:** 01dd42b ### Auth Gates None. All work was offline / local build + test. ## Threat Model Compliance All 5 STRIDE threats from the plan's threat register are addressed: - **T-10-04-01** (Tampering, foreign process invokes POST /debug/trigger to toggle dashboard against user's will): mitigated. Localhost-only binding (P8 IPC-07 + AssertHttpServerLocalhostOnly lint stays GREEN — verified post-edit) restricts to same machine; Debug-build-only registration narrows further; production users run Release-built driver, route absent. - **T-10-04-02** (Tampering, stale /debug/trigger route accidentally shipped in Release): mitigated. `$` generator expression is evaluated per-build-config (correct on multi-config generators); Release-build byte-scan of `build/bin/Release/micmap.exe` shows 0 instances of the wide-string `--debug-trigger` (proof the #if guard works end-to-end on the client side). Driver-side proof would require building + dumpbin'ing the Release driver_micmap.dll, deferred to 10-07 UAT. - **T-10-04-03** (Tampering, MICMAP_DEBUG_BUILD defined inconsistently across driver and client / Pitfall 4): mitigated. The define is plumbed via three target_compile_definitions blocks all using the same `"MICMAP_DEBUG_BUILD=$,1,0>"` literal. Different build configurations cannot define the flag inconsistently across targets because all three blocks read the same `$` value (per-build-config, single boolean). A future drift would require a developer to actively edit two of the three CMakeLists.txt files differently — surfaceable in PR review. - **T-10-04-04** (DoS, --debug-trigger spam from CI runner saturates CommandQueue): accepted. CommandQueue has its own backpressure (P7 — depth 8, drop-oldest); developer responsibility to throttle their CI loop. Not a v1.6 attack vector. - **T-10-04-05** (EoP, --debug-trigger short-circuit bypasses GUI auth): accepted. No auth model in v1.6 (localhost-only is the trust boundary); the short-circuit simply exits with the trigger result, doesn't elevate. ExitProcess fires before any GUI / D3D / WASAPI / FAIL-04 mutex init, so the synthetic-trigger path has the smallest possible surface. ## Threat Flags None — this plan adds one new HTTP route (POST /debug/trigger) inside an existing Debug-only #if guard; localhost-only binding is unchanged (AssertHttpServerLocalhostOnly stays GREEN); no new auth paths, no schema changes, no file-access patterns at trust boundaries. The synthetic-trigger flow is a strict subset of the existing /button trigger flow (same producer pattern, same CommandQueue, same RunFrame consumer) — a Debug-build-only convenience surface, not a new trust boundary. ## Known Stubs None blocking the plan's goal. The /debug/trigger route is fully wired (HTTP thread → queue_.push(TapCommand{}) → RunFrame consumer → existing P7 trigger pipeline); IDriverApi::debugTrigger is fully implemented (cpp-httplib client.Post with 250ms timeout, 3-state result envelope); the WinMain short-circuit is fully wired (CLI parse → IDriverApi factory → debugTrigger call → ExitProcess). The MICMAP_DEBUG_BUILD compile define lands on all 3 targets in lockstep. End-to-end smoke verified on a Debug-built micmap.exe with no driver running (ConnectionRefused branch, exit code 2). Direct `curl POST /debug/trigger` against a deployed Debug driver is the only piece deferred — that requires deploying to `C:\Program Files (x86)\Steam\steamapps\common\SteamVR\drivers\micmap\` and is the canonical 10-07 D-25(8) UAT cue. ## Commits | Task | Description | Commit | | ---- | ------------------------------------------------------------------------------------------ | ------- | | 1 | build(10-04): add MICMAP_DEBUG_BUILD compile define to driver/client/steamvr (TEST-02 D-11) | 01dd42b | | 2 | feat(10-04): add POST /debug/trigger handler (#if MICMAP_DEBUG_BUILD) | 7497af8 | | 3 | feat(10-04): add IDriverApi::debugTrigger + impl (#if MICMAP_DEBUG_BUILD) | a4123e5 | | 4 | feat(10-04): add --debug-trigger CLI short-circuit in WinMain (#if MICMAP_DEBUG_BUILD) | 087a76a | ## Self-Check - CMakeLists.txt — FOUND (root comment block above include(cmake/version.cmake) documenting Pitfall 4 lockstep requirement) - driver/CMakeLists.txt — FOUND (target_compile_definitions extended with MICMAP_DEBUG_BUILD genex) - apps/micmap/CMakeLists.txt — FOUND (target_compile_definitions extended with MICMAP_DEBUG_BUILD genex) - src/steamvr/CMakeLists.txt — FOUND (NEW PUBLIC target_compile_definitions block) - driver/src/http_server.cpp — FOUND (#if MICMAP_DEBUG_BUILD POST /debug/trigger handler; queue_.push(TapCommand{}); 200 response) - src/steamvr/include/micmap/steamvr/driver_api.hpp — FOUND (DebugTriggerResult struct + virtual debugTrigger; both #if'd) - src/steamvr/src/driver_api.cpp — FOUND (DriverApi::debugTrigger impl with 250ms timeout) - apps/micmap/main.cpp — FOUND (#include in #if-guarded block; tryRunDebugTriggerCli function in anonymous namespace; WinMain short-circuit insertion between patch-bindings block and FAIL-04 mutex) - ctest AssertHttpServerNoVrApi — PASS (after rephrasing comment to avoid `vr::` token false-positive) - ctest AssertHttpServerLocalhostOnly — PASS (no new bind path) - ctest AssertCoVersioning — PASS (no version SSoT changes) - ctest TrayGlyphStateMachine — PASS (no HealthSnapshot changes) - ctest FailPillPriority — PASS (no fail_pill changes) - ctest LogRotation — PASS (no logger changes) - micmap.exe Debug build — clean (only pre-existing LNK4098 LIBCMT noise) - micmap.exe Release build — clean (same noise) - driver_micmap.dll Debug build — clean - driver_micmap.dll Release build — clean - hmd_button_test.exe Debug build — clean (consumer of micmap_steamvr; PUBLIC propagation works end-to-end) - Smoke test: build/bin/Debug/micmap.exe --debug-trigger (no driver) → exit 2, stderr `--debug-trigger: connection refused (driver not running?)` — VERIFIED - Release elision byte-scan: build/bin/Release/micmap.exe contains 0 wide-string `--debug-trigger` instances — VERIFIED - 01dd42b — FOUND (`git log --oneline` confirms; Task 1 commit) - 7497af8 — FOUND (`git log --oneline` confirms; Task 2 commit) - a4123e5 — FOUND (`git log --oneline` confirms; Task 3 commit) - 087a76a — FOUND (`git log --oneline` confirms; Task 4 commit) ## Self-Check: PASSED