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

demos/larql_polysemantic_hierarchical/demo.py

@@ -82,7 +82,14 @@ def banner(title: str) -> None:
 
 
 def heatmap_tier(value: float) -> str:
-    """4-tier ASCII heatmap: '#' ≥ 0.7, 'o' ∈ [0.3, 0.7), '.' ∈ [0.05, 0.3), blank < 0.05."""
+    """4-tier ASCII heatmap: '#' ≥ 0.7, 'o' ∈ [0.3, 0.7), '.' ∈ [0.05, 0.3), blank < 0.05.
+
+    The dot tier includes values arbitrarily close to the blank threshold
+    (e.g. 0.055, 0.063 in the polysemy column below render as '.' but sit
+    just above the 0.05 cutoff). The per-concept table in section 4 prints
+    the exact tabulated decimal — treat that as the source of truth when
+    cross-checking against this heatmap.
+    """
     v = abs(value)
     if v >= 0.7:
         return "#"
@@ -97,6 +104,8 @@ def print_gram_heatmap(gram: np.ndarray) -> None:
     """Print |gram|² as a 4-tier 12×12 ASCII heatmap with hierarchy labels."""
     gsq = np.abs(gram) ** 2
     print("  |gram[i,j]|²  (# ≥ 0.7, o ∈ [0.3, 0.7), . ∈ [0.05, 0.3), blank < 0.05)")
+    print("  (dot tier includes values arbitrarily close to the blank threshold;")
+    print("   see the polysemy column in section 4 for exact tabulated decimals.)")
     print("  ", "".join(f"{i:>3}" for i in range(12)))
     for i in range(12):
         row = "".join(f"  {heatmap_tier(gsq[i, j])}" for j in range(12))

openspec/changes/tech-debt-backlog/tasks.md

@@ -1605,7 +1605,7 @@ picked up.
   example-driven (could miss tasks without `§N.M`-style
   anchors)".)
 
-- [ ] 7.20 **Re-tier the heatmap legend in the larql-polysemantic-
+- [x] 7.20 **Re-tier the heatmap legend in the larql-polysemantic-
   hierarchical demo to disambiguate the 0.055 rows.** Severity:
   LOW. Surface:
   `demos/larql_polysemantic_hierarchical/demo.py:85,99`. The
@@ -1629,6 +1629,20 @@ picked up.
   `logs/pr-review-2026-05-29.log`, "the 0.055 rows sit just
   above the heatmap's 0.05 display tier, which could briefly
   confuse a cross-checking reader".)
+  Took option (b). Extended the `heatmap_tier` docstring with a
+  short note pointing readers at the section-4 polysemy column
+  as the source of truth for exact decimals, and added a
+  two-line follow-up to `print_gram_heatmap`'s legend banner so
+  the disambiguation is visible at the heatmap itself (not only
+  to a reader who chases the helper docstring). The tier cutoffs
+  are unchanged so the rendered heatmap is byte-identical to the
+  prior demo output. Verified by running the `heatmap_tier`
+  classifier across the boundary values (`0.04` → blank,
+  `0.055`/`0.063` → `.`, `0.3` → `o`, `0.71` → `#`) and by
+  `tests/test_examples.py::TestExamples::test_larql_polysemantic_hierarchical_pipeline`
+  (the pipeline test exercises the parse/verify/compile path
+  the demo wraps; the legend strings aren't pinned by any test,
+  so the change is print-only).
 
 ## Feedback triage — 2026-06-05