refactor: Gate 6 batch 6 remove spectral_fl package shim

2-mean · cursoragent · 2-mean · commit ff62dd5850d7 · 2026-05-22T22:16:11.000+09:00
Drop the deprecated import root after serialized-asset scan showed no legacy
module paths. Refresh gate-check 3/4c, CI compile, package tests, and tombstone
docs. Remove leftover spectral_fl/ directory to avoid namespace package shadowing.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -28,8 +28,8 @@ jobs:
       - name: Compile Python files
         run: |
           python -m py_compile run_experiment.py run_vision_experiment.py run_vision_suite.py run_vision_stress_grid.py run_vision_client_count_sweep.py run_graph_ablation.py
-          python -m py_compile graphfl_lab/*.py spectral_fl/*.py
-          python -m compileall -q graphfl_lab spectral_fl tests scripts
+          python -m py_compile graphfl_lab/*.py
+          python -m compileall -q graphfl_lab tests scripts
 
       - name: Unit smoke tests
         run: python -m unittest discover -s tests
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
@@ -29,8 +29,8 @@ jobs:
       - name: Compile Python files
         run: |
           python -m py_compile run_experiment.py run_vision_experiment.py run_vision_suite.py run_vision_stress_grid.py run_vision_client_count_sweep.py run_graph_ablation.py
-          python -m py_compile graphfl_lab/*.py spectral_fl/*.py
-          python -m compileall -q graphfl_lab spectral_fl tests scripts
+          python -m py_compile graphfl_lab/*.py
+          python -m compileall -q graphfl_lab tests scripts
 
       - name: Unit smoke tests
         run: python -m unittest discover -s tests
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -25,7 +25,6 @@ python run_experiment.py --track cora ...
 During deprecation, old names remain available where documented:
 
 ```text
-spectral_fl (shim; `strategies.spectral` import path removed in Gate 6 batch 5)
 configs/general/...
 result_general_*   (readers only; new runs no longer write mirrors)
 general_suite_*    (readers only; new runs no longer write mirrors)
@@ -100,25 +99,15 @@ Gate sequence:
 Gate 0  workspace/status/check contract
 Gate 1  inventory
 Gate 2  schema/config contract
-Gate 3  graphfl_lab package migration with spectral_fl shim
+Gate 3  graphfl_lab package migration (`spectral_fl` shim removed in Gate 6 batch 6)
 Gate 4  unified runner and nightly
 Gate 5  behavior-preserving modularization
 Gate 6  hard cleanup and 1.0.0
 ```
 
-Gate 3 keeps a `spectral_fl` shim until Gate 6. The shim must cover:
-
-```text
-DeprecationWarning
-GRAPHFL_LAB_SILENCE_DEPRECATION=1
-sys.modules alias behavior
-pickle round-trip compatibility
-```
-
-Gate 6 must provide `scripts/dev/migrate_serialized_objects.py` before removing
-old import aliases. Any preserved pickle/checkpoint asset with `spectral_fl.*`
-module paths must be migrated before hard cleanup or explicitly declared outside
-post-Gate-6 compatibility guarantees.
+Gate 6 batch 6 removed the `spectral_fl` import shim. Use `graphfl_lab` for all
+new imports. Run `scripts/dev/migrate_serialized_objects.py` before loading
+external pickle assets; tracked repo assets had no legacy module-path markers.
 
 Migration C5 (public docs/commands) status: complete on `main`. Gate 4c nightly
 evidence is recorded in `docs/maintenance/last_nightly_run.json`. Gate 6
diff --git a/README.md b/README.md
@@ -231,14 +231,9 @@ graphfl_lab/
   strategies/
     graphfl/                      graph-FL runtime
     baselines/                    baseline strategies
-    spectral/                     old import compatibility
   experiments/
     vision/                       current run orchestration
     suites/vision/                suite grammar and reporting
-    general/                      old module compatibility
-
-spectral_fl/
-  __init__.py                     old package import shim
 
 scripts/
   checks/                         non-training validation
@@ -331,7 +326,6 @@ New code uses `vision`, `graphfl`, `graph_filtered_*`.
 
 | Old name | Role |
 |---|---|
-| `spectral_fl` | old package import shim |
 | `spectral_filtered_*`, `spectral_filter_strength` | config/result compatibility alias |
 | `general_suite_*`, `result_general_*` | historical output filenames (readers only; new runs use vision names) |
 
diff --git a/docs/maintenance/cleanup-status.md b/docs/maintenance/cleanup-status.md
@@ -9,12 +9,12 @@ disagree, rerun the relevant gate check and update this file from the result.
 
 | Field | Value |
 |---|---|
-| current_gate | Gate 4c complete on `main`; Gate 6 batches 1–3 in progress on `main` |
-| status | PR #2 merged; nightly 26288800411 green; Gate 6 batches 2–5 landed; `spectral_fl` shim and root `general_*` CLI facades remain per `gate-6-prep.md` |
+| current_gate | Gate 4c complete on `main`; Gate 6 batch 6 in progress on `main` |
+| status | PR #2 merged; nightly 26288800411 green; Gate 6 batches 2–6 landed (`spectral_fl` shim removed); root `general_*` CLI facades and batch 7–8 remain |
 | owner | codex |
 | started_at | 2026-05-21 |
 | last_verified | see `docs/maintenance/last_gate_check.json` |
-| next_step | Confirm CI green on batch 5 commit; then batch 6 (`spectral_fl` shim) only after grep shows no remaining imports; batch 7 legacy CLI tokens last |
+| next_step | Push batch 6 and confirm CI green; then batch 7 (legacy CLI choices / suite tokens); batch 8 close status + `removed-materials.md` |
 
 Only one Gate branch should be active at a time. In short: use a single Gate branch.
 If parallel work is
@@ -271,6 +271,8 @@ result-schema contracts.
 | 2026-05-22 | Gate 6 batch 3: root `run_general_*` and `plot_general_*` / `merge_general_*` / `deep_dive_general` wrappers only re-exported vision CLIs after C5. | Delete wrappers; compile canonical `run_vision_*` in CI/nightly; drop `run_general_experiment` from `gate-check 4b` contract. |
 | 2026-05-22 | Gate 6 batch 4: `graphfl_lab/experiments/general/` and `suites/general/` were star-import facades with no remaining in-repo consumers after batch 3. | Delete import-path wrappers; keep root `general_*` CLI shims and `strategies/spectral/` for batch 5+. |
 | 2026-05-22 | Gate 6 batch 5: `graphfl_lab/strategies/spectral/` mirrored `strategies/graphfl` with no in-repo Python imports; spectral math stays under `graph/operators` and `graphfl` modules. | Delete strategy import facades; use `graphfl_lab.strategies.graphfl` (or `spectral_fl.strategies.graphfl` via shim until batch 6). |
+| 2026-05-22 | Gate 6 batch 6 pre-check: active `spectral_fl` imports only in `tests/core/test_package_alias.py`, gate-check fixtures, `scripts/dev/*`, and `scripts/archive/` (archive skipped by gate 3b). `migrate_serialized_objects.py` reports 0 legacy byte markers. | Remove shim; tombstone in `docs/removed-materials.md`; update gate-check 3/4c and package tests; do not remove `general_*` CLI facades in same batch. |
+| 2026-05-22 | Deleting only `spectral_fl/__init__.py` left an on-disk `spectral_fl/__pycache__` tree; Python 3 still exposed a namespace package and gate-check 3 flagged the tracked path until the directory was removed. | Delete the full `spectral_fl/` directory (not only `__init__.py`); assert `ModuleNotFoundError` after clearing `sys.modules`. |
 
 ## Gate 4c Local Readiness
 
@@ -281,7 +283,7 @@ present: scripts/dev/golden.py + tests/dev/test_golden.py + tests/golden/README.
 local pass: python scripts/dev/run.py gate-check 4c
 local pass: python scripts/dev/run.py gate-check 5d-prep
 Gate 6 entry: pragmatic policy (4c + merge CI green; optional 1 more green before first deletion)
-Gate 6 hard removal: batches 2–5 done; batches 6–8 remain — see docs/maintenance/gate-6-prep.md
+Gate 6 hard removal: batches 2–6 done; batches 7–8 remain — see docs/maintenance/gate-6-prep.md
 ```
 
 ## Closure Policy
diff --git a/docs/maintenance/gate-6-prep.md b/docs/maintenance/gate-6-prep.md
@@ -36,7 +36,7 @@ replace with the recommended check above unless you explicitly want a week-long
 3. [x] Remove `run_general_*` root wrappers and `plot_general_*` / `merge_general_*` / `deep_dive_general` script wrappers.
 4. [x] Remove `graphfl_lab/experiments/general/` and `graphfl_lab/experiments/suites/general/` import facades.
 5. [x] Remove `graphfl_lab/strategies/spectral/` wrappers (keep real spectral math names in operators).
-6. Remove `spectral_fl` package shim last, after grep shows no remaining imports outside tests explicitly checking deprecation.
+6. [x] Remove `spectral_fl` package shim last, after grep shows no remaining imports outside tests explicitly checking deprecation.
 7. Remove legacy CLI choices (`spectral_filtered_*` inputs) and old suite token spellings only after suite/history policy is frozen.
 8. Update `docs/maintenance/cleanup-status.md` to `closed` and link from `docs/removed-materials.md`.
 
diff --git a/docs/maintenance/last_gate_check.json b/docs/maintenance/last_gate_check.json
@@ -1,7 +1,7 @@
 {
-  "gate": "5d-prep",
+  "gate": "3b",
   "pass": true,
   "failed_checks": [],
-  "verified_at": "2026-05-22T13:09:27.027433+00:00",
-  "commit_sha": "a81d70286aa817c3fcd012dc30a9ae263386ef62"
+  "verified_at": "2026-05-22T13:15:55.360258+00:00",
+  "commit_sha": "8e90b0caacc052cfc1eea833fedf122723c38f41"
 }
diff --git a/docs/removed-materials.md b/docs/removed-materials.md
@@ -14,6 +14,7 @@ documents after Gate 6.
 
 | Path or material | Status | Replacement |
 |---|---|---|
+| `spectral_fl/__init__.py` (package shim) | removed Gate 6 batch 6 | `graphfl_lab` canonical imports; serialized assets scanned via `scripts/dev/migrate_serialized_objects.py` |
 | `docs/maintenance/cleanup-status.md` | active until Gate 6 | After Gate 6, mark closed and link from this table. |
 | `docs/framework/experimental-design.md` | removed duplicate bridge | `docs/framework/graph_fl_experimental_design.md`, `docs/framework/graph_fl_experimental_design_appendix.md` |
 
diff --git a/docs/structure.md b/docs/structure.md
@@ -77,7 +77,6 @@ graphfl_lab/
 Keep these thin. Add new logic in scoped modules, then re-export only if compatibility requires it.
 
 ```text
-spectral_fl/__init__.py
 graphfl_lab/aggregation.py
 graphfl_lab/client.py
 graphfl_lab/general_client.py
diff --git a/pyproject.toml b/pyproject.toml
@@ -18,7 +18,7 @@ dependencies = [
 ]
 
 [tool.setuptools.packages.find]
-include = ["spectral_fl*", "graphfl_lab*"]
+include = ["graphfl_lab*"]
 
 [tool.flwr.app]
 publisher = "local"
diff --git a/scripts/archive/legacy-analysis/graph_preset_smoke_test.py b/scripts/archive/legacy-analysis/graph_preset_smoke_test.py
@@ -17,7 +17,7 @@
 if str(PROJECT_ROOT) not in sys.path:
     sys.path.insert(0, str(PROJECT_ROOT))
 
-from spectral_fl.graph.presets import resolve_graph_preset_spec
+from graphfl_lab.graph.presets import resolve_graph_preset_spec
 
 
 def _result_path(out_dir: Path, seed: int, run_tag: str) -> Path:
diff --git a/scripts/dev/migrate_serialized_objects.py b/scripts/dev/migrate_serialized_objects.py
@@ -70,7 +70,7 @@ def main() -> int:
         "gate6_action": (
             "no migration required"
             if not legacy
-            else "migrate or declare out-of-scope before removing spectral_fl shim"
+            else "no action (spectral_fl shim removed; scan for external pickle assets)"
         ),
     }
     print(json.dumps(report, indent=2))
diff --git a/scripts/dev/run.py b/scripts/dev/run.py
@@ -127,36 +127,26 @@
     "graphfl_lab/__init__.py": (
         "Canonical package root",
     ),
-    "spectral_fl/__init__.py": (
-        "Deprecated compatibility shim",
-        "DeprecationWarning",
-        "GRAPHFL_LAB_SILENCE_DEPRECATION",
-        "graphfl_lab",
-        "__path__",
-        "__getattr__",
-    ),
     "pyproject.toml": (
         "graphfl_lab*",
         "graphfl_lab.flower_app:server_app",
         "graphfl_lab.flower_app:client_app",
     ),
+    "docs/removed-materials.md": (
+        "spectral_fl/__init__.py",
+        "Gate 6 batch 6",
+    ),
     "tests/core/test_package_alias.py": (
         "test_graphfl_lab_imports_flower_app",
-        "test_spectral_fl_warns_by_default",
-        "test_spectral_fl_warning_can_be_silenced",
-        "test_sys_modules_alias_roots_exist",
+        "test_spectral_fl_shim_removed",
         "test_pickle_round_trip_for_canonical_import",
-        "test_legacy_submodule_import_still_resolves",
-        "test_pickle_round_trip_for_legacy_import",
     ),
 }
 
 GATE3B_FORBIDDEN_IMPORT_ALLOWLIST = {
     "graphfl_lab/__init__.py",
     "scripts/dev/migrate_serialized_objects.py",
     "scripts/dev/run.py",
-    "spectral_fl/__init__.py",
-    "tests/core/test_package_alias.py",
     "tests/dev/test_run_gate_check.py",
 }
 
@@ -203,7 +193,6 @@
 GATE4C_REQUIRED_TEXT = {
     ".github/workflows/ci.yml": (
         "graphfl_lab",
-        "spectral_fl",
         "python -m unittest discover -s tests",
     ),
     ".github/workflows/nightly.yml": (
@@ -779,11 +768,10 @@ def _forbidden_identity_imports(root: Path) -> list[str]:
 
 
 def _unexpected_legacy_package_files(root: Path) -> list[str]:
-    allowed = {"spectral_fl/__init__.py"}
     failures: list[str] = []
     for rel in _tracked_files(root):
-        if rel.startswith("spectral_fl/") and rel not in allowed:
-            failures.append(f"{rel}: legacy package should only contain the shim")
+        if rel.startswith("spectral_fl/"):
+            failures.append(f"{rel}: spectral_fl package removed in Gate 6 batch 6")
     return failures
 
 
diff --git a/spectral_fl/__init__.py b/spectral_fl/__init__.py
diff --git a/tests/core/test_package_alias.py b/tests/core/test_package_alias.py
@@ -1,9 +1,7 @@
 import importlib
-import os
 import pickle
 import sys
 import unittest
-import warnings
 
 
 class PackageAliasTest(unittest.TestCase):
@@ -13,47 +11,11 @@ def test_graphfl_lab_imports_flower_app(self):
         self.assertTrue(hasattr(module, "server_app"))
         self.assertTrue(hasattr(module, "client_app"))
 
-    def test_spectral_fl_warns_by_default(self):
-        import spectral_fl
-
-        with warnings.catch_warnings(record=True) as caught:
-            warnings.simplefilter("always", DeprecationWarning)
-            importlib.reload(spectral_fl)
-
-        self.assertTrue(
-            any("spectral_fl" in str(item.message) for item in caught),
-            [str(item.message) for item in caught],
-        )
-
-    def test_spectral_fl_warning_can_be_silenced(self):
-        import spectral_fl
-
-        old = os.environ.get("GRAPHFL_LAB_SILENCE_DEPRECATION")
-        os.environ["GRAPHFL_LAB_SILENCE_DEPRECATION"] = "1"
-        try:
-            with warnings.catch_warnings(record=True) as caught:
-                warnings.simplefilter("always", DeprecationWarning)
-                importlib.reload(spectral_fl)
-        finally:
-            if old is None:
-                os.environ.pop("GRAPHFL_LAB_SILENCE_DEPRECATION", None)
-            else:
-                os.environ["GRAPHFL_LAB_SILENCE_DEPRECATION"] = old
-
-        self.assertEqual([item for item in caught if item.category is DeprecationWarning], [])
-
-    def test_sys_modules_alias_roots_exist(self):
-        import graphfl_lab
-        import spectral_fl
-
-        self.assertIs(sys.modules["graphfl_lab"], graphfl_lab)
-        self.assertIs(sys.modules["spectral_fl"], spectral_fl)
-        self.assertEqual(list(spectral_fl.__path__), list(graphfl_lab.__path__))
-
-    def test_legacy_submodule_import_still_resolves(self):
-        module = importlib.import_module("spectral_fl.diagnostics.schema")
-
-        self.assertTrue(hasattr(module, "RoundDiagnostics"))
+    def test_spectral_fl_shim_removed(self):
+        sys.modules.pop("spectral_fl", None)
+        importlib.invalidate_caches()
+        with self.assertRaises(ModuleNotFoundError):
+            importlib.import_module("spectral_fl")
 
     def test_pickle_round_trip_for_canonical_import(self):
         from graphfl_lab.diagnostics.schema import RoundDiagnostics
@@ -89,40 +51,6 @@ def test_pickle_round_trip_for_canonical_import(self):
 
         self.assertEqual(restored.to_dict(), row.to_dict())
 
-    def test_pickle_round_trip_for_legacy_import(self):
-        from spectral_fl.diagnostics.schema import RoundDiagnostics
-
-        row = RoundDiagnostics(
-            run_id="run",
-            variant="v",
-            seed=1,
-            round=1,
-            accuracy=0.5,
-            loss=1.0,
-            di_pre=0.4,
-            di_post=0.3,
-            neff_pre=2.0,
-            neff_post=3.0,
-            align_mean_pre=0.1,
-            align_mean_post=0.2,
-            loo_mean_pre=0.5,
-            loo_mean_post=0.4,
-            graph_density=0.5,
-            graph_entropy=0.7,
-            alpha_entropy=0.6,
-            wall_time_sec=1.2,
-            graph_method="m",
-            correction_family="real_graph",
-            graph_source="update",
-            graph_variant="update",
-            aggregation_target="graph_filtered_update",
-            graph_kind="knn",
-        )
-
-        restored = pickle.loads(pickle.dumps(row))
-
-        self.assertEqual(restored.to_dict(), row.to_dict())
-
 
 if __name__ == "__main__":
     unittest.main()

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`		`- "gate": "5d-prep",`
	`2`	`+ "gate": "3b",`
`3`	`3`	`"pass": true,`
`4`	`4`	`"failed_checks": [],`
`5`		`- "verified_at": "2026-05-22T13:09:27.027433+00:00",`
`6`		`- "commit_sha": "a81d70286aa817c3fcd012dc30a9ae263386ef62"`
	`5`	`+ "verified_at": "2026-05-22T13:15:55.360258+00:00",`
	`6`	`+ "commit_sha": "8e90b0caacc052cfc1eea833fedf122723c38f41"`
`7`	`7`	`}`
Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@ dependencies = [`
`18`	`18`	`]`
`19`	`19`
`20`	`20`	`[tool.setuptools.packages.find]`
`21`		`-include = ["spectral_fl", "graphfl_lab"]`
	`21`	`+include = ["graphfl_lab*"]`
`22`	`22`
`23`	`23`	`[tool.flwr.app]`
`24`	`24`	`publisher = "local"`