docs: ADR-0019 — the bandpower shape function lives in the binning operator

[ggalloni]

What changed

Records ADR-0019 — the bandpower shape function lives in the binning operator —
and adds the three domain terms it separates to CONTEXT.md. Decision only; no code.
The implementation is tracked in three issues (below).

The binning weights w_ℓ in dC^b = Σ_ℓ w_{b,ℓ} b²_ℓ dC^ℓ declare what the spectrum
is assumed to do inside a bin, and the estimator returns the amplitude of that declared
shape. Unit weight is not a neutral choice — it declares C_ℓ flat in the bin. The Dl
path then ignored that declaration: it estimated C_b under the flat-C model and
rescaled by a single ℓ(ℓ+1)/2π evaluated at the bin midpoint. No scalar can do
that job. Once a bin is collapsed to one number the in-bin variation of ℓ(ℓ+1) is
gone, and convexity gives Σ_ℓ w_ℓ·ℓ(ℓ+1) = ℓ_eff(ℓ_eff+1) + Var_w(ℓ) — so any
single-ℓ scalar undershoots the true D-space factor by the weighted variance of ℓ
across the bin (≈5% at delta_ell=5, low ℓ).

The decision is to declare the shape once and delete the conversion rather than
correct it: Dl selects w_ℓ = 2π/(ℓ(ℓ+1)), the estimator returns D_b natively, and
F_b is already the Fisher for D_b. Separately, the effective multipole is the
centroid of the estimator's realised window — QML applies inverse-variance weighting
automatically, so it depends on noise and mask coupling and is knowable only from the
per-ℓ Fisher. It moves to Fisher, where the window lives. Bins keeps bin geometry
and no notion of an effective multipole: bin edges cannot know where a bandpower sits,
and by answering anyway they answered with the midpoint.

Public surface

None in this PR — it adds an ADR (status Proposed) and glossary terms. The public
surface it decides on is breaking and lands in the implementation PRs:
output_convention becomes an estimator setting (Dl will estimate a different
observable, so D_ℓ values, covariance and Fisher all change, and not by a uniform
factor); Bins.lbin → Bins.lmid; get_effective_ells() moves onto Fisher and will
require a completed Fisher run. Each carries its own changelog entry.

Implementation

Sequenced, and the first is a hard prerequisite — effective ells differ per spectrum,
so TEB cannot be served until the window supports it:

1. Lift the single-spectrum guard on the bandpower window function
2. Strip the unused xQML P/Q machinery from Bins; add shape weights; rename lbin to lmid
3. output_convention: Dl must select a bandpower shape, not a post-hoc scalar

Follow-up, deliberately unspecified: Fiducial-shaped binning operator.

Checklist

• docs/source/changelog.rst — not applicable; no package source touched, so the
  changelog job does not gate this. The behaviour changes it decides carry their
  entries in the implementation PRs.
• ADR added — docs/adr/0019-bandpower-shape-function.md, indexed in INDEX.md.
• CONTEXT.md updated — bandpower shape function, effective multipole and bin
  midpoint are now three distinct terms. Collapsing them into one lbin is the
  bug.
• Doc-drift sweep — no public surface moved in this PR. ADR-0007's rationale cites
  bin_spectra / bin_covariance / Dl weighting as our extensions on top of xQML;
  the Bins cleanup PR deletes those and must amend it (attribution to Vanneste+
  2018 and the GPLv3 obligation stay regardless).
• Tests — no code changed.

[codecov]

Codecov Report

✔️ No coverage data to report, because files changed do not require tests or are set to ignore

[Copilot]

Pull request overview

Adds a new Architecture Decision Record (ADR-0019) documenting that the bandpower “shape function” (in-bin spectral assumption) must be expressed in the binning operator (via weights (w_\ell)), and that effective multipoles should be derived from the realised window (via Fisher), not from bin midpoints. Also updates project glossary/context to explicitly separate the terms bandpower shape function, effective multipole, and bin midpoint.

Changes:

• Add ADR-0019 documenting the decision to eliminate post-hoc (C_\ell \to D_\ell) scalar conversion and instead declare the in-bin shape via (w_\ell).
• Index ADR-0019 in the ADR catalog and mark it as Proposed / deferred.
• Extend CONTEXT.md with clearer binning terminology aligned with ADR-0019.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
docs/adr/INDEX.md	Adds ADR-0019 to the bandpower/binning section and to the Proposed/deferred status list.
docs/adr/0019-bandpower-shape-function.md	New ADR specifying the bandpower shape-function decision, effective-multipole definition, and consequences.
CONTEXT.md	Adds and clarifies glossary terms: bandpower shape function, effective multipole, and bin midpoint (Bins.lmid).