Revert "docs: remove stale roadmap note"

This reverts commit 46ab302118.

ROADMAP.md

@@ -0,0 +1,221 @@
+# SDR Wideband Suite - Persisted Roadmap
+
+This file is the durable architectural roadmap and phase memory for the project.
+It exists so a context reset, model switch, or new coding agent can continue from the real project state without reconstructing the entire plan from chat history.
+
+## Current Project Status
+
+The project has progressed through four major milestones:
+
+- **Phase 1 complete**: architecture foundation
+- **Phase 2 complete**: multi-resolution surveillance semantics
+- **Phase 3 complete**: conservative runtime prioritization / admission / rebalance intelligence
+- **Phase 4 complete**: monitor-window operating model
+
+This roadmap reflects the actual code state as of the latest landed Phase-4 work.
+
+---
+
+## Phase 1 - Architecture Foundation (Complete)
+
+### Intent
+Turn the original SDR visualizer into a scalable, policy-driven wideband SDR engine.
+
+### Delivered
+- explicit config model for `pipeline`, `surveillance`, `refinement`, `resources`, `profiles`
+- separation of surveillance / refinement / presentation concerns
+- explicit candidate / refinement model
+- centralized arbitration / admission surface for refinement / record / decode
+- budget / hold / queue scaffolding
+- profile and policy surface established
+
+### Meaning
+Phase 1 established the architecture so later scaling would not require another ground-up rewrite.
+
+---
+
+## Phase 2 - Multi-Resolution Surveillance Semantics (Complete)
+
+### Intent
+Make surveillance genuinely multi-level and connect those levels to candidate behavior.
+
+### Delivered
+- operational surveillance level sets
+- derived / decimated surveillance spectra
+- primary / derived / support / presentation level roles
+- derived detection governance
+- candidate evidence model across levels
+- primary/derived fusion
+- level-aware refinement scoring
+- debug/API visibility for surveillance levels and evidence
+
+### Meaning
+Phase 2 moved the system from a single-spectrum mentality toward a real multi-resolution surveillance engine.
+
+---
+
+## Phase 3 - Runtime Prioritization / Admission / Rebalance (Complete)
+
+### Intent
+Move from architecture + heuristics to conservative runtime intelligence.
+
+### Delivered
+- priority tiers and admission classes
+- richer reason taxonomy across refinement / record / decode
+- budget preference and effective budget semantics
+- pressure summaries
+- hold / protection / opportunistic displacement semantics
+- intent-aware hold behavior
+- family-aware tier floors
+- conservative adaptive cross-resource rebalance
+- debug/API visibility for admission / pressure / rebalance state
+
+### Meaning
+Phase 3 created a real runtime decision layer rather than just a scoring layer.
+It is intentionally conservative, explainable, and incremental rather than a full adaptive scheduler.
+
+---
+
+## Phase 4 - Monitor-Window Operating Model (Complete)
+
+### Intent
+Turn monitor windows from simple goal/gating objects into operational monitoring zones inside a capture span.
+
+### Delivered
+- `monitor_windows` in config/goals/policy/runtime
+- monitor-window candidate gating
+- per-window candidate attribution
+- per-window stats
+- monitor-window priority bias
+- window-based record/decode actions
+- lightweight zone hints:
+  - `focus`
+  - `record`
+  - `decode`
+  - `background`
+- consolidated `window_summary`
+- per-window pressure / outcome summaries
+- overlap and zone/action tests
+- debug/API visibility for monitor-window behavior
+
+### Meaning
+Phase 4 delivered a practical operating model for multiple monitoring zones within a single capture span, without requiring full hardware multi-span orchestration.
+
+---
+
+# Next Planned Phases
+
+## Phase 5 - Span / Operating-Orchestration
+
+### Core idea
+Move from monitor windows inside one capture span to richer orchestration across operational spans / span groups / monitoring areas.
+
+### Target outcomes
+- explicit span / zone groups
+- span-aware resource allocation
+- stronger profile-driven operating modes
+- retune / dwell / revisit semantics where hardware or mode requires it
+- more operational behavior across multiple monitoring regions, not just one captured span
+
+### Likely sub-areas
+- span orchestration model
+- span-aware resource allocation
+- profile-driven operating modes
+- retune / scan / dwell semantics
+
+### Important note
+Phase 5 should still avoid unnecessary premature hardware-specific complexity, but it is the logical next step after the monitor-window model.
+
+---
+
+## Future Architecture Note - Observation/Track Reconciliation
+
+A likely later improvement is an explicit reconciliation layer between:
+- raw surveillance observations / candidates
+- stable tracked signals / identities
+
+This is intentionally NOT the first fix for live-audio regressions.
+For now, stable-ID-carrying signal sources should be used for stream/session-sensitive paths.
+If needed later, a dedicated observation-to-track reconciliation layer can be introduced as its own architecture block.
+
+## Phase 6 - Adaptive QoS / Scheduler Intelligence
+
+### Core idea
+Make the engine more adaptive under changing load and signal density.
+
+### Target outcomes
+- deeper QoS model
+- adaptive runtime rebalance beyond the conservative Phase-3 layer
+- richer priority ecology (decay, revisit, persistence, overload behavior)
+- broader operating-state behavior under calm / dense / overload conditions
+
+### Important note
+This should build on the operational structures from Phase 5 rather than bypass them.
+
+---
+
+## Phase 7 - Performance / Scale / Hardware Depth
+
+### Core idea
+Turn the architecture into a genuinely high-bandwidth, high-throughput system.
+
+### Target outcomes
+- GPU spectral pyramid / multi-resolution acceleration
+- better batching / buffering / async processing
+- larger stable operating bandwidths
+- profiling / benchmark / regression discipline for throughput
+
+### Important note
+Performance work should follow the behavioral model, not lead it.
+
+---
+
+## Phase 8 - Productization / Operator Workflow / Polish
+
+### Core idea
+Turn the powerful engine into a polished operator product.
+
+### Target outcomes
+- better UX and status visibility
+- reusable monitoring plans / templates
+- export / review / workflow polish
+- safer and clearer autonomous behavior
+- polished docs, defaults, and examples
+
+---
+
+# Practical Continuation Guidance
+
+If a future agent resumes work, the recommended order is:
+
+1. **Start with Phase 5**, not Phase 6/7/8.
+2. Treat Phases 1-4 as completed milestones.
+3. Avoid reopening already-closed phase work unless there is a concrete bug or mismatch.
+4. Before starting a new major block, inspect the current repo state and confirm the roadmap still matches the code.
+5. Prefer milestone-sized coherent blocks over broad speculative redesigns.
+
+---
+
+# Current Default Testing / Operator Context
+
+A valid FM/UKW-oriented test config was intentionally introduced for easier local testing.
+Current default direction:
+- FM broadcast band (87.5-108 MHz)
+- centered around 99.5 MHz
+- `wideband-balanced`
+- `broadcast-monitoring`
+- WFM/RDS-friendly priorities
+
+If that changes later, update this file when the default operator/testing posture changes materially.
+
+---
+
+# Why this file exists
+
+This file is meant to survive:
+- context resets
+- model changes
+- agent swaps
+- long pauses in development
+
+It should be kept updated whenever a phase is meaningfully completed or the roadmap changes materially.