tech-debt-backlog §7.20: clarify dot tier in polysemantic-hierarchical heatmap legend

[jascal]

Summary

Closes §7.20 of the tech-debt-backlog OpenSpec change.

• Took option (b) from the task body: add a one-sentence legend note explaining that the dot tier includes values arbitrarily close to the blank threshold and that the tabulated decimal in section 4 is the source of truth.
• The heatmap tier cutoffs (# ≥ 0.7, o ∈ [0.3, 0.7), . ∈ [0.05, 0.3), blank < 0.05) are unchanged, so the rendered heatmap is byte-identical to prior demo output — only the printed legend banner gains two clarifying lines, and the heatmap_tier docstring gains a short note pointing readers at the polysemy column.
• Marks §7.20 [x] in openspec/changes/tech-debt-backlog/tasks.md with the resolution note.

Test plan

• pytest -q — 1282 passed, 8 skipped (full suite green)
• pytest tests/test_examples.py::TestExamples::test_larql_polysemantic_hierarchical_pipeline -q — pipeline test that wraps the demo's parse/verify/compile path still passes
• heatmap_tier boundary classifier still returns the expected glyph at 0.04 (blank), 0.055/0.063 (.), 0.3 (o), 0.71 (#)
• No test pins the legend string, so the print-only change is safe

🤖 Generated with Claude Code

[jascal]

Code Review — Claude Sonnet 4.6

Thanks for closing out §7.20. This is a tightly-scoped, print-only documentation change to demos/larql_polysemantic_hierarchical/demo.py plus a tasks-list status flip. I checked out the branch, ran lint + the full test suite, and independently verified the factual claims in the docstring. This is a clean, low-risk change — ready to merge.

What I verified

• Lint (changed file): clean. .venv/bin/ruff check demos/larql_polysemantic_hierarchical/demo.py → All checks passed!. The repo has 18 pre-existing ruff errors, but all are E402 in test files (tests/test_verifier.py, tests/test_compiler.py, tests/test_examples.py, tests/test_noise_model_section.py, tests/test_qpc_convergence.py) and are unrelated to this PR — not introduced here, not a blocker for this change.
• Tests: green. .venv/bin/pytest -q → 1282 passed, 8 skipped (matches your test plan exactly). The cited tests/test_examples.py::TestExamples::test_larql_polysemantic_hierarchical_pipeline passes in isolation.
• Tier cutoffs unchanged → heatmap byte-identical. I ran heatmap_tier across the boundaries: 0.04→' ', 0.05→'.', 0.055→'.', 0.063→'.', 0.2999→'.', 0.3→'o', 0.6999→'o', 0.7→'#', 0.71→'#'. All correct; the inclusive lower bounds are untouched, so the rendered glyphs don't move. Your "byte-identical" claim holds.
• The docstring's example decimals are real, not illustrative. I recomputed the polysemy column from compute_concept_gram_mps on the actual machine: index 5 = 0.0552 and index 4 = 0.0626, which round to the 0.055/0.063 cited in the docstring. So the example isn't hand-waved — it points at genuine rows that sit ~0.005 above the 0.05 blank cutoff. This is exactly the disambiguation §7.20 asked for.
• Cross-reference is accurate. Both the docstring and the new banner lines point readers to "the polysemy column in section 4," and that section is literally titled 4. Per-concept polysemy column (line 248) and prints the exact tabulated decimals (the analytic column, line 274). The "source of truth" pointer lands where it claims to.

What looks good

• Option (b) was the right call. Putting the note in both places — the heatmap_tier docstring (for someone reading the code) and the print_gram_heatmap banner (for someone reading the demo output) — covers both audiences. A reader cross-checking the ASCII heatmap against the decimal table no longer has to wonder why a near-blank value shows a dot.
• Choosing not to re-tier the cutoffs is the conservative, correct decision: shifting the blank threshold would have changed every rendered heatmap in the demo's history for a purely cosmetic ambiguity. Clarifying the legend instead of moving the boundary is the lower-blast-radius fix.
• The tasks.md resolution note is unusually complete — it records the option taken, the rationale, the boundary-value verification, and why the change is test-safe. That traceability is genuinely useful for the next person auditing the backlog.

Minor observations (non-blocking, no change required)

• Hardcoded example decimals are a small durability liability. 0.055/0.063 are baked into the docstring. They're deterministic (fixed Ry angles → fixed Gram), so they won't drift under normal runs — and the docstring itself directs readers to the runtime table as the source of truth, which neutralizes most of the risk. But if the encoding angles in examples/larql-polysemantic-hierarchical.q.orca.md are ever retuned, these example values would silently go stale with nothing to catch them. Phrasing like "values just above the 0.05 cutoff (e.g. the cross-group rows in the polysemy column)" would be drift-proof. Not worth a revision on its own.
• No test pins the boundary behavior. You correctly note the legend strings aren't pinned by any test, which is what makes this print-only change safe. The flip side is that the heatmap_tier cutoffs themselves have no direct unit test guarding the 0.05/0.3/0.7 boundaries — so a future "byte-identical" claim couldn't be mechanically verified. That's pre-existing and out of scope here, but a 4-line parametrized test over the boundary values would be cheap insurance if this helper ever gets touched again.

Verdict

Correct, accurately documented, lint-clean on the touched file, and fully test-covered by the existing pipeline test. No security or performance surface (print-only). Approve in spirit — merge when ready.

This review was posted automatically by Claude Sonnet 4.6.

[jascal]

Closing as superseded. §7.20 was already resolved by #136 (2395d01, "§7.20: disambiguate the 0.055 / 0.063 dot-tier rows"), which landed on main before this branch could merge.

main's demos/larql_polysemantic_hierarchical/demo.py already prints the dot-tier disambiguation legend (option (b)), and §7.20 is marked [x] in tasks.md with a resolution note. The only net-new artifact here was a re-wording of the already-merged legend line plus a short heatmap_tier docstring note — not worth re-merging churn over an already-closed item.