fix(shadow): repair UTC sampling and persist v3 diagnostics

docs/superpowers/plans/2026-09-07-shadow-v3-observation-repair.md

@@ -0,0 +1,61 @@
+# Shadow v3 Observation Repair
+
+> Execute inline with test-driven-development and verification-before-completion. Subagents explore and review only, per project instructions.
+
+**Goal:** Restore timezone-independent shadow sampling and exportable diagnostics without changing Legacy.
+
+**Architecture:** Use a statement-scoped UTC Instant handler, a bounded shadow-only log, and literal sqlcmd output paths. Preserve all scheduling, freshness, transaction and mode guards.
+
+**Tech Stack:** Java 17, MyBatis 3.5.19, Microsoft JDBC 12.10.1, Logback, Windows CMD, SQL Server 2016 RTM.
+
+**Spec:** `docs/superpowers/specs/2026-09-03-ft546wms-shadow-v3-design.md`.
+
+## Constraints
+
+- No global timezone/type-handler override; no Legacy code or business SQL changes.
+- Keep SHADOW mode, 60-second snapshot freshness and existing single-worker coordination.
+- Do not restart field processes or migrate SQL objects. Keep historical metric counters.
+- Export with Windows integrated authentication, read-only SQL, and no overwriting existing evidence.
+
+## 1. UTC Mapping
+
+- [x] Add `ShadowUtcMappingTest` loading the real mapper. Exercise UTC and Asia/Shanghai reads through the actual driver's datetime2 conversion, preserve 100ns precision, and verify fresh/stale coordinator admission.
+- [x] Run the test and observe the eight-hour failure.
+- [x] Add `mapper/ShadowUtcInstantTypeHandler.java`; use `getTimestamp(..., Calendar.getInstance(TimeZone.getTimeZone("UTC")))` and `setTimestamp(..., Timestamp.from(value), utcCalendar)`.
+- [x] Add an explicit snapshot result map and bind the handler only to `snapshotSynchronizedAt` and both `flushedAt` placeholders in `ShadowInputMapper.xml`.
+- [x] Verify parameter writes, nulls, both JVM zones, and unchanged default MyBatis handler.
+
+## 2. Shadow Diagnostics
+
+- [x] Add an actual Logback routing test: a shadow WARN must reach a file; unrelated business WARN and INFO must not enter it.
+- [x] Observe failure with the current configuration.
+- [x] Add a shadow-only WARN-and-higher rolling appender with full dates, 10MB files, 14-day history and 100MB archive cap.
+- [x] Add bounded exception metadata (cause class, SQL state/vendor code, source frame) without messages, SQL or payloads; keep logging on the existing worker paths.
+- [x] Verify routing, error context, and existing caller isolation tests.
+
+## 3. Export Compatibility
+
+- [x] Add CMD behavior tests with spaced paths, literal SQL output destinations, success/failure, working-directory restoration and evidence preservation.
+- [x] Run and observe the existing output-path failure. Drain test process output without pipe deadlock.
+- [x] Run sqlcmd from `OUTPUT_DIR`, use literal `:out` names, balance pushd/popd and check each Git command failure.
+- [x] Label local export time honestly; add explicit zero-comparison status using read-only SQL.
+- [x] Update server AI instructions and add maintenance-window deployment/rollback steps, with no SQL reinstall.
+
+## Review Notes
+
+- UTC read/write and nanosecond mapping reviewed independently; no confirmed defect found.
+- Actual Logback configuration test passed with no ERROR status. The existing two root declarations are accepted by the installed Logback; changing them is unnecessary scope expansion.
+- Logger additivity intentionally preserves existing console/error behavior. The new file receives only shadow WARN/ERROR, confirmed by file-routing tests.
+- SQL diagnostics intentionally select the deepest SQLException within eight cause levels; exception messages and SQL are never logged. The worker test verifies SQLState, code, source and payload exclusion.
+- CMD fixture executes the real scripts but does not execute SQL. No live SQL Server or field deployment was performed locally; those remain explicit verification limits.
+
+## Verification and Delivery
+
+- [x] Run focused tests, then reactor tests and package with Maven 3.9.11 / JDK 17; run existing Node guards.
+- [x] Independent read-only review, address findings, rerun affected tests and `git diff --check`.
+- [x] Fetch remote again and verify no concurrent remote commits before preparing delivery.
+- [x] Prepare simple CMD update/rollback steps in `doc/algorithm-shadow/SHADOW_V32_UPDATE.md`.
+
+Final verification: 138 algorithm tests + 78 admin tests = 216 passed, zero failures/errors/skips. Maven reactor `package` succeeded on 2026-09-07; three existing Node scripts passed `node --check`. Existing Lombok/deprecation and JVM test-instrumentation warnings remain. No live SQL Server validation or field restart was performed.
+
+Delivery: commit and push only `test/ft546wms-shadow-v3-20260903`, verify the remote hash, and report it in the handoff. Do not merge into main or switch to ACTIVE.