refactor: Gate 6 batch 7 drop legacy CLI and suite spectral spellings

2-mean · cursoragent · 2-mean · commit 3442c0caf7e8 · 2026-05-22T22:21:06.000+09:00
Remove spectral_filtered_* from argparse choices and --spectral-filter-strength
CLI aliases; stop parsing ours_spectral_filtered_* suite launch tokens. Keep
config JSON aliases, aggregation runtime aliases, and reporting legacy tag pairing.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -28,8 +28,7 @@ During deprecation, old names remain available where documented:
 configs/general/...
 result_general_*   (readers only; new runs no longer write mirrors)
 general_suite_*    (readers only; new runs no longer write mirrors)
-spectral_filter_strength
-spectral_filtered_*
+spectral_filter_strength   (JSON config key alias only; CLI uses --graph-filter-strength)
 ```
 
 Root `run_general_*` and `plot_general_*` / `merge_general_*` /
diff --git a/README.md b/README.md
@@ -326,7 +326,7 @@ New code uses `vision`, `graphfl`, `graph_filtered_*`.
 
 | Old name | Role |
 |---|---|
-| `spectral_filtered_*`, `spectral_filter_strength` | config/result compatibility alias |
+| `spectral_filter_strength` | JSON config key alias via `config_io` (CLI flag is `--graph-filter-strength`) |
 | `general_suite_*`, `result_general_*` | historical output filenames (readers only; new runs use vision names) |
 
 Do not add new logic to compatibility paths.
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 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 |
+| current_gate | Gate 4c complete on `main`; Gate 6 batch 7 in progress on `main` |
+| status | PR #2 merged; nightly 26288800411 green; Gate 6 batches 2–7 landed; batch 8 (close status doc) and `general_*` CLI facades remain |
 | owner | codex |
 | started_at | 2026-05-21 |
 | last_verified | see `docs/maintenance/last_gate_check.json` |
-| next_step | Push batch 6 and confirm CI green; then batch 7 (legacy CLI choices / suite tokens); batch 8 close status + `removed-materials.md` |
+| next_step | Batch 8: mark `cleanup-status.md` closed, extend `removed-materials.md` tombstones; optional: remove root `general_*` CLI facades in a later batch if still listed in compatibility docs |
 
 Only one Gate branch should be active at a time. In short: use a single Gate branch.
 If parallel work is
@@ -273,6 +273,8 @@ result-schema contracts.
 | 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`. |
+| 2026-05-22 | Gate 6 batch 7 pre-check: no `configs/**` files use `ours_spectral_filtered_*` or `spectral_filtered_*`; reporting still pairs legacy result variant tags via `reporting.py` prefixes. | Remove CLI `choices`/dual flags and suite `parse_target_variant` spectral branch; keep `config_io` JSON key alias, lifecycle/strategy input aliases, and report readers. |
+| 2026-05-22 | Gate 6 batch 7: public CLI listed `spectral_filtered_*` choices and dual `--spectral-filter-strength`; suite parser accepted `ours_spectral_filtered_*` launch tokens. | Drop argparse choices/flags and suite launch tokens; keep runtime aggregation aliases and `reporting.py` legacy result-tag pairing for historical artifacts. |
 
 ## Gate 4c Local Readiness
 
