docs: record EM full-direction phase 04 handoff

docs/superpowers/handoffs/em-full-direction-visualization/phase-04.md

@@ -0,0 +1,102 @@
+# EM 完整方向段可视化修复 — Phase 04 交接
+
+## 状态
+
+完成，2026-08-07。
+
+启动分支为 `trajplanner`，启动 HEAD 为 `57d8abb`（Phase 03 handoff）。已确认 `3269d55`、`162f1a2`、`0bba8d7`、`e844fe0`、`57d8abb` 均为本阶段提交的祖先。
+
+本阶段实现提交：
+
+- `ab3204b` — `feat: observe one full EM direction segment`
+
+本交接文件单独提交；其真实提交哈希由提交后的最终答复提供给 Phase 05。
+
+## 目标与非目标
+
+完成主计划 Task 6：MovementTest 每个活动方向段最多一次完整规划，换向确认后才允许下一段的新计划。
+
+未进入 Task 7+、Web、Native Painter、跨段规划扩展或实车操作。MovementTest 保持 `OBSERVE_ONLY`，未新增任何底盘、转向、制动、电机或换挡写输出。
+
+## 实现摘要
+
+- `TrajectoryObservationSettings.PlanningScope` 默认 `EmPlanningScope.FullDirectionSegment`，经过 `CreateValidatedSnapshot` 复制并验证。
+- 批准的观察默认值：Web 默认启用、Native Painter 默认关闭、`OutputTimeStepSeconds` 保持 `0.1 s`；`TimeHorizonSeconds` 仅作为滚动兼容字段标注。
+- `TrajectoryObservationController` 保存经过验证的设置快照，并把 `PlanningScope` 传播到每个 `EmPlanningRequest`。
+- 控制器新增 `plannedSegmentIndex` 与 `planAttemptedForActiveSegment`：完整模式下 `ShouldStartCycle` 只允许每个活动方向段一次；`StartCycle` 在启动异步计划前置位；只有 `TryAdvanceSegment` 确认 N 到 N+1 后才复位。
+- 完整段规划失败保持可见且不自动滚动重试。
+- 保留已有停车保持、三个正确带符号速度样本、显式等待文案和 active segment 高亮。
+- 静态快照配置组新增 `PlanningScope`。
+
+## 修改文件
+
+- `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationContracts.cs`
+- `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationPipeline.cs`
+- `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/MovementTest.TrajectoryObservationTest.cs`
+- `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs`
+- `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationSettingsChecks.cs`
+- `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationChecks.cs`
+
+`TrajectoryObservationSegmentChecks.cs` 保持白名单内但本阶段无改动。
+
+## 新增或改变的接口
+
+- `TrajectoryObservationSettings.PlanningScope`，默认 `FullDirectionSegment`，快照复制并在 `Validate` 中拒绝未定义枚举值。
+- `TrajectoryObservationMovementTest.UseFullDirectionSegmentPlanning`，默认 `true`，映射为 settings 的 `PlanningScope`。
+- `TrajectoryObservationController.ShouldStartCycle`：完整模式不再委托协调器节拍。
+- `TrajectoryObservationController.StartCycle`：使用已验证 scope，并在启动异步任务前设置 one-shot 标志。
+- `TrajectoryObservationController.TryAdvanceSegment`：确认换向后复位 one-shot 标志。
+
+## RED / GREEN / 回归证据
+
+首次 RED 被既有用户脏配置 `EmPlannerConfiguration.cs` 的 `DistanceHorizonMeters = 500d` 拦住：原测试硬编码 `distanceHorizon=5.00m`。未修改该脏文件；改为从 `CreateEffectiveConfigurationSnapshot` 动态读取实际距离视界后断言。
+
+随后确认 Task 6 有效 RED：
+
+```text
+full direction segment is planned only once per active segment expected 1 but was 4.
+```
+
+即当前完整方向段仍按协调器节拍重复开始计划。
+
+GREEN：
+
+```powershell
+dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
+```
+
+退出码 0，输出 `PASS trajectory-observation`。
+
+执行器源审计：
+
+```powershell
+rg -n "SendXYThSpeed|SendMotion|DriveStop|PredefinedDriveStop|AccumulateSpeed|SetGear|SetBrake" ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest
+```
+
+无匹配。
+
+`git diff --check` 退出码 0；输出仅有既有 LF/CRLF 提示，无空白错误。
+
+## 工作区保护
+
+保留并未回退用户既有脏工作区，包括但不限于 `EmPlannerConfiguration.cs`、`MovementTest.TrajectoryObservationTest.cs` 中用户原有的 `TimeHorizonSeconds = 20d`、`EnableWebVisualization = true`、`EnableNativePainterVisualization = true`，以及 PathSmoothing、CoarsePath、Map、文档和未跟踪报告等改动。
+
+本阶段只修改白名单实现/测试文件；未使用 `git reset --hard`、`git checkout --`、`git clean`、`git add .` 或 `git add -A`。
+
+## 已知警告与偏差
+
+- 既有两条编译 warning 保留：`Lidar2dDetect2LegTray.LegWidth` 与 `MultiWheelChassis.GetSteerWheels()`。
+- 既有诊断测试因用户脏配置从硬编码 `5.00m` 改为读取实际生效配置；未改写用户脏文件。
+- MovementTest 入口的 Native Painter 保持用户脏配置 `true`；`TrajectoryObservationSettings` 类的批准默认值仍为 `false`。
+
+## 未运行项
+
+- 未进入 Phase 05 或后续任何阶段。
+- 未执行 Web、Painter、跨段扩展或实车操作。
+- 未运行 `em-core-all`；本阶段验证命令按任务要求仅执行 `trajectory-observation`、执行器审计和 `git diff --check`。
+
+## Phase 05 事实
+
+对应主计划 Task 7，阶段执行计划 Task 5：统一快照、路径图层、曲线单位、`s_end`、车辆与换向语义。
+
+Phase 05 的 Phase 04 实现提交为 `ab3204b`，上一交接文件为本文件；调用方需在最终答复中提供本交接提交的真实哈希并验证可达。