From 69fb09e61761b5c268d1614a05d70023df7e2d91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=81=E8=96=84=E4=BA=91?= Date: Tue, 4 Aug 2026 14:12:44 +0800 Subject: [PATCH] docs: plan planner comment overhaul --- ...planner-comment-overhaul-implementation.md | 295 ++++++++++++++++++ 1 file changed, 295 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-04-planner-comment-overhaul-implementation.md diff --git a/docs/superpowers/plans/2026-08-04-planner-comment-overhaul-implementation.md b/docs/superpowers/plans/2026-08-04-planner-comment-overhaul-implementation.md new file mode 100644 index 0000000..397dde9 --- /dev/null +++ b/docs/superpowers/plans/2026-08-04-planner-comment-overhaul-implementation.md @@ -0,0 +1,295 @@ +# PathSmoothing 与 TrajectoryExecution 注释改造实施计划 + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 为 PathSmoothing 生产规划核心与 TrajectoryExecution 全部生产代码补齐 CoarsePath 风格的中文 XML 文档注释。 + +**Architecture:** 只在现有声明之前增加或替换 `///` 文档注释，不改变任何命名、签名、数值、控制流或项目文件。公开 API 使用完整的职责、参数、返回值和失败语义；关键内部算法边界补充单位、数据所有权和不变量；私有小工具、测试、报告及可视化模块保持不动。 + +**Tech Stack:** C# XML documentation comments、PowerShell、现有 PathSmoothing 验证脚本、`EMPlannerVerificationHost`。 + +## Global Constraints + +- 只修改注释；禁止修改任何可执行 C# 语句、签名、命名空间、`using`、测试、`csproj`、UI、硬件或报告/可视化模块。 +- 注释使用中文，并保留 C# 类型名；每个数值参数或属性都要标明现有单位（m、rad、`1/m`、m/s、m/s²、m/s³、s）或明确其为 ID、索引、布尔值、枚举、快照或集合。 +- 每个公开构造函数和公开方法必须有 ``；有参数时逐项使用 ``；非 `void` 方法使用 ``；`Try...` 方法明确 `true` / `false` 和每个 `out` 参数。 +- 关键内部跨目录算法入口也使用相同规范；不为私有单行数学工具、测试、比较、报告或可视化代码增加注释。 +- 路径、状态和结果的注释必须说明不可变性、集合顺序、失败时的空结果或 `false` 语义；不得宣称代码当前未实现的动态障碍物、UI、硬件、横移或原地旋转能力。 +- 每个任务只能显式暂存该任务列出的文件；禁止 `git add .`、`git add -A`、清理命令或破坏性 Git 命令。 + +--- + +### Task 1: PathSmoothing 契约与公开门面注释 + +**Files:** +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/LocalG2QuinticOptions.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathQualityMetrics.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingConfiguration.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingDiagnostics.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionFailureReason.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionReport.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionStatus.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRequest.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingResult.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingStatus.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPoint.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPointSource.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathSegment.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothingMethod.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingService.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingComparisonService.cs` + +**Interfaces:** +- Consumes: `PlanningResult`、`PlanningGridMap`、`VehicleParameters`、不可变 `PathSmoothingRequest` 与 `PathSmoothingConfiguration`。 +- Produces: 只有成功状态才可消费的 `PathSmoothingResult`、严格递增弧长的 `SmoothedPathPoint` 序列，以及包含区域失败和性能信息的 `PathSmoothingDiagnostics`。 + +- [ ] **Step 1: 记录缺失参数/返回值注释的 RED 基线** + +```powershell +$path = 'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingService.cs' +$text = Get-Content $path -Raw -Encoding UTF8 +if ($text -notmatch 'public PathSmoothingResult Smooth\(') { throw 'Expected public Smooth entry point.' } +if ($text -match '') { throw 'RED baseline unexpectedly already documents request.' } +throw 'RED: PathSmoothingService.Smooth lacks parameter documentation.' +``` + +Expected: command exits nonzero with the RED message. + +- [ ] **Step 2: 为契约类型、构造函数、属性和门面补齐 XML 文档** + +使用 `apply_patch` 在每个公开类型前写职责和边界；在构造函数前写参数类型意义、单位、可空性、集合顺序和防御性复制语义；在关键属性前写数据含义和单位。为 `PathSmoothingService.Smooth`、比较服务入口和结果工厂写完整 `` / ``。 + +关键语义必须在注释中准确出现：`PathSmoothingRequest` 持有输入副本；`PathSmoothingResult` 仅在成功状态发布路径；`SmoothedPathPoint` 的位置为 m、航向 rad、曲率 `1/m`、弧长 m；失败结果不包含部分可消费路径。 + +- [ ] **Step 3: 运行 GREEN XML 契约检查** + +```powershell +$paths = @( + 'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRequest.cs', + 'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingResult.cs', + 'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPoint.cs', + 'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingService.cs' +) +$text = ($paths | ForEach-Object { Get-Content $_ -Raw -Encoding UTF8 }) -join "`n" +foreach ($marker in @('', '', '', 'm', 'rad', '1/m', '不可变')) { + if (-not $text.Contains($marker)) { throw "Missing XML documentation marker: $marker" } +} +if ($text -notmatch '失败.*部分|部分.*路径') { throw 'Missing partial-result failure semantics.' } +Write-Output 'PASS PathSmoothing contract XML documentation' +``` + +Expected: exit 0 and the PASS line. + +- [ ] **Step 4: 检查纯注释差异并提交 Task 1** + +```powershell +git diff --check +git diff -- ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade +git add -- ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/LocalG2QuinticOptions.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathQualityMetrics.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingConfiguration.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingDiagnostics.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionFailureReason.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionReport.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRegionStatus.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRequest.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingResult.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingStatus.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPoint.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathPointSource.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothedPathSegment.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothingMethod.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingService.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingComparisonService.cs +git diff --cached --check +git commit -m "docs: document path smoothing contracts" +git diff-tree --no-commit-id --name-only -r HEAD +``` + +Expected: cached diff and commit contain only the listed files, with no non-comment code changes. + +### Task 2: PathSmoothing 处理、校验与 LocalG2 阶段注释 + +**Files:** +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/ArcLengthResampler.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathGeometryAnalysis.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathGeometryAnalyzer.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathReferenceInterpolator.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathSmoothingPreprocessor.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PreparedDirectionSegment.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PreparedPath.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/RawPathBaselineBuilder.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/SmoothingPoint2D.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Validation/CurvatureLimitPolicy.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Validation/SmoothedPathValidator.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/CurvatureTransition.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/CurvatureTransitionDetector.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateBuilder.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateEvaluator.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateGeometry.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2OptionsSnapshot.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2PathSplicer.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2PreSmoothingPipeline.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2RegionWorkOrder.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2SmoothingRegion.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2WindowPlanner.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/QuinticHermiteCurve2D.cs` + +**Interfaces:** +- Consumes: 已准备的方向段、车辆约束、地图快照、局部 G2 配置和候选几何。 +- Produces: 连续且严格递增弧长的平滑段、候选评估/拒绝原因、验证结果和不可变区域报告。 + +- [ ] **Step 1: 记录关键 `Try...` 入口缺失返回语义的 RED 基线** + +```powershell +$path = 'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathSmoothingPreprocessor.cs' +$text = Get-Content $path -Raw -Encoding UTF8 +if ($text -notmatch 'TryPrepare\(') { throw 'Expected TryPrepare entry point.' } +if ($text -match '.*true.*false') { throw 'RED baseline unexpectedly documents TryPrepare outcomes.' } +throw 'RED: TryPrepare lacks true/false and out-result documentation.' +``` + +Expected: command exits nonzero with the RED message. + +- [ ] **Step 2: 补齐处理/验证/LocalG2 的阶段边界注释** + +使用 `apply_patch` 为公开类型与关键内部入口增加 ``、``、``。所有 `Try...` 方法必须说明成功/失败、`out` 值和原因字符串；几何方法必须说明世界坐标 m、航向 rad、曲率 `1/m`、弧长 m 和严格递增约束；校验器必须说明碰撞、曲率、换向锚点和无部分发布规则。 + +LocalG2 注释必须说明候选构建、预平滑、窗口选择、拼接和评估的输入/输出关系，不得将内部启发式误描述为动态障碍或控制功能。 + +- [ ] **Step 3: 运行 GREEN 内部算法注释检查** + +```powershell +$paths = @( + 'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathSmoothingPreprocessor.cs', + 'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Validation/SmoothedPathValidator.cs', + 'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2WindowPlanner.cs', + 'ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateEvaluator.cs' +) +$text = ($paths | ForEach-Object { Get-Content $_ -Raw -Encoding UTF8 }) -join "`n" +foreach ($marker in @('', '', 'true', 'false', 'm', 'rad', '1/m')) { + if (-not $text.Contains($marker)) { throw "Missing algorithm XML marker: $marker" } +} +if ($text -notmatch '严格递增|不发布部分') { throw 'Missing geometric or publication invariant.' } +Write-Output 'PASS PathSmoothing algorithm XML documentation' +``` + +Expected: exit 0 and the PASS line. + +- [ ] **Step 4: 运行既有 PathSmoothing 验证并提交 Task 2** + +```powershell +& .\ClumsyPilot\tests\verify_path_smoothing_geometry.ps1 +& .\ClumsyPilot\tests\verify_path_smoothing_validation.ps1 +& .\ClumsyPilot\tests\verify_path_smoothing_local_g2_integration.ps1 +git diff --check +git add -- ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/ArcLengthResampler.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathGeometryAnalysis.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathGeometryAnalyzer.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathReferenceInterpolator.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PathSmoothingPreprocessor.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PreparedDirectionSegment.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/PreparedPath.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/RawPathBaselineBuilder.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing/SmoothingPoint2D.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Validation/CurvatureLimitPolicy.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Validation/SmoothedPathValidator.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/CurvatureTransition.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/CurvatureTransitionDetector.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateBuilder.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateEvaluator.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2CandidateGeometry.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2OptionsSnapshot.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2PathSplicer.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2PreSmoothingPipeline.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2RegionWorkOrder.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2SmoothingRegion.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/LocalG2WindowPlanner.cs ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2/QuinticHermiteCurve2D.cs +git diff --cached --check +git commit -m "docs: document path smoothing pipeline" +git diff-tree --no-commit-id --name-only -r HEAD +``` + +Expected: three existing validation scripts exit 0; cached diff and commit contain only listed production files and comment-only changes. + +### Task 3: TrajectoryExecution 全部生产边界注释 + +**Files:** +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/EmPlanningCoordinator.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/GearSwitchState.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/GearSwitchStateMachine.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/IEmPlanningCycleSink.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/IVehicleStateProvider.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleIdentity.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleInput.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleResult.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryControlAdapter.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryControlCommand.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryExecutionState.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryExecutor.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryHandoffSelector.cs` +- Modify: `ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectorySampler.cs` + +**Interfaces:** +- Consumes: `IEmPlanningService`、调用方时钟与 `VehicleMotionState` 快照、已验证的不可变 `EmTrajectory`、方向确认状态和 `EmPlannerConfiguration`。 +- Produces: latest-wins `PlanningCycleResult`、安全交接选择、不可变 `TrajectoryExecutionState` 和控制器中立的 `TrajectoryControlCommand`。 + +- [ ] **Step 1: 记录协调器方法缺失完整契约的 RED 基线** + +```powershell +$path = 'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/EmPlanningCoordinator.cs' +$text = Get-Content $path -Raw -Encoding UTF8 +if ($text -notmatch 'PlanLatestAsync\(') { throw 'Expected PlanLatestAsync entry point.' } +if ($text -match '') { throw 'RED baseline unexpectedly already documents rolling input.' } +throw 'RED: PlanLatestAsync lacks caller-clocked input and cancellation documentation.' +``` + +Expected: command exits nonzero with the RED message. + +- [ ] **Step 2: 补齐执行、交接与控制契约注释** + +使用 `apply_patch` 为目录内所有公开类型、枚举、构造函数、属性和公开方法补齐 XML 文档；为 `CompleteCycle`、`SelectPoint`、交接/采样和换向状态机等跨职责内部入口补齐语义。 + +`EmPlanningCoordinator.PlanLatestAsync` 必须解释 caller-clocked `now`、取消旧周期、版本/身份检查和只发布完整成功轨迹。交接注释必须列出同段同方向、年龄、追踪、边界和末点拒绝。`UpdateCommand` 与 `TrajectoryControlCommand` 必须写明 m/s、rad/s、零速/制动、一次换向请求、无横向速度和无原地旋转。`TrySample` 必须明确区间外或跨边界时返回 `false`。 + +- [ ] **Step 3: 运行 GREEN 执行层 XML 契约检查** + +```powershell +$paths = @( + 'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/EmPlanningCoordinator.cs', + 'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryHandoffSelector.cs', + 'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryExecutor.cs', + 'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/GearSwitchStateMachine.cs', + 'ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryControlCommand.cs' +) +$text = ($paths | ForEach-Object { Get-Content $_ -Raw -Encoding UTF8 }) -join "`n" +foreach ($marker in @('', '', '', 'm/s', 'rad/s', 'latest-wins', '零速', 'false')) { + if (-not $text.Contains($marker)) { throw "Missing execution XML marker: $marker" } +} +if ($text -match 'MultiVehicleScriptVx|MultiVehicleScriptVy|MultiVehicleScriptVth') { + throw 'Documentation must not leak UI/hardware command fields.' +} +Write-Output 'PASS TrajectoryExecution XML documentation' +``` + +Expected: exit 0 and the PASS line. + +- [ ] **Step 4: 运行执行层回归并提交 Task 3** + +```powershell +dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- coordinator +dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- executor +git diff --check +git add -- ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/EmPlanningCoordinator.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/GearSwitchState.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/GearSwitchStateMachine.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/IEmPlanningCycleSink.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/IVehicleStateProvider.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleIdentity.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleInput.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/PlanningCycleResult.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryControlAdapter.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryControlCommand.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryExecutionState.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryExecutor.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectoryHandoffSelector.cs ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/TrajectorySampler.cs +git diff --cached --check +git commit -m "docs: document trajectory execution contracts" +git diff-tree --no-commit-id --name-only -r HEAD +``` + +Expected: both execution gates exit 0; cached diff and commit contain only listed files and comment-only changes. + +### Task 4: 最终注释审查与完整回归 + +**Files:** +- Modify: Task 1 至 Task 3 的文件（仅在发现缺失、错误单位或文档与实际行为矛盾时修正）。 + +**Interfaces:** +- Consumes: CoarsePath 风格的 XML 文档约定、PathSmoothing 的纯规划边界和 TrajectoryExecution 的 caller-clocked 执行边界。 +- Produces: 与实际代码一致、可由 IDE XML 文档显示的中文 API 说明。 + +- [ ] **Step 1: 检查差异仅包含注释** + +```powershell +$diff = git diff 297186a..HEAD -- ClumsyPilot/ParkrobTrajplanner/PathSmoothing ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution +$codeLines = $diff | Where-Object { $_ -match '^[+-](?![+-/\s])' } +if ($codeLines.Count -gt 0) { $codeLines; throw 'Non-comment C# changes detected.' } +Write-Output 'PASS comment-only diff review' +``` + +Expected: exit 0 and the PASS line. Ignore `+++` / `---` headers and `///` documentation lines. + +- [ ] **Step 2: 运行最终构建与门禁** + +```powershell +dotnet build ClumsyPilot/ClumsyPilot.csproj --no-restore +dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- em-all +git diff --check +git status --short -- ClumsyPilot/ParkrobTrajplanner/PathSmoothing ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution +``` + +Expected: build 和 `em-all` 退出 0；无 whitespace 错误；两个目标目录没有未提交状态。 + +- [ ] **Step 3: 仅在最终审查发现需修正时，显式暂存和提交** + +```powershell +git add -- ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Processing ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Validation ClumsyPilot/ParkrobTrajplanner/PathSmoothing/LocalG2 ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution +git diff --cached --check +git commit -m "docs: verify planner XML comments" +git diff-tree --no-commit-id --name-only -r HEAD +``` + +Expected: 仅在文字修正发生时创建提交；否则不执行此步骤。