diff --git a/docs/superpowers/specs/2026-07-30-local-g2-path-presmoothing-design.md b/docs/superpowers/specs/2026-07-30-local-g2-path-presmoothing-design.md index aa125fb..6814e01 100644 --- a/docs/superpowers/specs/2026-07-30-local-g2-path-presmoothing-design.md +++ b/docs/superpowers/specs/2026-07-30-local-g2-path-presmoothing-design.md @@ -225,7 +225,7 @@ r''(u_endpoint) = λ² κ_geometric N ### 9.3 单个曲率事件 -窗口外端点从稳定的原始圆弧读取位置、切线和曲率。原运动基元边界的位置和航向作为内部锚点,跳变两侧的两个曲率值替换为一个共享的内部目标曲率。 +窗口外端点从稳定的原始圆弧读取位置、切线和曲率。原运动基元边界的航向作为内部硬边界值;其位置默认作为内部锚点,但允许按 `2026-07-31-local-g2-soft-anchor-candidate-recovery-design.md` 在配置偏移范围内沿运动法向生成有限软位置锚点候选。跳变两侧的两个曲率值替换为一个共享的内部目标曲率。 内部目标曲率首先按照事件左右可用长度做距离加权插值: @@ -245,7 +245,7 @@ r''(u_endpoint) = λ² κ_geometric N 当窗口重叠时: - 合并为一个联合区域。 -- 保留各运动基元边界的位置和航向作为内部锚点。 +- 保留各运动基元边界的航向;位置按软锚点恢复设计生成有限、同配置的内部位置候选。 - 每个内部锚点只允许一个共享曲率值。 - 相邻五次 Hermite 片段共享位置、一阶导数和二阶导数。 - 内部共享曲率和导数尺度通过有限、确定性的候选组合选取。 diff --git a/docs/superpowers/specs/2026-07-31-local-g2-soft-anchor-candidate-recovery-design.md b/docs/superpowers/specs/2026-07-31-local-g2-soft-anchor-candidate-recovery-design.md index e434081..4008cc0 100644 --- a/docs/superpowers/specs/2026-07-31-local-g2-soft-anchor-candidate-recovery-design.md +++ b/docs/superpowers/specs/2026-07-31-local-g2-soft-anchor-candidate-recovery-design.md @@ -26,9 +26,34 @@ Three alternatives were considered: family. 3. Keep all outer window boundary states exact while treating each internal primitive boundary as a bounded, deterministic soft anchor. Chosen: it - expands geometry freedom only inside the existing `0.10 m` deviation budget; + expands geometry freedom only inside the configured deviation budget; every candidate still passes the unchanged evaluator before publication. +This document explicitly overrides the internal-anchor position rule in +sections 9.3 and 9.4 of the main Local G2 design. Path start, path end, gear +switches, and outer window endpoints remain hard position anchors. An internal +primitive boundary becomes a soft **position** anchor only; its vehicle heading +and distance-weighted shared curvature remain hard boundary values for a given +candidate. No other main-design contract is relaxed. + +## Feasibility gate before production + +The fixed-anchor sweep does not prove that any particular soft-anchor offset is +feasible. Before changing `LocalG2CandidateBuilder`, a temporary test-only +probe must construct the exact soft-anchor profiles defined below for the real +`SingleTurn` fixture and evaluate them with the unchanged +`LocalG2CandidateEvaluator`. + +The probe records, for every attempted tuple, the window, signed offset, +derivative multiplier, rejection reason, maximum vehicle curvature, raw and +candidate curvature range, peak `|dκ/ds|`, variation cost, maximum deviation, +and minimum clearance. It is removed after the evidence is recorded. + +The feasibility gate passes only if at least one non-zero-offset tuple satisfies +all existing gates, including 20 percent peak-gradient improvement. If it does +not pass, production builder work stops and this design must be revised; fixture +expectations and evaluator thresholds are not changed to force GREEN. + ## Candidate construction For each `LocalG2SmoothingRegion`, the outer window endpoints remain exact @@ -48,23 +73,75 @@ internal anchors in a combined region, so adjacent quintic pieces still share one position, heading, derivative scale, and curvature at each anchor and therefore remain G2. -The finite profile order for every legal window is: +The finite profile order for every selected representative window is: -1. `offset = 0.00 m`, derivative multiplier `1.00` (exact-anchor baseline); -2. `offset = +0.05 m`, derivative multiplier `0.85`; -3. `offset = -0.05 m`, derivative multiplier `1.15`. +1. `offset = 0`, derivative multiplier `1.00` (exact-anchor baseline); +2. `offset = +softOffset`, derivative multiplier `1.00`; +3. `offset = -softOffset`, derivative multiplier `1.00`. + +The offset is configuration-aware: + +```text +softOffset = min(0.05 m, 0.5 × MaximumDeviationMeters) +``` + +If `softOffset <= 1e-10 m`, only the exact-anchor baseline is emitted. Offset +and derivative scale are not coupled in this recovery: the feasibility result +must isolate whether position freedom itself fixes the geometric limitation. +The existing `0.85` and `1.15` derivative profiles are not silently combined +with soft offsets; adding them later requires separate evidence and another +bounded design update. The signed offsets are intentionally both present; vehicle turn sign and map orientation must not choose a preferred side. A two-node, one-piece region has -no internal anchor and therefore emits only the exact-anchor baseline. The -existing global `MaximumCandidatesPerRegion` cap remains authoritative; profile -enumeration is deterministic and stops at that cap. No configuration value is -added in this recovery step. +no internal anchor and therefore emits only the exact-anchor baseline. No +configuration value is added in this recovery step. -The 0.05 m profile displacement is only a candidate-construction bound, not an -acceptance relaxation. The unchanged evaluator must still prove the complete -candidate's maximum deviation is at most the configured 0.10 m, as well as all -curvature, collision, clearance, finite-value, direction, and quality gates. +`softOffset` is only a candidate-construction bound, not an acceptance +relaxation. The unchanged evaluator must still prove the complete candidate's +maximum deviation is at most the request's configured +`MaximumDeviationMeters`, as well as all curvature, collision, clearance, +finite-value, direction, and quality gates. + +## Candidate-budget scheduling + +`MaximumCandidatesPerRegion` limits emitted geometries, not window variants. +The window planner and builder must not exhaust the budget on asymmetric splits +or three profiles for the first few targets. + +The window planner exposes total-length targets in deterministic coverage +passes. Distinct, legal target lengths are ordered as preferred, minimum, +maximum, 0.75 × preferred, and 1.25 × preferred. The first pass attempts the +balanced split for every target, the second pass attempts 40/60, and the third +pass attempts 60/40. Each pass stops at the existing window-variant cap. Thus +the default limit of 12 exposes preferred, minimum, and maximum total-length +windows before optional asymmetric variants can consume the budget. With a +configured limit below three, only the earliest target lengths are guaranteed; +the result remains deterministic and within the user's requested cap. + +From the variants actually exposed by the planner, the builder selects at most +four distinct representative windows in this fixed order: + +1. the planner's first window (preferred planner order); +2. the legal window with minimum total length; +3. the legal window with maximum total length; +4. the legal window with greatest left/right asymmetry. + +Ties use `LocalG2WindowVariant.CandidateIndex`; duplicate window references are +removed. If fewer than four representatives exist, all distinct +representatives are used. If the candidate limit is below the required count, +enumeration is profile-major and window-stable: + +1. emit the exact-anchor baseline once for each representative window; +2. emit `+softOffset` once for each representative window; +3. emit `-softOffset` once for each representative window; +4. stop immediately when the configured limit (capped by the existing hard + maximum of 12) is reached. + +This guarantees baseline coverage before optional soft profiles and prevents a +single window from consuming the complete budget. Invalid or duplicate +geometries do not alter the deterministic attempt order; candidate indices are +assigned densely to successfully emitted geometries. ## Publication and failure behavior @@ -82,24 +159,44 @@ regression to assert all of the following against actual preprocessor, detector, window planner, builder, and evaluator instances: - the exact-anchor baseline remains present and deterministic; -- at least one emitted candidate is accepted by the unchanged evaluator; -- the accepted candidate stays within the configured 0.10 m deviation limit, +- the feasibility probe finds at least one accepted non-zero-offset tuple before + production code changes; +- after implementation, a non-zero-offset builder candidate is emitted and at + least one such candidate is accepted by the unchanged evaluator; +- the accepted candidate stays within the configured `MaximumDeviationMeters`, original curvature range, vehicle curvature limit, collision/clearance gates, and 20 percent peak-gradient-improvement gate; +- the outer window endpoint positions, headings, and curvatures remain exact; +- every moved internal anchor retains its original heading and shared curvature, + and both adjacent pieces meet it with one shared position/tangent/curvature; +- with the default candidate cap, representative-window selection includes the + preferred, minimum, maximum, and most-asymmetric legal windows when they are + distinct; +- limits from `1` through `12` never emit more candidates than configured and + preserve the documented profile-major order; +- a configuration with `MaximumDeviationMeters < 0.10 m` scales `softOffset` + and never constructs an anchor outside half of that configured budget; - the same request produces the same candidate sequence and selected result on two runs; -- forward and reverse source/heading conventions remain unchanged. +- forward and reverse source/heading conventions remain unchanged; +- a combined multi-event region remains internally G2 and does not exceed the + candidate budget when the same signed profile is applied to all soft anchors. -The test must be observed failing before production changes, then pass after the -smallest builder-only implementation. Task 8 service integration must then +The permanent regression must be observed failing before production changes, +then pass after the smallest planner-and-builder implementation. Task 8 +service integration must then restore `SingleTurn -> Complete` and continue to prove cancellation, rollback, two-region work order, report order, and legacy-method isolation. ## Scope -Production change is limited to `LocalG2CandidateBuilder.cs`; the focused -candidate verifier and existing Task 8 integration/service files may change for -TDD and end-to-end coverage. The previously authorized evaluator boundary -de-duplication remains part of this Task 8 recovery. No safety threshold, -validator tolerance, window length, vehicle model, comparison-default method, -or collision/clearance behavior changes. +Production changes are limited to `LocalG2WindowPlanner.cs` and +`LocalG2CandidateBuilder.cs`; the focused detection/candidate verifiers and +existing Task 8 integration/service files may change for TDD and end-to-end +coverage. The previously authorized evaluator boundary de-duplication remains +part of this Task 8 recovery. No safety threshold, validator tolerance, window +length, vehicle model, comparison-default method, or collision/clearance +behavior changes. The main Local G2 design is amended only to reclassify +internal primitive-boundary positions as bounded soft anchors and to guarantee +representative target coverage before asymmetric window variants; all other +hard-anchor and safety contracts remain unchanged.