From 554c84f8eb4027c2e3b0cf104ad80a42c68b6bb7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=A2=81=E8=96=84=E4=BA=91?= <lby115@126.com>
Date: Mon, 3 Aug 2026 21:50:37 +0800
Subject: [PATCH] docs: design windowed EM planner execution

---
 ...03-em-planner-windowed-execution-design.md | 366 ++++++++++++++++++
 1 file changed, 366 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-03-em-planner-windowed-execution-design.md

diff --git a/docs/superpowers/specs/2026-08-03-em-planner-windowed-execution-design.md b/docs/superpowers/specs/2026-08-03-em-planner-windowed-execution-design.md
new file mode 100644
index 0000000..16bc46d
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-03-em-planner-windowed-execution-design.md
@@ -0,0 +1,366 @@
+# EM Planner 多窗口执行与交接设计
+
+## 1. 目标
+
+将已批准的 28 个 EM Planner 实施任务拆成多个相互独立、可恢复的 Codex 窗口阶段，使每个窗口只需要有限上下文即可安全继续工作。
+
+该设计解决以下问题：
+
+- 避免单个会话连续执行 28 个任务造成上下文持续膨胀；
+- 避免每个新窗口重新理解完整聊天历史；
+- 保证任务、提交、验证和下一步之间存在可审计的交接链；
+- 保证新窗口不会误改当前工作区中大量既有用户变更；
+- 保证中途关闭、上下文压缩或执行失败后能够从文件和 Git 状态恢复；
+- 保持 Foundation、OSQP、LS、ST、Rolling 五个子系统的边界。
+
+## 2. 基本原则
+
+### 2.1 阶段大小
+
+一个窗口执行一个阶段，一个阶段最多包含三个连续任务。
+
+优先保持子系统边界，不为满足“三个任务”而把两个不同子系统强行放入同一个窗口。因此 OSQP 和 LS 的收尾阶段各只有两个任务。
+
+### 2.2 信息来源优先级
+
+新窗口按以下优先级读取信息：
+
+1. 当前 Git 工作区和分支；
+2. `em-planner-progress.md` 中最近一次已提交检查点；
+3. 当前阶段对应的实施计划任务；
+4. EM Planner 总体设计规范；
+5. 最近相关提交；
+6. 旧聊天记录仅作为可选背景，不是继续执行的必要条件。
+
+若进度文件与 Git 事实不一致，以 Git 已提交内容和实际验证结果为准，并先修复进度文件再继续。
+
+### 2.3 一次只推进一个阶段
+
+窗口不得提前实现下一阶段任务。当前阶段通过完整验收、完成检查点提交并生成下一窗口提示词后，当前窗口即结束。
+
+### 2.4 任务提交与阶段检查点
+
+实施计划中每个任务仍保留独立功能提交。完成该阶段所有任务后，再提交一次只包含进度文件的阶段检查点。
+
+提交顺序如下：
+
+```text
+Task N 功能/测试提交
+Task N+1 功能/测试提交
+Task N+2 功能/测试提交
+阶段验证
+进度文件检查点提交
+```
+
+阶段检查点不得混入生产代码、测试代码、二进制或其他文档修改。
+
+## 3. 十个窗口阶段
+
+### 阶段 1：Foundation 契约与边界
+
+计划：`2026-08-03-em-planner-foundation-implementation.md`
+
+包含：
+
+1. Task 1 — Verification Host and Immutable Contracts；
+2. Task 2 — Configuration, Diagnostics, and Request Validation；
+3. Task 3 — Direction Segmentation and Exact Boundary Anchors。
+
+阶段出口：验证宿主可运行；核心请求/结果/轨迹契约存在；配置和状态验证确定；换向配对与精确边界锚点测试通过。
+
+### 阶段 2：Foundation 坐标与走廊
+
+计划：`2026-08-03-em-planner-foundation-implementation.md`
+
+包含：
+
+1. Task 4 — Reverse-Safe Frenet Projection and Reconstruction；
+2. Task 5 — Topology-Preserving Static Corridor；
+3. Task 6 — Foundation Documentation and Gate。
+
+阶段出口：前进/倒车投影和重建通过；静态走廊保持既有绕障拓扑；`all-foundation` 验收通过。
+
+### 阶段 3：OSQP 契约与原生加载
+
+计划：`2026-08-03-em-planner-osqp-backend-implementation.md`
+
+包含：
+
+1. Task 1 — Solver-Neutral Sparse QP Contracts；
+2. Task 2 — Reproducible OSQP 1.0.0 Native Package；
+3. Task 3 — Absolute-Path Native Loader and ABI Structures。
+
+阶段出口：稀疏 QP 契约通过；固定 OSQP 原生包、许可证和哈希存在；绝对路径加载与失败诊断通过。
+
+### 阶段 4：OSQP 求解与验收
+
+计划：`2026-08-03-em-planner-osqp-backend-implementation.md`
+
+包含：
+
+1. Task 4 — OSQP Solve Lifecycle and Status Mapping；
+2. Task 5 — Backend Completion Gate。
+
+阶段出口：固定可行/不可行 QP 状态正确；重复分配和释放稳定；干净插件目录加载通过。
+
+### 阶段 5：LS 模型与几何验证
+
+计划：`2026-08-03-em-planner-lateral-ls-implementation.md`
+
+包含：
+
+1. Task 1 — Variable Layout and Exact Discrete Lateral Dynamics；
+2. Task 2 — Normalized Objective and Linear Hard Constraints；
+3. Task 3 — Nonlinear Geometry Evaluation and Independent Validation。
+
+阶段出口：LS 变量布局、离散动力学、代价和硬约束系数测试通过；世界坐标重建和车辆曲率独立验证通过。
+
+### 阶段 6：LS SQP 与真实场景
+
+计划：`2026-08-03-em-planner-lateral-ls-implementation.md`
+
+包含：
+
+1. Task 4 — Sequential Convex Outer Loop and Feasible-Candidate Fallback；
+2. Task 5 — Real-OSQP Lateral Scenarios and Gate。
+
+阶段出口：SQP 外循环、信赖域和最后可行解回退通过；真实 OSQP 横向场景通过；输出实际 `PathS`。
+
+### 阶段 7：ST 模型与纵向优化
+
+计划：`2026-08-03-em-planner-longitudinal-st-implementation.md`
+
+包含：
+
+1. Task 1 — Speed Envelope over Actual PathS；
+2. Task 2 — Time-Knot Layout, Dynamics, Objective, and Hard Constraints；
+3. Task 3 — Longitudinal Outer Loop and Strict Validation。
+
+阶段出口：速度包络、停车预检、ST 动力学、代价、约束和纵向外循环通过。
+
+### 阶段 8：轨迹发布与单次规划服务
+
+计划：`2026-08-03-em-planner-longitudinal-st-implementation.md`
+
+包含：
+
+1. Task 4 — Complete Trajectory Assembly and Redundant-Field Consistency；
+2. Task 5 — Independent World-Space Publication Validator；
+3. Task 6 — Pure One-Shot EmPlanningService。
+
+阶段出口：完整轨迹字段一致；世界坐标发布验证通过；纯单次规划流水线和状态覆盖通过。
+
+### 阶段 9：滚动协调与换向执行
+
+计划：`2026-08-03-em-planner-rolling-execution-implementation.md`
+
+包含：
+
+1. Task 1 — Cycle Identity, Scheduling Decision, and Stale-Result Suppression；
+2. Task 2 — Safe Previous-Trajectory Handoff；
+3. Task 3 — Gear-Switch State Machine and Trajectory Executor。
+
+阶段出口：最新版本发布、旧结果淘汰、安全拼接、零速换向状态机通过。
+
+### 阶段 10：控制适配、插件发布与总验收
+
+计划：`2026-08-03-em-planner-rolling-execution-implementation.md`
+
+包含：
+
+1. Task 4 — Generic Control Adapter；
+2. Task 5 — Plugin Output and License Packaging；
+3. Task 6 — Rolling End-to-End and Final Gate。
+
+阶段出口：通用控制命令通过；`ClumsyPilot.dll`、`osqp.dll` 和许可证目录打包通过；第一版 EM Planner 全链路验收通过。
+
+## 4. 进度文件设计
+
+实施时创建：
+
+```text
+docs/superpowers/progress/em-planner-progress.md
+```
+
+它是跨窗口唯一的人工可读运行状态文件，包含以下固定章节：
+
+````markdown
+# EM Planner Execution Progress
+
+## Current State
+- Current stage:
+- Stage status:
+- Current branch:
+- Last checkpoint commit:
+
+## Completed Tasks
+| Stage | Plan | Tasks | Commits | Verification |
+
+## Current Verification
+- Commands:
+- Result:
+- Verified commit:
+
+## Preserved Workspace State
+- Existing unrelated changes remain untouched.
+- Known baseline build issue:
+
+## Decisions Needed
+- None, or an exact blocking decision.
+
+## Next Stage
+- Stage:
+- Plan:
+- Tasks:
+- Entry checks:
+- Exit gate:
+
+## Next-Window Prompt
+```text
+可直接复制的完整提示词
+```
+````
+
+状态仅允许：
+
+```text
+NotStarted
+InProgress
+Blocked
+Completed
+```
+
+只有阶段出口验证真实通过后，才能写入 `Completed`。
+
+## 5. 新窗口启动协议
+
+每个窗口开始时必须依次执行：
+
+1. 确认当前工作目录和分支；
+2. 读取总体设计规范；
+3. 读取本多窗口执行规范；
+4. 读取进度文件；
+5. 读取当前阶段对应计划中的指定任务；
+6. 检查 `git status --short`，不得把既有无关修改当成本阶段修改；
+7. 检查进度文件记录的最后提交是否存在；
+8. 运行进度文件列出的阶段入口验证；
+9. 若入口验证与记录不一致，停止实施，先诊断并修正交接状态；
+10. 使用当前阶段计划开始 TDD 实施。
+
+新窗口不需要读取 28 个任务的全部计划，只读取当前阶段对应计划和必要的前置接口文件。
+
+## 6. 窗口结束协议
+
+阶段结束前必须依次执行：
+
+1. 确认该阶段每个任务都有独立提交；
+2. 确认每个提交只包含计划指定文件；
+3. 运行阶段出口验证；
+4. 运行 `git diff --check`；
+5. 记录实际测试命令、退出码和关键输出；
+6. 检查暂存区为空；
+7. 更新进度文件中的已完成任务、提交和验证证据；
+8. 填写下一阶段入口检查、任务和出口门槛；
+9. 生成下一窗口提示词；
+10. 单独提交进度文件；
+11. 再次确认用户原有工作区修改仍被保留；
+12. 向用户返回本阶段摘要和下一窗口提示词。
+
+任何测试未通过时，不得把阶段标记为完成，也不得生成声称前置条件已满足的下一窗口提示词。
+
+## 7. 下一窗口提示词模板
+
+阶段结束时按实际阶段号、提交号和验证命令填充以下模板：
+
+```text
+请继续 ParkingRobot 仓库的 EM Planner 多窗口实施。
+
+工作目录：D:\Users\Desktop\项目\prakrobot\ParkingRobot
+
+必须先完整读取：
+1. docs/superpowers/specs/2026-08-03-em-planner-ls-st-design.md
+2. docs/superpowers/specs/2026-08-03-em-planner-windowed-execution-design.md
+3. docs/superpowers/progress/em-planner-progress.md
+4. <当前阶段对应计划路径>
+
+本窗口只执行阶段 <N>：<阶段名称>。
+只执行计划中的 Task <范围>，不得提前执行下一阶段。
+
+开始前：
+- 检查当前分支、git status 和进度文件记录的最近检查点提交；
+- 运行进度文件中的阶段入口验证；
+- 保留所有既有无关工作区修改，不得清理、覆盖或顺带提交；
+- 若进度与 Git 或验证结果不一致，先诊断并报告，不要直接实施。
+
+执行要求：
+- 按对应实施计划逐任务使用 TDD；
+- 每个任务只提交计划指定文件并形成独立提交；
+- 不使用子代理；
+- 不实现当前阶段范围外功能；
+- 不处理已明确延期的动态障碍预测和动态绕障决策；
+- 生产代码不得依赖 UI、硬件对象或当前工作目录；
+- 任何完成声明前运行计划指定验证。
+
+阶段结束时：
+- 运行完整阶段出口验证和 git diff --check；
+- 更新并单独提交 docs/superpowers/progress/em-planner-progress.md；
+- 返回完成任务、提交、测试证据、遗留问题；
+- 给出阶段 <N+1> 可直接复制的新窗口提示词。
+```
+
+阶段 10 完成时，最后一项改为输出全链路验收结果，不再生成下一实施窗口提示词。
+
+## 8. 工作区保护
+
+当前仓库已有大量与 EM Planner 无关或作为前置工作的未提交修改。每个窗口必须：
+
+- 在开始和结束时保存 `git status --short` 结果用于范围对照；
+- 使用显式文件路径暂存，不使用 `git add .` 或 `git add -A`；
+- 不使用 `git reset --hard`、`git checkout --` 或清理未跟踪文件；
+- 不修改计划范围外的 Map、CoarsePath、PathSmoothing 和旧 `auto_avoidance` 文件；
+- 修改已有脏文件 `ClumsyPilot.csproj` 前先查看差异，只追加计划要求的最小变更；
+- 每次提交后用 `git diff-tree` 核对提交文件集合；
+- 发现与本阶段文件重叠的未知用户修改时停止并请求确认。
+
+已知主项目构建可能被旧 `auto_avoidance/MultiWheelAutoAvoidance.cs` 缺少 `NetTopologySuite` 和 `OpenCvSharp` 引用阻断。各阶段必须运行隔离的 EM 验证宿主；不得通过擅自删除旧功能来使主项目构建通过，也不得把该既有错误声明为 EM 回归。
+
+## 9. 失败与恢复
+
+### 9.1 任务中途失败
+
+保留已提交的前置任务。未完成任务不得提交半成品；若工作区已有该任务的未提交修改，在进度文件中记录准确文件和失败命令，阶段状态写为 `Blocked` 或 `InProgress`，不得写为 `Completed`。
+
+### 9.2 窗口意外关闭
+
+新窗口通过以下顺序恢复：
+
+```text
+git status
+git log 最近相关提交
+进度文件最近检查点
+对应计划中第一个未完成任务
+该任务的失败/通过验证
+```
+
+如果功能提交存在但进度文件未更新，以提交和测试为依据补写检查点；不得重复实现已经完成的任务。
+
+### 9.3 验证记录过期
+
+若进度文件记录的 `Verified commit` 不是当前相关 HEAD，新窗口必须重新运行入口验证。不得复用其他提交上的通过结果。
+
+### 9.4 外部依赖缺失
+
+OSQP 构建工具、原生 DLL 或许可证无法获得时，仅阻塞 OSQP 对应阶段。记录实际缺失项和命令输出；不得用假 DLL、空文件或跳过验证继续 LS/ST 集成。
+
+## 10. 成功标准
+
+多窗口执行协议满足以下条件时视为设计落地：
+
+1. 28 个任务被完整且无重复地映射到 10 个阶段；
+2. 每阶段最多三个任务且不跨子系统边界；
+3. 任意新窗口无需旧聊天记录即可定位当前任务；
+4. 每个已完成阶段都有功能提交、阶段验证证据和进度检查点提交；
+5. 任何失败都能明确定位到任务、文件、命令和提交；
+6. 用户既有工作区修改不会被暂存、提交、清理或覆盖；
+7. 阶段 1 至阶段 9 均产生可直接复制的下一窗口提示词；
+8. 阶段 10 产生完整的第一版 EM Planner 验收报告。