From e5380ff6fbd1f8c8afad8883e33b4bb400f82fd4 Mon Sep 17 00:00:00 2001
From: Drew T <50529377+Druthulu@users.noreply.github.com>
Date: Tue, 4 Aug 2026 16:14:13 -0600
Subject: [PATCH] fix(tools): family_hseq's stdout claimed "fleet" for an
 OVERLAYS-ONLY number
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

load() globs .run/sig.ov_*.jsonl, so main and the resident are absent from every denominator —
the numbers run ~0.3-1.0pp above the authoritative `make report` fleet (measured today: 96.6/94.6/
89.7 vs the digest's 96.28/94.1/88.7). docs/family-hseq.md has always carried the "(overlays)"
qualifier; the stdout print did not.

That asymmetry matters because stdout is the channel a session actually reads and transcribes into
a checkpoint — a right number under a wrong label is how a wrong number propagates (R35: the
measurement was fine, the instrument's LABEL was the defect; R14: a checkpoint that disagrees with
the digest must lose, and it can only lose if the disagreement is visible).

Print-only; the metric itself is unchanged and correct for its scope.
---
 docs/family-hseq.md  | 6 +++---
 tools/family_hseq.py | 9 ++++++++-
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/docs/family-hseq.md b/docs/family-hseq.md
index 6bdb65f92..899786169 100644
--- a/docs/family-hseq.md
+++ b/docs/family-hseq.md
@@ -2,13 +2,13 @@
 
 > Generated by `tools/family_hseq.py` from the 138 overlay sigs + per-overlay src stubs. Ranked by TEMPLATABLE byte-weight (PURE+IMM members × nins × 4). The byte-gate is the arbiter.
 >
-> **Scope: the 138 OVERLAYS only** (no main, no resident) · generated at HEAD `commit:1392` · stub set derived from `corpus.stubs` — the same oracle `progress.py` counts, so same-tree overlay totals agree by construction; compare digests only at the same HEAD.
+> **Scope: the 138 OVERLAYS only** (no main, no resident) · generated at HEAD `commit:1396` · stub set derived from `corpus.stubs` — the same oracle `progress.py` counts, so same-tree overlay totals agree by construction; compare digests only at the same HEAD.
 
-**Fleet (overlays):** 96.5% fn / 94.5% instr / 89.7% distinct-code matched. Unmatched: 12,140 instances / 715,541 ins (9,706 distinct classes).
+**Fleet (overlays):** 96.6% fn / 94.6% instr / 89.7% distinct-code matched. Unmatched: 12,114 instances / 712,124 ins (9,680 distinct classes).
 
 **Tail cross-check (Phase-25 close):** 7,860 tail fns / 389,899 ins → 432 h_seq families ≥2, **109 substantial (nins≥80) / 85,863 ins**.
 
-**Full frontier (all unmatched by h_seq):** 2031 target families (≥2 members or a matched sibling) + 3767 singletons (Step-D residue). Substantial: **368 families / 254,222 templatable ins**, 34 with a matched sibling (zero-crack). Substantial member classes: 1,518 PURE · 23 IMM · 6 STRUCT-excluded.
+**Full frontier (all unmatched by h_seq):** 2026 target families (≥2 members or a matched sibling) + 3767 singletons (Step-D residue). Substantial: **363 families / 250,805 templatable ins**, 29 with a matched sibling (zero-crack). Substantial member classes: 1,492 PURE · 23 IMM · 6 STRUCT-excluded.
 
 
 ## Top substantial families (by templatable byte-weight)
diff --git a/tools/family_hseq.py b/tools/family_hseq.py
index 6e2f3d8b2..484241070 100644
--- a/tools/family_hseq.py
+++ b/tools/family_hseq.py
@@ -216,7 +216,14 @@ def main():
                  f"{f['byte_weight_templatable']//4:,} |")
     open("docs/family-hseq.md", "w").write("\n".join(L) + "\n")
 
-    print(f"fleet: {metrics['fn_count_matched_pct']}% fn / {metrics['instr_weighted_matched_pct']}% instr / "
+    # OVERLAYS-ONLY, and say so ON STDOUT. load() globs .run/sig.ov_*.jsonl — main and the resident
+    # are NOT in these denominators, so every number here runs ~0.3-1.0pp ABOVE the authoritative
+    # `make report` / docs/progress.fleet.md fleet numbers. docs/family-hseq.md has always carried
+    # the "(overlays)" qualifier; this print did not — and stdout is the channel a session actually
+    # reads and transcribes into a checkpoint, which is how a wrong-labelled right number spreads
+    # (R35: the measurement was fine, the instrument's LABEL was the defect).
+    print(f"fleet (OVERLAYS ONLY — not comparable to `make report`; excludes main + resident): "
+          f"{metrics['fn_count_matched_pct']}% fn / {metrics['instr_weighted_matched_pct']}% instr / "
           f"{metrics['distinct_matched_pct']}% distinct")
     print(f"tailcheck: {tailcheck['hseq_families_ge2']} families ≥2, {tailcheck['substantial_families']} "
           f"substantial / {tailcheck['substantial_ins']:,} ins"