chore(docs): pin the validation-page figures #214 left out of scope

[bioedca]

Maintenance kind

test

Work requested

#214 pinned docs/validation.md to its source artifacts and landed as PR #436, merged
2026-08-12 UTC as 0b96be5. Its approved acceptance criteria enumerated a specific set — the
four $.tolerance bounds, the four $.tolerance_by_method.ebhmm bounds, both pooled_worst
blocks, the kinSoft matrices, the named module constants — and asked for external historical facts
to be excluded with a recorded reason. tests/test_docs_validation_numbers.py does exactly
that, in 74 pins across three pin kinds (Cell, Prose, Quote).

Two categories of figure on the page are still unpinned, and unlike the excluded ones a
committed artifact does hold their value, so the exclusion reason recorded in the test ("no
machine-readable source") does not apply to them. Filed separately rather than absorbed into
#214, whose scope hash was approved as written.

1. The two tMAVEN commit values. #214 put the commit hashes out of scope on the ground that
they are external. That is true of the upstream dates and changed-line counts printed beside
them, but the hashes themselves are committed: $.method.tmaven_commit and
$.measured_by_method.ebhmm.method.tmaven_commit in schema/parity_tolerance.json. The only two
occurrences of tmaven_commit in the guard module are on one line of EXCLUSIONS prose — no pin
reads either field, so a re-measure that moved a build leaves every printed hash stale with every
gate green. The §(b) build table pins the two sidecar_python_version values and neither
commit.

The page prints the hashes in six places:

Page location	Printed as	Live source
§(b) build table, tmaven_commit row, M0.5 column	`71cfa1af…`	$.method.tmaven_commit, first 8 hex + ellipsis
§(b) build table, tmaven_commit row, ebFRET column	`10f4230b…`	$.measured_by_method.ebhmm.method.tmaven_commit, first 8 hex + ellipsis
§(b) build table, How the values were obtained row, ebFRET column	`@10f4230` — 7 hex, so no commit[:8] derivation covers it	quoted out of $.measured_by_method.ebhmm.method.build_provenance
§(b) prose, "The pin every live assertion uses is …"	the full 40 hex	the ebFRET pointer, in full
§(b) "Gap, stated plainly" blockquote	`71cfa1af` and `10f4230b`	both pointers, first 8 hex, no ellipsis
§Scope and known limitations, third bullet	`71cfa1af` and `10f4230b`	both pointers, first 8 hex, no ellipsis

That third row is a table cell and gets its own disposition — the sixth hash location
criterion below — rather than a pin: it is mechanically unreachable under the landed
mechanism, and saying so in EXCLUSIONS is the whole of the work it needs.

The §(b) prose paragraph also names NOTICE, TMAVEN_SPEC in .github/workflows/sidecar.yml
and scripts/setup_sidecar.py as carrying the same pin. Those are corroboration for the reader;
the artifact stays the single authority a pin reads, exactly as every other pin in the module.

2. Prose restatements that sit outside the regions the guard selects. A pin selects a table
row/column or one anchored paragraph, so a value restated elsewhere on the page is unguarded. Four
prose passages restate an artifact-backed value:

• §(b) prose, "The pin every live assertion uses is …" — the full ebFRET hash and both
  occurrences of 3.12.13 in that paragraph
  ($.measured_by_method.ebhmm.method.sidecar_python_version): once as "on CPython 3.12.13" and
  again as "python=3.12.* in sidecar/environment.yml resolving to 3.12.13 on all four
  platforms".
• §(b) "Gap, stated plainly" blockquote. §(b) carries two blockquotes opening with that
  lead-in (measured); the one meant here, and everywhere "the blockquote" appears below, is the
  one that restates $.pooled_worst. It restates both 8-hex prefixes, 3.9.23
  ($.method.sidecar_python_version), $.pooled_worst rounded to three significant figures
  ("1.0 on both floors and 8.35e-09 / 1.00e-09"), the two $.tolerance ceilings it compares them
  against ("0.02 and 0.01"), --n-runs 20 ($.method.n_runs_per_fixture) and the quoted
  "vbconhmm (vb Consensus HMM)" the page itself labels the committed value of
  $.coverage.measured_methods.
• §(b), the test_load_frozen_tolerance_selects_per_method bullet and the paragraph that follows
  it — 0.5249 appears three times outside the pinned table cell ("dropped to ebFRET's
  frozen 0.5249 or below (0.5249 and 0.40 fail; …)" and "as long as the default state-count
  floor stays above 0.5249"), all keyed to
  $.tolerance_by_method.ebhmm.state_count_min_fraction.
• §Scope and known limitations, third bullet — both 8-hex prefixes and both
  sidecar_python_version values.

Verified mechanism — read this before writing a pin

Every claim below was executed against origin/main's module and page, so the design is settled
and no cycle need be spent rediscovering it. Fetch origin/main first — the module landed on
2026-08-12 and is newer than some local checkouts.

• A truncated hash needs no new pin kind and no new comparator. _states compares a table
  cell's backticked-token set to the pin's value by exact set equality, and the cell's only token
  is 71cfa1af…. A Cell pin whose value is derived live as commit[:8] + "…" therefore
  passes on today's page and fails against the full hash — the same "render the live value the way
  the page spells it" move Quote(scale=100) already makes for the two percentages.
• That same set equality is why the How the values were obtained row cannot be pinned. Its
  ebFRET cell carries five code spans — .github/workflows/sidecar-measure.yml, python 3.12.13,
  @10f4230, sidecar/conda-lock.yml, TMAVEN_SPEC — so _states is False for any single one
  of them, and _prose_paragraphs drops table blocks, so no Quote can reach the cell either.
  Both were executed.
• Prose cannot pin any of these. _owned_literals attributes a literal to the nearest
  preceding name token. In the boundary sentence five literals land on the English words
  frozen, below, and (twice) and fail — measured: frozen → {0.5249}, below → {0.5249},
  and → {0.4, 0.6}, fail → {0.525} — and $.tolerance.state_count_min_fraction owns nothing
  at all; in the hash and version restatements the tokenizer splits 71cfa1af into the number
  71 and the name cfa1af, and 3.9.23 into 3.9 and 23. Use Quote.
• The measured_methods quotation is not a Quote either. A Quote placeholder captures
  (\S+?), and vbconhmm (vb Consensus HMM) contains spaces. The existing _VERBATIM_QUOTES
  mechanism is the right one: a further entry carrying the same fragment and pointer as the landed
  one, anchored on the blockquote instead, checks both sides with no new code. Executed — it holds
  today and goes red when the blockquote's copy is altered.
• A Quote template must have a non-empty tail. _template_regex captures (\S+?)
  non-greedily, so a template ending in the placeholder captures a single character.
  on CPython {} captures 3; on CPython {}. That is captures 3.9.23. Where the value sits at
  the end of a code span, the closing backtick belongs inside the template — otherwise the capture
  keeps it and the comparison fails against a correct page.
• _flat leaves the blockquote markers inline, so a template spanning a line break inside
  > … cannot match: "are {} on both floors" finds nothing today because the flattened text
  reads are 1.0 on > both floors. Stripping a leading > per line when flattening fixes it and
  leaves all 74 existing pins and both _VERBATIM_QUOTES entries green (executed). Without
  that fix every blockquote pin is hostage to where the paragraph happens to wrap, which is the
  exact fragility _flat's docstring says it exists to prevent.
• Three significant figures in scientific notation is the page's rounding rule.
  format(v, ".2e") reproduces 8.35e-09 and 1.00e-09 exactly. .3g does not — it yields
  1e-09. The floors clause is not rounded: $.pooled_worst.state_count_fraction and
  .viterbi_agreement are both exactly 1.0, so that clause needs a shortest-round-trip
  rendering (repr), not f"{v:g}", which prints 1.
• Every paragraph these pins need is reachable under today's paragraph(), and this issue
  deliberately does not name the anchors. Selection was executed for all of them, so no page
  edit is required to make a pin selectable — but which anchor string to use is the
  implementer's call, not a fact this body states. Earlier drafts named specific anchors and
  those were the claims that turned out false under execution, so what is required here is a
  property: each anchor resolves to exactly one non-table paragraph of its section, and is not
  one of the values its own pin reads. Two selection mechanisms are available and both are
  needed — equality against a backticked token, and the documented lead-in startswith
  fallback, which paragraph() consults only when the token form matched nothing. At least one
  paragraph in scope carries no backticked token unique to it, so the fallback is load-bearing
  there (measured). Getting an anchor wrong is cheap and loud rather than silent: paragraph()
  asserts a unique match and its own message says to re-anchor the pin rather than relax it.
• _mutate is ##-section-scoped, so a mutation context need only be unique inside its own
  section. measured against tMAVEN `71cfa1af` occurs twice on the page and once in each of
  §(b) and §Scope, which is why the demonstrations below are written per section.
• A second pin on an already-pinned pointer needs a source label of its own. Both
  mutation tiers collect [p for p in REGISTRY if p.source == source] and require every
  collected pin to reject one mutated page, so two pins sharing a label are safe only where a
  single edit breaks both — which two page locations never are. Executed, and it bites in both
  directions: reusing the bare label breaks a landed case for
  $.tolerance_by_method.ebhmm.state_count_min_fraction and a new case for
  $.method.n_runs_per_fixture. The first acceptance criterion states the rule.
• Every figure in scope matches its source today, checked field by field against
  origin/main's schema/parity_tolerance.json: both tmaven_commit values against the page's
  two 8-hex prefixes and its full 40-hex prose copy; both sidecar_python_version values;
  $.tolerance_by_method.ebhmm.state_count_min_fraction 0.5249; the two $.tolerance
  ceilings 0.02 and 0.01; $.method.n_runs_per_fixture 20; both $.pooled_worst floors at
  exactly 1.0; format(…, ".2e") of the other two $.pooled_worst metrics as 8.35e-09 and
  1.00e-09; and $.coverage.measured_methods as ["vbconhmm (vb Consensus HMM)"]. So no
  number on docs/validation.md should need correcting. If one does turn out wrong, stop and
  ask — a published validation number is a scientific claim, not a test fixture.

Acceptance criteria

• Every new pin's source label names its location, not just its pointer, and no landed
  mutation case changes. This is a construction constraint rather than a new guard, and it is
  load-bearing: test_a_deliberate_one_value_mismatch_fails and
  test_a_contradiction_beside_a_correct_value_fails both collect
  [p for p in REGISTRY if p.source == source] and then require every collected pin to
  reject the one mutated page. Each of their ten landed cases collects exactly one pin today
  (executed). This issue pins one artifact field in as many as four places at once
  ($.measured_by_method.ebhmm.method.tmaven_commit: the build table, the §(b) prose
  paragraph, the blockquote, §Scope), so a new pin reusing a bare pointer as its label gets
  collected by a mutation that does not touch its location. Executed, and it bites in both
  directions: a prose pin on frozen `0.5249` or below labelled
  $.tolerance_by_method.ebhmm.state_count_min_fraction survives the landed case that edits
  the table cell | `state_count_min_fraction` | floor | 0.9 | 0.5249 | — so that
  landed case goes red; and a blockquote pin on --n-runs 20 labelled
  $.method.n_runs_per_fixture would be collected by its own new case beside the landed
  {} self-reseeded fits per fixture pin, which that mutation does not touch, so the new
  case goes red. Duplicate labels are not banned in general — five sources carry two or
  three pins today ($.measured_utc, $.band.rate_rel_deviation_max, $.schema_version,
  $.frozen_at_milestone, $.measured_by_method.ebhmm.measured_utc) — which is why this
  has to be stated rather than assumed. The module already labels by location where one field
  feeds two pins ($.levels.level3.ground_truth.note kbright / … kdark) and where a value
  is derived (sum of $.spread_by_fixture.*.n_comparisons); the new labels take that shape.
  The bare pointer stays in the registry on the landed pin that already carries it, which
  is what keeps test_every_frozen_bound_in_both_blocks_is_pinned and
  test_every_pooled_worst_metric_in_both_blocks_is_pinned green: both build
  {p.source for p in REGISTRY} and require the bare $.tolerance.*,
  $.tolerance_by_method.ebhmm.* and $.pooled_worst.* strings to be in it. Neither mutation
  test's body may be relaxed — in particular its for pin in pins loop may not become an
  any — and no landed case may be edited or dropped; new cases are appended.
• The build-table hashes are pinned prefix-wise. Two Cell pins read
  $.method.tmaven_commit and $.measured_by_method.ebhmm.method.tmaven_commit live and
  compare the page against commit[:8] + "…". Currently-failing demonstration: in §(b),
  | `71cfa1af…` (2025-05-06) | → | `81cfa1af…` (2025-05-06) | and
  | `10f4230b…` (2025-10-05) | → | `20f4230b…` (2025-10-05) | are both accepted
  by the whole suite today (executed); after this change each has a mutation case in
  test_a_deliberate_one_value_mismatch_fails that goes red, and a pin holding the full 40 hex
  is rejected by the unmutated page.
• The §(b) prose paragraph beginning "The pin every live assertion uses is …" carries three
  pins: the full 40-hex ebFRET commit, and both occurrences of 3.12.13 in it, each bound to
  $.measured_by_method.ebhmm.method.sidecar_python_version. Currently-failing
  demonstrations, all three green today:
  `10f4230b6d13c6d2ad67b05d801696b4a40eff4a` → one hex character changed;
  3.12.13 — `TMAVEN_SPEC` → 3.12.14 — `TMAVEN_SPEC`; and
  resolving to 3.12.13 → resolving to 3.12.14. Each context is unique inside §(b).
• Every measured value the §(b) blockquote restates from schema/parity_tolerance.json is
  pinned — ten of them: the two 8-hex prefixes; 3.9.23; the "1.0 on both floors" clause,
  pinned to the single common value of $.pooled_worst.state_count_fraction and
  .viterbi_agreement with an assertion that the two are equal (if they ever diverge there is
  no single value "on both floors" can state — the shape _blinking_rate already uses); the
  two three-significant-figure values 8.35e-09 and 1.00e-09; the two ceilings 0.02
  ($.tolerance.state_mean_abs_delta_max) and 0.01 ($.tolerance.relative_elbo_max);
  --n-runs 20 ($.method.n_runs_per_fixture, the invocation the paragraph calls the faithful
  reproduction of the recorded M0.5 run); and the quoted "vbconhmm (vb Consensus HMM)", which
  takes an added _VERBATIM_QUOTES entry anchored on this blockquote rather than a Quote,
  because the fragment contains spaces. Currently-failing demonstrations, one per literal and
  every one green today (executed): tMAVEN `71cfa1af` (2025-05-06) on CPython 3.9.23. That is → 81cfa1af; the pinned `10f4230b` (2025-10-05) → 20f4230b;
  on CPython 3.9.23. That is → 3.9.24; are 1.0 on → are 1.00 on;
  8.35e-09 / 1.00e-09 → 8.36e-09 and → 1.01e-09;
  ceilings of 0.02 and 0.01 → ceilings of 0.03 and 0.01 and →
  ceilings of 0.02 and 0.02; --n-runs 20 → --n-runs 30;
  and `"vbconhmm (vb Consensus HMM)"` quoted below → (VB Consensus HMM).
• Nothing else artifact-derived in that blockquote is left unpinned without a recorded
  reason. The list above is stated as the ten that must be pinned, not as a closed inventory
  — an enumeration asserted complete by inspection is how test(docs): pin the validation-page numbers to their source artifacts #214's own deferral note went wrong.
  Three further artifact-derived strings were checked during grooming and are deliberately
  excluded, each with its reason recorded in EXCLUSIONS: the bare model_281mol.hdf5 (the
  basename of $.spread_by_fixture.smd_281mol.reference, which is unpinned page-wide
  rather than only here, so covering it is a coverage extension and neither of this issue's two
  categories); the M0.5 label in "the M0.5 worst cases" ($.frozen_at_milestone, already
  pinned as a Prose entry in §(b)'s Frozen-tolerance paragraph); and the ["vbconhmm"] /
  "ebFRET (M6)" literals, which belong to scripts/measure_parity.py and not to the
  artifact — verified: ebFRET (M6) appears nowhere in schema/parity_tolerance.json, whose
  $.coverage.applied_to is ["vbFRET (per-trace, M2)", "consensus VB-HMM (M6)"]. Anything
  else in that blockquote traceable to the artifact and left unpinned gets an EXCLUSIONS
  entry too; test_every_exclusion_records_why stays green.
• The rounding rule is written down where the pin lives, as three significant figures in
  scientific notation, format(value, ".2e"), applied to the live value only — the page's
  printed text is never rounded before comparison, so a page that prints 8.3472e-09 or
  8.3e-09 fails. A committed test asserts that the rounded rendering and the exact rendering
  disagree for $.pooled_worst.state_mean_abs_delta, so the two paths cannot silently become
  one.
• Blockquote flattening strips the > marker, with a test that re-wraps the "Gap, stated
  plainly" blockquote so a pinned phrase spans a line break and the pin still holds.
  Demonstration: that re-wrap is red before the flattening change and green after — today
  "are {} on both floors" captures nothing at all while "are {} on" captures 1.0, so the
  pin's robustness depends on the line break. The existing suite is unaffected either way: all
  74 pins and both _VERBATIM_QUOTES entries stay green under the change (executed).
• Two of the three prose restatements of 0.5249 are pinned to the value; the third is
  checked structurally instead. The two pinned ones are the frozen `0.5249` or below
  clause in the test_load_frozen_tolerance_selects_per_method bullet and the
  stays above `0.5249` clause in the paragraph that follows it, both bound to
  $.tolerance_by_method.ebhmm.state_count_min_fraction. The third is the first
  fail-side literal of the illustrative pair, which the straddle check in the next
  criterion owns; that check asserts it is <= the floor rather than equal to it, so a page
  printing 0.5248 and 0.40 fail still passes. Saying "all three are pinned" would
  overstate what lands.
  Currently-failing demonstrations, both green today and both unique inside §(b):
  frozen `0.5249` or below → frozen `0.5250` or below, and
  stays above `0.5249` → stays above `0.5250`. A bare 0.5249 may not be used
  as the mutation string: it occurs four times on the page and _mutate asserts its argument is
  unique inside the section.
• The illustrative pair in that sentence is checked structurally rather than transcribed.
  A helper parses the (… fail; … pass) clause and asserts every fail-side literal is <=
  the ebFRET floor it is given and every pass-side literal is > it, so the sentence's claim
  that 0.5250 and 0.60 pass cannot survive a re-freeze that moves the floor past them. The
  floor is a parameter, so a test can drive the helper with a hypothetical 0.60 and assert it
  rejects the sentence. Demonstration: nothing reads that clause today, and the helper driven
  with 0.60 is red.
• The §Scope and known limitations third bullet is pinned: both 8-hex prefixes and both
  sidecar_python_version values.
  Currently-failing demonstrations, all four green today and all unique inside §Scope:
  measured against tMAVEN `71cfa1af` → 81cfa1af;
  behind the pinned `10f4230b` → 20f4230b; on CPython 3.9.23 — 13 upstream → 3.9.24;
  on CPython 3.12.13 that CI → 3.12.14.
  State the selection dependency in the criterion and assert it. The anchor itself is the
  implementer's to choose; the criterion is the property — it resolves to exactly one
  non-table paragraph of §Scope and is none of the four values the pin reads. That puts it
  outside the third bullet, whose only two code spans are two of those values (measured),
  and that is what makes selection fragile: paragraph() selects one blank-line-separated
  block, and the Validation-coverage list is a single 41-line block today, which is the only
  reason the third bullet's values are inside the selected paragraph at all. Inserting one
  blank line between the anchor's own bullet and the third bullet — a routine Markdown edit —
  moves those values out of the selection, and the pins then fail as though the page stated
  a wrong value on a page whose values are still correct. So the pins are accompanied by an
  assertion that the selected paragraph still contains the third bullet's lead-in text, which
  fails with a message naming the re-anchor rather than the value.
• The sixth hash location is dispositioned rather than silently skipped. The §(b) build
  table's How the values were obtained row restates python 3.12.13 and the commit as a
  7-hex @10f4230 (ebFRET column) and 2026-06-26 (M0.5 column). Those are quotations of
  two free-text build_provenance fields, not one:
  $.measured_by_method.ebhmm.method.build_provenance records the dispatch log's
  'python 3.12.13 hd63d673_0_cpython conda-forge' and its resolved
  …tmaven.git@10f4230, while the M0.5 column's date is a quotation of the other block's
  $.method.build_provenance ("the environment is not guaranteed unchanged since
  2026-06-26"). All three are accepted by the whole suite today (executed). None can be
  pinned under the landed mechanism: _states requires a cell's whole backticked-or-quoted
  token set to equal the one live value, and both cells state fragments rather than a
  field — the ebFRET cell carries five code spans, the M0.5 cell one quoted phrase lifted out
  of a paragraph-long build_provenance string — while _prose_paragraphs drops table
  blocks, so no Quote can reach a table cell either. EXCLUSIONS therefore
  gains one entry keyed on that row whose reason states those mechanical facts, and which
  does not claim "no machine-readable source" — that would be false, since both
  build_provenance fields hold their strings verbatim. Extending the comparator so that a
  single span, or a fragment of a field, can be pinned inside a table cell is mechanism work
  and is not this issue's.
• No pin transcribes a value. Every expected text is computed from at(PARITY, …) or
  module_constant(…) at test time. For the derived renderings — the 8-hex prefix and the
  three-significant-figure rounding — a test builds the same pin against a hypothetical
  re-measured value and asserts the unchanged page is rejected, so a derivation bug cannot
  accept anything the page happens to say.
• EXCLUSIONS is corrected in both entries that this work falsifies, and neither correction
  publishes a false attribution.
  "tMAVEN upstream commit hashes and their 2025-05-06 / 2025-10-05 dates" narrows to the two
  upstream dates alone.
  "second restatements of a pinned value elsewhere in the page's prose" narrows to what
  actually remains. It may no longer name the rounded pooled-worst figures, which are pinned by
  then — but it keeps RMS <= 0.5 px, with the reason corrected. The current reason is
  unusable and the obvious pin is wrong. The landed module's own docstring names
  RMS ≤ 0.5 px as one of the prose restatements it defers to this issue, so the
  disposition has to be recorded rather than dropped. The page's sentence
  (docs/validation.md, §(a)'s enforcing-tests paragraph, "native degree-2 fit vs the
  imported .tmap: RMS ≤ 0.5 px and ≥ 95 % of molecule positions agreeing within 1 px")
  describes
  tests/test_register.py::test_native_fit_reproduces_tmap_within_tolerance, which
  hard-codes all three literals itself — assert point_rms(native_pred, tmap_pred) <= 0.5
  and assert np.mean(agreement <= 1.0) >= 0.95, the second carrying both the 1 px and
  the 95 % — and whose docstring says in words that its figures are registration
  faithfulness, not the colocalization-recall criterion. No test
  asserts oracle.RMS_THRESHOLD_PX as that gate. The constant is not absent from tests/:
  git grep -n RMS_THRESHOLD_PX origin/main -- src tests matches
  src/tether/project/oracle.py twice and tests/test_docs_validation_numbers.py once, in
  the four-name tuple that builds §(a)'s Cell pins — so it is already pinned, to the
  §(a) Frozen tolerance table's Value cell, and to nothing else. Binding the
  sentence's 0.5 to it would attribute a registration gate to the M1 extraction oracle,
  the same error as binding the 95 % to oracle.RECALL_THRESHOLD; both coincide
  numerically, at 0.5 and 0.95, by accident. oracle.MATCH_TOL_PX is 2.0, so nothing at
  all holds the sentence's within 1 px. The module already says as much in its own words:
  the docstring of test_every_constant_the_page_states_a_value_for_is_pinned lists
  RMS ≤ 0.5 px beside PRD §11.2 and PEP 610 as reading like a capitalised name
  followed by a number, none of which is a symbol anything could be pinned to.
  So the narrowed entry records all three of that sentence's literals — RMS <= 0.5 px,
  >= 95 % and within 1 px — as unpinned because they are that test's hard-coded
  literals and no artifact or module constant is their source, and it names the numeric
  coincidence so a later reader does not re-discover it as an oversight. No remaining entry
  may give "no machine-readable source" as the reason for a figure a committed artifact or
  module constant is the source of. test_every_exclusion_records_why stays green.
• Regression fence, already green today — listed because it constrains how the new pins
  may be written: the 74 existing pins are unchanged and still green, and no existing
  anchor is re-pointed. Re-anchoring the four value-embedding anchors is chore(docs): harden the validation-page guard (deferred #436 nitpicks) #440's work, not
  this issue's.
• Regression fence, already green today: docs/validation.md is not edited. Every
  figure in scope was checked against its source during grooming and all of them match.
• pytest tests/test_docs_validation_numbers.py passes, then pre-commit run --all-files,
  then the matrix line for the lane
  ($env:QT_QPA_PLATFORM='offscreen'; pytest -m "not large and not sidecar and not deep" in
  native PowerShell, QT_QPA_PLATFORM=offscreen pytest -m "not large and not sidecar and not deep" in WSL bash), then mkdocs build --strict.

Scope and non-goals

In scope: tests/test_docs_validation_numbers.py only — the new registry entries, the added
_VERBATIM_QUOTES entry, the derived renderings (8-hex prefix, three-significant-figure rounding,
shortest-round-trip), the blockquote-aware flattening, the mutation cases that prove each new pin
bites — each under a source label of its own — and the EXCLUSIONS corrections.

Out of scope:

• Re-measuring or re-freezing anything. That is a deliberate re-freeze needing an ADR (PRD §11.2).
• Editing docs/validation.md, schema/, or src/.
• Pinning any part of §(a)'s enforcing-tests sentence. Its RMS ≤ 0.5 px, ≥ 95 % and
  within 1 px are tests/test_register.py's own hard-coded literals; the work here is to record
  that correctly in EXCLUSIONS, not to bind them to a coincidentally equal module constant.
• The upstream commit dates, the 13-commits-behind count and the 256 / 42 changed-line counts:
  upstream-repository facts no committed artifact holds.
• The historical Actions runs and ADR-0022's local-run numbers, whose test(docs): pin the validation-page numbers to their source artifacts #214 exclusions stand.
• The blockquote's "exactly ten top-level keys" claim, the key list beside it, and the
  ["vbconhmm"] / "ebFRET (M6)" literals. All of those describe the literal dict at the end of
  main() in scripts/measure_parity.py, which the paragraph itself names as the authority — a
  different kind of claim from a transcribed artifact value, and not this issue's.
• Extending _states or paragraph() so a single code span, or a fragment of a field, can be
  pinned inside a table cell. That is what makes the How the values were obtained row an
  exclusion here.
• Re-anchoring the four value-embedding anchors, hardening module_constant, the dead
  PAGE.is_file() assertion, routing every mutation through _mutate, and fenced-code-block
  handling. All of that is chore(docs): harden the validation-page guard (deferred #436 nitpicks) #440.

Size estimate

M — up to 400 added lines. The original XS estimate was written before the count was known: this
adds 20 REGISTRY entries (2 build-table cells, 3 in the TMAVEN_SPEC paragraph, 9 blockquote
quotes, 2 for 0.5249, 4 in §Scope) plus one _VERBATIM_QUOTES entry, three derived renderings,
a flattening change, the straddle helper, one case per named value demonstration — twenty-one of
them, twenty in test_a_deliberate_one_value_mismatch_fails plus the verbatim-quote one, which
cannot be one of those because _VERBATIM_QUOTES entries are not in REGISTRY — and three
rewritten or added exclusion reasons.

Risk level

low — the lane: Codex on the draft, then CodeRabbit

Does this need an architecture decision record?

no

Dependencies / blockers

None open. #214 closed 2026-08-12 and landed as PR #436 (0b96be5), which is the module this
extends.

#440 edits the same file and must not be worked at the same time. It is not a hard
predecessor: every paragraph this issue's pins read is uniquely selectable under today's
paragraph(), verified by execution. One coordination point in either order — #440 adds a round-trip assertion to the
exact Quote rendering, and the deliberately-rounded rendering added here must stay a separate,
declared path so that assertion keeps holding where it belongs. Whichever lands second rebases and
re-runs the focused test.

Related work / file overlap

#214 (introduced tests/test_docs_validation_numbers.py), #436 (the PR that landed it), #158
(added the page), #207 (the transcription PR that deferred pinning), #215 (added
build_provenance, the field naming these commits), #440 (hardens the same module). File overlap:
tests/test_docs_validation_numbers.py.

Target area

CI / repository governance

Milestone

M9

Required safety attestations

• I searched existing issues and this is not a duplicate.
• I am not reporting a vulnerability publicly; security reports use the private advisory flow.
• I included no secrets or private, raw, unlicensed, user, or lab data.

Grooming status — 2026-08-13

• Status: unblocked.
• Open dependencies: none. test(docs): pin the validation-page numbers to their source artifacts #214 closed 2026-08-12, delivered by PR test(docs): pin the validation-page numbers to their source artifacts #436 (0b96be5).
• Autonomy: agent-can-do-alone.
• Chosen design: the truncated hashes are pinned by deriving the page's spelling from the live
  artifact value (commit[:8], plus the ellipsis in the build table) rather than by adding a
  comparator; the rounded pooled-worst figures use format(value, ".2e"), three significant
  figures in scientific notation, applied to the live side only; the exact "1.0 on both floors"
  clause uses a shortest-round-trip rendering; the measured_methods quotation reuses
  _VERBATIM_QUOTES because a Quote placeholder cannot capture a value containing spaces; the
  literals of the boundary sentence are split into two pins of the value 0.5249 and a
  structural straddle check for the illustrative pair; and the one row no mechanism can
  reach — How the values were obtained, whose cells quote fragments of two free-text fields
  rather than either field — is recorded in EXCLUSIONS with the mechanical reason rather than
  left looking like an oversight. All of it was executed against the page before being written
  here.
• Review risk: the reviewers will ask whether a prefix comparison is a real pin. Answer it in
  the pull request: the prefix is derived from the live 40-hex value, the full value is pinned
  exactly in the §(b) prose paragraph, and the truncation is the page's typography rather than the
  test's tolerance. They may also ask why §(a)'s RMS ≤ 0.5 px is excluded rather than pinned;
  the answer is in the criterion — no test asserts oracle.RMS_THRESHOLD_PX as that
  registration gate, the gate's three literals are hard-coded in tests/test_register.py, and
  the constant is 0.5 by coincidence and is already pinned where it belongs, to §(a)'s
  table row. Pinning the sentence to it would publish a false attribution.
• Terminal condition: PR-ready handoff. Merge authority is not granted here; the maintainer
  arms it on the pull request.
• Ready condition: met; awaiting a fresh exact-scope marker.

---

Filed from the #214 implementation. Raised as a separate item rather than absorbed, because
#214's title/body snapshot was approved as written and its criteria name these figures as
excluded.

[bioedca]

Approved for agent work: this snapshot's acceptance criteria are accepted and the issue is groomed to agent-can-do-alone.

Editing the title or body after this comment voids the approval - the marker binds the SHA-256 of the exact snapshot above.