@theglitchking/babel-fish 2.4.2 → 2.5.0

package/.claude/install.sh

@@ -98,6 +98,10 @@ POST-INSTALL COMMANDS
     python .claude/project-map/mine-sessions.py --verbose
     python .claude/project-map/mine-sessions.py --dry-run
 
+  Check auto-loaded context (CLAUDE.md + .claude/rules/) — budget, pointers:
+    python .claude/project-map/context-check.py
+    python .claude/project-map/context-check.py --budget 80000 --map-style
+
   Re-install git hooks (if you cloned a fresh copy):
     bash .githooks/install.sh
 
@@ -121,7 +125,7 @@ KEY FILES AFTER INSTALL
   .claude/rules/project-vocabulary.md       — Auto-loaded every session
   .claude/rules/operational-runbook.md      — Edit manually to grow over time
   .claude/skills/<slug>-developer-skill/    — Your developer skill
-  .githooks/pre-commit                      — Auto-regenerates map on commit
+  .githooks/pre-commit                      — Regenerates map; checks auto-loaded context
 
 GRADING CATEGORIES (90% to pass)
   Section completeness  25%  — All 19 sections generated
@@ -378,17 +382,45 @@ if echo "$STAGED_FILES" | grep -qE "$EXTENSIONS_PATTERN" 2>/dev/null; then
 fi
 # ── End Codebase Mapper ──────────────────────────────────────────────────────'
 
-    if [ -f "$pre_commit" ]; then
-        if ! grep -q 'Codebase Mapper' "$pre_commit" 2>/dev/null; then
-            { echo ""; echo "$hook_snippet"; } >> "$pre_commit"
-            ok "Appended to existing pre-commit hook"
-        else
-            ok "pre-commit hook already contains Codebase Mapper snippet"
+    # Own marker, checked separately: hooks installed before #20 already carry
+    # the Codebase Mapper block, and re-running the installer must still add this.
+    local check_snippet
+    check_snippet=$(cat <<'SNIPPET'
+# ── Context Check: auto-loaded instructions stay in budget, pointers resolve ──
+if git diff --cached --name-only 2>/dev/null | grep -qE '^(\.claude/)?CLAUDE(\.local)?\.md$|^\.claude/rules/.*\.md$'; then
+    CHECK_SCRIPT=".claude/project-map/context-check.py"
+    if [ -f "$CHECK_SCRIPT" ]; then
+        PYTHON=""
+        if [ -f ".venv/bin/python3" ]; then PYTHON=".venv/bin/python3"
+        elif command -v python3 &>/dev/null; then PYTHON="python3"
+        elif command -v python &>/dev/null; then PYTHON="python"
         fi
-    else
-        printf '#!/bin/bash\n%s\n' "$hook_snippet" > "$pre_commit"
+        if [ -n "$PYTHON" ] && ! $PYTHON "$CHECK_SCRIPT"; then
+            echo "[context-check] Commit blocked. Fix the FAIL lines above, or add flags (--budget N, --map-style) to this call in .githooks/pre-commit." >&2
+            exit 1
+        fi
+    fi
+fi
+# ── End Context Check ────────────────────────────────────────────────────────
+SNIPPET
+)
+
+    if [ ! -f "$pre_commit" ]; then
+        printf '#!/bin/bash\n' > "$pre_commit"
         ok "Created pre-commit hook"
     fi
+    if ! grep -q 'Codebase Mapper' "$pre_commit" 2>/dev/null; then
+        { echo ""; echo "$hook_snippet"; } >> "$pre_commit"
+        ok "Added Codebase Mapper to pre-commit hook"
+    else
+        ok "pre-commit hook already contains Codebase Mapper snippet"
+    fi
+    if ! grep -q 'Context Check' "$pre_commit" 2>/dev/null; then
+        { echo ""; echo "$check_snippet"; } >> "$pre_commit"
+        ok "Added Context Check to pre-commit hook"
+    else
+        ok "pre-commit hook already contains Context Check snippet"
+    fi
 
     chmod +x "$pre_commit"
 
@@ -512,6 +544,7 @@ if [ "$PLUGIN_SOURCE_DIR" != "$CLAUDE_DIR" ]; then
     cp -r "$PLUGIN_SOURCE_DIR/project-map/generate.py" "$CLAUDE_DIR/project-map/" 2>/dev/null || true
     cp -r "$PLUGIN_SOURCE_DIR/project-map/grader.py" "$CLAUDE_DIR/project-map/" 2>/dev/null || true
     cp -r "$PLUGIN_SOURCE_DIR/project-map/mine-sessions.py" "$CLAUDE_DIR/project-map/" 2>/dev/null || true
