tech-debt-backlog §7.20: disambiguate dot-tier rows near the blank threshold

[jascal]

Summary

Single XS-sized item from PR #82's review log. Adds a one-sentence
legend note to the larql-polysemantic-hierarchical demo's heatmap
print routine so the strawberry/blueberry/car/bike rows at
0.055 / 0.063 no longer read as "should have been blank" when a
reader cross-checks the heatmap against the tabulated decimals.

• §7.20 — chose option (b), the explicitly-flagged lower-risk fix.
  demos/larql_polysemantic_hierarchical/demo.py:print_gram_heatmap
  now prints "The dot tier includes values arbitrarily close to the
  blank threshold (e.g. 0.055, 0.063 below); the tabulated decimal is
  the source of truth." immediately after the existing tier-legend
  line. The four-tier cutoffs themselves (# ≥ 0.7, o ∈ [0.3, 0.7),
  . ∈ [0.05, 0.3), blank < 0.05) and heatmap_tier's docstring
  stay canonical, so the demo's heatmap output is visually stable for
  downstream readers and there is no duplication of the explanatory
  text. Option (a) — lifting the ./blank boundary to 0.07 — was
  explicitly the higher-risk alternative because it nudges the demo's
  rendered tiers, so option (b) is the right call.

Bundled solo (no §-companion) because PR #135 is already in flight
for §§7.16/7.17 and §7.20 lives in a different file with a different
audience.

Test plan

• .venv/bin/python demos/larql_polysemantic_hierarchical/demo.py
  runs end-to-end and reports Result : PASS (max
  |empirical − analytic| ≈ 0.019 against a 3 · mc_std ≈ 0.047
  threshold).
• New legend line renders directly under the existing legend:
  "The dot tier includes values arbitrarily close to the blank
  threshold (e.g. 0.055, 0.063 below); the tabulated decimal is
  the source of truth.".
• pytest -q: 1282 passed, 8 skipped — the demo file is not
  referenced by any test and the four-tier cutoff itself is
  unchanged.
• §7.20 marked [x] with closing notes in
  openspec/changes/tech-debt-backlog/tasks.md per the file's
  convention.

🤖 Generated with Claude Code

[jascal]

Code Review — Claude Sonnet 4.6

Scope: docs/demo-only. One added print(...) legend line in print_gram_heatmap (demos/larql_polysemantic_hierarchical/demo.py) plus the [x] closure note for §7.20 in openspec/changes/tech-debt-backlog/tasks.md. No production code, no test code, no change to the heatmap_tier cutoffs.

Verdict

Looks good — ship it. The change is the lower-risk option (b) it claims to be, the cited numbers are accurate, and it introduces zero lint or test debt. One non-blocking precision note below.

Correctness / accuracy (the real bar here)

The whole value of this change rides on whether 0.055 and 0.063 are actually dot-tier cells of the gram heatmap, so I verified it directly rather than trusting the prose. Reconstructing the matrix from the demo's own pipeline:

gram = compute_concept_gram_mps(machine); gsq = |gram|²
distinct dot-tier (|gsq| ∈ [0.05, 0.3)) off-diagonal values:
  [0.055, 0.062, 0.063, 0.079, 0.140, 0.141, 0.178]
0.055 present in gram?  True
0.063 present in gram?  True

So the examples are genuine heatmap cells, not numbers borrowed from a neighboring table — 0.055 and 0.063 really do sit in [0.05, 0.3) and render as ., just barely above the < 0.05 blank threshold. That's exactly the cross-checking confusion §7.20 set out to defuse ("the 0.055 rows sit just above the heatmap's 0.05 display tier"). The legend text is also consistent with the canonical heatmap_tier boundaries at demo.py:85 (. ∈ [0.05, 0.3), blank < 0.05), which the PR correctly leaves untouched.

I also confirmed the surrounding test-plan claims:

• compute_concept_gram_mps is analytic (statevector/MPS exact, no Monte-Carlo sampling), so 0.055 / 0.063 are deterministic across runs — the example values can't silently drift between invocations.
• The demo runs end-to-end and prints Result : PASS (max |empirical − analytic| ≈ 0.0226 vs a 3·std ≈ 0.0469 threshold).
• The new line renders directly beneath the existing tier legend, as the PR body promises.

One precision note (non-blocking)

"… the tabulated decimal is the source of truth." The gram heatmap (Section 3) prints only tier glyphs plus summary min/max ranges — there is no per-cell decimal table for the gram matrix itself. The nearest decimals a reader will actually see are in Section 4's per-concept polysemy column (P(|000>) analytic), which happens to show 0.063/0.055 for strawberry/blueberry/car/bike — but that's a different observable (single-concept feature-match probability), not the pairwise |⟨c_i|c_j⟩|² the heatmap renders. They coincide numerically, which is what makes the cross-reference "work," but a careful reader chasing "the tabulated decimal" for a heatmap cell won't find one. If you want the pointer to be airtight, consider either softening to "the underlying analytic value is the source of truth" or naming where that value is printed. Purely optional — the primary message ("a dot can be a hair above 0.05; don't read it as should-have-been-blank") lands cleanly as written.

A related, even smaller point: the 0.055/0.063 literals are hardcoded in the print string. I verified they're exact current gram entries, so there's no live bug; just be aware that editing the concept set / circuit angles later would silently stale the example without any test catching it (the demo isn't asserted on). Acceptable for a frozen demo.

Lint (ruff)

.venv/bin/ruff check demos/larql_polysemantic_hierarchical/demo.py → All checks passed! The full-tree ruff check . reports 18 errors, but every one is pre-existing and confined to test files (test_compiler.py ×9, test_noise_model_section.py ×5, test_verifier.py ×2, test_qpc_convergence.py ×1, test_examples.py ×1) — unused pytest imports and E402. This PR adds zero lint debt. (Same baseline flagged in the #135 review; still a good candidate for a dedicated cleanup task.)

Tests

.venv/bin/pytest --tb=short -q on this branch: 1282 passed, 8 skipped, 0 failed (~23s). The demo file is not referenced by any test, and the tier cutoffs are unchanged, so a green suite is expected — and confirmed.

Test coverage

N/A — no behavior change. Worth noting for the record that this demo's output (including the gram tiers and the new legend) is never asserted on anywhere under tests/, so its correctness rests entirely on manual runs like the one in the test plan. Not something to fix in this PR, but it's why the hardcoded-literal drift note above can't be caught automatically.

Security / performance

None. A single extra print on a demo's startup path.

What's good

• The claim was checkable, and it checked out exactly — 0.055/0.063 are real dot-tier gram cells, not hand-waved. That's the right kind of precision for a legend whose entire purpose is to prevent a reader from mis-trusting the rendering.
• Choosing option (b) (annotate) over option (a) (lift the ./blank boundary to 0.07) is the correct risk call — it leaves every rendered tier byte-identical for downstream readers while still resolving the ambiguity.
• The tasks.md closure note is specific and honest about the trade-off ("four-tier cutoffs themselves are unchanged so the demo's heatmap output is visually stable") — good documentation discipline.

This review was posted automatically by Claude Sonnet 4.6.