refactor: trim spectral compatibility aliases after Gate 6

Move graph vector helper to graphfl source module, canonicalize aggregation
targets, and stop mirroring spectral_filter_strength in new result metadata.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 2-mean

docs/maintenance/last_gate_check.json

@@ -1,7 +1,7 @@
 {
-  "gate": "5d-prep",
+  "gate": "0",
   "pass": true,
   "failed_checks": [],
-  "verified_at": "2026-05-22T13:33:39.051204+00:00",
-  "commit_sha": "4fa973671850982b5366b976c0599ac2976e4761"
+  "verified_at": "2026-05-22T13:45:01.273462+00:00",
+  "commit_sha": "450e3a80659c8a5a0e97666c3532346990c02531"
 }

docs/maintenance/rename-inventory.md

@@ -18,7 +18,8 @@ legacy surface is discovered.
 | `general_suite_*` | old suite artifact filename | compatibility mirror; new writes emit `vision_suite_*` first via `write_suite_summary_artifacts()` until Gate 6 |
 | `result_vision_*`, `vision_suite_*` | canonical output filenames | prefer in new docs, scripts, and directory listings |
 | `graphfl_lab/experiments/suites/vision/artifacts.py` | artifact discovery helper | canonical-first readers for plots/smoke/sweeps |
-| `spectral_filter_strength` | old config/result key | schema policy in Gate 2, removal in Gate 6 |
+| `graph_filter_strength` | canonical config/result key | prefer in new writes; JSON may still alias `spectral_filter_strength` via `config_io` |
+| `spectral_filter_strength` | old config/result key | JSON alias only after Gate 6 phase 2; not written to new traces |
 | `spectral_filtered_*` | old aggregation target/result spelling | internal migration in Gate 3, removal in Gate 6 |
 | `ours_spectral_filtered_*` | old suite token | keep through deprecation |
 | `_spectral_only`, `_speconly` | old suite suffixes | keep through deprecation |

docs/removed-materials.md

@@ -35,13 +35,24 @@ Execution log (findings and decisions): [`docs/maintenance/cleanup-status.md`](m
 
 Legacy experiment trees with old filenames stay **gitignored** (see root `.gitignore`).
 
+## Post-Gate-6 Phase 2 — Spectral Alias Trim (2026-05-22)
+
+| Removed / changed | Replacement / policy |
+|---|---|
+| `graphfl_lab/graph/sources/spectral.py` | `graph_vectors_for_graphfl` in `graph/sources/graphfl.py` |
+| `graph_vectors_for_spectral` export | removed; import `graph_vectors_for_graphfl` |
+| Strategy ctor / trace field `spectral_filter_strength` | `graph_filter_strength` only in new writes |
+| Dual CLI `Namespace` setattr for filter strength | JSON key alias in `config_io` only |
+| Explicit `spectral_filtered_*` branches in targets | `canonical_aggregation_target()` input map |
+
 ## Remaining Compatibility Debt
 
 | Surface | Status | Notes |
 |---|---|---|
-| Runtime `spectral_filtered_*` aggregation **input** aliases | retained | lifecycle/strategy accept legacy target strings |
-| `spectral_filter_strength` in traces / JSON config keys | retained | maps to `graph_filter_strength` |
+| Runtime `spectral_filtered_*` aggregation **input** aliases | retained | `targets.canonical_aggregation_target()` + `config_io` JSON keys |
+| `spectral_filter_strength` JSON config key | retained | read alias → `graph_filter_strength`; not written to new result meta |
 | `ours_spectral_filtered_*` in **reporting** result tags | retained | pairs historical run labels only; not suite launch tokens |
+| Diagnostic trace keys `spectral_filter_gain_*` | retained | metric names, not public rename surface |
 
 ## Tombstones
 

graphfl_lab/app/config.py

@@ -194,7 +194,6 @@ def args_from_context(context: Context) -> Namespace:
         fixed_tau=float(cfg["fixed-tau"]),
         tau_source=str(cfg["tau-source"]),
         graph_filter_strength=float(cfg["graph-filter-strength"]),
-        spectral_filter_strength=float(cfg["graph-filter-strength"]),
         client_update_ema_alpha=float(cfg["client-update-ema-alpha"]),
         diagnostic_only=bool_value(cfg["diagnostic-only"]),
         e_std_threshold=float(cfg["e-std-threshold"]),

graphfl_lab/config_io.py

@@ -11,6 +11,9 @@
 
 ARG_DEST_ALIASES = {
     "spectral_filter_strength": "graph_filter_strength",
+    "spectral_filtered_update": "graph_filtered_update",
+    "spectral_filtered_ema_update": "graph_filtered_ema_update",
+    "spectral_filtered_weight": "graph_filtered_weight",
 }
 
 
@@ -114,15 +117,7 @@ def parse_args_with_config(parser: argparse.ArgumentParser) -> argparse.Namespac
 
 
 def normalize_arg_aliases(args: argparse.Namespace) -> argparse.Namespace:
-    """Populate canonical/compatibility argparse attributes after parsing."""
-    if hasattr(args, "graph_filter_strength") and not hasattr(
-        args, "spectral_filter_strength"
-    ):
-        setattr(args, "spectral_filter_strength", args.graph_filter_strength)
-    if hasattr(args, "spectral_filter_strength") and not hasattr(
-        args, "graph_filter_strength"
-    ):
-        setattr(args, "graph_filter_strength", args.spectral_filter_strength)
+    """Normalize argparse namespace after parsing (canonical fields only)."""
     return args
 
 

graphfl_lab/experiments/cora/single_run.py

@@ -416,7 +416,6 @@ def build_meta(args, client_class_distribution: List[List[int]], out_path: Path)
             "fixed_tau": float(args.fixed_tau),
             "tau_source": args.tau_source,
             "graph_filter_strength": float(args.graph_filter_strength),
-            "spectral_filter_strength": float(args.graph_filter_strength),
             "client_update_ema_alpha": float(args.client_update_ema_alpha),
         },
 
@@ -485,7 +484,6 @@ def build_meta(args, client_class_distribution: List[List[int]], out_path: Path)
         "fixed_tau": float(args.fixed_tau),
         "tau_source": args.tau_source,
         "graph_filter_strength": float(args.graph_filter_strength),
-        "spectral_filter_strength": float(args.graph_filter_strength),
         "min_client_weight": float(args.min_client_weight),
         "diagnostic_only": bool(args.diagnostic_only),
         "partition": args.partition,

graphfl_lab/experiments/suites/vision/features.py

@@ -58,10 +58,7 @@ def trace_value(key: str, default: str = "") -> str:
         "server_optimizer": trace_value("server_optimizer"),
         "tau_source_used": trace_value("tau_source_used"),
         "graph_filter_strength": trace_value(
-            "graph_filter_strength", trace_value("spectral_filter_strength")
-        ),
-        "spectral_filter_strength": trace_value(
-            "spectral_filter_strength", trace_value("graph_filter_strength")
+            "graph_filter_strength", trace_value("graph_filter_strength")
         ),
         "client_update_ema_alpha": trace_value("client_update_ema_alpha"),
         "client_update_ema_source": trace_value("client_update_ema_source"),

graphfl_lab/experiments/suites/vision/summary.py

@@ -35,11 +35,16 @@ def build_summary_rows(rows: List[Dict[str, Any]], args: Namespace) -> List[Dict
         def gmean(key: str):
             return safe_mean([x.get(key) for x in group])
 
-        def gfirst(key: str) -> str:
+        def gfirst(key: str, fallback_key: str | None = None) -> str:
             for x in group:
                 value = x.get(key)
                 if value not in (None, ""):
                     return str(value)
+            if fallback_key is not None:
+                for x in group:
+                    value = x.get(fallback_key)
+                    if value not in (None, ""):
+                        return str(value)
             return ""
 
         row_base = {
@@ -66,8 +71,7 @@ def gfirst(key: str) -> str:
             "aggregation_target_used": gfirst("aggregation_target_used"),
             "server_optimizer": gfirst("server_optimizer"),
             "tau_source_used": gfirst("tau_source_used"),
-            "graph_filter_strength": gfirst("graph_filter_strength"),
-            "spectral_filter_strength": gfirst("spectral_filter_strength"),
+            "graph_filter_strength": gfirst("graph_filter_strength", "spectral_filter_strength"),
             "client_update_ema_alpha": gfirst("client_update_ema_alpha"),
             "client_update_ema_source": gfirst("client_update_ema_source"),
             "server_learning_rate": gfirst("server_learning_rate"),

graphfl_lab/experiments/vision/single_run.py

@@ -116,7 +116,6 @@ def build_vision_meta(
             "fixed_tau": float(args.fixed_tau),
             "tau_source": args.tau_source,
             "graph_filter_strength": float(args.graph_filter_strength),
-            "spectral_filter_strength": float(args.graph_filter_strength),
             "client_update_ema_alpha": float(args.client_update_ema_alpha),
         },
         "aggregation": {
@@ -197,7 +196,6 @@ def build_vision_meta(
         "diagnostic_only": bool(args.diagnostic_only),
         "tau_source": args.tau_source,
         "graph_filter_strength": float(args.graph_filter_strength),
-        "spectral_filter_strength": float(args.graph_filter_strength),
         "client_update_ema_alpha": float(args.client_update_ema_alpha),
         "graph_smoothing_lambda": float(getattr(args, "graph_smoothing_lambda", 0.05)),
         "graph_smoothing_operator": str(

graphfl_lab/graph/__init__.py

@@ -64,7 +64,6 @@
     graph_source_names,
     graph_vectors_for_fedsim,
     graph_vectors_for_graphfl,
-    graph_vectors_for_spectral,
     normalize_key,
     register_graph_source,
     unregister_graph_source,
@@ -101,7 +100,6 @@
     "pfedgraph_qp_graph",
     "graph_vectors_for_fedsim",
     "graph_vectors_for_graphfl",
-    "graph_vectors_for_spectral",
     "apply_graph_preset_to_namespace",
     "graph_method_names",
     "graph_preset_names",