wikifier 4.5.3__tar.gz → 4.5.5__tar.gz

{wikifier-4.5.3/wikifier.egg-info → wikifier-4.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.5.3
+Version: 4.5.5
 Summary: Zero-dependency agent-to-agent codebase wiki for LLMs and AI agents. Autonomously maintained via record-change and mark-green for token-efficient lookup of files, dependencies, health, and summaries — across tiny scripts to 50k+ monorepos. Optional MCP server with rich tools for agents.
 Author-email: Aron Amos <aron@example.com>
 Maintainer: Aron Amos
@@ -40,7 +40,19 @@ Dynamic: license-file
 
 Wikifier is an **agent-to-agent** tool: it builds a living map of a project (health matrix, dependency graph, short file summaries) and agents keep that map current as they work. Humans can peek via a small dashboard; the product is the agent loop, not a general docs site or IDE.
 
-Works from small scripts to large monorepos. **Deep import maps** cover **Python + JavaScript/TypeScript** (barrels, cycles, incremental updates). Other languages can still use health/journal/watch; they won’t get full import graphs until a parser exists.
+Works from small scripts to large monorepos. **Deep import/include maps** (zero-dep regex parsers):
+
+| Language | Extensions | Notes |
+|----------|------------|--------|
+| Python | `.py` | full ACS/CDIA path |
+| JavaScript / TypeScript | `.js` `.ts` `.jsx` `.tsx` | barrels (BREE), dynamic/CDIA |
+| Rust | `.rs` | `use` / `mod` / `extern crate` |
+| Go | `.go` | `import` / import blocks |
+| C / C++ | `.c` `.h` `.cpp` `.cc` `.cxx` `.hpp` `.hh` | `#include` (local + system) |
+| C# | `.cs` | `using` namespaces |
+| Java | `.java` | `import` / `import static` |
+
+Health/journal still work for any monitored path. Parsers are **pragmatic regex** (not full cargo/`go.mod`/classpath/`-I` resolution). Prefer **lean `monitored_paths.txt`** on huge monorepos; raise dirty cap with `WIKIFIER_CHECK_CHANGES_MAX` (default 2000) only when needed.
 
 ## Why
 
@@ -90,7 +102,7 @@ MCP **Core 6** (start every session): `get_project_status`, `check_changes`, `ge
 
 ## What you get
 
-- **Import analysis** — Python + JS/TS (ESM, CommonJS, dynamic imports, path aliases, package exports); per-edge confidence; name-routed barrel expansion (precise leaves, not edge explosion)
+- **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust, Go, C/C++ includes, C# usings; per-edge confidence; name-routed barrel expansion for TS/JS
 - **Incremental pipeline** — pure-Python `update-maps`: dirty parse → import cache → reverse deps → cycles → `library.md`
 - **Selective agent work** — health + suggest bias to 🔴/🟡 only; ACS *actionable* low-conf excludes stdlib/external noise
 - **Scale** — reverse index + barrel invalidation so one edit doesn’t re-scan the monorepo

{wikifier-4.5.3 → wikifier-4.5.5}/README.md

@@ -8,7 +8,19 @@
 
 Wikifier is an **agent-to-agent** tool: it builds a living map of a project (health matrix, dependency graph, short file summaries) and agents keep that map current as they work. Humans can peek via a small dashboard; the product is the agent loop, not a general docs site or IDE.
 
-Works from small scripts to large monorepos. **Deep import maps** cover **Python + JavaScript/TypeScript** (barrels, cycles, incremental updates). Other languages can still use health/journal/watch; they won’t get full import graphs until a parser exists.
+Works from small scripts to large monorepos. **Deep import/include maps** (zero-dep regex parsers):
+
+| Language | Extensions | Notes |
+|----------|------------|--------|
+| Python | `.py` | full ACS/CDIA path |
+| JavaScript / TypeScript | `.js` `.ts` `.jsx` `.tsx` | barrels (BREE), dynamic/CDIA |
+| Rust | `.rs` | `use` / `mod` / `extern crate` |
+| Go | `.go` | `import` / import blocks |
+| C / C++ | `.c` `.h` `.cpp` `.cc` `.cxx` `.hpp` `.hh` | `#include` (local + system) |
+| C# | `.cs` | `using` namespaces |
+| Java | `.java` | `import` / `import static` |
+
+Health/journal still work for any monitored path. Parsers are **pragmatic regex** (not full cargo/`go.mod`/classpath/`-I` resolution). Prefer **lean `monitored_paths.txt`** on huge monorepos; raise dirty cap with `WIKIFIER_CHECK_CHANGES_MAX` (default 2000) only when needed.
 
 ## Why
 
@@ -58,7 +70,7 @@ MCP **Core 6** (start every session): `get_project_status`, `check_changes`, `ge
 
 ## What you get
 
-- **Import analysis** — Python + JS/TS (ESM, CommonJS, dynamic imports, path aliases, package exports); per-edge confidence; name-routed barrel expansion (precise leaves, not edge explosion)
+- **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust, Go, C/C++ includes, C# usings; per-edge confidence; name-routed barrel expansion for TS/JS
 - **Incremental pipeline** — pure-Python `update-maps`: dirty parse → import cache → reverse deps → cycles → `library.md`
 - **Selective agent work** — health + suggest bias to 🔴/🟡 only; ACS *actionable* low-conf excludes stdlib/external noise
 - **Scale** — reverse index + barrel invalidation so one edit doesn’t re-scan the monorepo

{wikifier-4.5.3 → wikifier-4.5.5}/skills/run.md

@@ -12,7 +12,8 @@
 - **First-run:** `init` → `update-maps` → `health --summary` → `suggest_next_actions`. Map is automatic; wiki *prose* is agent-filled over time.
 - **Steady-state selective work:** only 🔴/🟡 (never re-wiki 🟢 unless required). ACS suggestions use `actionable_low_conf_edges` (stdlib/external bare demoted).
 - **Deletions:** `record-deletion` + check-changes ghost detection (missing paths → Red DELETED).
-- **Languages:** deep import maps = Python + JS/TS. journal/pending = audit queue, not Jira.
+- **Languages:** deep import maps = Python, JS/TS, Rust, Go, C/C++, C#, Java (regex; not full toolchain resolution). journal/pending = audit queue, not Jira.
+- **Huge monorepos:** lean `monitored_paths.txt` (package roots, not bare `.`). Optional `WIKIFIER_CHECK_CHANGES_MAX` (default 2000). `update-maps` seeds Yellow health stubs for newly parsed files (map-first).
 - **Monitor:** optional background `monitor`/`daemon` for mtime heartbeat; agents still own wiki/mark-green.
 - Health module: use `importlib.import_module("wikifier.health")` or `wikifier.health_module` — `from wikifier import health` is the *function*.
 

{wikifier-4.5.3 → wikifier-4.5.5}/tests/test_gap_closure.py

@@ -123,6 +123,72 @@ class TestGhostAndDeletionG7(TempProjectTestCase):
         self.assertIn("🔴", entries["gone.py"]["status"])
         self.assertIn("DELETED", entries["gone.py"]["reason"])
 
+    def test_record_deletion_rejects_flag_paths(self):
+        res = cli.record_deletion("--help", "oops", project_root=self.root)
+        self.assertFalse(res.get("success"))
+        self.assertIn("flag", (res.get("error") or "").lower())
+
+
+class TestPendingAndPollutionHygiene(TempProjectTestCase):
+    def test_pending_empty_marker_not_counted_and_no_dual_state(self):
+        health_mod = importlib.import_module("wikifier.health")
+        # Dual-state pollution (historical bug): empty marker + real items
+        p = self.root / "pending_updates.md"
+        p.write_text(
+            "# Pending Updates\n\n(no active items)\n- src/a.py: review\n",
+            encoding="utf-8",
+        )
+        self.assertEqual(health_mod.count_pending(self.root), 1)
+        # Normalize via remove of the only item → empty marker only
+        health_mod.remove_from_pending(self.root, "src/a.py")
+        text = p.read_text(encoding="utf-8")
+        self.assertIn("no pending", text.lower())
+        self.assertNotIn("- src/a.py", text)
+        self.assertEqual(health_mod.count_pending(self.root), 0)
+        # Add clears empty marker
+        health_mod.add_to_pending(self.root, "src/b.py", "need wiki")
+        text2 = p.read_text(encoding="utf-8")
+        self.assertIn("- src/b.py:", text2)
+        self.assertNotIn("no pending", text2.lower())
+        self.assertNotIn("no active", text2.lower())
+        self.assertEqual(health_mod.count_pending(self.root), 1)
+        summary = health_mod.get_summary(self.root)
+        self.assertEqual(summary["pending_updates"], 1)
+
+    def test_superseded_and_flag_deleted_keys_pruned(self):
+        health_mod = importlib.import_module("wikifier.health")
+        # Inject pollution keys directly then save
+        data = {
+            "version": 2,
+            "last_updated": "2026-01-01",
+            "entries": {
+                "M5.3 Cycle1 evidence append: 3 subs spawned": {
+                    "status": "🔴 Red",
+                    "reason": "DELETED — Historical early M5.3 launch note",
+                    "last_updated": "2026-01-01",
+                },
+                "--help": {
+                    "status": "🔴 Red",
+                    "reason": "DELETED — removed",
+                    "last_updated": "2026-01-01",
+                },
+                "real.py": {
+                    "status": "🟢 Green",
+                    "reason": "ok",
+                    "last_updated": "2026-01-01",
+                },
+            },
+        }
+        health_mod.save_health(self.root, data)
+        entries = health_mod.load_health(self.root)["entries"]
+        self.assertNotIn("M5.3 Cycle1 evidence append: 3 subs spawned", entries)
+        self.assertNotIn("--help", entries)
+        self.assertIn("real.py", entries)
+        # Real path DELETED audit is kept
+        health_mod.upsert_entry(self.root, "gone_real.py", "🔴 Red", "DELETED — intentional")
+        entries2 = health_mod.load_health(self.root)["entries"]
+        self.assertIn("gone_real.py", entries2)
+
 
 if __name__ == "__main__":
     unittest.main()

wikifier-4.5.5/tests/test_multi_lang_parsers.py

@@ -0,0 +1,104 @@
+"""Multi-language parser smoke tests (Rust, Go, C/C++, C#)."""
+
+import unittest
+from pathlib import Path
+
+from tests._base import TempProjectTestCase
+
+from wikifier.parsers import rust, go_lang, c_cpp, csharp, java
+from wikifier.cli import run_full_update, check_changes
+import importlib
+import os
+
+
+class TestRustParser(TempProjectTestCase):
+    def test_use_and_mod(self):
+        self.write("lib.rs", "mod foo;\nuse crate::foo::Bar;\nuse std::io;\n")
+        self.write("foo.rs", "pub struct Bar;\n")
+        edges = rust.parse_rust_imports(str(self.root / "lib.rs"))
+        kinds = {e.get("statement_type") for e in edges}
+        self.assertIn("mod", kinds)
+        self.assertIn("use", kinds)
+        mod_e = next(e for e in edges if e.get("statement_type") == "mod")
+        self.assertTrue(mod_e.get("resolved_path") and mod_e["resolved_path"].endswith("foo.rs"))
+
+
+class TestGoParser(TempProjectTestCase):
+    def test_import_block(self):
+        self.write("main.go", 'package main\nimport (\n\t"fmt"\n\t"os"\n)\n')
+        edges = go_lang.parse_go_imports(str(self.root / "main.go"))
+        mods = {e["raw_module"] for e in edges}
+        self.assertIn("fmt", mods)
+        self.assertIn("os", mods)
+
+
+class TestCParser(TempProjectTestCase):
+    def test_local_and_system_include(self):
+        self.write("a.c", '#include "b.h"\n#include <stdio.h>\n')
+        self.write("b.h", "int x;\n")
+        edges = c_cpp.parse_c_cpp_imports(str(self.root / "a.c"))
+        self.assertGreaterEqual(len(edges), 2)
+        local = next(e for e in edges if e["raw_module"] == "b.h")
+        self.assertTrue(local.get("resolved_path"))
+        sys_e = next(e for e in edges if e["raw_module"] == "stdio.h")
+        self.assertEqual((sys_e.get("diagnostic") or {}).get("category"), "external_or_bare")
+
+
+class TestCsharpParser(TempProjectTestCase):
+    def test_using(self):
+        self.write("A.cs", "using System;\nusing System.IO;\nusing MyApp.Core;\n")
+        edges = csharp.parse_csharp_imports(str(self.root / "A.cs"))
+        mods = {e["raw_module"] for e in edges}
+        self.assertIn("System", mods)
+        self.assertIn("MyApp.Core", mods)
+
+
+class TestJavaParser(TempProjectTestCase):
+    def test_import(self):
+        self.write("A.java", "import java.util.List;\nimport com.foo.Bar;\n")
+        edges = java.parse_java_imports(str(self.root / "A.java"))
+        mods = {e["raw_module"] for e in edges}
+        self.assertIn("java.util.List", mods)
+        self.assertIn("com.foo.Bar", mods)
+
+
+class TestPipelineMultiLang(TempProjectTestCase):
+    def test_run_full_update_parses_all_langs(self):
+        self.write("a.py", "import os\n")
+        self.write("b.rs", "mod x;\n")
+        self.write("x.rs", "pub fn f() {}\n")
+        self.write("c.go", 'package p\nimport "fmt"\n')
+        self.write("d.c", '#include "e.h"\n')
+        self.write("e.h", "int y;\n")
+        self.write("f.cs", "using System;\n")
+        self.write("G.java", "import java.io.File;\n")
+        res = run_full_update(root=self.root, force_full=True, verbose=False)
+        self.assertTrue(res.get("success"))
+        self.assertGreaterEqual(res.get("files_parsed", 0), 5)
+        self.assertIn("languages_parsed", res)
+        self.assertGreaterEqual(res.get("health_stubs_seeded", 0), 1)
+        health_mod = importlib.import_module("wikifier.health")
+        entries = health_mod.load_health(self.root).get("entries") or {}
+        self.assertTrue(any(k.endswith((".py", ".rs", ".java", ".cs", ".go", ".c")) for k in entries))
+
+    def test_check_changes_cap_env(self):
+        self.write("monitored_paths.txt", ".\n")
+        for i in range(5):
+            self.write(f"f{i}.py", f"x={i}\n")
+        run_full_update(root=self.root, force_full=True, verbose=False)
+        import time
+        time.sleep(0.05)
+        for i in range(5):
+            (self.root / f"f{i}.py").write_text(f"x={i + 1}\n")
+        os.environ["WIKIFIER_CHECK_CHANGES_MAX"] = "2"
+        try:
+            r = check_changes(project_root=self.root)
+            self.assertTrue(r.get("success"))
+            self.assertLessEqual(r.get("changes_detected", 0), 2)
+            self.assertTrue(r.get("dirty_truncated") or (r.get("dirty_total") or 0) <= 2)
+        finally:
+            os.environ.pop("WIKIFIER_CHECK_CHANGES_MAX", None)
+
+
+if __name__ == "__main__":
+    unittest.main()

{wikifier-4.5.3 → wikifier-4.5.5}/wikifier/__init__.py

@@ -71,4 +71,4 @@ from .contracts import (
     compute_acs_confidence,
 )
 
-__version__ = "4.5.3"
+__version__ = "4.5.5"

{wikifier-4.5.3 → wikifier-4.5.5}/wikifier/cli.py

@@ -174,7 +174,13 @@ def _collect_candidate_source_files(root: Path) -> List[Path]:
         ".pnpm", ".yarn", ".store", "store", "virtual-store", ".pnp",
         ".pnp.cjs", "node_modules/.pnpm", "node_modules/.yarn"
     }
-    exts = (".py", ".js", ".ts", ".jsx", ".tsx")
+    # Deep-map languages (agent multi-lang dogfood)
+    exts = (
+        ".py", ".js", ".ts", ".jsx", ".tsx",
+        ".rs", ".go",
+        ".c", ".h", ".cpp", ".cc", ".cxx", ".hpp", ".hh",
+        ".cs", ".java",
+    )
     try:
         root = Path(root).resolve()
     except Exception:
@@ -499,6 +505,26 @@ def run_full_update(
         # === 3. Parse every dirty file (in-process, BREE batched) ===
         from .parsers import javascript as js_parser
         from .parsers import python as py_parser
+        try:
+            from .parsers import rust as rust_parser
+        except Exception:
+            rust_parser = None
+        try:
+            from .parsers import go_lang as go_parser
+        except Exception:
+            go_parser = None
+        try:
+            from .parsers import c_cpp as c_cpp_parser
+        except Exception:
+            c_cpp_parser = None
+        try:
+            from .parsers import csharp as csharp_parser
+        except Exception:
+            csharp_parser = None
+        try:
+            from .parsers import java as java_parser
+        except Exception:
+            java_parser = None
         try:
             from .parsers import bree as bree_mod
         except Exception:
@@ -521,10 +547,28 @@ def run_full_update(
             except Exception:
                 return None
 
+        def _parse_file(fstr: str, low: str):
+            if low.endswith((".js", ".ts", ".jsx", ".tsx")):
+                return js_parser.parse_javascript_imports(fstr) or []
+            if low.endswith(".py"):
+                return py_parser.parse_python_imports(fstr) or []
+            if low.endswith(".rs") and rust_parser is not None:
+                return rust_parser.parse_rust_imports(fstr) or []
+            if low.endswith(".go") and go_parser is not None:
+                return go_parser.parse_go_imports(fstr) or []
+            if low.endswith((".c", ".h", ".cpp", ".cc", ".cxx", ".hpp", ".hh")) and c_cpp_parser is not None:
+                return c_cpp_parser.parse_c_cpp_imports(fstr) or []
+            if low.endswith(".cs") and csharp_parser is not None:
+                return csharp_parser.parse_csharp_imports(fstr) or []
+            if low.endswith(".java") and java_parser is not None:
+                return java_parser.parse_java_imports(fstr) or []
+            return None
+
         new_entries: Dict[str, Dict[str, Any]] = {}
         edges_total = 0
         parsed_count = 0
         parse_errors: List[Dict[str, str]] = []
+        lang_counts: Dict[str, int] = {}
 
         if bree_mod is not None:
             try:
@@ -536,11 +580,8 @@ def run_full_update(
                 fstr = str(f)
                 low = fstr.lower()
                 try:
-                    if low.endswith((".js", ".ts", ".jsx", ".tsx")):
-                        edges = js_parser.parse_javascript_imports(fstr) or []
-                    elif low.endswith(".py"):
-                        edges = py_parser.parse_python_imports(fstr) or []
-                    else:
+                    edges = _parse_file(fstr, low)
+                    if edges is None:
                         continue
                 except Exception as pe:
                     parse_errors.append({"file": fstr, "error": f"{type(pe).__name__}: {pe}"})
@@ -557,6 +598,8 @@ def run_full_update(
                 }
                 parsed_count += 1
                 edges_total += len(pairs)
+                ext = Path(low).suffix.lower() or "unknown"
+                lang_counts[ext] = lang_counts.get(ext, 0) + 1
                 if verbose and parsed_count % 200 == 0:
                     print(f"[run_full_update] parsed {parsed_count}/{len(dirty)}")
         finally:
@@ -568,10 +611,28 @@ def run_full_update(
 
         result["files_parsed"] = parsed_count
         result["edges_persisted"] = edges_total
+        result["languages_parsed"] = lang_counts
         if parse_errors:
             result["parse_errors"] = parse_errors[:10]
             result["parse_error_count"] = len(parse_errors)
 
+        # Seed health stubs for newly parsed files (map-first wiki: agents fill prose later)
+        health_seeded = 0
+        if _health_mod is not None and new_entries:
+            try:
+                existing = (_health_mod.load_health(root) or {}).get("entries") or {}
+                for rel in new_entries:
+                    if rel in existing:
+                        continue
+                    _health_mod.upsert_entry(
+                        root, rel, "🟡 Yellow",
+                        "Initial stub — parsed into map; agent should wiki + mark-green when editing"
+                    )
+                    health_seeded += 1
+            except Exception:
+                health_seeded = 0
+        result["health_stubs_seeded"] = health_seeded
+
         # === 4. Persist (single save; reload first to pick up the barrel flush) ===
         cache = ic.load_cache(root) or {}
         cache.update(new_entries)
@@ -744,16 +805,40 @@ def main():
                 if res.get("message"):
                     print(res["message"])
                 return 0 if res.get("success", True) else 1
-            if _cmd0 == "record-change" and len(_args) >= 2:
+            if _cmd0 == "record-change":
+                if not _args or _args[0] in ("--help", "-h", "help"):
+                    print('Usage: wikifier record-change <file> "<reason>"')
+                    return 0
+                if _args[0].startswith("-") or len(_args) < 2:
+                    print('Usage: wikifier record-change <file> "<reason>"', file=sys.stderr)
+                    return 1
                 res = record_change(_args[0], " ".join(_args[1:]), project_root=project_root)
                 print(res.get("message") or res)
                 return 0 if res.get("success") else 1
-            if _cmd0 == "mark-green" and len(_args) >= 1:
+            if _cmd0 == "mark-green":
+                if not _args or _args[0] in ("--help", "-h", "help"):
+                    print("Usage: wikifier mark-green <file> [reason]")
+                    return 0
+                if _args[0].startswith("-"):
+                    print("Usage: wikifier mark-green <file> [reason]", file=sys.stderr)
+                    return 1
                 reason = " ".join(_args[1:]) if len(_args) > 1 else ""
                 res = mark_green(_args[0], reason, project_root=project_root)
                 print(res.get("message") or res)
                 return 0 if res.get("success") else 1
-            if _cmd0 == "record-deletion" and len(_args) >= 1:
+            if _cmd0 == "record-deletion":
+                # Guard: `record-deletion --help` must not treat `--help` as a file path
+                # (that polluted health with a 🔴 DELETED "--help" key).
+                if not _args or _args[0] in ("--help", "-h", "help"):
+                    print('Usage: wikifier record-deletion <file> "<reason>"')
+                    return 0
+                if _args[0].startswith("-"):
+                    print(
+                        'Usage: wikifier record-deletion <file> "<reason>"\n'
+                        "  <file> must be a project path, not a flag.",
+                        file=sys.stderr,
+                    )
+                    return 1
                 reason = " ".join(_args[1:]) if len(_args) > 1 else "removed"
                 res = record_deletion(_args[0], reason, project_root=project_root)
                 print(res.get("message") or res)
@@ -978,8 +1063,14 @@ def _ensure_journal_entry(root: Path, action: str, file: str, reason: str) -> No
 
 
 def _add_to_pending(root: Path, file: str, msg: str) -> None:
-    """Pure-Py pending_updates.md appender (skeleton, matches sh add_pending)."""
+    """Append to pending_updates.md via health helpers (normalized empty/items)."""
     try:
+        if _health_mod is not None and hasattr(_health_mod, "add_to_pending"):
+            # Caller may already hold project lock (re-entrant).
+            _health_mod._do_add_to_pending(root, file, msg) if hasattr(
+                _health_mod, "_do_add_to_pending"
+            ) else _health_mod.add_to_pending(root, file, msg)
+            return
         p = root / "pending_updates.md"
         line = f"- {file}: {msg}\n"
         with open(p, "a", encoding="utf-8") as f:
@@ -989,8 +1080,14 @@ def _add_to_pending(root: Path, file: str, msg: str) -> None:
 
 
 def _remove_from_pending(root: Path, file: str) -> None:
-    """Best-effort removal (used by mark_green skeleton)."""
+    """Best-effort removal (used by mark_green). Prefers health normalizer."""
     try:
+        if _health_mod is not None and hasattr(_health_mod, "_do_remove_from_pending"):
+            _health_mod._do_remove_from_pending(root, file)
+            return
+        if _health_mod is not None and hasattr(_health_mod, "remove_from_pending"):
+            _health_mod.remove_from_pending(root, file)
+            return
         p = root / "pending_updates.md"
         if p.exists():
             lines = [ln for ln in p.read_text(encoding="utf-8").splitlines() if file not in ln]
@@ -1079,11 +1176,28 @@ def check_changes(project_root: Optional[Union[str, Path]] = None) -> Dict[str,
                 except Exception:
                     pass
 
+            # Cap is configurable: WIKIFIER_CHECK_CHANGES_MAX (default 2000; was hard 200).
+            # Huge monorepos with monitored_paths=. can still thrash — prefer lean monitored paths.
+            try:
+                max_dirty = int(os.environ.get("WIKIFIER_CHECK_CHANGES_MAX", "2000") or "2000")
+            except ValueError:
+                max_dirty = 2000
+            max_dirty = max(1, min(max_dirty, 50000))
+            try:
+                max_ghosts = int(os.environ.get("WIKIFIER_CHECK_CHANGES_GHOST_MAX", "200") or "200")
+            except ValueError:
+                max_ghosts = 200
+            max_ghosts = max(1, min(max_ghosts, 10000))
+
+            dirty_list = list(dirty or [])
+            dirty_truncated = len(dirty_list) > max_dirty
+            dirty_batch = dirty_list[:max_dirty]
+
             changed_count = 0
             ghosts_marked = 0
             if _health_mod is not None:
                 root_res = root.resolve()
-                for p in (dirty or [])[:200]:  # bounded for skeleton safety at scale
+                for p in dirty_batch:
                     try:
                         pr = Path(p).resolve()
                         if not str(pr).startswith(str(root_res)):
@@ -1102,7 +1216,8 @@ def check_changes(project_root: Optional[Union[str, Path]] = None) -> Dict[str,
                 # G7: surface ghost health entries (tracked path missing on disk, not already DELETED)
                 try:
                     if hasattr(_health_mod, "find_ghost_entries"):
-                        for g in (_health_mod.find_ghost_entries(root) or [])[:50]:
+                        ghosts_all = _health_mod.find_ghost_entries(root) or []
+                        for g in ghosts_all[:max_ghosts]:
                             _health_mod.upsert_entry(
                                 root, g, "🔴 Red",
                                 "DELETED — path missing on disk (check_changes ghost detection)"
@@ -1115,15 +1230,24 @@ def check_changes(project_root: Optional[Union[str, Path]] = None) -> Dict[str,
                 except Exception:
                     pass
 
+            msg = (
+                f"Python-primary check_changes complete: {changed_count} files marked/updated"
+                + (f", {ghosts_marked} ghost(s) marked Red" if ghosts_marked else "")
+                + ". Health + pending + journal touched."
+            )
+            if dirty_truncated:
+                msg += (
+                    f" Note: dirty set truncated to {max_dirty} of {len(dirty_list)} "
+                    f"(set WIKIFIER_CHECK_CHANGES_MAX or lean monitored_paths.txt)."
+                )
             result.update({
                 "success": True,
                 "changes_detected": changed_count,
+                "dirty_total": len(dirty_list),
+                "dirty_truncated": dirty_truncated,
+                "max_dirty": max_dirty,
                 "ghosts_marked": ghosts_marked,
-                "message": (
-                    f"Python-primary check_changes complete: {changed_count} files marked/updated"
-                    + (f", {ghosts_marked} ghost(s) marked Red" if ghosts_marked else "")
-                    + ". Health + pending + journal touched."
-                ),
+                "message": msg,
             })
     except Exception as e:
         result["error"] = str(e)
@@ -1177,9 +1301,13 @@ def record_deletion(file: str, reason: str, project_root: Optional[Union[str, Pa
 
     G7: marks 🔴 DELETED, pending + journal, and best-effort prunes barrel cache
     references so deleted paths do not keep invalidating importers forever.
+    Rejects flag-like paths (`--help`) so CLI misuse cannot pollute health.
     """
     root = _get_effective_root(project_root)
     result: Dict[str, Any] = {"success": False, "file": file, "project_root": str(root), "action": "deletion"}
+    if not file or str(file).startswith("-") or str(file) in ("--help", "-h", "help"):
+        result["error"] = "file must be a project path, not a flag/empty string"
+        return result
     try:
         lock_ctx = (locking.file_lock(root) if locking is not None else _nullcontext())
         with lock_ctx:
@@ -1191,7 +1319,11 @@ def record_deletion(file: str, reason: str, project_root: Optional[Union[str, Pa
             except Exception:
                 rel = file
             if _health_mod is not None:
-                _health_mod.upsert_entry(root, rel, "🔴 Red", f"DELETED — {reason}")
+                # Prefer unlocked upsert when we already hold the project lock.
+                if hasattr(_health_mod, "_do_upsert_entry"):
+                    _health_mod._do_upsert_entry(root, rel, "🔴 Red", f"DELETED — {reason}")
+                else:
+                    _health_mod.upsert_entry(root, rel, "🔴 Red", f"DELETED — {reason}")
             _add_to_pending(root, rel, f"File was deleted. Consider wiki archival. {reason}")
             _ensure_journal_entry(root, "record-deletion", rel, reason or "No reason provided.")
             prune_stats: Dict[str, Any] = {}