docs-battery-count-drift

Answer

Root cause. shim/test_battery.py is the count owner (44 tests after the suite grew), but four live docs still carried the pre-growth count 43 — root AGENTS.md (prose + compliance table), h3/AGENTS.md, README.md (5 spots: prose, pass-rate, compliance line, notes), and skills/SKILL.md (43/43). H3-GAP-016's PASS-grep only scanned the named files and missed README/SKILL.md (the #249 partial-fix lesson). The fix is a whole-repo sweep with three-way classification so era-correct artifacts and sibling-owned files are never blind-mutated.

Fix (fix_battery_count_drift.py, run with --root <repo>):

COUNT_RE = re.compile(r"(?<![\d.])\b43\b(?![\d.])")   # bare 43 only: no 143 / 0.43
AUTH_RE  = re.compile(r"^def (test_\w+)\s*\(", re.MULTILINE)
PROTECTED_DIRS = {"snapshots", "prd", "shim"}

def authoritative_count(test_file: Path) -> int:      # count owned by the shim suite
    return len(AUTH_RE.findall(test_file.read_text(encoding="utf-8")))

def classify(path: Path) -> str:
    parts = {p.lower() for p in path.parts}
    if parts & {"snapshots", "prd"}: return "snapshot"     # era-correct by design
    if "shim" in parts and path.name == "AGENTS.md": return "sibling"  # cross-repo
    return "live"

def sweep(root: Path, auth: int) -> Report:
    for path in sorted(root.rglob("*")):
        if not path.is_file() or path.suffix not in {".md", ".html", ".txt"}: continue
        if path.name == "test_battery.py": continue          # count owner, skip
        text = path.read_text(encoding="utf-8")
        if not COUNT_RE.findall(text): continue
        kind = classify(path)
        if kind == "sibling":                                # Rule 3: flag, never edit
            print(DUCKBRAIN_FLAG, file=sys.stderr); report.flagged.append(str(path)); continue
        if kind == "snapshot":                               # Rule 2: annotate, don't replace
            path.write_text(text + "\n" + ANNOTATION.format(stamp=stamp, auth=auth) + "\n")
            report.annotated.append(str(path)); continue
        fixed = COUNT_RE.sub(str(auth), text)                # Rule 1: live doc -> replace
        if fixed != text:
            path.write_text(fixed); report.changed.append(f"{path} ({len(hits)} spot(s))")

Key decisions, each mapped to the filing's lessons: