feat(cli): separate-branches rename, short aliases, clean dry-run

- --normalize-to-one renamed to --separate-branches (no alias; the
  name now describes the output choice: total spectrum with
  intensity-normalized branches vs separate branches, each
  normalized to unit area with intensities left to the data user).
  SpectrumConfig.normalize_to_one -> separate_branches, CSV header
  word to_one -> separate.
- every long option gains a single-letter alias: -N -i -s -m -o -p
  -L -d -c -V -S -b (only -v/-q existed before)
- dry-run drops the top-level Transition: line — the per-branch
  list below already reports each branch's transition type
- version bumped to 0.4.1 (pyproject, __version__, CSV semantics
  docstring, TODO roadmap entry)

tests/integration/test_cli_flows.py

@@ -66,12 +66,12 @@ def n_points_of(header: List[str]) -> int:
 class TestCLIJsonFlows:
     """Options must propagate through the JSON config flow (D2)."""
 
-    def test_json_honors_normalize_to_one_and_tab_separator(
+    def test_json_honors_separate_branches_and_tab_separator(
         self, tmp_path: Any
     ) -> None:
         src = write_json(tmp_path)
         out = str(tmp_path / "to_one.csv")
-        main([src, "--output", out, "--normalize-to-one", "--csv-separator", "tab"])
+        main([src, "--output", out, "--separate-branches", "--csv-separator", "tab"])
 
         with open(out) as f:
             body = "".join(ln for ln in f if not ln.startswith("#"))
@@ -136,7 +136,7 @@ class TestCLIDegenerateFlows:
                     out,
                     "--neutrino-mass",
                     "0.35",
-                    "--normalize-to-one",
+                    "--separate-branches",
                 ]
             )
         assert exc.value.code == 1
@@ -147,9 +147,9 @@ class TestCLIDegenerateFlows:
 class TestCLIPaceENSDF:
     """paceENSDF flow honors the same export options."""
 
-    def test_paceensdf_honors_normalize_to_one(self, tmp_path: Any) -> None:
+    def test_paceensdf_honors_separate_branches(self, tmp_path: Any) -> None:
         out = str(tmp_path / "p32.csv")
-        main(["P32", "--output", out, "--normalize-to-one"])
+        main(["P32", "--output", out, "--separate-branches"])
 
         df = read_export(out)
         assert "total_spectrum" not in df.columns

tests/physics/test_core_spectrum.py

@@ -313,8 +313,8 @@ class TestCSVExportCoreSemantics:
         assert "phase_space" in core_line[0]
         assert "fermi" in core_line[0]
 
-    def test_normalize_to_one_per_branch_unit_area(self, tmp_path: Any) -> None:
-        config = make_multi_config(normalize_to_one=True)
+    def test_separate_branches_per_branch_unit_area(self, tmp_path: Any) -> None:
+        config = make_multi_config(separate_branches=True)
         spectrum = BetaSpectrum.from_config(config)
         analyzer = BetaSpectrumAnalyzer(spectrum, config)
         _, df = export_and_read(analyzer, tmp_path)
@@ -334,12 +334,12 @@ class TestCSVExportCoreSemantics:
             analyzer.export_to_csv(path)
         assert not (tmp_path / "degenerate.csv").exists()
 
-    def test_degenerate_export_raises_in_normalize_to_one_mode(
+    def test_degenerate_export_raises_in_separate_branches_mode(
         self, tmp_path: Any
     ) -> None:
-        """The positive-integral guard must apply in to_one mode too:
+        """The positive-integral guard must apply in separate-branches mode too:
         no all-zero CSV may be written for a degenerate spectrum."""
-        config = make_degenerate_config(normalize_to_one=True)
+        config = make_degenerate_config(separate_branches=True)
         spectrum = BetaSpectrum.from_config(config)
         analyzer = BetaSpectrumAnalyzer(spectrum, config)
         path = str(tmp_path / "degenerate_to_one.csv")
@@ -567,13 +567,13 @@ class TestAnalyzerUniversalFactor:
 
 
 class TestNormalizationModeMatrix:
-    """to_one and intensity modes must behave consistently across CSV
+    """separate_branches and intensity modes must behave consistently across CSV
     verbosity, branch count and the CSV-driven visualizer."""
 
-    def test_to_one_concise_multi_unit_area_no_total_no_components(
+    def test_separate_branches_concise_multi_unit_area_no_total_no_components(
         self, tmp_path: Any
     ) -> None:
-        config = make_multi_config(normalize_to_one=True)
+        config = make_multi_config(separate_branches=True)
         spectrum = BetaSpectrum.from_config(config)
         analyzer = BetaSpectrumAnalyzer(spectrum, config)
         path, df = export_and_read(
@@ -587,14 +587,14 @@ class TestNormalizationModeMatrix:
             "branch_3",
         }
         header = header_lines_of(path)
-        assert any("branch normalization: to_one" in h for h in header)
+        assert any("branch normalization: separate" in h for h in header)
         energies = df["energy_MeV"].to_numpy()
         for col in ("branch_1", "branch_2", "branch_3"):
             area = np.trapezoid(df[col].to_numpy(), energies)
             assert np.isclose(area, 1.0, rtol=5e-4)
 
-    def test_to_one_single_mode_unit_area(self, tmp_path: Any) -> None:
-        config = make_single_config(normalize_to_one=True)
+    def test_separate_branches_single_mode_unit_area(self, tmp_path: Any) -> None:
+        config = make_single_config(separate_branches=True)
         spectrum = BetaSpectrum.from_config(config)
         analyzer = BetaSpectrumAnalyzer(spectrum, config)
         _path, df = export_and_read(analyzer, tmp_path, "to_one_single.csv")
@@ -622,10 +622,10 @@ class TestNormalizationModeMatrix:
         nonzero = total > 1e-12
         assert np.all(np.abs(summed[nonzero] - total[nonzero]) <= total[nonzero] * 5e-4)
 
-    def test_plot_from_csv_to_one_plots_branches_without_total(
+    def test_plot_from_csv_separate_branches_plots_branches_without_total(
         self, tmp_path: Any
     ) -> None:
-        config = make_multi_config(normalize_to_one=True)
+        config = make_multi_config(separate_branches=True)
         spectrum = BetaSpectrum.from_config(config)
         analyzer = BetaSpectrumAnalyzer(spectrum, config)
         path, df = export_and_read(analyzer, tmp_path, "to_one_plot.csv")
@@ -633,7 +633,7 @@ class TestNormalizationModeMatrix:
         fig = Visualizer.plot_from_csv(path, save_path=None, show_components=True)
         assert len(fig.axes) == 4
         # Panel 1 has exactly the 3 branch curves — no total spectrum
-        # exists in to_one mode.
+        # exists in separate-branches mode.
         panel = fig.axes[0]
         curves = [np.asarray(ln.get_xydata()) for ln in panel.lines]
         assert len(curves) == 3
@@ -641,8 +641,10 @@ class TestNormalizationModeMatrix:
         assert np.allclose(curves[0][:, 0], energies)
         assert np.allclose(curves[0][:, 1], df["branch_1_spectrum"].to_numpy())
 
-    def test_plot_analysis_to_one_returns_figure(self, tmp_path: Any) -> None:
-        config = make_multi_config(normalize_to_one=True)
+    def test_plot_analysis_separate_branches_returns_figure(
+        self, tmp_path: Any
+    ) -> None:
+        config = make_multi_config(separate_branches=True)
         spectrum = BetaSpectrum.from_config(config)
         analyzer = BetaSpectrumAnalyzer(spectrum, config)
         save = str(tmp_path / "analysis.png")
@@ -650,10 +652,10 @@ class TestNormalizationModeMatrix:
         assert len(fig.axes) == 4
         assert (tmp_path / "analysis.png").exists()
 
-    def test_plot_from_csv_to_one_concise_warns_and_falls_back(
+    def test_plot_from_csv_separate_branches_concise_warns_and_falls_back(
         self, tmp_path: Any, capsys: Any
     ) -> None:
-        config = make_multi_config(normalize_to_one=True)
+        config = make_multi_config(separate_branches=True)
         spectrum = BetaSpectrum.from_config(config)
         analyzer = BetaSpectrumAnalyzer(spectrum, config)
         path, df = export_and_read(

tests/quality/test_cli_options.py

@@ -0,0 +1,137 @@
+"""CLI option surface tests: renamed branch-separation flag, short
+aliases for every long option, and dry-run output shape (audit follow-up
+by the maintainer: rename --normalize-to-one, add short options, drop the
+redundant top-level Transition line)."""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, Optional
+
+import pytest
+
+from beta_spectrum import BranchConfig, SpectrumConfig
+from beta_spectrum.cli import _build_parser, _print_dry_run_output
+
+pytestmark = pytest.mark.quality
+
+
+def make_config() -> SpectrumConfig:
+    return SpectrumConfig(
+        Z_parent=59,
+        Z_daughter=60,
+        A_number=144,
+        endpoint_MeV=2.98,
+        transition_type="F1",
+        e_step_MeV=0.001,
+        branches=[
+            BranchConfig(endpoint_MeV=2.98, transition_type="F1", intensity=0.9),
+            BranchConfig(endpoint_MeV=2.1, transition_type="A", intensity=0.1),
+        ],
+    )
+
+
+class TestSeparateBranchesRename:
+    """--normalize-to-one was renamed to --separate-branches (no alias)."""
+
+    def test_flag_parses_true(self) -> None:
+        parser = _build_parser()
+        args = parser.parse_args(["input.json", "--separate-branches"])
+        assert args.separate_branches is True
+
+    def test_flag_default_is_none(self) -> None:
+        parser = _build_parser()
+        args = parser.parse_args(["input.json"])
+        assert args.separate_branches is None
+
+    def test_old_flag_is_rejected(self) -> None:
+        parser = _build_parser()
+        with pytest.raises(SystemExit):
+            parser.parse_args(["input.json", "--normalize-to-one"])
+
+    def test_config_field_renamed(self) -> None:
+        names = {f.name for f in dataclasses.fields(SpectrumConfig)}
+        assert "separate_branches" in names
+        assert "normalize_to_one" not in names
+
+    def test_config_old_kwarg_rejected(self) -> None:
+        kwargs: dict[str, Any] = {
+            "Z_parent": 15,
+            "Z_daughter": 16,
+            "A_number": 32,
+            "endpoint_MeV": 1.7103,
+            "transition_type": "A",
+            "normalize_to_one": True,
+        }
+        with pytest.raises(TypeError):
+            SpectrumConfig(**kwargs)
+
+
+# (short, long, value-or-None-for-store_true)
+_SHORT_EQUIV = [
+    ("-N", "--nuclide", "Cs137"),
+    ("-i", "--input", "in.json"),
+    ("-s", "--e-step", "0.01"),
+    ("-m", "--neutrino-mass", "0.15"),
+    ("-o", "--output", "out.csv"),
+    ("-p", "--plot", "plot.png"),
+    ("-L", "--log-file", "calc.log"),
+    ("-d", "--dry-run", None),
+    ("-c", "--intensity-cutoff", "0.5"),
+    ("-V", "--csv-verbosity", "concise"),
+    ("-S", "--csv-separator", "tab"),
+    ("-b", "--separate-branches", None),
+]
+
+
+class TestShortOptions:
+    """Every long option gains a single-letter alias (only -v/-q existed)."""
+
+    @pytest.mark.parametrize(
+        "short,long,value",
+        _SHORT_EQUIV,
+        ids=[s.lstrip("-") for s, _, _ in _SHORT_EQUIV],
+    )
+    def test_short_matches_long(
+        self, short: str, long: str, value: Optional[str]
+    ) -> None:
+        parser = _build_parser()
+        argv_long = [long] if value is None else [long, value]
+        argv_short = [short] if value is None else [short, value]
+        args_long = parser.parse_args(["Tc99"] + argv_long)
+        args_short = parser.parse_args(["Tc99"] + argv_short)
+        dest = long.lstrip("-").replace("-", "_")
+        assert getattr(args_short, dest) == getattr(args_long, dest)
+        assert getattr(args_long, dest) is not None or value is None
+
+    def test_existing_shorts_unchanged(self) -> None:
+        parser = _build_parser()
+        args = parser.parse_args(["Tc99", "-v", "-q"])
+        assert args.verbose == 1
+        assert args.quiet is True
+
+
+class TestDryRunOutputShape:
+    """The top-level Transition line is redundant with the per-branch
+    list (for multi-branch runs) and was removed."""
+
+    def test_multi_branch_dry_run_no_top_level_transition(self, capsys: Any) -> None:
+        _print_dry_run_output(make_config(), "paceENSDF")
+        out = capsys.readouterr().out
+        assert "Transition:" not in out
+        assert "transition=F1" in out
+        assert "transition=A" in out
+        assert "Multi-branch mode: 2 branches" in out
+
+    def test_single_branch_dry_run_reports_endpoint(self, capsys: Any) -> None:
+        config = SpectrumConfig(
+            Z_parent=15,
+            Z_daughter=16,
+            A_number=32,
+            endpoint_MeV=1.7103,
+            transition_type="A",
+        )
+        _print_dry_run_output(config, "json")
+        out = capsys.readouterr().out
+        assert "Transition:" not in out
+        assert "Mode: single-branch" in out

tests/quality/test_logging_utils.py

@@ -154,7 +154,7 @@ class TestCSVMetadataHeader:
             lines = f.readlines()
 
         assert any("# beta-spectrum v" in line for line in lines)
-        assert any("0.4.0" in line for line in lines)
+        assert any("0.4.1" in line for line in lines)
         os.unlink(filename)
 
     def test_header_contains_timestamp(self):