[Epic] Fable 5 architecture closeout — remaining decompositions and behavior consolidations

[suraj-ranganath]

🤖 This epic replaces and supersedes #197 and #205. It tracks the remaining Fable 5 architecture closeout work that was intentionally not included in PR #204 because it either changes observable behavior, spans broad ownership boundaries, or decomposes large modules.

Summary

Complete the remaining Fable 5 architecture and behavior-consolidation findings in bounded, reviewable phase PRs. The goal is not cosmetic churn. Each phase must remove real duplicated contracts, correct behavior drift where EEGLAB parity or EEGPrep session semantics require it, and preserve EEGPrep as a standalone Python application that remains familiar and pleasant for EEG researchers.

Branching

• Epic branch: feature/fable5-architecture-closeout
• Phase PR target: feature/fable5-architecture-closeout
• Final epic PR target: develop
• Base stack: this branch starts from fable5/epic / PR [Epic] Fable 5 Findings — whole-codebase code-quality remediation #206, so it is stacked on the Fable 5 umbrella PR until [Epic] Fable 5 Findings — whole-codebase code-quality remediation #206 merges.

Scope

In scope:

• Remaining findings from [Fable 5 Findings] Phase 4 — Architecture: kill duplication, fix ownership & decompose sprawl #197 that were not fully completed by [arch] Kill duplication, fix ownership & layering (Fable 5 Phase 4) #204.
• All follow-up items from [Fable 5 Findings] Phase 4b — large-file decomposition & behavior-changing consolidations #205.
• Tests and docs needed to prove behavior remains correct or is deliberately corrected.

Out of scope:

• New EEGPrep product features unrelated to the Fable 5 findings.
• Broad formatting-only churn.
• Reopening completed Phase 1/2/3/5 work from [Fable 5 Findings] Phase 1 — Test-suite integrity: make CI able to fail #194, [Fable 5 Findings] Phase 2 — EEG data integrity: stop mutating the caller & preserve ICA invariants #195, [Fable 5 Findings] Phase 3 — Correctness bugs, silent failures & misleading contracts #196, or [Fable 5 Findings] Phase 5 — Standalone packaging, dependencies, docs & dead-code cleanup #198 unless a phase needs a small adjacent regression test.

Phases

• [Fable 5 Architecture Closeout] Phase 1 — shared contracts, boundary events, and history mutation #208 — Phase 1: shared contracts, boundary events, and history mutation
• [Fable 5 Architecture Closeout] Phase 2 — rejection, ICA, and clean_rawdata helper convergence #209 — Phase 2: rejection, ICA, and clean_rawdata helper convergence
• [Fable 5 Architecture Closeout] Phase 3 — STUDY, time-frequency, and statistics behavior consolidation #210 — Phase 3: STUDY, time-frequency, and statistics behavior consolidation
• [Fable 5 Architecture Closeout] Phase 4 — CLI and extension architecture consolidation #211 — Phase 4: CLI and extension architecture consolidation
• [Fable 5 Architecture Closeout] Phase 5 — BIDS, Qt, and FIR ownership decomposition #212 — Phase 5: BIDS, Qt, and FIR ownership decomposition
• [Fable 5 Architecture Closeout] Phase 6 — statistics and ICLabel decomposition closeout #213 — Phase 6: statistics and ICLabel decomposition closeout

Parallelization And Merge Order

1. Merge [Fable 5 Architecture Closeout] Phase 1 — shared contracts, boundary events, and history mutation #208 first. It defines the shared low-level contracts other phases should consume.
2. After [Fable 5 Architecture Closeout] Phase 1 — shared contracts, boundary events, and history mutation #208, [Fable 5 Architecture Closeout] Phase 2 — rejection, ICA, and clean_rawdata helper convergence #209, [Fable 5 Architecture Closeout] Phase 3 — STUDY, time-frequency, and statistics behavior consolidation #210, [Fable 5 Architecture Closeout] Phase 4 — CLI and extension architecture consolidation #211, and [Fable 5 Architecture Closeout] Phase 5 — BIDS, Qt, and FIR ownership decomposition #212 can run in parallel if agents coordinate imports and helper names.
3. Merge [Fable 5 Architecture Closeout] Phase 2 — rejection, ICA, and clean_rawdata helper convergence #209 and [Fable 5 Architecture Closeout] Phase 3 — STUDY, time-frequency, and statistics behavior consolidation #210 before [Fable 5 Architecture Closeout] Phase 6 — statistics and ICLabel decomposition closeout #213, because [Fable 5 Architecture Closeout] Phase 6 — statistics and ICLabel decomposition closeout #213 does final audit/closeout and the statistics split should follow the behavior-consolidation decisions.
4. Merge [Fable 5 Architecture Closeout] Phase 6 — statistics and ICLabel decomposition closeout #213 last and run the epic-level integration/review pass before opening the final epic PR.

Recommended order: #208 -> (#209 + #210 + #211 + #212) -> #213 -> final epic PR.

Epic-Level Acceptance Criteria

• [Fable 5 Findings] Phase 4 — Architecture: kill duplication, fix ownership & decompose sprawl #197 and [Fable 5 Findings] Phase 4b — large-file decomposition & behavior-changing consolidations #205 are replaced by this issue tree and closed as superseded.
• Every remaining [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 finding is either fixed in a phase PR or explicitly reclassified with a defensible reason in the final closeout PR.
• Phase PRs are independently reviewable and target feature/fable5-architecture-closeout.
• Runtime code has no dependency on src/eegprep/eeglab.
• GUI, eegprep-console, CLI, extension, STUDY, and BIDS behavior stay synchronized with EEGPrep’s documented contracts.
• Final branch passes ruff check, ruff format --check, ty check, ./pre-commit.py --changed-from origin/develop, and relevant pytest suites. Use MATLAB parity tests where the behavior is numerical and deterministic.

Closeout Evidence

All phase PRs have merged into feature/fable5-architecture-closeout: #214, #215, #217, #218, #216, and #219. Local epic-branch verification passed ruff check, ruff format --check, ty check, ./pre-commit.py --changed-from origin/develop, focused architecture integration tests, and EEGPREP_SKIP_MATLAB=1 uv run --no-sync pytest -m "not slow".

[claude]

🤖 Plan:

• Read AGENTS.md, fix-issue and pull-request skills
• Fetch and analyze issue body
• Duplicate-work preflight (no open PRs targeting feature/fable5-architecture-closeout)
• Decide actionability

Assessment: not actionable as a single PR.

This is an epic/tracker, not a concrete change request. The body explicitly defers content: "Concrete phase issue links will be added after the sub-issues are created." There is no specific file/module to change, no reproduction or definition of done for a single PR, and the scope ("remaining #197/#205 findings") is unenumerated here.

What is needed before an agent can implement anything:

1. Create the phase sub-issues that decompose this epic. Each sub-issue must name the affected modules/files, the specific finding from [Fable 5 Findings] Phase 4 — Architecture: kill duplication, fix ownership & decompose sprawl #197 or [Fable 5 Findings] Phase 4b — large-file decomposition & behavior-changing consolidations #205 it addresses, and acceptance criteria (tests, parity check, or behavior assertion).
2. Confirm the epic branch feature/fable5-architecture-closeout exists and its base (currently stacked on [Epic] Fable 5 Findings — whole-codebase code-quality remediation #206 / fable5/epic).
3. Point an agent at a specific phase issue (e.g. /fix-issue <phase-id>), not at this epic.

Stopping here per the fix-issue skill: no PR will be opened against an epic with no enumerated phases. Re-invoke against a concrete phase issue once one exists.