+    cp -r "$PLUGIN_SOURCE_DIR/project-map/context-check.py" "$CLAUDE_DIR/project-map/" 2>/dev/null || true
 fi
 
 # ── Step 1: Ensure Python ─────────────────────────────────────────────────────

package/.claude/project-map/context-check.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""
+context-check.py — Babel Fish
+Keeps the files Claude Code auto-loads at session start small and pointing at
+things that exist (#20).
+
+`CLAUDE.md` and every `.claude/rules/*.md` load into every session. Past the
+harness limit (150k chars) rules stop binding and nothing reports it; before
+that, growth is one paragraph at a time and nobody sees the total. Three checks:
+
+1. BUDGET    — total chars under --budget (default 60k, well under the limit).
+2. POINTERS  — every `→ `path``, backticked `.documentation/…md` path and
+               relative markdown link names a file that exists. hewtd link-checks
+               only INSIDE `.documentation/`, so archiving or renaming a doc a
+               rule points at breaks the pointer silently.
+3. RULE LINES (--map-style only) — in a rules file every bullet is
+               `- ALWAYS|NEVER <rule> — <why> → `doc``; in CLAUDE.md every
+               bullet with a pointer is. Opt-in: it is one repo's convention, and
+               this runs from the pre-commit hook of every babel-fish install.
+
+Deliberately NOT part of generate.py: the hook runs generate.py only when code
+is staged, `.claude/` is outside the watch set, and the hook discards its
+errors — a failure there could never block a commit.
+
+Usage:
+    python context-check.py [--budget N] [--map-style] [--descriptive a.md,b.md]
+                            [--warn-only] [--project-root PATH]
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).parent.parent.parent
+
+HARNESS_LIMIT = 150_000
+DEFAULT_BUDGET = 60_000
+# Maps whose lines describe (tools, traps, vocabulary) rather than rule — exempt
+# from the ALWAYS/NEVER form. project-vocabulary.md is babel-fish's own output.
+DEFAULT_DESCRIPTIVE = {"operational-runbook.md", "project-vocabulary.md", "tool-registry.md"}
+
+ARROW_RE = re.compile(r"→ `([^`\s*]+?\.md)(?:#[^`]*)?`")
+DOC_PATH_RE = re.compile(r"`(\.documentation/[^`\s*]+?\.md)(?:#[^`]*)?`")
+MD_LINK_RE = re.compile(r"\]\(([^)\s]+)\)")
+FENCE_RE = re.compile(r"^```.*?^```", re.MULTILINE | re.DOTALL)
+RULE_RE = re.compile(r"- (ALWAYS|NEVER)\b")
+
+
+def configure_paths(project_root: Path) -> None:
+    """Read root. Nothing here writes, but match the sibling scripts (#18)."""
+    global PROJECT_ROOT
+    PROJECT_ROOT = project_root
+
+
+def loaded() -> dict[str, str]:
+    """-> {relpath: text} for every file Claude Code loads at session start."""
+    paths = [PROJECT_ROOT / n for n in ("CLAUDE.md", "CLAUDE.local.md", ".claude/CLAUDE.md")]
+    # ponytail: rules with `paths:` frontmatter load lazily but are counted anyway —
+    # over-counting errs toward the budget, not past the limit.
+    paths += sorted((PROJECT_ROOT / ".claude" / "rules").rglob("*.md"))
+    return {p.relative_to(PROJECT_ROOT).as_posix(): p.read_text(encoding="utf-8", errors="replace")
+            for p in paths if p.is_file()}
+
+
+def bullets(text: str) -> list[str]:
+    return [ln for ln in text.split("\n") if ln.startswith("- ")]
+
+
+def bad_rule_lines(text: str) -> list[str]:
+    """-> bullets that are not `- ALWAYS|NEVER … → `path``."""
+    return [ln for ln in bullets(text) if not RULE_RE.match(ln) or not ARROW_RE.search(ln)]
+
+
+def unresolved(text: str, file_dir: Path) -> list[str]:
+    """-> every pointer in `text` naming a path that does not exist.
+
+    `→` pointers and backticked `.documentation/` paths are root-relative (that is
+    how the map convention writes them); markdown links resolve relative to the file or
+    to the root. Code fences are skipped — examples are not pointers.
+    """
+    text = FENCE_RE.sub("", text)
+    missing = [p for p in set(ARROW_RE.findall(text)) | set(DOC_PATH_RE.findall(text))
+               if not (PROJECT_ROOT / p).exists()]
+    for link in MD_LINK_RE.findall(text):
+        target = link.split("#", 1)[0]
+        if not target or re.match(r"[a-z][a-z0-9+.-]*:", target, re.I):  # anchor-only, http:, mailto:
+            continue
+        target = target.lstrip("/")
+        # File-relative is markdown; root-relative is how Claude reads a path, and
+        # what the installer's own .claude/CLAUDE.md pointer uses. Either counts.
+        if not ((file_dir / target).exists() or (PROJECT_ROOT / target).exists()):
+            missing.append(link)
+    return sorted(set(missing))
+
+
+def run(budget: int, map_style: bool, descriptive: set[str]) -> int:
+    """Print the report; return the number of failed checks."""
+    fails = 0
+
+    def check(name: str, ok: bool, detail: str = "") -> None:
+        nonlocal fails
+        print(f"  {'PASS' if ok else 'FAIL'}  {name}" + (f"  -- {detail}" if detail and not ok else ""))
+        fails += not ok
+
+    files = loaded()
+    total = sum(len(t) for t in files.values())
+
+    print("\nthe budget")
+    check(f"auto-loaded context is under {budget:,} chars", total <= budget,
+          f"{total:,} -- move detail into .documentation/ and leave one line pointing at it")
+    for k, t in sorted(files.items(), key=lambda kv: -len(kv[1])):
+        print(f"        {len(t):>7,}  {k}")
+    print(f"        {total:>7,}  total ({total / HARNESS_LIMIT:.0%} of the {HARNESS_LIMIT:,} harness limit)")
+
+    print("\nevery pointer resolves")
+    for k, t in files.items():
+        miss = unresolved(t, (PROJECT_ROOT / k).parent)
+        check(f"{k}: all pointers exist", not miss, ", ".join(miss[:3]))
+
+    if map_style:
+        print("\nrule lines are ALWAYS/NEVER, with a pointer")
+        for k, t in files.items():
+            if Path(k).name in descriptive:
+                continue
+            if k.startswith(".claude/rules/"):
+                bad = bad_rule_lines(t)
+                check(f"{k}: every bullet is ALWAYS|NEVER → doc", not bad, bad[0][:80] if bad else "")
+            else:  # CLAUDE.md: tool lines may go unpointed; a pointed bullet is a rule
+                bad = [ln for ln in bad_rule_lines(t) if "→" in ln]
+                check(f"{k}: every pointed bullet is ALWAYS|NEVER", not bad, bad[0][:80] if bad else "")
+
+    print(f"\n{'OK' if not fails else f'{fails} FAILED'}")
+    return fails
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Check the context Claude Code auto-loads (#20).")
+    ap.add_argument("--budget", type=int, default=DEFAULT_BUDGET,
+                    help=f"max total chars (default {DEFAULT_BUDGET:,}; harness limit {HARNESS_LIMIT:,})")
+    ap.add_argument("--map-style", action="store_true",
+                    help="also require rule bullets to be `- ALWAYS|NEVER … → `doc``")
+    ap.add_argument("--descriptive", default=",".join(sorted(DEFAULT_DESCRIPTIVE)),
+                    help="comma-separated filenames exempt from --map-style (default: %(default)s)")
+    ap.add_argument("--warn-only", action="store_true", help="report, but always exit 0")
+    ap.add_argument("--project-root", type=Path, default=None)
+    args = ap.parse_args()
+    if args.project_root:
+        configure_paths(args.project_root.resolve())
+    fails = run(args.budget, args.map_style, {n.strip() for n in args.descriptive.split(",") if n.strip()})
+    sys.exit(1 if fails and not args.warn_only else 0)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/project-map/test_context_check.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""Regression tests for context-check.py — run: python3 .claude/project-map/test_context_check.py
+
+Stdlib assert + __main__, same shape as the sibling suites. Every check is proven
+to DETECT something (a seeded bad input) as well as to pass a good one: a check
+that only ever prints PASS is indistinguishable from one that checks nothing.
+
+Every fixture is a temp project passed via --project-root, so nothing here reads
+or writes the real repo (#18).
+"""
+from __future__ import annotations
+
+import inspect
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+HERE = Path(__file__).parent
+SCRIPT = HERE / "context-check.py"
+REPO = HERE.parent.parent
+
+GOOD_RULES = "# Rules\n\n- NEVER do the bad thing — it breaks. → `.documentation/a.md`\n"
+
+
+def make_project(root: Path, claude_md: str = "# Project\n", rules: dict[str, str] | None = None) -> Path:
+    (root / ".documentation").mkdir(parents=True, exist_ok=True)
+    (root / ".documentation/a.md").write_text("# A\n")
+    (root / "CLAUDE.md").write_text(claude_md)
+    (root / ".claude/rules").mkdir(parents=True, exist_ok=True)
+    for name, text in (rules or {}).items():
+        (root / ".claude/rules" / name).write_text(text)
+    return root
+
+
+def check(root: Path, *flags: str) -> subprocess.CompletedProcess:
+    return subprocess.run([sys.executable, str(SCRIPT), "--project-root", str(root), *flags],
+                          capture_output=True, text=True)
+
+
+# ── budget ───────────────────────────────────────────────────────────────────
+
+def test_under_budget_passes(tmp):
+    r = check(make_project(tmp, rules={"r.md": GOOD_RULES}))
+    assert r.returncode == 0, r.stdout
+
+
+def test_over_budget_fails_and_names_the_file(tmp):
+    make_project(tmp, rules={"huge.md": "x" * 2_000})
+    r = check(tmp, "--budget", "1000")
+    assert r.returncode == 1, r.stdout
+    assert "FAIL  auto-loaded context is under 1,000" in r.stdout
+    assert ".claude/rules/huge.md" in r.stdout
+
+
+def test_budget_counts_nested_rules_and_dot_claude_claude_md(tmp):
+    make_project(tmp)
+    (tmp / ".claude/rules/sub").mkdir()
+    (tmp / ".claude/rules/sub/deep.md").write_text("y" * 600)
+    (tmp / ".claude/CLAUDE.md").write_text("z" * 600)
+    r = check(tmp, "--budget", "1000")
+    assert r.returncode == 1, r.stdout
+    assert ".claude/rules/sub/deep.md" in r.stdout and ".claude/CLAUDE.md" in r.stdout
+
+
+def test_warn_only_exits_zero(tmp):
+    r = check(make_project(tmp, rules={"huge.md": "x" * 2_000}), "--budget", "1000", "--warn-only")
+    assert r.returncode == 0 and "FAIL" in r.stdout, r.stdout
+
+
+# ── pointers ─────────────────────────────────────────────────────────────────
+
+def test_dangling_arrow_pointer_fails(tmp):
+    r = check(make_project(tmp, rules={"r.md": "- NEVER x — y. → `.documentation/gone.md`\n"}))
+    assert r.returncode == 1 and ".documentation/gone.md" in r.stdout, r.stdout
+
+
+def test_dangling_backticked_doc_path_fails(tmp):
+    r = check(make_project(tmp, claude_md="See `.documentation/missing/doc.md` for more.\n"))
+    assert r.returncode == 1 and "missing/doc.md" in r.stdout, r.stdout
+
+
+def test_dangling_markdown_link_fails_relative_to_the_file(tmp):
+    # This repo's runbook links docs this way — the fork's regexes never saw them.
+    make_project(tmp, rules={"r.md": "[doc](../../.documentation/a.md) and [bad](../../.documentation/nope.md)\n"})
+    r = check(tmp)
+    assert r.returncode == 1, r.stdout
+    assert "nope.md" in r.stdout and "a.md" not in r.stdout.split("--")[-1], r.stdout
+
+
+def test_root_relative_link_in_dot_claude_is_accepted(tmp):
+    # The installer writes exactly this into .claude/CLAUDE.md. Strictly file-relative,
+    # it blocked the first commit of every fresh install.
+    make_project(tmp)
+    (tmp / ".claude/project-map").mkdir()
+    (tmp / ".claude/project-map/PROJECT_MAP.md").write_text("# Map\n")
+    (tmp / ".claude/CLAUDE.md").write_text("[map](.claude/project-map/PROJECT_MAP.md)\n")
+    r = check(tmp)
+    assert r.returncode == 0, r.stdout
+
+
+def test_anchor_url_and_code_fence_are_not_false_alarms(tmp):
+    make_project(tmp, claude_md=(
+        "→ `.documentation/a.md#section`\n"
+        "[site](https://example.com/x.md) [mail](mailto:a@b.c) [here](#top)\n"
+        "```md\n→ `.documentation/example-only.md`\n[x](nowhere.md)\n```\n"
+    ))
+    r = check(tmp)
+    assert r.returncode == 0, r.stdout
+
+
+# ── rule lines (--map-style) ─────────────────────────────────────────────────
+
+def test_rule_lines_ignored_without_map_style(tmp):
+    r = check(make_project(tmp, rules={"r.md": "- just some context\n"}))
+    assert r.returncode == 0 and "ALWAYS/NEVER" not in r.stdout, r.stdout
+
+
+def test_context_line_in_rules_file_fails(tmp):
+    r = check(make_project(tmp, rules={"r.md": "- run the gates first → `.documentation/a.md`\n"}), "--map-style")
+    assert r.returncode == 1 and "run the gates first" in r.stdout, r.stdout
+
+
+def test_rule_without_pointer_fails(tmp):
+    r = check(make_project(tmp, rules={"r.md": "- NEVER do it — because.\n"}), "--map-style")
+    assert r.returncode == 1, r.stdout
+
+
+def test_good_rule_line_passes(tmp):
+    r = check(make_project(tmp, rules={"r.md": GOOD_RULES}), "--map-style")
+    assert r.returncode == 0, r.stdout
+
+
+def test_descriptive_files_are_exempt(tmp):
+    make_project(tmp, rules={"operational-runbook.md": "- a trap, described\n"})
+    assert check(tmp, "--map-style").returncode == 0
+    r = check(tmp, "--map-style", "--descriptive", "other.md")
+    assert r.returncode == 1, r.stdout
+
+
+def test_claude_md_only_pointed_bullets_must_be_rules(tmp):
+    make_project(tmp, claude_md="- `run it` with docker\n")
+    assert check(tmp, "--map-style").returncode == 0
+    (tmp / "CLAUDE.md").write_text("- a tool line → `.documentation/a.md`\n")
+    assert check(tmp, "--map-style").returncode == 1
+
+
+# ── wiring ───────────────────────────────────────────────────────────────────
+
+def test_this_repo_passes():
+    r = subprocess.run([sys.executable, str(SCRIPT)], capture_output=True, text=True, cwd=REPO)
+    assert r.returncode == 0, r.stdout
+
+
+def _block(text: str) -> str:
+    start = text.index("# ── Context Check")
+    end = text.index("# ── End Context Check")
+    return text[start:end]
+
+
+def test_installer_writes_the_same_hook_block():
+    assert _block((REPO / ".githooks/pre-commit").read_text()) == _block((REPO / ".claude/install.sh").read_text())
+
+
+def test_hooks_are_committed_executable():
+    # Git silently skips a non-executable hook. Until #20 both were committed 100644,
+    # so no clone of this repo ever ran its pre-commit hook.
+    out = subprocess.run(["git", "ls-files", "-s", ".githooks/"], capture_output=True, text=True,
+                         cwd=REPO, check=True).stdout
+    modes = {line.split("\t")[1]: line.split()[0] for line in out.splitlines()}
+    assert modes and all(m == "100755" for m in modes.values()), modes
+
+
+def test_hook_blocks_a_bad_rules_commit(tmp):
+    git = ["git", "-c", "user.name=t", "-c", "user.email=t@t", "-c", "core.hooksPath=.githooks"]
+    subprocess.run(["git", "init", "-q", str(tmp)], check=True)
+    make_project(tmp, rules={"r.md": GOOD_RULES})
+    (tmp / ".githooks").mkdir()
+    shutil.copy(REPO / ".githooks/pre-commit", tmp / ".githooks/pre-commit")
+    (tmp / ".githooks/pre-commit").chmod(0o755)  # the mode itself is test_hooks_are_committed_executable's job
+    (tmp / ".claude/project-map").mkdir(parents=True)
+    shutil.copy(SCRIPT, tmp / ".claude/project-map/context-check.py")
+    commit = lambda msg: subprocess.run(git + ["commit", "-qm", msg], cwd=tmp, capture_output=True, text=True)
+
+    subprocess.run(["git", "add", "-A"], cwd=tmp, check=True)
+    r = commit("good")
+    assert r.returncode == 0, r.stdout + r.stderr
+
+    (tmp / ".claude/rules/r.md").write_text("- NEVER x — y. → `.documentation/gone.md`\n")
+    subprocess.run(["git", "add", "-A"], cwd=tmp, check=True)
+    r = commit("bad")
+    assert r.returncode != 0, "hook let a dangling pointer through"
+    assert "Commit blocked" in r.stderr, r.stderr
+
+
+def main() -> int:
+    tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
+    failed = []
+    base = Path(tempfile.mkdtemp(prefix="context-check-test-"))
+    try:
+        for fn in tests:
+            d = base / fn.__name__
+            d.mkdir(parents=True)
+            try:
+                if "tmp" in inspect.signature(fn).parameters:
+                    fn(d)
+                else:
+                    fn()
+                print(f"  ok   {fn.__name__}")
+            except Exception as e:
+                failed.append(fn.__name__)
+                print(f"  FAIL {fn.__name__}: {type(e).__name__}: {e}")
+    finally:
+        shutil.rmtree(base, ignore_errors=True)
+    print(f"\n{len(tests) - len(failed)}/{len(tests)} passed")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/project-map/test_generate.py

@@ -30,7 +30,12 @@ def load_generate(project_root: Path):
         spec.loader.exec_module(mod)
     finally:
         sys.argv = argv
-    mod.PROJECT_ROOT = project_root
+    # configure_paths(), not `mod.PROJECT_ROOT = ...`: generate.py binds MAP_DIR,
+    # SECTIONS_DIR, CHECKSUMS, LEARNED_VOC and GLOSSARY at import time from
+    # __file__, and rebinds them only here. Setting PROJECT_ROOT alone left every
+    # output path aimed at the real repo, so the suite overwrote its own
+    # glossary.json with fixture data and still passed (#18).
+    mod.configure_paths(project_root)
     return mod
 
 
@@ -232,7 +237,11 @@ def test_glossary_survives_foreign_project_root(g):
     PROJECT_ROOT when --project-root points elsewhere. That combination raised
     ValueError from relative_to()."""
     import json
-    g.write_glossary([], g.load_stack())  # PROJECT_ROOT is the temp fixture here
+    # Recreate the mismatch explicitly. It used to arrive for free because the
+    # loader left SECTIONS_DIR pointing at the script dir — the same leak that
+    # let this test write into the real repo (#18).
+    g.SECTIONS_DIR = HERE / "sections"
+    g.write_glossary([], g.load_stack())
     data = json.loads(g.GLOSSARY.read_text())
     assert data["source"].endswith("01-vocabulary.md"), data["source"]
 

package/.claude/project-map/test_mine_sessions.py

@@ -28,7 +28,10 @@ def load_miner(project_root: Path, cursor_dir: Path):
         spec.loader.exec_module(mod)
     finally:
         sys.argv = argv
-    mod.PROJECT_ROOT = project_root
+    # configure_paths(), not `mod.PROJECT_ROOT = ...` — see the same note in
+    # test_generate.py (#18). LEARNED_VOC is bound at import time from __file__,
+    # so assigning PROJECT_ROOT alone leaves it aimed at the real repo.
+    mod.configure_paths(project_root)
     mod.MINE_CURSOR = cursor_dir / ".mine-cursor.json"
     return mod
 

package/.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for babel-fish - Codebase introspection and vocabulary translation for AI coding assistants",
-    "version": "2.4.2"
+    "version": "2.5.0"
   },
   "plugins": [
     {
       "name": "babel-fish",
       "description": "Auto-generates a project map, vocabulary translation layer, and developer skill for any codebase. Introspects routes, models, services, features, infrastructure, and session history to give Claude instant full-stack context. Self-updates via pre-commit hook.",
-      "version": "2.4.2",
+      "version": "2.5.0",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "babel-fish",
   "description": "Auto-generates a project map, vocabulary translation layer, and developer skill for any codebase. Introspects routes, models, services, features, infrastructure, and session history to give Claude instant full-stack context. Self-updates via pre-commit hook.",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "author": {
     "name": "TheGlitchKing",
     "email": "theglitchking@users.noreply.github.com"

package/.githooks/pre-commit

@@ -21,3 +21,20 @@ if echo "$STAGED_FILES" | grep -qE "$EXTENSIONS_PATTERN" 2>/dev/null; then
     fi
 fi
 # ── End Codebase Mapper ──────────────────────────────────────────────────────
+
+# ── Context Check: auto-loaded instructions stay in budget, pointers resolve ──
+if git diff --cached --name-only 2>/dev/null | grep -qE '^(\.claude/)?CLAUDE(\.local)?\.md$|^\.claude/rules/.*\.md$'; then
+    CHECK_SCRIPT=".claude/project-map/context-check.py"
+    if [ -f "$CHECK_SCRIPT" ]; then
+        PYTHON=""
+        if [ -f ".venv/bin/python3" ]; then PYTHON=".venv/bin/python3"
+        elif command -v python3 &>/dev/null; then PYTHON="python3"
+        elif command -v python &>/dev/null; then PYTHON="python"
+        fi
+        if [ -n "$PYTHON" ] && ! $PYTHON "$CHECK_SCRIPT"; then
+            echo "[context-check] Commit blocked. Fix the FAIL lines above, or add flags (--budget N, --map-style) to this call in .githooks/pre-commit." >&2
+            exit 1
+        fi
+    fi
+fi
+# ── End Context Check ────────────────────────────────────────────────────────

package/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.5.0] - 2026-09-25
+
+### Added
+
+- **`context-check.py` — keeps auto-loaded context small and its pointers live**
+  ([#20](https://github.com/TheGlitchKing/babel-fish/issues/20)). `CLAUDE.md` and
+  every `.claude/rules/*.md` load into every session; past Claude Code's 150k-char
+  limit rules stop binding, and nothing reports it. glitch-stock-trading-rig had
+  reached 225.6k before forking `generate.py` to enforce a budget.
+
+  The new script checks three things. **Budget:** total chars under `--budget`
+  (default 60,000). **Pointers:** every `` → `path` ``, backticked `.documentation/`
+  path and relative markdown link resolves. hewtd link-checks only inside
+  `.documentation/`, so a renamed doc used to break a rule's pointer silently.
+  **Rule lines** (opt-in, `--map-style`): each rule bullet reads
+  `` - ALWAYS|NEVER <rule> — <why> → `doc` ``. That form is one repo's convention,
+  and the hook ships to every install, so it is off by default.
+
+  The pre-commit hook runs it when `CLAUDE.md` or `.claude/rules/` is staged, and a
+  failure blocks the commit. It is a separate script rather than part of
+  `generate.py`: the hook runs `generate.py` only for code changes, `.claude/` is
+  outside the watch set, and the hook discards `generate.py`'s errors. The block
+  has its own marker, so re-running `bash .claude/install.sh` adds it to hooks
+  installed by older versions.
+
+  Registry drift (item 4 of #20) stays in the downstream fork; babel-fish has no
+  tool registry.
+
+### Fixed
+
+- **This repo's pre-commit hook never ran.** Both `.githooks/` files were
+  committed `100644`, and git skips a non-executable hook without a word, so no
+  clone ever regenerated its map on commit. Both are `100755` now, and
+  `test_hooks_are_committed_executable` holds them there.
+
+  57 tests pass across four suites. Each context check was mutation-tested: breaking
+  it fails at least one test. A fresh install and an upgrade over a pre-2.5.0 hook
+  were both run end to end.
+
+## [2.4.3] - 2026-09-05
+
+### Fixed
+
+- **`npm test` overwrote the map it was testing, and still reported every test
+  passing** ([#18](https://github.com/TheGlitchKing/babel-fish/issues/18)). A run
+  rewrote the working tree's `.claude/project-map/glossary.json` with fixture
+  data — 10 entries down to 1 — and printed a clean pass. Caught only by
+  diffing before a commit during the 2.4.2 release.
+
+  `generate.py` and `mine-sessions.py` bind `MAP_DIR`, `SECTIONS_DIR`,
+  `CHECKSUMS`, `LEARNED_VOC` and `GLOSSARY` at import time from `__file__`, and
+  rebind them only inside `configure_paths()`. Both test loaders assigned
+  `mod.PROJECT_ROOT` and stopped there, so every output path stayed aimed at the
+  real repo while the tests believed they were in a temp fixture; whichever test
+  called `write_glossary()` last won. This is the [#15](https://github.com/TheGlitchKing/babel-fish/issues/15)
+  defect class — writes escaping to the script's own directory — surviving in
+  the harness after being fixed in the scripts themselves.
+
+  Both loaders now call `configure_paths(fixture_root)`.
+  `test_glossary_survives_foreign_project_root` depended on the leak (it needs
+  `SECTIONS_DIR` outside `PROJECT_ROOT`, which used to arrive for free) and now
+  recreates that mismatch explicitly, so it still covers the `ValueError` from
+  `relative_to()` without writing outside its fixture — verified by mutation:
+  deleting the `try`/`except` in `_relative_source()` fails that test and only
+  that one. `test_grader.py` is deliberately untouched; its loader assigns a map
+  dir rather than a project root.
+
+  38 tests pass across the three suites, and a full run now leaves the tree
+  clean.
+
 ## [2.4.2] - 2026-09-05
 
 ### Fixed

package/README.md

@@ -146,7 +146,7 @@ See [CHANGELOG.md](./CHANGELOG.md) for the full 2.0.0 release notes, breaking-ch
 2. Detects your stack (language, framework, database, ORM, auth, infra)
 3. Runs `generate.py` → grades with `grader.py` (iterates up to 3× until 90%+ quality)
 4. Renders your developer skill and rules files
-5. Installs the pre-commit hook (auto-regenerates map on source file changes)
+5. Installs the pre-commit hook (auto-regenerates map on source file changes; checks auto-loaded context when `CLAUDE.md` or `.claude/rules/` changes)
 6. Updates `CLAUDE.md` with a project map pointer
 7. Prints a full quality report
 
@@ -227,6 +227,21 @@ Entries follow a simple format: symptom → cause → fix. This is the anti-drif
 
 ---
 
+## Auto-loaded Context Check *(2.5.0+)*
+
+Everything in `CLAUDE.md` and `.claude/rules/` loads into every session, and past Claude Code's 150k-char limit rules stop binding silently. When those files are staged, the pre-commit hook runs `context-check.py` and blocks the commit if:
+
+- the total exceeds the budget (default 60,000 chars), or
+- a pointer names a file that doesn't exist. hewtd only link-checks inside `.documentation/`, so a renamed doc breaks a rule's pointer unnoticed.
+
+Opt in to `--map-style` to also require every rule bullet to read `` - ALWAYS|NEVER <rule> — <why> → `doc` ``. See [auto-loaded context check](./.documentation/standards/auto-loaded-context-check.md).
+
+```bash
+python .claude/project-map/context-check.py --budget 80000 --map-style
+```
+
+---
+
 ## File Structure
 
 ```
@@ -235,6 +250,7 @@ Entries follow a simple format: symptom → cause → fix. This is the anti-drif
 │   ├── generate.py              # Introspection script
 │   ├── grader.py                # Quality grader
 │   ├── mine-sessions.py         # Session vocabulary miner
+│   ├── context-check.py         # Budget + pointer check for auto-loaded files
 │   ├── PROJECT_MAP.md           # TOC + quick routing guide
 │   ├── sections/                # 19 focused section files
 │   ├── reports/                 # Install and iteration reports
@@ -247,7 +263,7 @@ Entries follow a simple format: symptom → cause → fix. This is the anti-drif
     └── <project>-developer-skill/
         └── SKILL.md
 .githooks/
-├── pre-commit                   # Auto-regenerates map on commit
+├── pre-commit                   # Regenerates map; runs the context check
 └── install.sh                   # Register hooks: bash .githooks/install.sh
 ```
 
@@ -281,6 +297,7 @@ Entries follow a simple format: symptom → cause → fix. This is the anti-drif
 | `python .claude/project-map/generate.py --force` | Force-regenerate project map |
 | `python .claude/project-map/grader.py` | Grade map quality (0–100%) |
 | `python .claude/project-map/mine-sessions.py` | Mine session vocabulary |
+| `python .claude/project-map/context-check.py` | Check auto-loaded context: budget, pointers |
 | `bash .githooks/install.sh` | (Re)install git hooks |
 | `bash .claude/install.sh` | Re-run full plugin installer |
 

package/checksums.json

@@ -1,4 +1,4 @@
 {
-  "install_sh": "565ad35c264c8e683ade82f441ab5a9f8feb3921e0b4180623bb038b23452518",
+  "install_sh": "eb3a15ddeaf969b3b0e609fe6cde7792efd7c60ef2305d8593cb761fe812c1aa",
   "note": "SHA256 of .claude/install.sh \u2014 verified by the remote installer before execution"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/babel-fish",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "Gives your AI coding assistant instant, accurate knowledge of every route, model, service, feature, and infrastructure element in your codebase.",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "postinstall": "node scripts/link-skills.js",
-    "test": "python3 .claude/project-map/test_generate.py && python3 .claude/project-map/test_mine_sessions.py && python3 .claude/project-map/test_grader.py"
+    "test": "python3 .claude/project-map/test_generate.py && python3 .claude/project-map/test_mine_sessions.py && python3 .claude/project-map/test_grader.py && python3 .claude/project-map/test_context_check.py"
   },
   "files": [
     "bin/",
@@ -22,9 +22,11 @@
     ".claude/project-map/generate.py",
     ".claude/project-map/grader.py",
     ".claude/project-map/mine-sessions.py",
+    ".claude/project-map/context-check.py",
     ".claude/project-map/test_generate.py",
     ".claude/project-map/test_mine_sessions.py",
     ".claude/project-map/test_grader.py",
+    ".claude/project-map/test_context_check.py",
     ".githooks/",
     "skills/",
     "install.sh",