@@ -283,7 +285,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–6 done; batches 7–8 remain — see docs/maintenance/gate-6-prep.md
+Gate 6 hard removal: batches 2–7 done; batch 8 (doc closure) remains — 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
@@ -37,7 +37,7 @@ replace with the recommended check above unless you explicitly want a week-long
 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. [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.
+7. [x] 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`.
 
 ## Verify After Each Batch
diff --git a/docs/maintenance/last_gate_check.json b/docs/maintenance/last_gate_check.json
@@ -1,7 +1,7 @@
 {
-  "gate": "3b",
+  "gate": "5d-prep",
   "pass": true,
   "failed_checks": [],
-  "verified_at": "2026-05-22T13:15:55.360258+00:00",
-  "commit_sha": "8e90b0caacc052cfc1eea833fedf122723c38f41"
+  "verified_at": "2026-05-22T13:20:40.596332+00:00",
+  "commit_sha": "ff62dd5850d7320b1b192ec3be9b8b382b75b092"
 }
diff --git a/graphfl_lab/cli/aggregation_targets.py b/graphfl_lab/cli/aggregation_targets.py
@@ -8,21 +8,16 @@
     "graph_filtered_update",
     "graph_filtered_ema_update",
     "graph_filtered_weight",
-    # Compatibility aliases retained until Gate 6.
-    "spectral_filtered_update",
-    "spectral_filtered_ema_update",
-    "spectral_filtered_weight",
 )
 
 AGGREGATION_TARGET_HELP = (
     "AggregationOperator knob: object averaged with alpha_i to form the next global model. "
-    "Prefer graph_filtered_update, graph_filtered_ema_update, or graph_filtered_weight. "
-    "spectral_filtered_* spellings remain accepted compatibility aliases."
+    "Use graph_filtered_update, graph_filtered_ema_update, or graph_filtered_weight."
 )
 
 AGGREGATION_TARGET_SUITE_HELP = (
     "Default aggregation target forwarded to the underlying single-run command. "
-    "Prefer graph_filtered_* spellings; spectral_filtered_* remains a compatibility alias."
+    "Use graph_filtered_* spellings for filtered aggregation families."
 )
 
 __all__ = [
diff --git a/graphfl_lab/cli/cora_experiment.py b/graphfl_lab/cli/cora_experiment.py
@@ -179,7 +179,6 @@ def parse_args():
     )
     p.add_argument(
         "--graph-filter-strength",
-        "--spectral-filter-strength",
         dest="graph_filter_strength",
         type=float,
         default=1.0,
diff --git a/graphfl_lab/cli/vision_client_count_sweep.py b/graphfl_lab/cli/vision_client_count_sweep.py
@@ -59,7 +59,6 @@ def parse_args() -> argparse.Namespace:
     p.add_argument("--tau-source", type=str, default="h_spec")
     p.add_argument(
         "--graph-filter-strength",
-        "--spectral-filter-strength",
         dest="graph_filter_strength",
         type=float,
         default=1.0,
diff --git a/graphfl_lab/cli/vision_experiment.py b/graphfl_lab/cli/vision_experiment.py
@@ -367,7 +367,6 @@ def parse_args():
     )
     p.add_argument(
         "--graph-filter-strength",
-        "--spectral-filter-strength",
         dest="graph_filter_strength",
         type=float,
         default=1.0,
diff --git a/graphfl_lab/cli/vision_stress_grid.py b/graphfl_lab/cli/vision_stress_grid.py
@@ -65,7 +65,6 @@ def parse_args() -> argparse.Namespace:
     p.add_argument("--tau-source", type=str, default="h_spec")
     p.add_argument(
         "--graph-filter-strength",
-        "--spectral-filter-strength",
         dest="graph_filter_strength",
         type=float,
         default=1.0,
diff --git a/graphfl_lab/cli/vision_suite.py b/graphfl_lab/cli/vision_suite.py
@@ -137,7 +137,6 @@ def parse_args():
     )
     p.add_argument(
         "--graph-filter-strength",
-        "--spectral-filter-strength",
         dest="graph_filter_strength",
         type=float,
         default=1.0,
diff --git a/graphfl_lab/experiments/suites/vision/variant_targets.py b/graphfl_lab/experiments/suites/vision/variant_targets.py
@@ -60,12 +60,4 @@ def parse_target_variant(v: str) -> ParsedVariant | None:
     if graph_filtered is not None:
         return graph_filtered
 
-    spectral_filtered = _parse_filtered_target(
-        "spectral_filtered",
-        "graph_filtered_update",
-        v,
-    )
-    if spectral_filtered is not None:
-        return spectral_filtered
-
     return None
diff --git a/scripts/dev/run.py b/scripts/dev/run.py
@@ -358,7 +358,7 @@
     "graphfl_lab/experiments/suites/vision/variant_targets.py": (
         "parse_target_variant",
         "graph_filtered_update",
-        '"spectral_filtered"',
+        '"graph_filtered"',
     ),
     "graphfl_lab/experiments/suites/vision/variants.py": (
         "from graphfl_lab.experiments.suites.vision.variant_commands import build_base_cmd",
@@ -406,7 +406,7 @@
     ),
     "tests/experiments/vision/test_variant_targets.py": (
         "test_parse_target_variant_handles_graph_filtered_family",
-        "test_parse_target_variant_preserves_legacy_spectral_family",
+        "test_parse_target_variant_rejects_legacy_spectral_suite_tokens",
     ),
     "docs/maintenance/cleanup-status.md": (
         "Gate 5c-prep",
diff --git a/tests/core/test_config_io.py b/tests/core/test_config_io.py
@@ -67,7 +67,6 @@ def test_spectral_filter_strength_config_aliases_to_graph_key(self):
         add_config_argument(parser)
         parser.add_argument(
             "--graph-filter-strength",
-            "--spectral-filter-strength",
             dest="graph_filter_strength",
             type=float,
             default=1.0,
@@ -94,7 +93,6 @@ def test_graph_filter_strength_config_populates_compat_attr(self):
         add_config_argument(parser)
         parser.add_argument(
             "--graph-filter-strength",
-            "--spectral-filter-strength",
             dest="graph_filter_strength",
             type=float,
             default=1.0,
diff --git a/tests/diagnostics/test_result_schema.py b/tests/diagnostics/test_result_schema.py
@@ -32,7 +32,6 @@ def test_config_aliases_are_recorded(self):
         add_config_argument(parser)
         parser.add_argument(
             "--graph-filter-strength",
-            "--spectral-filter-strength",
             dest="graph_filter_strength",
             type=float,
             default=1.0,
diff --git a/tests/experiments/vision/test_variant_targets.py b/tests/experiments/vision/test_variant_targets.py
@@ -18,12 +18,8 @@ def test_parse_target_variant_handles_graph_filtered_family(self):
         self.assertEqual(_last_flag_value(args, "--graph-mode"), "magnitude_knn")
         self.assertEqual(_last_flag_value(args, "--knn-k"), "2")
 
-    def test_parse_target_variant_preserves_legacy_spectral_family(self):
-        _, _, args = parse_target_variant("ours_spectral_filtered_random_matched_k3")
-
-        self.assertEqual(_last_flag_value(args, "--aggregation-target"), "graph_filtered_update")
-        self.assertEqual(_last_flag_value(args, "--graph-mode"), "random")
-        self.assertEqual(_last_flag_value(args, "--knn-k"), "3")
+    def test_parse_target_variant_rejects_legacy_spectral_suite_tokens(self):
+        self.assertIsNone(parse_target_variant("ours_spectral_filtered_random_matched_k3"))
 
     def test_parse_target_variant_handles_weight_agg_and_returns_none_for_sources(self):
         _, label, args = parse_target_variant("ours_weight_agg")
diff --git a/tests/experiments/vision/test_variants.py b/tests/experiments/vision/test_variants.py
@@ -167,26 +167,6 @@ def test_new_extension_variants_are_wrapped(self):
                 "--graph-mode",
                 "rbf_knn",
             ),
-            "ours_spectral_filtered_knn_k2": (
-                "--aggregation-target",
-                "graph_filtered_update",
-            ),
-            "ours_spectral_filtered_random_matched_k2": (
-                "--graph-mode",
-                "random",
-            ),
-            "ours_spectral_filtered_uniform": (
-                "--graph-mode",
-                "uniform",
-            ),
-            "ours_spectral_filtered_magnitude_knn_k2": (
-                "--graph-mode",
-                "magnitude_knn",
-            ),
-            "ours_spectral_filtered_rbf_knn_k2": (
-                "--graph-mode",
-                "rbf_knn",
-            ),
         }
         for variant, expected in cases.items():
             with self.subTest(variant=variant):

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`		`- "gate": "3b",`
	`2`	`+ "gate": "5d-prep",`
`3`	`3`	`"pass": true,`
`4`	`4`	`"failed_checks": [],`
`5`		`- "verified_at": "2026-05-22T13:15:55.360258+00:00",`
`6`		`- "commit_sha": "8e90b0caacc052cfc1eea833fedf122723c38f41"`
	`5`	`+ "verified_at": "2026-05-22T13:20:40.596332+00:00",`
	`6`	`+ "commit_sha": "ff62dd5850d7320b1b192ec3be9b8b382b75b092"`
`7`	`7`	`}`
Original file line number	Diff line number	Diff line change
`@@ -179,7 +179,6 @@ def parse_args():`
`179`	`179`	`)`
`180`	`180`	`p.add_argument(`
`181`	`181`	`"--graph-filter-strength",`
`182`		`- "--spectral-filter-strength",`
`183`	`182`	`dest="graph_filter_strength",`
`184`	`183`	`type=float,`
`185`	`184`	`default=1.0,`
Original file line number	Diff line number	Diff line change
`@@ -367,7 +367,6 @@ def parse_args():`
`367`	`367`	`)`
`368`	`368`	`p.add_argument(`
`369`	`369`	`"--graph-filter-strength",`
`370`		`- "--spectral-filter-strength",`
`371`	`370`	`dest="graph_filter_strength",`
`372`	`371`	`type=float,`
`373`	`372`	`default=1.0,`