# EM Planner 与 TrajectoryExecution README 实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 以 `CoarsePath/README.md` 的结构重写 EMPlanner 文档，并为 TrajectoryExecution 新增准确、可操作的模块 README。

**Architecture:** README 只描述现有的不可变请求、纯单次规划、滚动协调、轨迹执行和通用控制命令边界。两份文档均从上游空间路径到未来硬件适配器的单向数据流解释职责；不改变任何 C#、测试、项目文件或发布脚本。

**Tech Stack:** Markdown、PowerShell、Git、现有 `EMPlannerVerificationHost` 命令。

## Global Constraints

- 仅修改 `ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md` 和新建的 `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md`。
- 保留所有既有用户工作区改动；只显式暂存本任务指定的 README，绝不使用 `git add .` 或 `git add -A`。
- 从仓库根目录运行所有检查；不改动 LS/ST/OSQP、测试夹具、发布脚本、`csproj`、UI 或硬件代码。
- `EmPlanningService.Plan(EmPlanningRequest, CancellationToken)` 是纯、同步、一次性的规划入口。
- 只有 `Success` 和 `SuccessWithFallback` 可携带可消费的 `EmTrajectory`；其余状态不可发布部分轨迹。
- 动态障碍物、时空占用、行为决策、UI/硬件集成、横移、蟹行和原地旋转均明确为未实现范围。
- 验证命令只引用当前的 `em-core-all`、`coordinator`、`executor`、`plugin-package` 和 `em-all`。

---

### Task 1: 重写 EMPlanner 模块 README

**Files:**
- Modify: `ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md`

**Interfaces:**
- Consumes: `PathSmoothingResult`、`PlanningGridMap`、`VehicleParameters`、`VehicleMotionState`、`EmPlannerConfiguration` 和可选上一条 `EmTrajectory` 快照。
- Produces: 文档化的 `IEmPlanningService.Plan(EmPlanningRequest request, CancellationToken cancellationToken)` 消费边界，以及仅在 `Success`/`SuccessWithFallback` 时可消费的 `EmTrajectory`。

- [ ] **Step 1: 记录旧文档的 RED 基线**

从仓库根目录运行：

```powershell
$text = Get-Content ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md -Raw -Encoding UTF8
if ($text -notmatch '尚未实现 LS 横向优化、\s*ST 纵向优化、滚动协调、轨迹发布') {
  throw 'Expected the stale Foundation-only scope marker.'
}
```

Expected: 找到一条 Foundation 阶段的旧描述，证明重写前 README 与当前实现不一致。

- [ ] **Step 2: 以 CoarsePath 风格重写 README**

使用 `apply_patch` 以 UTF-8 Markdown 整体替换文件。文档必须按以下顺序覆盖：

```text
模块说明（职责/非职责与唯一入口）
文件结构（Configuration、Contracts、Segmentation、Frenet、Corridor、Lateral、Longitudinal、Trajectory、Validation、Facade）
规划数据流（校验 -> 方向段 -> 走廊 -> LS -> ST -> 装配 -> 独立验证）
结果、状态与停止
坐标、单位与前进/倒车符号
最小调用示例
详细使用指南
验证命令
常见错误
第一版限制
```

正文必须声明静态走廊、OSQP 通过 solver-neutral `IQpSolver`/`QuadraticProgram`、实际 `PathS`、终端零速安全尾段、世界空间独立复核和纯服务边界。示例只构造 `EmPlanningService` 和调用 `Plan`，不得包含 UI 或硬件对象。模块概览和首版限制都必须以相对链接指向 `../TrajectoryExecution/README.md`，说明滚动执行不属于纯规划服务。

- [ ] **Step 3: 运行 GREEN 文档契约检查**

从仓库根目录运行：

```powershell
$path = 'ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md'
$text = Get-Content $path -Raw -Encoding UTF8
$required = @(
  '## 模块说明（Module Overview）',
  '## 文件结构（File Structure）',
  '## 规划数据流（Planning Data Flow）',
  'EmPlanningService.Plan',
  'SuccessWithFallback',
  'em-core-all',
  'em-all',
  '动态障碍物'
)
foreach ($item in $required) {
  if (-not $text.Contains($item)) { throw "Missing README contract: $item" }
}
if ($text -match '尚未实现 LS 横向优化、\s*ST 纵向优化、滚动协调、轨迹发布') {
  throw 'Stale Foundation-only scope remains.'
}
```

Expected: exit 0 without `Missing README contract` or stale-scope error.

- [ ] **Step 4: 检查差异并提交 Task 1**

```powershell
git diff --check
git add -- ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md
git diff --cached --check
git diff --cached --name-only
git commit -m "docs: rewrite EM Planner readme"
git diff-tree --no-commit-id --name-only -r HEAD
```

Expected: staged 和提交范围仅为 EMPlanner README；所有 diff 检查退出 0。

### Task 2: 新增 TrajectoryExecution 模块 README

