# EM 纵向滚动规划四阶段执行路线图

日期：2026-08-05

## 目标

把原有的 10 个实现任务拆成 4 个可以在不同 Codex 窗口中依次完成的阶段。每个阶段必须独立验证、记录实际结果，并根据真实代码状态生成下一阶段的精细提示词。

本路线图只负责阶段划分和跨窗口交接。技术设计与逐步实现细节仍以下列文件为准：

- 设计规格：`docs/superpowers/specs/2026-08-05-em-longitudinal-rolling-planning-design.md`
- 十任务实施计划：`docs/superpowers/plans/2026-08-05-em-longitudinal-rolling-planning.md`

如三份文档发生冲突，设计规格决定行为语义，十任务实施计划决定具体实现步骤，本路线图决定阶段边界和停止位置。

## 不可破坏的全局约束

- `DistanceHorizonMeters` 是 LS 空间前视范围，不是车辆在一个 ST 周期内必须走完的距离。
- `TimeHorizonSeconds` 是单次 ST 优化覆盖的未来时间，不是观察循环周期。
- 只有真实 `Goal` 或 `GearSwitchApproach` 边界允许触发精确停车。
- `RollingContinuation` 和 `ApproachStopBoundary` 不得被强制设置末速度为零。
- `ExactStopAtBoundary` 必须在 QP 时间范围结束前达到 `S=S_end、U=0、A=0`，并在 QP 内至少保留一个完整 `OutputTimeStepSeconds` 的静止稳定区间。
- 不通过放宽速度、加速度、jerk、QP 残差或轨迹发布验证阈值掩盖逻辑错误。
- `OBSERVE_ONLY` 必须保持不变。本路线图不授权增加底盘命令、轨迹跟踪器或超时看门狗。
- 工作树内已有且与本任务无关的修改全部视为用户资产。禁止清理、回退或提交这些修改。
- 每次只实施当前阶段；完成交接文件后立即停止，不得提前执行下一阶段。

## 阶段总览

| 阶段 | 原计划任务 | 核心结果 | 阶段验收 |
|---|---:|---|---|
| 1. 纵向基础与窗口语义 | 1–2 | jerk 受限停车数学、三种纵向模式、空间窗口与真实停车边界分离、输入与配置验证 | `foundation`、`longitudinal-model` |
| 2. ST 优化核心 | 3–5 | 模式化速度包络、条件化 QP 终端约束、独立解验证、按模式生成初始解 | `longitudinal-model`、`longitudinal-integration` |
| 3. 发布与跨周期连续性 | 6–7 | 条件化轨迹采样、停车锚点和稳定尾段、发布验证、上一周期轨迹软参考 | `trajectory`、`em-planning-service`、`coordinator`、`executor` |
| 4. 端到端集成与诊断 | 8–10 | 模式流转、多周期 Goal/GearSwitch 回归、MovementTest 诊断、全量回归和目标机 OSQP 验证 | `em-core-all`、观察测试、构建、目标机探针 |

## 阶段一：纵向基础与窗口语义

对应十任务计划中的 Task 1 和 Task 2。

### 实施范围

- 新建完整 jerk 受限停车数学，统一停车距离、停车时间、末速度和末加速度语义。
- 新建 `EmLongitudinalMode`：
  - `RollingContinuation`
  - `ApproachStopBoundary`
  - `ExactStopAtBoundary`
- 新建 `LongitudinalTerminalSchedule`，计算精确停车稳定尾段的起始 knot。
- 让 `PlanningHorizonSelector` 分离：
  - LS 空间窗口末端；
  - 真实 Goal/GearSwitch 停车边界；
  - 当前纵向模式。
- 扩展 `LongitudinalPlanningInput` 和请求验证，拒绝不一致的模式、边界和稳定时间配置。

### 允许修改的主要文件

- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Contracts/EmLongitudinalMode.cs`
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Longitudinal/JerkLimitedStoppingMath.cs`
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Longitudinal/LongitudinalTerminalSchedule.cs`
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Longitudinal/PathSpeedLimitBuilder.cs`
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Segmentation/PlanningHorizonSelector.cs`
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Longitudinal/LongitudinalPlanningInput.cs`
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Validation/EmPlanningRequestValidator.cs`
- `ClumsyPilot/ParkrobTrajplanner/EMPlanner/Facade/EmPlanningService.cs`
- `ClumsyPilot/tests/EMPlannerVerificationHost/LongitudinalModelChecks.cs`
- `ClumsyPilot/tests/EMPlannerVerificationHost/FoundationChecks.cs`

若编译修复必须触及直接调用者，可以进行最小兼容修改，但必须在阶段交接中逐项解释。

### 完成条件

```powershell
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- foundation
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- longitudinal-model
```

两项均须输出 `PASS`。阶段内按原十任务计划保留 Task 1、Task 2 两个独立提交。

## 阶段二：ST 优化核心

对应十任务计划中的 Task 3、Task 4 和 Task 5。

### 实施范围

- 按纵向模式构造 PathS 速度包络。
- Rolling 模式的局部路径末端不再出现人为零速边界。
- 仅为 `ExactStopAtBoundary` 添加停车位置、速度、加速度以及稳定尾段硬约束。
- 让 QP 行数、上下界和验证器随模式与稳定尾段 knot 数量变化。
- 使用与 QP 相同的恒 jerk 离散动力学做精确停车可达性验证。
- 为 Rolling、ApproachStop 和 ExactStop 构造各自合理的初始解和外层迭代行为。

### 阶段输入

- 阶段一完成后的提交。
- `docs/superpowers/handoffs/2026-08-05-em-longitudinal-rolling-phase-1.md`。
- 阶段一生成的阶段二精细提示词。

### 完成条件

```powershell
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- longitudinal-model
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- longitudinal-integration
```

两项均须输出 `PASS`，并保留 Task 3、Task 4、Task 5 的独立提交边界。

## 阶段三：轨迹发布与跨周期连续性

对应十任务计划中的 Task 6 和 Task 7。

### 实施范围

- 在轨迹元数据中保存纵向模式和真实停车边界身份。
- Rolling 和 ApproachStop 只发布时间范围内的运动轨迹，不追加虚假零速保持点。
- ExactStop 发布 QP 内部静止稳定段，并按配置追加外部零速保持点。
- 轨迹验证器按模式检查终端状态，同时保持普通运动学、碰撞和边界验证。
- 将上一条已发布轨迹按绝对时间重采样，并映射到新路径的 PathS，作为软参考而不是硬约束。

### 阶段输入

- 阶段二完成后的提交和交接文档。
- 阶段二根据实际结果生成的阶段三精细提示词。

### 完成条件

至少运行并通过：

```powershell
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- em-planning-service
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- coordinator
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- executor
```

保留 Task 6 和 Task 7 的独立提交边界。

## 阶段四：端到端集成与实测诊断

对应十任务计划中的 Task 8、Task 9 和 Task 10。

### 实施范围

- 完成 `RollingContinuation → ApproachStopBoundary → ExactStopAtBoundary` 的服务流转。
- 覆盖真实 Goal、GearSwitchApproach、多周期滚动和停车稳定尾段。
- 完善 MovementTest 终端/UI 诊断，但继续保持 `OBSERVE_ONLY`。
- 更新 EMPlanner 文档。
- 完成全量回归、构建和目标运行环境中的 OSQP 探针。

### 阶段输入

- 阶段三完成后的提交和交接文档。
- 阶段三根据实际结果生成的阶段四精细提示词。

### 完成条件

严格执行十任务计划 Task 10 中列出的全部验证命令。至少包含：

```powershell
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- em-core-all
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- coordinator
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- executor
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
dotnet build ClumsyPilot/ClumsyPilot.csproj
```

目标机 OSQP 验证必须在实际部署/测试机器上运行；若当前窗口不在目标机，只能明确记录为“待目标机验证”，不得声称已通过。

## 跨窗口交接协议

### 每个阶段开始时

1. 阅读设计规格、十任务计划、本路线图、上一阶段交接文件和当前阶段提示词。
2. 运行 `git status --short` 和 `git log -8 --oneline`，记录阶段开始基线。
3. 确认上一阶段要求的提交存在；若不存在或测试不通过，先停止并报告，不得假设已完成。
4. 只执行当前阶段对应的原计划任务。

### 每个阶段结束时

1. 重新运行本阶段全部验收命令，不能只引用较早的结果。
2. 检查每个提交只包含当前任务文件，不得使用 `git add .` 或 `git add -A`。
3. 创建交接文件：

   `docs/superpowers/handoffs/2026-08-05-em-longitudinal-rolling-phase-N.md`

4. 交接文件必须记录：

   - 阶段开始和结束提交；
   - 每个任务的提交号；
   - 实际修改和新增的文件；
   - 新增或改变的公开/内部接口；
   - 每条验证命令、退出码和关键输出；
   - 未解决问题、目标机限制和与计划的偏差；
   - 下一阶段必须继承的具体事实。

5. 根据交接文件和当前仓库状态创建下一阶段提示词：

   `docs/superpowers/prompts/2026-08-05-em-longitudinal-rolling-phase-(N+1).md`

6. 下一阶段提示词不得只写“继续原计划”，必须包含实际提交号、实际接口、准确任务边界、允许修改文件、测试命令、提交边界和完成后的交接要求。
7. 提交交接文件与下一阶段提示词，然后停止，不执行下一阶段代码。

阶段四没有下一阶段提示词，改为生成最终验收报告：

`docs/superpowers/handoffs/2026-08-05-em-longitudinal-rolling-final.md`

## 阶段状态

- [ ] 阶段一：纵向基础与窗口语义
- [ ] 阶段二：ST 优化核心
- [ ] 阶段三：轨迹发布与跨周期连续性
- [ ] 阶段四：端到端集成与实测诊断

当前入口提示词：`docs/superpowers/prompts/2026-08-05-em-longitudinal-rolling-phase-1.md`
