gated-caller, hermetic-check: name the population boundary — #544's instrument was outside the sentence, not inside it as a finding

tools/gated-caller.py

@@ -304,6 +304,25 @@ def census(tools_dir=None, timeout=120):
                    " indistinguishable from a clean board. This is NOT the same defect as an"
                    " uninvoked control: a dead control yields a false all-clear, a dead sweep"
                    " yields no signal at all.")
+    # ⛔ NAME THE BOUNDARY OR THE COUNT IS UNREADABLE. This population is `tools/*.py`, NOT a
+    # recursive walk — tools/README.md keeps subdirectories out of scope deliberately. ⚠ But a
+    # reader of "N of M" takes M for the instrument count, and an instrument in a subdirectory is
+    # then not reported as UNCALLED: it is outside the sentence entirely.
+    # ★ #544 is exactly this case — tools/architect-sweeps/prior-art.py is the instrument whose
+    #   skipped run shipped a duplicate, and no caller audit here can see it to say so.
+    # ⇒ Named, not indexed. Only DIRECTORIES and COUNTS are printed; the quarantine's disposition
+    #   is the operator's and contributes 0 qualifying instruments in any case.
+    subdirs = []
+    for d in sorted(x for x in Path(tools_dir).iterdir() if x.is_dir() and x.name != "__pycache__"):
+        n = sum(1 for f in sorted(d.glob("*.py"))
+                if "--self-test" in f.read_text(encoding="utf-8", errors="replace"))
+        if n:
+            subdirs.append((d.name, n))
+    if subdirs:
+        detail = " · ".join(f"{name}/ {n}" for name, n in subdirs)
+        out.append(f"  ⚠ POPULATION BOUNDARY: {sum(n for _, n in subdirs)} instrument(s) exposing"
+                   f" --self-test live in SUBDIRECTORIES and are OUTSIDE the counts above"
+                   f" — {detail}. They are not reported as uncalled; they are not reported.")
     out.append(tree_provenance())
     out.append("  ⚠ RUNNER is INVOCATION, not evidence. A blanket runner passes --self-test to"
                " every subject; whether a given tool's control DISCRIMINATES is a separate"
@@ -433,6 +452,31 @@ def self_test():
               f" than omitting the row")
         (td / Path(__file__).name).unlink()
 
+        # ⛔ THE BOUNDARY LINE NEEDS A DEMONSTRATED INSTANCE, and its ABSENCE needs one too.
+        # ⚠ Asserted as a pair: "the line appears when a subdir instrument exists" passes if the
+        #   line were unconditional; "no line when no subdir" passes if it never printed at all.
+        _, before = census(tools_dir=td, timeout=60)
+        quiet = not any("POPULATION BOUNDARY" in l for l in before)
+        sub = td / "extra-sweeps"
+        sub.mkdir()
+        (sub / "hidden.py").write_text('import sys\nif "--self-test" in sys.argv:\n'
+                                       '    raise SystemExit(0)\nraise SystemExit(0)\n')
+        _, after = census(tools_dir=td, timeout=60)
+        named = any("POPULATION BOUNDARY" in l and "extra-sweeps" in l for l in after)
+        hit = quiet and named
+        ok &= hit
+        print(f"  {'ok  ' if hit else 'FAIL'}  a subdirectory instrument is NAMED as outside the "
+              f"population, and the line is ABSENT when there is none (absent={quiet}, "
+              f"named={named}) — an excluded row must not be a silent one")
+
+        # ⛔ A SUBDIR FILE WITHOUT --self-test DOES NOT QUALIFY, so it must not inflate the count.
+        (sub / "plain.py").write_text("raise SystemExit(0)\n")
+        _, after2 = census(tools_dir=td, timeout=60)
+        one = any("BOUNDARY: 1 instrument" in l for l in after2)
+        ok &= one
+        print(f"  {'ok  ' if one else 'FAIL'}  a subdirectory file NOT exposing --self-test is not"
+              f" counted (still 1) — the boundary reports the population, not the directory")
+
         rc, lines = census(tools_dir=td, timeout=60)
         hit = rc == 1 and any("NO CALLER" in l for l in lines)
         ok &= hit

tools/hermetic-check.py

@@ -175,6 +175,23 @@ def survey(tools_dir, timeout=180, quiet=False):
     lines.append("  ⚠ HERMETIC WITH RESPECT TO gh ONLY. This tool varies exactly one binary. A "
                  "suite reaching the network by another route — curl, urllib, a git remote — is "
                  "NOT covered and is not thereby clean.")
+    # ⛔ NAME THE BOUNDARY. This population is `<tools>/test_*.py`, NOT a recursive walk, and a
+    # reader of "N of N" takes N for the suite count. ⚠ Suites in subdirectories are not reported
+    # as leaky and not reported as clean — they are outside the sentence.
+    # ⇒ COUNTED, NEVER RUN. tools/teamlead/ is quarantined: not indexed, not silenced, and nobody
+    #   investigates it. A count and a directory name satisfy "not silenced" without indexing a
+    #   single file, and nothing here executes what it counts.
+    subs = []
+    for d in sorted(x for x in Path(tools_dir).iterdir()
+                    if x.is_dir() and x.name != "__pycache__"):
+        n = len(list(d.glob("test_*.py")))
+        if n:
+            subs.append((d.name, n))
+    if subs:
+        lines.append(f"  ⚠ POPULATION BOUNDARY: {sum(n for _, n in subs)} suite(s) live in"
+                     f" SUBDIRECTORIES and are OUTSIDE the count above — "
+                     + " · ".join(f"{name}/ {n}" for name, n in subs)
+                     + ". Counted, never run; not reported hermetic and not reported leaky.")
     lines.append(tree_provenance())
     return (1 if leaks else 0), lines
 
@@ -244,6 +261,19 @@ def self_test():
         finally:
             os.environ["PATH"] = real_path
 
+        # ⛔ THE BOUNDARY NEEDS BOTH DIRECTIONS. "the line appears" passes if it were
+        # unconditional; "no line when no subdir" passes if it never printed. Neither alone fails.
+        _, base = survey(str(td), timeout=60, quiet=True)
+        quiet = not any("POPULATION BOUNDARY" in l for l in base)
+        (td / "nested").mkdir()
+        (td / "nested" / "test_hidden.py").write_text(CLEAN)
+        _, withsub = survey(str(td), timeout=60, quiet=True)
+        named = any("POPULATION BOUNDARY" in l and "nested" in l for l in withsub)
+        ok &= quiet and named
+        print(f"  {'ok  ' if quiet and named else 'FAIL'}  a suite in a SUBDIRECTORY is named as "
+              f"outside the population, and the line is absent when there is none "
+              f"(absent={quiet}, named={named}) — never run, only counted")
+
         # ⛔ an empty population is VOID, not clean
         empty = Path(d) / "bare"
         empty.mkdir()