ParkingRobot/docs/superpowers/plans/2026-08-03-local-g2-only-path-smoothing-reorganization.md

# LocalG2-Only PathSmoothing Reorganization Implementation Plan

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

**Goal:** Convert `PathSmoothing` into a LocalG2-only module, remove the three legacy smoothing algorithms, preserve LocalG2 visualization and fixture workflows, and organize the source tree and README using the established `CoarsePath` module pattern.

**Architecture:** The production facade always runs the LocalG2 pipeline. Shared path preparation and validation remain intact; B-spline, local Bezier, and piecewise quintic implementations and their configuration are removed. Offline reports remain a factual comparison of raw coarse path versus LocalG2 only, with visualization sources placed below an `Output` layer like `CoarsePath`.

**Tech Stack:** C# 10, .NET SDK, Newtonsoft.Json, existing System.Drawing/StbImageWriteSharp report exporter, PowerShell verification hosts.

## Global Constraints

- Do not read, search, enumerate, copy, modify, delete, stage, or commit `ClumsyPilot/ParkrobTrajplanner/auto_avoidance`; do not enumerate `ClumsyPilot/ParkrobTrajplanner` as a parent.
- Preserve LocalG2 candidate construction, validation, publication statuses, fixture data, diagnostic candidate visualization, and generated report artifacts below `ClumsyPilot/obj/path_smoothing_reports`.
- Remove all production references to `CubicBSpline`, `LocalCubicBezier`, and `PiecewiseQuintic` smoothing.
- Retain the raw-path baseline in reports. Normal reports must contain only raw and LocalG2 series and four figures; diagnostic reports may append the already-rejected LocalG2 candidate as a fifth figure.
- Maintain current default `MinimumClearanceReserveMeters = 0d`.
- Do not delete unrelated user work or generated report directories.

---

### Task 1: Establish a LocalG2-only verification contract

**Files:**
- Modify: `ClumsyPilot/tests/verify_path_smoothing_comparison.ps1`
- Modify: `ClumsyPilot/tests/verify_path_smoothing_svg_csv.ps1`
- Modify: `ClumsyPilot/tests/PathSmoothingPngVerificationHost/Program.cs`

**Interfaces:**
- The comparison request exposes exactly one requested method: `SmoothingMethod.LocalG2Quintic`.
- A normal report has a raw baseline plus one LocalG2 row/series; the diagnostic report retains its optional rejected candidate figure.

- [ ] Add failing assertions that reject the three removed enum names, require one requested comparison method, require two normal figure series, and require exactly two CSV rows after the header.
- [ ] Run the focused PowerShell checks and confirm they fail against the four-algorithm implementation.
- [ ] Update host assertions for the new two-series normal report while retaining the seven-file diagnostic contract.
- [ ] Re-run the focused checks after Tasks 2 and 3 and record the exit codes.

### Task 2: Remove legacy algorithms and simplify the production facade

**Files:**
- Delete: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Algorithms/`
- Delete: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/CubicBSplineOptions.cs`
- Delete: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/LocalCubicBezierOptions.cs`
- Delete: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PiecewiseQuinticOptions.cs`
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/SmoothingMethod.cs`
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingConfiguration.cs`
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingRequest.cs`
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathSmoothingResult.cs`
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Facade/PathSmoothingService.cs`

**Interfaces:**
- `SmoothingMethod` retains only `LocalG2Quintic`.
- `PathSmoothingConfiguration` defaults `Method` to `LocalG2Quintic` and exposes only shared safety/sampling fields and `LocalG2Quintic` options.
- `PathSmoothingService.Smooth(request, cancellationToken)` directly validates/prepares/builds the raw baseline and invokes `LocalG2PreSmoothingPipeline`.

- [ ] Delete legacy source files only after their callers are removed.
- [ ] Remove legacy smoothness/retry configuration and cloning code; preserve output spacing, collision step, clearance reserve, and LocalG2 options.
- [ ] Replace the multi-method resolver and fallback path in `PathSmoothingService` with its LocalG2-only route.
- [ ] Compile the isolated PathSmoothing host and confirm no source references to the removed methods remain in allowed paths.

### Task 3: Reorganize report sources into an Output layer and reduce the report model

**Files:**
- Move: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Comparison/` to `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Output/Comparison/`
- Move: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Visualization/` to `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Output/Visualization/`
- Delete: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Output/Comparison/SmoothingMethodRanker.cs`
- Modify: moved comparison request/result/service consumers and all moved visualization files.

**Interfaces:**
- `PathSmoothingComparisonRequest` owns one immutable LocalG2 request rather than a caller-selectable method list.
- `PathSmoothingComparisonResult` contains a raw baseline and exactly one LocalG2 entry.
- Normal figure and CSV builders emit `RawPath` and `LocalG2Quintic` only.

- [ ] Move source directories with their namespaces changed from `PathSmoothing.Comparison` and `PathSmoothing.Visualization` to `PathSmoothing.Output.Comparison` and `PathSmoothing.Output.Visualization`.
- [ ] Simplify comparison execution to warm up and measure LocalG2 only; retain deterministic timing/digest behavior for its sole entry.
- [ ] Remove visual style colors, legend rows, labels, metric rows, and all source references for the three deleted algorithms.
- [ ] Publish four normal figures with stable stems `01-coarse-path-overview`, `02-all-paths-comparison`, `03-local-g2-overview`, and `04-curvature-comparison`; append `05-local-g2-diagnostic-candidate` only to an augmented diagnostic model.
- [ ] Update all allowed source/test imports to the new `Output` namespaces.

### Task 4: Align test/demo entry points and document the module

**Files:**
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Test/PathSmoothingComparisonDemo.cs`
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Test/SmoothingScenarioFactory.cs`
- Modify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Test/LocalG2DiagnosticVisualizationDemo.cs`
- Create: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/README.md`

**Interfaces:**
- Fixture reports use the LocalG2-only comparison request and retain all eight fixtures.
- The README mirrors the `CoarsePath/README.md` information architecture for LocalG2 inputs, safety gates, result statuses, report output, and known limitations.

- [ ] Update test/demo imports and expected report shapes for the Output namespaces and LocalG2-only model.
- [ ] Create `README.md` with the following ordered sections: Module Overview, File Structure, Smoothing Data Flow, Result Status and Publication Rules, Coordinates and Units, Minimal Call Example, Detailed Usage Guide, Fixture Reports and Visualization, Common Errors, and First-Version Limits.
- [ ] State explicitly that a candidate passing collision validation may still be retained when its quality gate fails, and that `0 m` reserve removes only the additional clearance reserve, not collision or curvature checks.

### Task 5: Verify source layout and retain visualization artifacts

**Files:**
- Verify: `ClumsyPilot/ParkrobTrajplanner/PathSmoothing/`
- Verify: `ClumsyPilot/obj/path_smoothing_reports/`

- [ ] Build and run the isolated current-source LocalG2 visualization host against all eight fixture scenarios.
- [ ] Confirm all normal report directories contain the expected four PNG/SVG figures and CSV, and that `02-all-paths-comparison.png` presents raw plus LocalG2 only.
- [ ] Run the focused comparison/SVG/diagnostic verification scripts where their dependencies are available; report any root-build limitation separately.
- [ ] Inspect at least the `single-turn` normal report and `05-local-g2-diagnostic-candidate.png` to confirm LocalG2 labels, nonblank rendering, and retained diagnostic semantics.
- [ ] Update `.superpowers/sdd/progress.md` with the actual cleanup results and verification evidence.