# SignalReach Phase 10 Handoff (CLI)

## Ground rules
- Work only on the CLI app (signalreach). UI will launch python and render outputs; do not add UI post-processing requirements.
- Keep mission JSON schema stable (UI depends on it). Add new knobs via raw JSON reads when possible.
- Prefer reversible edits: always make backups; avoid brittle regex patchers that rewrite large blocks.
- Output KMLs/PNGs are written into a run folder; relative references assume files live together.

## Current “known-good” behavior
- JSON input is read with UTF-8-SIG tolerant read (BOM-safe).
- Validation gate is conservative: “full_cov” is forced from Fresnel/LOS union over validation points to avoid false 100% coverage.
- LOS sampling supports stratified sampling:
  - mission.los.sampling = "random" | "stratified"
  - mission.los.strata_spacing_m = meters (recommended 150–200)
- Workers: mission.workers supports 1–8; default 8 for field boxes.

## Locked field-grade preset (validated)
- Stratified sampling: strata_spacing_m=150
- los.max_points≈10000
- workers=8
- validate_full=true, validate_full_max_points=20000, warn_delta=2.0
On test AOI, delta converged to about -0.2%.

## Performance notes
- Big runtime is dominated by candidate LOS evaluation when los.max_points is large.
- Tiered planning can be heavy; extenders precompute can parallelize.

## Candidate selection “Phase 10+” upgrade backlog (pin these)
1) Coverage-frontier candidate injection (cluster worst pockets, inject, re-opt)
2) Crest snap (local max elevation within radius)
3) Saddle detection and inclusion
4) Multi-resolution candidate mining (coarse→prune→refine)
5) Early backhaul plausibility scoring in candidate ranking
6) Redundancy/resilience scoring (marginal gain + secondary paths; penalize SPOF)
Optional: feasible-deployment constraints (roads/slope/land access)

## Output contract reminders (UI integration)
- Run directory is unit-of-truth: out\runs\<run_id>\
- KMLs expect referenced images to be in SAME folder (serve directory as-is).
- Don’t rename/move files post-run; it breaks Google Earth rendering.