docs: design staged EM full-direction execution

docs/superpowers/specs/2026-08-06-em-full-direction-segment-staged-execution-design.md

@@ -0,0 +1,181 @@
+# EM 完整方向段规划与可视化修复阶段执行设计
+
+**日期：** 2026-08-06
+
+**状态：** 已批准阶段划分
+
+**适用仓库：** `D:\Users\Desktop\项目\prakrobot\ParkingRobot`
+
+## 1. 目的
+
+现有设计和总实施计划覆盖规划器、MovementTest、Web、Native Painter、文档和实车验收，若在一个长窗口中连续实现，容易累积过多上下文、混淆旧证据与新证据，并增加无关修改被误带入提交的风险。
+
+本设计把已批准的 11 个实施任务重新组织为 9 个可独立交接的阶段。每个阶段由一个新窗口中的智能体执行；阶段完成后必须留下可审计交接，并生成下一阶段可直接复制的新提示词。阶段协议只切分执行，不改变功能设计、测试标准或安全边界。
+
+## 2. 权威资料与职责
+
+以下文档保持各自职责，不互相复制或替代：
+
+- 功能设计：`docs/superpowers/specs/2026-08-06-em-full-direction-segment-visualization-repair-design.md`。
+- 总实施计划：`docs/superpowers/plans/2026-08-06-em-full-direction-segment-visualization-repair.md`。
+- 本阶段执行设计：定义跨窗口边界、交接格式、阻塞行为和提示词协议。
+- 后续阶段执行计划：逐阶段列出需要阅读的总计划任务、允许修改范围、验证命令、提交和提示词正文。
+- 阶段交接：`docs/superpowers/handoffs/em-full-direction-visualization/phase-XX.md`。
+
+功能设计是需求权威；总实施计划是 TDD 步骤和接口权威；阶段执行计划只负责安排顺序。若三者出现不一致，新窗口必须停止扩展实现，记录矛盾并请求用户决定，不得自行重新设计。
+
+## 3. 阶段划分
+
+| 阶段 | 对应总计划 | 核心结果 | 阶段退出门禁 |
+| --- | --- | --- | --- |
+| 1 | Task 1–2 | 显式规划范围、配置、状态码、完整方向段选择 | 契约、默认值、复制、请求验证、滚动兼容和完整段选择测试通过 |
+| 2 | Task 3 | 从 Local G2 `s_end` 和速度/停车包络导出自适应优化结点与 `T_end` | 时间结点、资源上限、滚动兼容和发布采样独立性测试通过 |
+| 3 | Task 4–5 | 静止起步、零进度拒绝、终点 3 cm/5° 位姿和发布样本门禁 | 原始全零症状变红后修复；终点、yaw wrap、样本数和 jerk 测试通过 |
+| 4 | Task 6 | MovementTest 每个方向段只规划一次，换向后才规划下一段 | 一次规划、观察持续、停车保持与三个带符号速度样本测试通过；无执行器调用 |
+| 5 | Task 7 | 统一快照、路径图层、曲线单位、`s_end`、车辆与换向语义 | C# 快照和可视化契约宿主通过；完整段不重复发布 current horizon |
+| 6 | Task 8 | 真实 DOM/SVG 测试、分页、空白总览、双轴刻度和论文风格图层修复 | jsdom 与 .NET 可视化宿主通过；原网页结构不重做 |
+| 7 | Task 9 | 每张图独立框选、滚轮、重置和全屏观察 | 交互 DOM 测试证明视域变化且原始快照不变 |
+| 8 | Task 10 | Native Painter 坐标、比例、LS/ST 和标记语义修正 | Painter 几何/源审计与观察宿主通过；不出现大黑三角 |
+| 9 | Task 11 | 文档、全量自动化、本地烟雾和受监督实车验收 | 自动证据新鲜；实车安全执行后通过，或明确保持“实车待验/阻塞” |
+
+每阶段最多实现表中列出的总计划任务。不得为了“顺手完成”提前修改下一阶段文件，除非当前阶段编译所需的最小签名传播已经在总计划中明确列出。
+
+## 4. 阶段 9 的双检查点
+
+阶段 9 允许使用两个新窗口，但仍属于同一验收阶段：
+
+1. **阶段 9 自动验收窗口：** 更新 README，运行全量自动验证和确定性本地网页烟雾，创建 `phase-09.md`。若没有可确认的有人监督安全环境，将状态写为“自动验收完成但实车待验”，并输出阶段 9 实车续验提示词。
+2. **阶段 9 实车续验窗口：** 只核查自动证据是否仍可沿用，并在受监督安全环境执行实车清单。通过或阻塞后创建 `phase-09-vehicle.md`。
+
+自动验收不替代实车观察。任何实车项无法安全执行都必须记录为未完成，不得声称整体完成。不得通过操作真实底盘帮助只读观察条件成立。
+
+## 5. 每个阶段的启动协议
+
+新窗口首先执行以下只读动作：
+
+1. 记录当前分支、HEAD 和最近提交。
+2. 验证上一阶段交接声明的实现提交和交接提交均为当前 HEAD 的祖先。
+3. 完整阅读功能设计、本阶段执行计划中的当前阶段、总实施计划中映射的 Task，以及上一阶段交接。
+4. 读取提示词要求的技能文件；实现阶段必须使用 test-driven-development，出现测试失败或意外行为时使用 systematic-debugging，完成声明和提交前使用 verification-before-completion。
+5. 检查 `git status --short` 和 `git diff --cached --name-only`，记录既有脏工作区与暂存区。
+6. 对准备修改且已经脏的文件，先保存其精确 diff 证据，并逐 hunk 保留用户修改。
+7. 如果上一阶段后相关代码发生变化，先重跑受影响的上一阶段验证，不能直接沿用旧证据。
+
+新窗口不得重新 brainstorming、重新选择架构、扩展功能或派生子智能体。若权威资料存在真实矛盾，停止实现并写阻塞交接。
+
+## 6. 阶段内执行协议
+
+每阶段严格遵循总实施计划的 RED → GREEN → 回归验证顺序：
+
+1. 先添加当前阶段指定的失败测试。
+2. 运行精确命令，确认失败原因就是目标缺失或已知回归。
+3. 实现使该测试通过的最小改动。
+4. 运行当前阶段聚焦验证。
+5. 运行被修改共享接口影响的既有回归验证。
+6. 执行源审计、`git diff --check` 和显式暂存范围核查。
+7. 使用精确路径暂存并提交；不得使用 `git add .`、`git add -A` 或宽泛 glob。
+
+如果 RED 因环境、既有脏修改、依赖缺失或无关故障而失败，必须先用 systematic-debugging 确定首个有效原因。没有有效 RED 证据时不得写实现。
+
+## 7. 提交协议
+
+一个阶段可以包含总实施计划要求的多个小型实现提交，但必须满足：
+
+- 每个实现提交只包含当前阶段允许范围内的文件。
+- 提交信息沿用总实施计划给出的信息。
+- 共享脏文件只暂存本阶段 hunk；用户无关 hunk保持未暂存。
+- 当前阶段最后一个实现提交通过验证后，再创建阶段交接文件。
+- 阶段交接文件单独提交，信息格式为 `docs: record EM full-direction phase XX handoff`。
+
+交接提交不得夹带实现、测试、构建产物、截图、日志或用户脏文件。日志与截图只在交接中记录路径。
+
+## 8. 阶段交接格式
+
+每个 `phase-XX.md` 必须包含：
+
+- 状态：`完成` 或 `阻塞`；阶段 9 自动窗口可使用 `自动验收完成但实车待验`。
+- 阶段目标和明确非目标。
+- 启动分支、启动 HEAD、上一阶段交接提交。
+- 本阶段实现提交；交接提交的真实哈希由提交后的最终回答记录。
+- 修改文件列表。
+- 新增或改变的接口与精确语义。
+- RED 命令、首个有效失败和失败原因。
+- GREEN/回归命令、退出码、PASS 数量或关键输出。
+- 源审计、无硬件写输出和清理证据。
+- 保留的脏工作区/暂存内容。
+- 未运行验证及原因。
+- 已知警告和偏差。
+- 下一阶段允许范围。
+- 下一阶段所需的事实输入、允许范围和验证要求。
+
+交接里的验证必须是本阶段新鲜证据。只引用更早阶段证据时，要明确说明可达提交和为什么代码未受影响。
+
+## 9. 阻塞协议
+
+出现以下任一情况，阶段状态写为“阻塞”，不得推进到下一阶段：
+
+- 当前阶段的首个有效回归未能在允许范围内修复。
+- 需要修改下一阶段或无关系统才能继续。
+- 权威设计和总计划发生真实矛盾。
+- 既有用户脏修改与目标 hunk 无法安全合并。
+- 必需环境或依赖不可用，且没有等价的安全验证。
+- 实车条件不受监督或不安全。
+
+阻塞交接必须记录首个有效失败、最小复现、当前安全影响、已排除原因、允许恢复的精确文件/命令范围，并生成“同阶段恢复提示词”，而不是下一阶段提示词。
+
+恢复窗口只处理交接记录的首个有效失败。恢复成功后补全原阶段交接，再生成下一阶段提示词。
+
+## 10. 下一阶段提示词协议
+
+每个阶段在交接文件提交完成后，最终回答必须包含一份可直接复制的完整提示词。交接文件负责保存生成该提示词所需的全部事实，但不写入尚未产生的自身提交哈希。最终回答中的提示词必须使用已创建的真实交接提交哈希，且不得依赖上一窗口聊天内容。提示词至少包含：
+
+1. 当前任务是阶段几、目标和对应总计划 Task。
+2. 仓库绝对路径、预期分支和上一阶段实现/交接提交。
+3. 必读设计、总计划具体 Task、阶段执行计划具体节和上一阶段交接路径。
+4. 必须读取的技能及触发条件。
+5. 启动时的分支、HEAD、祖先、提交可达性、脏工作区和相关变化核查。
+6. 本阶段允许创建/修改的精确文件范围。
+7. 本阶段禁止事项，包括不提前实现下一阶段、不扩展功能、不派生子智能体。
+8. 必须执行的 RED、GREEN、回归、构建、源审计和清理命令。
+9. 阶段成功的精确退出门禁。
+10. 交接文件路径、单独提交信息和最终回答格式。
+11. 阻塞时的记录要求和恢复提示词要求。
+
+提示词必须把上一阶段产生的真实提交哈希、验证事实、警告和未完成项填入正文，不能保留未解析的哈希变量、未决事项或依赖聊天上文的描述。
+
+## 11. 最终回答协议
+
+阶段完成时，最终回答按以下顺序给出：
+
+1. 阶段状态和完成的功能边界。
+2. 新鲜 RED/GREEN/回归证据。
+3. 实现提交和交接提交。
+4. 保留的脏工作区、未运行项和警告。
+5. 一个独立代码块中的下一阶段完整提示词。
+
+阻塞时先给出真实失败和安全影响，再给同阶段恢复提示词。不得在阻塞状态下输出下一阶段提示词。
+
+阶段 9 实车全部通过后，`phase-09-vehicle.md` 必须使用总实施计划规定的独立提交信息 `docs: record EM visualization vehicle acceptance`。最终回答列出新鲜实车证据和该提交，明确整体完成，不再输出后续提示词。
+
+## 12. 第一阶段启动输入
+
+在阶段执行计划获得批准并提交后，当前窗口负责生成阶段 1 的完整提示词。阶段 1 提示词至少要求阅读：
+
+- 本设计全文；
+- 功能设计第 1–6、9–12 节；
+- 总实施计划 Task 1–2；
+- 阶段执行计划阶段 1；
+- 当前阶段前置基线说明。
+
+阶段 1 只允许实现显式规划范围、配置/复制/校验、状态码、元数据和完整方向段选择；不得开始自适应时间结点、静止起步修复、MovementTest 或任何可视化修改。
+
+## 13. 完成标准
+
+阶段执行体系只在以下条件全部满足时视为建立完成：
+
+- 9 个阶段都具有明确输入、输出、允许范围和退出门禁。
+- 每阶段都能由不了解聊天历史的新窗口仅凭仓库文档启动。
+- 完成阶段会生成下一阶段完整提示词；阻塞阶段会生成同阶段恢复提示词。
+- 提交与交接分离，并保护所有无关脏工作区和暂存内容。
+- 自动验收与实车验收被明确分开，实车安全条件不可被自动证据替代。
+- 阶段 1 的首个可复制提示词包含真实基线提交且没有未解析变量。