[Epic] Close out Fable 5 architecture findings

[suraj-ranganath]

Summary

Completes the Fable 5 architecture closeout epic (#207), which supersedes the deferred architecture findings from #197 and #205 after the earlier Fable 5 umbrella work. This PR removes duplicated behavior contracts, decomposes large ownerless modules, and tightens architecture around rejection, ICA, clean_rawdata, STUDY/time-frequency/statistics, CLI/extensions, BIDS, Qt, FIR, statistics, and ICLabel/viewprops while preserving EEGPrep's standalone runtime and EEGLAB-familiar user behavior.

Phase Issues And PRs

• [Fable 5 Architecture Closeout] Phase 1 — shared contracts, boundary events, and history mutation #208 / PR [Fable 5] Consolidate shared contracts #214: Shared contracts, boundary events, and history mutation. Added canonical value parsing, event/boundary helpers, pop-result/session-history handling, and regression tests so GUI, console, and processing paths share the same contracts.
• [Fable 5 Architecture Closeout] Phase 2 — rejection, ICA, and clean_rawdata helper convergence #209 / PR Converge rejection ICA clean helpers #215: Rejection, ICA, and clean_rawdata helper convergence. Consolidated rejection-family plumbing, ICA component activation/sorting helpers, clean_rawdata channel-removal masks, and sample-data regressions.
• [Fable 5 Architecture Closeout] Phase 3 — STUDY, time-frequency, and statistics behavior consolidation #210 / PR Consolidate STUDY time-frequency stats behavior #217: STUDY, time-frequency, and statistics behavior consolidation. Centralized STUDY trial/design/measure helpers, bootstrap/FDR/p-value logic, time-frequency parsing, and clustering/statistics behavior while preserving tested outputs.
• [Fable 5 Architecture Closeout] Phase 4 — CLI and extension architecture consolidation #211 / PR Consolidate CLI and extension architecture #218: CLI and extension architecture consolidation. Routed CLI pipeline transforms through canonical command helpers, fixed structured error behavior, restored EEG-facing plugin metadata, and updated agent CLI docs/skill guidance.
• [Fable 5 Architecture Closeout] Phase 5 — BIDS, Qt, and FIR ownership decomposition #212 / PR Decompose BIDS Qt and FIR ownership #216: BIDS, Qt, and FIR ownership decomposition. Extracted BIDS raw/montage ownership, FIR design helpers, clean_rawdata filter ownership, and Qt dialog widget-family structure without changing user-facing dialogs.
• [Fable 5 Architecture Closeout] Phase 6 — statistics and ICLabel decomposition closeout #213 / PR [Fable 5] Decompose statistics and ICLabel closeout modules #219: Statistics and ICLabel decomposition closeout. Split the statistics mega-module into same-name implementation modules, separated ICLabel pop/history glue from numerics and dashboard rendering, and recorded the [Fable 5 Findings] Phase 4 — Architecture: kill duplication, fix ownership & decompose sprawl #197/[Fable 5 Findings] Phase 4b — large-file decomposition & behavior-changing consolidations #205 closeout mapping in implementation notes.

What This Enables

• Architecture now follows EEGPrep ownership boundaries: pop wrappers coordinate user workflows, low-level helpers own signal/statistical behavior, GUI rendering is separated from processing logic, and extension/CLI surfaces reuse package contracts instead of carrying parallel implementations.
• Rejection, ICA, clean_rawdata, time-frequency, STUDY, CLI, BIDS, FIR, statistics, and ICLabel/viewprops code paths are easier to maintain because duplicated kernels and divergent semantics have been consolidated or explicitly documented as non-goals.
• EEGPrep remains standalone. Runtime code does not depend on the vendored EEGLAB checkout; EEGLAB stays a parity reference only.
• GUI and eegprep-console behavior remain synchronized through session/history helpers, and user-facing command/history strings are preserved where the phases touched those paths.

GUI Evidence

This epic is primarily architecture and behavior consolidation. It did not introduce new GUI screens. PR #219 preserves the existing pop_prop_extended dialog/dashboard behavior, and the visual parity suite remains the evidence surface for the affected GUI flows. No new side-by-side image attachment was required for this final closeout PR.

Verification

• uv run --no-sync ruff check .
• uv run --no-sync ruff format --check .
• uv run --no-sync ty check
• ./pre-commit.py --changed-from origin/develop
• EEGPREP_SKIP_MATLAB=1 uv run --no-sync pytest tests/test_clean_rawdata_channel_removal.py tests/test_cli_pipeline_qc_report.py tests/test_cli_transforms.py tests/test_plugin_menu.py tests/test_extension_runtime.py tests/test_phase4_timefreq_statistics.py tests/test_study_long_tail_helpers.py tests/test_study_clustering.py tests/test_rejection_workflows.py tests/test_bids_load_frombids_helpers.py tests/test_firfilt_helpers.py tests/test_statistics_package.py tests/test_pop_prop_extended.py tests/test_gui_pop_prop_extended.py -q
• EEGPREP_SKIP_MATLAB=1 uv run --no-sync pytest -m "not slow" -q

Closes #193
Closes #207

[claude]

PR Review: Close out Fable 5 architecture findings

• Gather PR context and diff vs origin/develop
• Review correctness & regressions
• Review EEGLAB parity & data structures
• Review CLAUDE.md/AGENTS.md compliance & maintainability
• Validate findings
• Post review

View job run

[suraj-ranganath]

🤖 claude review this PR again. The earlier Claude review check was cancelled; please review the current final Fable 5 architecture closeout PR against develop.

[suraj-ranganath]

🤖 @claude review this

[claude]

Claude finished @suraj-ranganath's task in 13s —— View job

---

PR Review: Close out Fable 5 architecture findings

• Gather PR context and diff vs origin/develop
• Review correctness & regressions
• Review EEGLAB parity & data structures
• Review CLAUDE.md/AGENTS.md compliance & maintainability
• Validate findings
• Post review