Modularize agentic ecal

[vh2001]

Summary

Refactors the single-file energy model (scripts/clean/agentic_ecal.py) into a clean,
modular, installable package at the repo root, without changing any numbers. The refactor is
proven behaviour-preserving by a golden-master test suite that runs the original model and the new
package side by side and asserts bit-for-bit identical results. Also flattens the project layout,
adds examples, Sphinx-ready docstrings, and CI.

What changed

New package — agentic_ecal_pkg/

• The model split by concern: descriptors, rates, calib, components, workflow,
  registries, builders, validation, cli.
• Public API re-exported unchanged, so import agentic_ecal_pkg as ae is a drop-in for the old
  import agentic_ecal as ae.
• Google-style (Napoleon) docstrings throughout, ready for Sphinx autodoc.
• agentic-ecal console script + python -m agentic_ecal_pkg (with --json), byte-identical to
  the original module's demo output.

Tests — tests/

• pytest golden-master / parity suite (~2957 parametrized cases) covering every public function,
  registry, workflow builder, and the full Workflow.run() breakdown.
• test_paper_numbers.py pins the manuscript's anchors and case-study figures.
• The original model is frozen as tests/agentic_ecal_reference.py (the golden master).

Layout

• Everything flattened to the repo root; scripts/clean/ removed.
• Figure/analysis scripts moved to figure_scripts/ (repointed at the package, output paths fixed).
• Added examples/ (basic call, case study, custom workflow) and pyproject.toml ([dev] extra
  with pytest, pytest config).

CI

• .github/workflows/tests.yml runs the suite on push/PR across Python 3.9–3.13.

Housekeeping

• results/ and the experiment directories (experimental_results/, experiments_fig12/,
  experiments_qwen3_8_27B/, experiments_qwen35_9B/) are no longer tracked; .gitignore and
  README.md updated accordingly.

Verification

• pytest — all ~2957 tests pass (package == frozen reference, bit-exact).
• python -m agentic_ecal_pkg reproduces the original demo output exactly.
• All examples run; all figure scripts regenerate their figures.
• Case study reproduces the paper: 4990 prefill / 1020 decode tokens, 5240.26 J, 0.3022 J/bit.

Notes / follow-ups

• results/ is intentionally untracked — measured CSVs must be provided separately for the
  measured/placement figures (see README).
• The docstrings are Napoleon-ready but no docs/ scaffold is included yet; can add one on request.