# 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: 仅在文字修正发生时创建提交；否则不执行此步骤。