contract: manuscript is upstream of the contract; lock contract ownership

[nceglia]

Reorders the authority: the manuscript is ground truth, the contract is downstream.
Where they disagree the contract is wrong, and an ambiguity is a question for the
authors — not something to infer from what makes the code or a benchmark look right.

Source documents are now in the repo

Both live in docs/contract/source/, with their SHA-256 prefixes recorded in the
metrics manifest and checked by a test. A silent revision becomes a failing build rather
than something a human has to spot.

They are separate documents with colliding equation numbers:

	owns
metrics_2026-08-05.docx	eqs 2–7	joint entropy, clonotypic/phenotypic entropy, MI, NMI, KL
supplementary_note_1_SS_2026-08-03.pdf	eqs 1–12	generative model, variational family, ELBO, perturbation

"eq 3" is the clonotypic entropy in one and the VampPrior in the other. Every note_eq
now names its document, and a test refuses a bare reference. Note 1 carries no entropy
or MI definitions at all — its only mention of the metric is the benchmark estimand
MI(C,φ) = I(C;φ) — so a metric citing it fails the suite.

The eq 3–4 erratum is closed

The 2026-08-05 document corrects both: eq 3 weights by the conditional, eq 4's left side
reads H(p(φ|c)). They now agree with the code, which was never changed. SOURCE_ERRATA
is retired and replaced by RESOLVED_ERRATA, kept because it records how the
disagreement was settled — by the MI decomposition identity producing a negative mutual
information under the literal equations, not by authority. That is the precedent for the
next one.

Manifest gaps closed

• phenotypic_flux was implemented but entirely unspecified. Now in METRIC_SPECS.
• Joint entropy (eq 2) is defined in the document but not implemented — recorded under
  UNIMPLEMENTED rather than left silently absent.

New: OPEN_QUESTIONS

Live disagreements with the document, deliberately kept separate from
SANCTIONED_EXTENSIONS so a pending decision cannot be quietly filed as a feature. A
test asserts no key appears in both.

• normalize_mode default — eq 6 specifies the mean denominator; the package
  defaults to min. Every number produced with the default therefore does not follow eq 6.
• phenotypic_flux default — eq 7 defines flux as D_KL; the code defaults to l1.
  The kernels already exist (kl/dkl, l1, js/jsd); only the default differs.
• Posterior summary of a nonlinear metric — E[NMI(J)] vs NMI(E[J]). These differ
  materially (0.267 vs 0.128 on a benchmark cell). Note 1's benchmark prose reads as the
  current behaviour but is ambiguous; needs an author's answer rather than a guess.

Ownership

.github/CODEOWNERS restricts contracts, conformance tests, prose twins and source
documents to @nceglia and @salehis.

⚠️ Advisory until you enable "Require review from Code Owners" on the main branch
protection rule — that is a repository setting I can't change. Without it, CODEOWNERS
only auto-requests reviewers and blocks nothing.

Tests

169 passed, 3 skipped (up from 166 — four new guards, one replaced).

🤖 Generated with Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.