**Files:**
- Create: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md`

**Interfaces:**
- Consumes: `IEmPlanningService`、调用方冻结的 `PlanningCycleInput`、当前 `VehicleMotionState` 与已发布不可变 `EmTrajectory`。
- Produces: `EmPlanningCoordinator.PlanLatestAsync` 的当前版本发布语义，以及 `TrajectoryExecutor.UpdateCommand` 返回的 `TrajectoryControlCommand`。

- [ ] **Step 1: 记录 README 缺失的 RED 基线**

从仓库根目录运行：

```powershell
if (Test-Path ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md) {
  throw 'TrajectoryExecution README unexpectedly already exists.'
}
throw 'RED: TrajectoryExecution README is absent.'
```

Expected: command exits nonzero and prints the RED message.

- [ ] **Step 2: 新增 CoarsePath 风格 README**

使用 `apply_patch` 创建 UTF-8 Markdown。按以下顺序说明：

```text
模块说明（协调、交接、执行与控制适配职责）
文件结构（所有 .cs 文件）
滚动执行数据流
周期身份、latest-wins 与安全交接
换向状态机和停止语义
通用控制命令的字段、单位及硬件边界
最小调用示例
详细使用指南
验证命令与插件部署链接
常见错误
第一版限制
```

文件结构必须逐项列出当前文件，且只赋予现有职责：

```text
TrajectoryExecution/
├── EmPlanningCoordinator.cs
├── GearSwitchState.cs
├── GearSwitchStateMachine.cs
├── IEmPlanningCycleSink.cs
├── IVehicleStateProvider.cs
├── PlanningCycleIdentity.cs
├── PlanningCycleInput.cs
├── PlanningCycleResult.cs
├── TrajectoryControlAdapter.cs
├── TrajectoryControlCommand.cs
├── TrajectoryExecutionState.cs
├── TrajectoryExecutor.cs
├── TrajectoryHandoffSelector.cs
└── TrajectorySampler.cs
```

文档必须给出状态序列 `Following -> ApproachingGearSwitch -> HoldingZero -> RequestingDirectionChange -> AwaitingDirectionConfirmation -> Following`，说明失败重规划不覆盖上一条完整轨迹、轨迹末点不外推，以及 `TrajectoryControlCommand` 没有横向车体速度或原地旋转字段。插件章节必须指向 EMPlanner README 的 Windows x64 打包说明，不能重写发布脚本的细节。

- [ ] **Step 3: 运行 GREEN 文档契约检查**

从仓库根目录运行：

```powershell
$path = 'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md'
$text = Get-Content $path -Raw -Encoding UTF8
$required = @(
  '## 模块说明（Module Overview）',
  '## 文件结构（File Structure）',
  '## 滚动执行数据流（Rolling Execution Data Flow）',
  'EmPlanningCoordinator.PlanLatestAsync',
  'TrajectoryExecutor.UpdateCommand',
  'Following -> ApproachingGearSwitch -> HoldingZero',
  'TrajectoryControlCommand',
  '../EMPlanner/README.md',
  'em-all',
  '动态障碍物'
)
foreach ($item in $required) {
  if (-not $text.Contains($item)) { throw "Missing README contract: $item" }
}
```

Expected: exit 0 without `Missing README contract`.

- [ ] **Step 4: 执行文档关联与回归验证**

从仓库根目录运行：

```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 -- plugin-package
git diff --check
```

Expected: 四个验证组均退出 0 并输出对应 `PASS` 行；`git diff --check` 退出 0。

- [ ] **Step 5: 检查差异并提交 Task 2**

```powershell
git add -- ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md
git diff --cached --check
git diff --cached --name-only
git commit -m "docs: add trajectory execution readme"
git diff-tree --no-commit-id --name-only -r HEAD
```

Expected: staged 和提交范围仅为 TrajectoryExecution README；所有 diff 检查退出 0。

### Task 3: 最终 README 交叉核查

**Files:**
- Modify: `ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md`（仅在发现失效相对链接或错误命令时修正）
- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md`（仅在发现失效相对链接或错误命令时修正）

**Interfaces:**
- Consumes: Task 1 的单次规划边界和 Task 2 的执行边界。
- Produces: 两份边界互不矛盾、命令与仓库现状一致的交接文档。

- [ ] **Step 1: 运行最终文本与相对链接检查**

```powershell
$em = Get-Content ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md -Raw -Encoding UTF8
$execution = Get-Content ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md -Raw -Encoding UTF8
if ($em -match '尚未实现 LS 横向优化') { throw 'EMPlanner retains stale completion state.' }
if ($em -notmatch 'TrajectoryExecution') { throw 'EMPlanner does not describe its execution boundary.' }
if ($execution -notmatch '../EMPlanner/README.md') { throw 'Execution README lacks EMPlanner link.' }
if ($execution -match 'MultiVehicleScriptVx|MultiVehicleScriptVy|MultiVehicleScriptVth') {
  throw 'Execution README leaks a prohibited hardware/UI field.'
}
```

Expected: exit 0.

- [ ] **Step 2: 运行最终门禁并检查工作区范围**

```powershell
dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- em-all
git diff --check
git status --short -- ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md
```

Expected: `em-all` exit 0；无 whitespace 错误；两个 README 均已提交，因此范围状态为空。

- [ ] **Step 3: 如步骤 1 或 2 要求更正，显式暂存两份 README 并提交**

```powershell
git add -- ClumsyPilot/ParkrobTrajplanner/EMPlanner/README.md ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/README.md
git diff --cached --check
git commit -m "docs: verify EM Planner readme links"
git diff-tree --no-commit-id --name-only -r HEAD
```

Expected: 仅当发生文字修正时才创建提交；否则不执行此步骤。