# Adaptive Breast Shield Implementation Plan

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

**Goal:** Replace the seven-rail female chest plate with a continuous adaptive breast-and-upper-abdomen shield that blocks leash penetration across the complete front contour.

**Architecture:** A pure `AdaptiveBreastShieldPolicy` builds an actor-local basis and continuous surface from left/right Breast01 plus Spine/Spine1/Spine2. `ActorBodyCollision` interpolates that shield, evaluates overlap/sweeps against it, and renders sampled debug contours while RopeSolver remains on its existing point + single midpoint collision path.

**Tech Stack:** C++20, CommonLibSSE-NG runtime integration, portable GCC/Clang policy tests, Python source-integration tests.

**Spec:** `docs/superpowers/specs/2026-08-26-adaptive-breast-shield-design.md`

## Global Constraints
- No CBBE/3BA triangle-mesh collision.
- Do not change pull, recovery, persistence, DynamicMeshes, leash NIFs/nodes, material physics, or `RECOMPILAR_DLL_NATIVO.bat`.
- Keep RopeSolver's original single midpoint segment collision architecture; do not add multiple segment samples.
- Preserve old JSON compatibility by retaining `enabled`, `radiusScale`, and `forwardOffset` keys while adding defaulted `surfaceMargin` and `abdomenCoverage` fields.

---

### Task 1: Continuous shield policy

**Files:**
- Create: `src/Physics/AdaptiveBreastShieldPolicy.h`
- Create: `tests/adaptive_breast_shield_test.cpp`
- Modify: `cmake/SourceFiles.cmake`

**Interfaces:**
- Consumes: no runtime collision policy; the new header owns its portable point math and adaptive-shield settings.
- Produces: `AdaptiveBreastShieldPolicy::Shield`, `BuildShield(...)`, `EvaluateSurface(...)`, `ComputeOutwardOverlap(...)`, `SweepSphere(...)`.

- [x] Write portable failing tests for left/right lobes, convex center bridge, abdomen taper, overlap projection, sweep crossing, and invalid/disabled input.
- [x] Run GCC and Clang tests and verify RED because `AdaptiveBreastShieldPolicy.h` is absent.
- [x] Implement the minimal continuous surface policy with bounded bisection for sweeps.
- [x] Run the new GCC and Clang tests and verify GREEN.

### Task 2: Actor body integration and debug shape

**Files:**
- Modify: `src/Physics/ActorBodyCollision.h`
- Modify: `src/Physics/ActorBodyCollision.cpp`
- Modify: `src/Physics/SimulationSettings.h`
- Modify: `src/UI/ModMenu.cpp`
- Create: `tests/adaptive_breast_shield_integration_test.py`

**Interfaces:**
- Consumes: `AdaptiveBreastShieldPolicy::Shield` and collision functions from Task 1.
- Produces: runtime female chest shield integrated into `FindDeepestOverlap`, `SweepSphere`, bounds, interpolation, and debug drawing.

- [x] Write failing source-integration tests asserting no `ChestPlatePolicy::BuildPlate`/rail collision remains in ActorBodyCollision and that debug uses sampled shield surface lines.
- [x] Run integration test and verify RED against the seven-rail baseline.
- [x] Replace `ChestPlatePolicy::Plate` with `AdaptiveBreastShieldPolicy::Shield`, keep generic torso primitives unchanged, and update menu labels only.
- [x] Run portable and integration tests and verify GREEN.

### Task 3: Remove obsolete cleavage side-lock path without changing rope collision topology

**Files:**
- Modify: `src/Physics/RopeSolver.h`
- Modify: `src/Physics/RopeSolver.cpp`
- Modify: `src/Physics/ActorBodyCollision.h`
- Modify: `src/Physics/ActorBodyCollision.cpp`
- Modify: `src/Physics/WorldCollision.h`
- Modify: `src/Physics/WorldCollision.cpp`
- Create: `tests/adaptive_shield_rope_integration_test.py`

**Interfaces:**
- Consumes: normal actor-body `Hit` without cleavage-side state.
- Produces: same collision calls and exactly one midpoint sweep per leash segment, with no cleavage side-lock state.

- [x] Write failing source-integration tests requiring zero `_cleavageSideLock` references and exactly one `fromMid`/midpoint segment path.
- [x] Run integration test and verify RED because side-lock remnants still exist.
- [x] Remove legacy cleavage-side plumbing only; do not alter point-sweep, contact, constraint, or midpoint behavior.
- [x] Run all portable and integration tests and verify GREEN.

### Task 4: Package and regression verification

**Files:**
- Package the complete mod tree to `/mnt/data/LeashFramework_COMPLETE_v7_Stable_AdaptiveBreastShield.zip`.
- Create focused diff `/mnt/data/LeashFramework_v7_ChestPlate_to_AdaptiveBreastShield.diff`.

- [x] Run `python3 tools/verify_v7.py`.
- [x] Run every portable test with GCC and Clang.
- [x] Run every Python integration test.
- [x] Compare all NIF hashes, ESM, packaged DLL, and rebuild BAT against the ChestPlate baseline and require them to be byte-identical.
- [x] Re-extract the final ZIP and repeat verifier/tests from the extracted package.
- [x] Compute SHA-256 hashes for the ZIP, diff, BAT, and packaged DLL.
