Fix TOML annotation drift and enforce the convention via pre-commit (#274)

[priyanshlunia]

Summary

Closes #274.

The standardization sweep in #285 established one shared annotation convention for the
config-style TOMLs, but the issue stayed open — and in the weeks since that merge, 9 new
TOMLs were added and most existing ones modified, reintroducing drift. This PR fixes all
current violations and adds pre-commit enforcement so the convention holds going forward.

1. Fix the drift (11 files, 887bd8f):

• Missing headers added: DIIID-like_gal_resistive_example,
  DIIID-like_gal_resistive_pe_example, the regression_solovev_kinetic_nuzero fixture,
  and the diiid_slayer_n1, gal_resistive_diiid, gal_resistive_pe,
  solovev_kinetic_nuzero regression cases.
• Missing inline descriptions completed: the whole [SLAYER] section and scan grid in
  the SLAYER example, rtol_xlmda/write_outputs_to_HDF5/verbose in the canonical
  DIIID-like_ideal_example, and the same trailing keys in the Solovev kinetic decks.
• Deprecated keys removed (all warn-and-deleted by the loader, never read):
  mat_flag, ode_flag, power_bp, power_b, power_r, truncate_at_dW_peak (SLAYER
  example) and force_wv_symmetry (Solovev NTV example).
• Cleanups: decorative # --- dividers stripped from diiid_slayer_n1.toml; the
  psiedge comment claiming "integration truncated at peak" corrected in 3 files (the
  edge-dW scan is diagnostic-only with truncate_at_dW_peak = false).

2. Enforce the convention (af540d5): four declarative pygrep hooks in
.pre-commit-config.yaml — no external scripts, config-only like the existing hooks:

• toml-header-block — covered files must open with a # header block
• toml-no-decorative-dividers — rejects # -----style dividers
• toml-inline-annotations — every key = value line needs a trailing # description
  (examples/ and test/test_data/ only)
• toml-no-deprecated-keys — rejects keys mirrored from
  _DEPRECATED_FFS_KEYS/_DEPRECATED_EQUIL_KEYS

3. Docs: docs/development/toml-conventions.md gains an Enforcement section and
codifies the regression-case exemption (the repetitive [quantities.*] schema keys are
developer metadata and don't need inline comments — cases need the header plus informative
per-quantity block comments). The setup guide's pre-commit list mentions the new checks.

Scope

• 11 example/fixture/case TOMLs, .pre-commit-config.yaml, 2 dev-docs files.
• No src/, no test-code changes.

Verification

• Value-neutral: TOML.parsefile comparison of every touched file vs develop —
  parsed values byte-identical except the 7 intentionally removed deprecated keys, which
  the loader warns about and discards before the control structs are built.
• Hooks verified both ways: all four patterns pass clean on this branch and reproduce
  the full audited violation set (missing headers, 8 dividers, 19 unannotated lines,
  5 deprecated keys) when run against develop's versions of the files.
• Hygiene: no trailing whitespace, single final newline, LF endings; YAML parses.
• Regression harness: to be run on this branch before merge
  (regress --cases solovev_n1,diiid_n1,diiid_slayer_n1,solovev_kinetic_ntv --refs develop,local);
  expected all-zero deltas given the value-neutrality check above.

🤖 Generated with Claude Code