diff --git a/AGENT-LOG.md b/AGENT-LOG.md index dcf23f7..e5b88ae 100644 --- a/AGENT-LOG.md +++ b/AGENT-LOG.md @@ -642,3 +642,144 @@ Verified `docs/design/configuration-system.md` line-by-line against `AppConfig.h | File | Action | |------|--------| | `docs/design/configuration-system.md` | Documented the `@`-attribute (BadgerFish) convention, string-vector `` serialization, and empty-name→`node` element fallback in `DataTree` | + +--- + +## Session: Design Doc Reorganization — PRIORITY Merge and Reorg Plan + +**Date:** 2026-08-05 +**Model:** opencode/deepseek-v4-flash-free + +Reviewed all 9 design docs plus PLAN/PRIORITY/RECOMMENDATIONS. Found `PRIORITY.md` duplicating `PLAN.md` (code-quality table + execution order), the CMake-mismatch table duplicated between `design/README.md` and `PRIORITY.md`, and cross-doc duplication (ReBuffer in signal-flow+threading, VisualProcessor pipeline in threading+visual-architecture, canvas OnIdle in both). Per user approval, executed items #1 and #2 and wrote a reorg plan for #3A + the visual split. + +### Files Modified + +| File | Action | +|------|--------| +| `docs/PLAN.md` | Added "Source Fixes & Documentation" section (items 1-6 from PRIORITY), registered reorganize-design-docs plan in the plans table | +| `docs/PRIORITY.md` | Deleted (items folded into PLAN; no remaining references) | +| `docs/design/README.md` | Removed CMakeLists source/header mismatch table (now single-sourced in PLAN) | +| `docs/plans/reorganize-design-docs.md` | Created: owner-per-module consolidation (#3A) and visual-architecture render/data split | + +## Session: Design Doc Reorganization — Plan Self-Containment Check + +**Date:** 2026-08-05 +**Model:** opencode/deepseek-v4-flash-free + +Re-audited the reorg plan against the source docs via grep. Found it was incomplete for a future +agent: ReBuffer actually appears in three docs (signal-flow, threading, audio-subsystem), not two; +VisualProcessor internals are restated across threading Pattern 6/7 and visual-architecture; and the +`busy_run`/`busy_update` thread-safety and OnIdle pull model were duplicated with no owner decision. +Rewrote `docs/plans/reorganize-design-docs.md` to be fully self-contained with a verified duplication +audit table, explicit owner boundaries, a section-by-section split map for both new visual files, +index-update steps, out-of-scope items, and grep-based verification criteria. + +### Files Modified + +| File | Action | +|------|--------| +| `docs/plans/reorganize-design-docs.md` | Rewrote with duplication audit, owner boundaries, section-level split map, verification criteria | + +## Session: Reorg Plan — Accuracy Review and Softening + +**Date:** 2026-08-05 +**Model:** opencode/deepseek-v4-flash-free + +Re-verified the reorganize-design-docs plan against every design doc. Confirmed accuracy (ReBuffer in +signal-flow+threading+audio; VisualProcessor in threading+visual-architecture; canvas pull in +threading+visual-architecture; only README.md and PLAN.md link the to-be-deleted file). Applied +corrections to the plan: resolved the Overview/data-path diagram to single ownership +(visual-data-pipeline.md owns the topology diagram; visual-rendering.md keeps overview prose and links); +assigned the `ReBuffer`/`SpinMutex` thread-safety row to `signal-flow.md` rather than the pipeline doc; +clarified the "SpinMutex / atomically-just" wording; fixed a duplicate "GL state" typo; and added the +plan to PLAN.md's Recommended Execution Order (it was listed among plans but missing from the order). + +### Files Modified + +| File | Action | +|------|--------| +| `docs/plans/reorganize-design-docs.md` | Clarified diagram and SpinMutex row ownership, fixed wording/typo, noted PLAN.md execution-order gap | +| `docs/PLAN.md` | Added "Reorganize Design Docs" as step 7 in Recommended Execution Order (renumbered 7-10 to 8-11) | + +## Session: Reorg Plan — Verification and Corrections + +**Date:** 2026-08-05 +**Model:** opencode/deepseek-v4-flash-free + +Re-verified the reorganize-design-docs plan against the actual docs. Confirmed the audit table rows, +section split coverage, and size claim; found two issues and applied corrections: (1) the "Update +Indexes" step claimed the plan was missing from PLAN.md's execution order, but PLAN.md already lists it +in the plans table and as step 7 — removed that stale instruction; (2) the audit under-counted +`signal-flow.md`, whose "Visual Processing Pipeline" restates the visual topology diagram, +`FFTDataDistributor` rate-limiting, and the canvas pull model — added it as a duplicate source (rows 2 +and 3) and upgraded its handling from "add a cross-link" to "trim to cross-links" in the Update Indexes +and Files sections. + +### Files Modified + +| File | Action | +|------|--------| +| `docs/plans/reorganize-design-docs.md` | Corrected stale PLAN.md execution-order claim; added signal-flow.md as duplicate source and changed its handling to a trim-to-cross-links step | + +--- + +## Session: Reorg Plan — Correction of Remaining Owner-Boundary Inconsistencies + +**Date:** 2026-08-06 +**Model:** opencode/deepseek-v4-flash-free + +Re-verified the reorganize-design-docs plan against every design doc (audit rows, section split map, +index claims, dead-link check). Confirmed the plan was accurate and complete, then applied three +owner-boundary clarifications: (1) removed the "lists which canvases poll in OnIdle vs OnPaint" step +from threading.md's "wxWidgets Integration", which contradicted visual-rendering.md's single ownership +of that per-canvas table; (2) noted that the two generic Thread Safety Summary rows +(`ThreadBlockingQueue`, `std::shared_ptr`) are already owned by threading Pattern 1 and are not +restated after the split; (3) clarified that threading's Synchronization table remains the canonical +lock inventory for `SpinMutex` → ReBuffer, with signal-flow mentioning SpinMutex only as a one-line +pool-mechanics note. + +### Files Modified + +| File | Action | +|------|--------| +| `docs/plans/reorganize-design-docs.md` | Step 1: threading drops the per-canvas OnIdle/OnPaint enumeration; added note on generic Thread Safety rows; clarified `SpinMutex`/ReBuffer canonical ownership. Files table: threading row updated to match | + +--- + +## Session: Reorg Plan — Disambiguation Edits + +**Date:** 2026-08-06 +**Model:** opencode/deepseek-v4-flash-free + +Re-verified the reorganize-design-docs plan against all design docs and source (ReBuffer constants, +SpinMutex lock, audit rows, section split, index claims, dead-link check) and applied four small edits +to the plan doc: (1) size claim "roughly 2-5x" instead of "2-4x"; (2) noted `cache_busy` SpinMutex stays +in visual-rendering.md as component-internal detail (threading lock inventory unchanged); (3) recorded +that `SpectrumVisualData`/`ScopeRenderData` in signal-flow.md's Data Types table stay there as +data-path artifacts (visual-data-pipeline.md references by name); (4) verification note that +`AGENT-LOG.md` references the old filename as history and should be left untouched. + +### Files Modified + +| File | Action | +|------|--------| +| `docs/plans/reorganize-design-docs.md` | Wording/disambiguation: size claim, GL concurrency lock note, Data Types ownership note, AGENT-LOG.md exclusion note | + +## Session: Reorg Plan — Implementation Readiness Prep + +Independent verification of the `reorganize-design-docs.md` plan against all current design docs +(signal-flow, threading, visual-architecture, audio-subsystem, design/README, PLAN). Confirmed every +audit row, the section-split boundaries, the index/dead-link claims (only `design/README.md` and +`docs/PLAN.md` link the to-be-deleted `visual-architecture.md`; AGENT-LOG.md references are historical), +and the audio/ReBuffer ownership notes. Because a separate agent session will perform the final +implementation, added a verbatim **Source-to-Destination Map** section to the plan mapping every +`visual-architecture.md` heading to its destination file (rendering vs data-pipeline, plus the +Thread-Safety-rows reassignment), so the split is mechanical and nothing is dropped or misassigned. +Also disambiguated the `signal-flow.md` SpinMutex phrasing (it is an end-state instruction, not current +content). No changes were made to any design document. + +### Files Modified + +| File | Action | +|------|--------| +| `docs/plans/reorganize-design-docs.md` | Added "Source-to-Destination Mapping" table and inline split reconciliation notes; clarified SpinMutex end-state phrasing | diff --git a/docs/PLAN.md b/docs/PLAN.md index 96a641d..b341ef3 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -39,6 +39,27 @@ Design documents covering the system architecture are in [docs/design/](design/) | [Remove MSVC C4996 Suppression](plans/remove-c4996-suppression.md) | Medium | 1-2 days | None | | [Add CI Test Execution](plans/add-ci-test-execution.md) | Low | 2 hours | add-unit-tests | | [Update Vendored Dependencies](plans/update-vendored-deps.md) | High | 3-5 days | None | +| [Reorganize Design Docs](plans/reorganize-design-docs.md) | Low | 1 day | None | + +## Source Fixes & Documentation + +Discrete tasks not covered by the implementation plans above, tracked here as the single source for their next-step list. + +### Source Code Fixes + +| # | Action | Risk | Effort | Notes | +|---|--------|------|--------|-------| +| 1 | Fix 17m band range in `BookmarkMgr.cpp` | Low | 5 min | Change to ITU 18.068-18.168 MHz. Check if adjacent bands need adjustment. | +| 2 | Fix CMakeLists.txt source/header mismatches | None | 10 min | 5 entries in wrong category. Doesn't break build but misrepresents structure. | + +### Documentation Improvements + +| # | Action | Risk | Effort | Notes | +|---|--------|------|--------|-------| +| 3 | Add CONTRIBUTING.md | None | 1 hr | Build instructions, code style, PR process. Currently missing. | +| 4 | Add CHANGELOG.md | None | 1 hr | Version history. Currently missing. | +| 5 | Add Doxygen config | None | 2 hr | API docs generation. Currently missing. | +| 6 | Improve README.md | None | 30 min | Add inline build instructions (currently only on external wiki). | ## Recommended Execution Order @@ -50,7 +71,8 @@ Execute in this order to minimize risk and satisfy dependencies: 4. **Replace reinterpret_cast** — Low risk, standalone, improves correctness 5. **Modernize CMake** — Low-medium risk, standalone, enables better build practices 6. **Split AppFrame.cpp** — Low risk, standalone, reduces cognitive load for later work -7. **Resolve TODOs** — Depends on AppFrame split and reinterpret_cast replacement -8. **Replace Raw new/delete** — Medium risk; do after tests exist to catch regressions -9. **Remove C4996 Suppression** — Medium risk; requires touching many files -10. **Update Vendored Dependencies** — Highest risk; do last, requires extensive testing +7. **Reorganize Design Docs** — Low risk, documentation only, standalone, reduces cross-doc drift +8. **Resolve TODOs** — Depends on AppFrame split and reinterpret_cast replacement +9. **Replace Raw new/delete** — Medium risk; do after tests exist to catch regressions +10. **Remove C4996 Suppression** — Medium risk; requires touching many files +11. **Update Vendored Dependencies** — Highest risk; do last, requires extensive testing diff --git a/docs/PRIORITY.md b/docs/PRIORITY.md deleted file mode 100644 index 8aca814..0000000 --- a/docs/PRIORITY.md +++ /dev/null @@ -1,36 +0,0 @@ -# Priority Next Steps - -Recommended actions after architecture documentation review. Items are ordered by priority and dependency. - -## Source Code Fixes - -| # | Action | Risk | Effort | Notes | -|---|--------|------|--------|-------| -| 1 | Fix 17m band range in `BookmarkMgr.cpp` | Low | 5 min | Change to ITU 18.068-18.168 MHz. Check if adjacent bands need adjustment. | -| 2 | Fix CMakeLists.txt source/header mismatches | None | 10 min | 5 entries in wrong category. Doesn't break build but misrepresents structure. | - -## Documentation Improvements - -| # | Action | Risk | Effort | Notes | -|---|--------|------|--------|-------| -| 3 | Add CONTRIBUTING.md | None | 1 hr | Build instructions, code style, PR process. Currently missing. | -| 4 | Add CHANGELOG.md | None | 1 hr | Version history. Currently missing. | -| 5 | Add Doxygen config | None | 2 hr | API docs generation. Currently missing. | -| 6 | Improve README.md | None | 30 min | Add inline build instructions (currently only on external wiki). | - -## Code Quality (from RECOMMENDATIONS.md) - -Execute in this order per `docs/PLAN.md`: - -| # | Plan | Risk | Effort | Dependencies | -|---|------|------|--------|-------------| -| 7 | Fix .gitignore | None | 5 min | None | -| 8 | Add unit tests | Low | 2-3 days | None | -| 9 | Add CI test execution | Low | 2 hours | #8 | -| 10 | Replace reinterpret_cast type punning | Low | 1 day | None | -| 11 | Modernize CMake | Low-Med | 1-2 days | None | -| 12 | Split AppFrame.cpp | Low | 1 day | None | -| 13 | Resolve open TODOs | Low | 1 day | #11, #12 | -| 14 | Replace raw new/delete | Medium | 1 day | #8 | -| 15 | Remove MSVC C4996 suppression | Medium | 1-2 days | None | -| 16 | Update vendored dependencies | High | 3-5 days | None | diff --git a/docs/design/README.md b/docs/design/README.md index 19c6d03..77190a9 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -59,17 +59,3 @@ src/ | `AudioSinkFileThread` | `src/audio/AudioSinkFileThread.h` | WAV file recording | | `IOThread` | `src/IOThread.h` | Base class for all worker threads | | `ThreadBlockingQueue` | `src/util/ThreadBlockingQueue.h` | Primary inter-thread communication mechanism | - -### CMakeLists.txt Source/Header Mismatches - -The `CMakeLists.txt` source file lists have several entries in the wrong category: - -| File | Listed As | Should Be | -|------|----------|-----------| -| `src/sdr/SoapySDRThread.h` | Source | Header | -| `src/panel/MeterPanel.h` | Source | Header | -| `src/sdr/SoapySDRThread.cpp` | Header | Source | -| `src/ui/UITestCanvas.cpp` | Header | Source | -| `src/ui/UITestContext.cpp` | Header | Source | - -CMake treats both lists as source files for compilation, so these mismatches do not affect the build.