wikifier 4.5.2__tar.gz → 4.5.4__tar.gz

{wikifier-4.5.2/wikifier.egg-info → wikifier-4.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.5.2
+Version: 4.5.4
 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,65 +40,75 @@ 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 (Python + JavaScript/TypeScript imports, barrels, cycles, incremental updates).
+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
 
 Context windows are finite. Re-reading a large file to answer “what is this and who depends on it?” wastes tokens.
 
-Wikifier keeps a small set of artifacts agents can query:
-
 | Artifact | Role |
 |----------|------|
 | `file_health.md` | 🟢 / 🟡 / 🔴 matrix — what to trust, what to fix first |
 | `library.md` | File tree, Mermaid dependency map, import tables, cycles + confidence |
-| `*.wiki.md` | Short per-file “what this is for” notes (agent-maintained) |
-| `journal/` | Semantic *why* trail from `record-change` |
+| `*.wiki.md` | Short per-file “what this is for” notes (**agent-maintained** prose) |
+| `journal/` + `pending_updates.md` | Semantic *why* trail + work queue (audit, **not** a full issue tracker) |
 
-Lookup beats re-ingest. That’s the whole idea.
+**Map first, wiki depth second:** `update-maps` builds the structural map automatically. Rich per-file wiki text is filled by agents as they work — not a free full-repo “understand everything” pass on init.
 
-## Quick start
+## First run (bootstrap the map)
 
 ```bash
 pip install wikifier            # pure Python stdlib core — no runtime deps
 pip install wikifier[mcp]       # optional Model Context Protocol (MCP) server
 
 cd /path/to/your/project
-wikifier init
-wikifier update-maps            # dependency graph + library.md
-wikifier check-changes
-wikifier health --summary
+wikifier init                   # seeds + human index.html
+wikifier update-maps            # full structural map → library.md + import cache
+wikifier health --summary       # matrix counts
+wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only
 ```
 
-Always set an explicit root for external trees:
+Always set an explicit root for external trees: `WIKIFIER_PROJECT_ROOT=/abs/path wikifier …`
 
-```bash
-WIKIFIER_PROJECT_ROOT=/abs/path/to/project wikifier check-changes
-```
-
-## Agent loop
+## Steady state (only touch what needs it)
 
 Full protocol: [`skills/run.md`](skills/run.md).
 
 ```bash
-wikifier check-changes
-# prioritize 🔴 then 🟡 in file_health.md / pending_updates.md
-# ... edit source ...
+wikifier check-changes          # yellow dirty files; red ghosts (missing paths)
+# prioritize 🔴 then 🟡 — do NOT re-wiki 🟢 Green files
+# ... edit only those sources ...
 wikifier record-change "path/file.py" "why this changed"   # required
-# ... refresh that file’s wiki summary ...
+# ... refresh that file’s wiki summary only ...
 wikifier mark-green "path/file.py"
-wikifier update-maps            # if imports/structure changed
+wikifier update-maps            # only if imports/structure changed
+# removals:
+wikifier record-deletion "path/gone.py" "why removed"
 ```
 
-`record-change` logs intent a git diff can’t reconstruct for the next agent (or human).
+MCP **Core 6** (start every session): `get_project_status`, `check_changes`, `get_files_needing_attention`, `get_file_wiki`, `suggest_next_actions`, `record_change` / `mark_green`. Intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`. Always pass `project_root=` for external trees.
 
 ## 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
-- **MCP tools** — optional server for Claude, Cursor, Cline, and other MCP clients (`get_project_status`, `get_dependencies`, `get_file_wiki`, `record_change`, …)
+- **MCP tools** — optional server for Claude, Cursor, Cline, and other MCP clients
 - **Zero core dependencies** — stdlib only; forks can add their own stack on top
+- **Agent navigability** — short **AGENT MAP** docstrings on core modules; self-tests under `tests/` (not buried in parsers)
 
 ## Performance (measured)
 
@@ -118,13 +128,16 @@ Tests: `python -m unittest discover tests` (stdlib only).
 | `wikifier check-changes` | Incremental scan → health / pending |
 | `wikifier record-change <file> "reason"` | Log *why* (required after edits) |
 | `wikifier mark-green <file>` | Mark wiki current |
+| `wikifier record-deletion <file> "reason"` | Mark removed paths 🔴 + prune barrel refs |
+| `wikifier suggest-next` | Next actions (🔴/🟡 only) |
 | `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` |
 | `wikifier health [--summary\|--json]` | Health matrix (machine-friendly flags) |
+| `wikifier validate` | Missing wiki rows + ghost paths |
 | `wikifier cycles` | Circular deps + break hints |
-| `wikifier monitor` / `daemon` | Background maintenance |
+| `wikifier monitor` / `daemon` | Background maintenance (`WIKIFIER_DAEMON_MAPS=0` for check-only) |
 | `wikifier serve` | Localhost dashboard with Run/Stop |
 
-Library: `from wikifier import check_changes, record_change, mark_green, health, update_maps`.
+Library: `from wikifier import check_changes, record_change, mark_green, suggest_next_actions, update_maps, health`.
 
 ## MCP
 
@@ -146,6 +159,8 @@ Setup and tool list: [`wikifier/mcp/README.md`](wikifier/mcp/README.md).
 **In:** agent-maintained codebase wiki, dependency intelligence, token-saving lookup for LLMs and coding agents.  
 **Out:** general human documentation systems, IDE plugins, “docs for everyone” product growth.
 
+**Agent navigability:** Prefer protocol ([`skills/run.md`](skills/run.md)) + MCP Core 6 over reading 20k LOC of parsers/cache. Production modules carry a short **AGENT MAP** docstring; self-tests live under `tests/` and `tests/selftest/`, not inline at the bottom of parsers.
+
 ## Links
 
 - [PyPI](https://pypi.org/project/wikifier/) · [GitHub](https://github.com/IronAdamant/wikifier)

{wikifier-4.5.2 → wikifier-4.5.4}/README.md

@@ -8,65 +8,75 @@
 
 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 (Python + JavaScript/TypeScript imports, barrels, cycles, incremental updates).
+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
 
 Context windows are finite. Re-reading a large file to answer “what is this and who depends on it?” wastes tokens.
 
-Wikifier keeps a small set of artifacts agents can query:
-
 | Artifact | Role |
 |----------|------|
 | `file_health.md` | 🟢 / 🟡 / 🔴 matrix — what to trust, what to fix first |
 | `library.md` | File tree, Mermaid dependency map, import tables, cycles + confidence |
-| `*.wiki.md` | Short per-file “what this is for” notes (agent-maintained) |
-| `journal/` | Semantic *why* trail from `record-change` |
+| `*.wiki.md` | Short per-file “what this is for” notes (**agent-maintained** prose) |
+| `journal/` + `pending_updates.md` | Semantic *why* trail + work queue (audit, **not** a full issue tracker) |
 
-Lookup beats re-ingest. That’s the whole idea.
+**Map first, wiki depth second:** `update-maps` builds the structural map automatically. Rich per-file wiki text is filled by agents as they work — not a free full-repo “understand everything” pass on init.
 
-## Quick start
+## First run (bootstrap the map)
 
 ```bash
 pip install wikifier            # pure Python stdlib core — no runtime deps
 pip install wikifier[mcp]       # optional Model Context Protocol (MCP) server
 
 cd /path/to/your/project
-wikifier init
-wikifier update-maps            # dependency graph + library.md
-wikifier check-changes
-wikifier health --summary
+wikifier init                   # seeds + human index.html
+wikifier update-maps            # full structural map → library.md + import cache
+wikifier health --summary       # matrix counts
+wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only
 ```
 
-Always set an explicit root for external trees:
+Always set an explicit root for external trees: `WIKIFIER_PROJECT_ROOT=/abs/path wikifier …`
 
-```bash
-WIKIFIER_PROJECT_ROOT=/abs/path/to/project wikifier check-changes
-```
-
-## Agent loop
+## Steady state (only touch what needs it)
 
 Full protocol: [`skills/run.md`](skills/run.md).
 
 ```bash
-wikifier check-changes
-# prioritize 🔴 then 🟡 in file_health.md / pending_updates.md
-# ... edit source ...
+wikifier check-changes          # yellow dirty files; red ghosts (missing paths)
+# prioritize 🔴 then 🟡 — do NOT re-wiki 🟢 Green files
+# ... edit only those sources ...
 wikifier record-change "path/file.py" "why this changed"   # required
-# ... refresh that file’s wiki summary ...
+# ... refresh that file’s wiki summary only ...
 wikifier mark-green "path/file.py"
-wikifier update-maps            # if imports/structure changed
+wikifier update-maps            # only if imports/structure changed
+# removals:
+wikifier record-deletion "path/gone.py" "why removed"
 ```
 
-`record-change` logs intent a git diff can’t reconstruct for the next agent (or human).
+MCP **Core 6** (start every session): `get_project_status`, `check_changes`, `get_files_needing_attention`, `get_file_wiki`, `suggest_next_actions`, `record_change` / `mark_green`. Intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`. Always pass `project_root=` for external trees.
 
 ## 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
-- **MCP tools** — optional server for Claude, Cursor, Cline, and other MCP clients (`get_project_status`, `get_dependencies`, `get_file_wiki`, `record_change`, …)
+- **MCP tools** — optional server for Claude, Cursor, Cline, and other MCP clients
 - **Zero core dependencies** — stdlib only; forks can add their own stack on top
+- **Agent navigability** — short **AGENT MAP** docstrings on core modules; self-tests under `tests/` (not buried in parsers)
 
 ## Performance (measured)
 
@@ -86,13 +96,16 @@ Tests: `python -m unittest discover tests` (stdlib only).
 | `wikifier check-changes` | Incremental scan → health / pending |
 | `wikifier record-change <file> "reason"` | Log *why* (required after edits) |
 | `wikifier mark-green <file>` | Mark wiki current |
+| `wikifier record-deletion <file> "reason"` | Mark removed paths 🔴 + prune barrel refs |
+| `wikifier suggest-next` | Next actions (🔴/🟡 only) |
 | `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` |
 | `wikifier health [--summary\|--json]` | Health matrix (machine-friendly flags) |
+| `wikifier validate` | Missing wiki rows + ghost paths |
 | `wikifier cycles` | Circular deps + break hints |
-| `wikifier monitor` / `daemon` | Background maintenance |
+| `wikifier monitor` / `daemon` | Background maintenance (`WIKIFIER_DAEMON_MAPS=0` for check-only) |
 | `wikifier serve` | Localhost dashboard with Run/Stop |
 
-Library: `from wikifier import check_changes, record_change, mark_green, health, update_maps`.
+Library: `from wikifier import check_changes, record_change, mark_green, suggest_next_actions, update_maps, health`.
 
 ## MCP
 
@@ -114,6 +127,8 @@ Setup and tool list: [`wikifier/mcp/README.md`](wikifier/mcp/README.md).
 **In:** agent-maintained codebase wiki, dependency intelligence, token-saving lookup for LLMs and coding agents.  
 **Out:** general human documentation systems, IDE plugins, “docs for everyone” product growth.
 
+**Agent navigability:** Prefer protocol ([`skills/run.md`](skills/run.md)) + MCP Core 6 over reading 20k LOC of parsers/cache. Production modules carry a short **AGENT MAP** docstring; self-tests live under `tests/` and `tests/selftest/`, not inline at the bottom of parsers.
+
 ## Links
 
 - [PyPI](https://pypi.org/project/wikifier/) · [GitHub](https://github.com/IronAdamant/wikifier)

{wikifier-4.5.2 → wikifier-4.5.4}/skills/run.md

@@ -3,11 +3,19 @@
 **Formerly "Wikifier Skills & Commands". This is the authoritative, versioned specification for agent behavior when using Wikifier.**
 
 **Version**: v0.6 (v4.2.0 real-pipeline + reliability update; package current **4.5.x**)  
-**Date**: 2026-06-10 (package notes refreshed 2026-07-09)  
+**Date**: 2026-06-10 (package notes refreshed 2026-07-09; gap-closure contract 2026-07-09)  
 **Status**: Active. Supersedes v0.5.  
-**See also**: `README.md` (Intended Use section: strictly agent-to-agent wiki for token saving), M5-Dogfood-Assessment-Report.md, Findings/2026-06-10-Dogfood-Refactor-Validation.md, and the library in wikifier/.
-
-**Package 4.5.x notes (additive; protocol still v0.6):** File Tree as primary structure view in `library.md` + dashboard pan/zoom graph; `wikifier serve` with real Run/Stop controls; Python parser no longer leaks `#`-comment text into edges; MCP `get_project_status` / `get_files_needing_attention` use library+emoji health statuses (not legacy `[GREEN]` tags). Full history: `CHANGELOG.md`.
+**See also**: `README.md`, `Findings/gap-closure-report.md`, and the library in wikifier/.
+
+**Package 4.5.x + gap-closure notes (additive; protocol still v0.6):**
+- File Tree + `wikifier serve`; MCP status/attention use library + emoji (not `[GREEN]` tags).
+- **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, 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*.
 
 **v0.6 migration notes (packages v4.2.0–v4.3.0)** — changes are additive or strictly-better defaults; v0.5 agent behavior keeps working:
 - `update-maps` (CLI) now runs the **pure-Python full pipeline**: every dirty file is parsed in-process, the canonical per-file cache is persisted, reverse deps + cycles + ACS are computed, and `library.md` is regenerated atomically. `--python-primary` is accepted but redundant; the in-shell first-pass was retired entirely (wikifier.sh's update-maps delegates to this pipeline; `--sh`/`--legacy-sh` are deprecated no-ops). Scoping is explicit via `--directory=`/`--max-files=` and reported in the result (`files_skipped`) — there are no silent caps.
@@ -24,33 +32,54 @@ This protocol + the Python package + MCP server form the bridge for consistent,
 
 **This file is the primary contract for any LLM or agent operating Wikifier.**
 
+## Agent architecture (navigability — G12)
+
+Do **not** open megamodules (`javascript.py`, `import_cache.py`, `bree.py`) to decide workflow. Use this map:
+
+| Need | Use |
+|------|-----|
+| First-run map | `init` → `update-maps` → `health --summary` → `suggest-next` |
+| Steady-state | `check-changes` → edit 🔴/🟡 only → `record-change` → wiki → `mark-green` |
+| Lookup | MCP Core 6: status, check_changes, needing_attention, get_file_wiki, suggest, record/mark |
+| Deps / cycles | `get_dependencies`, `get_dependents`, `get_cycles` (json) |
+| Deletion | `record-deletion` |
+| Code entry | `wikifier/cli.py` (dispatch) + `wikifier/health.py` + parsers — self-tests live in `tests/` + `tests/selftest/` |
+
+**CLI pure-Python vs shell:** mutators and maps prefer `python -m wikifier …`. Shell still owns `init`, `monitor`, `daemon`, `serve`, `journal`.  
+**Scope:** `monitored_paths` = change detection; `exclude_patterns` + optional `--directory` = map walk.  
+**Human HTML** is secondary observation only.
+
 ## Mandatory New-Session Rule
 
 **Copy this exact block into the system prompt or the very first instruction of every new LLM session that uses Wikifier:**
 
 ```
-You are now operating inside a Wikifier-managed codebase (Agent Protocol v0.6 — v4.2.0).
+You are now operating inside a Wikifier-managed codebase (Agent Protocol v0.6 — package 4.5.x).
+
+This is strictly an agent-to-agent wiki for token saving: map lookup (health + file wikis + deps) instead of full sources; selective wiki updates; not a human docs product or Jira.
 
-This is strictly an agent-to-agent wiki for token saving: quick file lookup (health matrix + file wikis + BRC + stele instead of full sources), autonomous wiki summary updates, and creation of new wiki entries as you work. It should not be used for anything more.
+SELECTIVE WORK (mandatory): Only update/remove/re-wiki 🔴 Red and 🟡 Yellow files. Do not re-summarize 🟢 Green files or the whole tree. First-run builds the structural map; wiki depth is filled as you touch files.
 
-FIRST ACTIONS (mandatory, post-M5 hardened):
-1. If the Wikifier MCP server is connected, prefer its tools (get_project_status, get_file_wiki, check_changes, get_barrel_reports, suggest_next_actions, etc.). Always pass project_root= for external/user projects (e.g. RecipeLab_alt, ConsistencyHub, llvm subs).
-2. If MCP times out or is unavailable (rare since v4.2.0 fixed the workflow-call deadlock and batched barrel persistence; historically seen on BRC-heavy or 50k+ scale targets), fall back immediately to reliable CLI/library:
+FIRST ACTIONS:
+1. Prefer MCP tools when connected (get_project_status, get_file_wiki, check_changes, suggest_next_actions, get_dependencies, …). Always pass project_root= for external projects.
+2. CLI/library fallback:
      WIKIFIER_PROJECT_ROOT=/path/to/target python -m wikifier check-changes
-     python -m wikifier health --summary   # or format=json/summary for machine use (token-efficient lookup)
-     ... perform edit on source ...
-     python -m wikifier record-change "path/to/file" "concise semantic reason (why, not what). Include subid if agent work."
-     ... write/update the wiki summary for the file ...
-     python -m wikifier mark-green "path/to/file" "Reason for Green (e.g. after autonomous agent update)."
-     if imports changed: python -m wikifier update-maps [--directory=src/]  # pure-Python full pipeline by default (v4.2.0)
      python -m wikifier health --summary
-3. For sustained agent work: launch `python -m wikifier monitor` (or wikifier.sh monitor) in bg / daemon for 30s "Pruned 0 / No new" heartbeat + auto BRC healing. Use .last_check + health for observability.
-4. Immediately consult the small health matrix (file_health.md or health --summary) + pending_updates.md. Prioritise 🔴 then 🟡. Use this for quick reference instead of full file reads to save tokens.
-5. For edits to agent-maintained docs (e.g. this protocol, README, Findings/M5-*.md): precede with FRESH 3 hygiene (grep for 0 def matches on the target .md), use record-change + mark-green.
-6. Always pass explicit project_root / WIKIFIER_PROJECT_ROOT for any external or multi-project work (M5 lesson: absolute monitored_paths.txt, no pollution).
-7. Re-validate with health + suggest_next_actions (or equivalent) at end of turn/session. Use monitor for long-running.
+     python -m wikifier suggest-next   # or suggest_next_actions(format="json")
+     ... edit only red/yellow sources ...
+     python -m wikifier record-change "path/to/file" "why (semantic). Include subid if agent work."
+     ... update that file's wiki only ...
+     python -m wikifier mark-green "path/to/file" "reason"
+     if imports changed: python -m wikifier update-maps [--directory=src/]
+     if file removed: python -m wikifier record-deletion "path" "why"
+     python -m wikifier health --summary
+3. Optional background: `python -m wikifier monitor` or daemon for mtime heartbeat — you still own wiki + mark-green.
+4. Prioritize 🔴 then 🟡 from health/pending. Lookup greens via get_file_wiki; do not rewrite them.
+5. Agent docs edits: record-change + mark-green.
+6. Always explicit project_root / WIKIFIER_PROJECT_ROOT for external/multi-project work.
+7. End turn: health + suggest_next_actions.
 
-Never skip record-change — it is the semantic audit trail (journal + health + pending + BRC).
+Never skip record-change — semantic audit trail (journal + health + pending).
 
 **M5+ notes (2026-06)**: 
 - External projects: always explicit root. CLI is battle-tested fallback (M5.1 MCP reliability: 60s timeout + better errors; M5 dogfood on alt BRC exact named services, 79k llvm, etc.).

wikifier-4.5.4/tests/test_gap_closure.py

@@ -0,0 +1,128 @@
+"""Gap-closure regressions (G4 ACS actionable, G5 health module, G7 ghosts/deletion)."""
+
+import importlib
+import unittest
+
+from tests._base import TempProjectTestCase
+
+from wikifier import import_cache as ic
+from wikifier import cli
+
+
+class TestHealthModuleImportG5(unittest.TestCase):
+    def test_importlib_health_is_module_with_get_summary(self):
+        mod = importlib.import_module("wikifier.health")
+        self.assertTrue(hasattr(mod, "get_summary"))
+        self.assertTrue(hasattr(mod, "find_ghost_entries"))
+        self.assertTrue(callable(mod.get_summary))
+
+    def test_health_module_alias_on_package(self):
+        import wikifier
+        self.assertTrue(hasattr(wikifier, "health_module"))
+        self.assertTrue(hasattr(wikifier.health_module, "get_summary"))
+        # Convenience function still exported as wikifier.health
+        self.assertTrue(callable(wikifier.health))
+
+
+class TestAcsActionableG4(TempProjectTestCase):
+    def test_external_noise_excluded_from_actionable_low_conf(self):
+        cache = {}
+        # Project-internal low-conf edge
+        ic.update_file_data(
+            cache,
+            "app.py",
+            mtime=1,
+            imports=["./util"],
+            resolved_pairs=[{
+                "raw": "./util",
+                "resolved": "util.py",
+                "resolved_path": "util.py",
+                "confidence_score": 0.4,
+                "confidence_reasons": ["base:low", "via_barrel"],
+                "confidence_explanation": "Base low. Recommendation: Review project edge.",
+                "diagnostic": {"category": "project"},
+                "resolution_metadata": {"strategy": "relative-fs"},
+            }],
+        )
+        # External/stdlib-style edge (noise)
+        ic.update_file_data(
+            cache,
+            "app.py",
+            mtime=1,
+            imports=["json", "./util"],
+            resolved_pairs=[
+                {
+                    "raw": "./util",
+                    "resolved": "util.py",
+                    "resolved_path": "util.py",
+                    "confidence_score": 0.4,
+                    "confidence_reasons": ["base:low"],
+                    "confidence_explanation": "Project low. Recommendation: Review.",
+                    "resolution_metadata": {"strategy": "relative-fs"},
+                },
+                {
+                    "raw": "json",
+                    "resolved": "json",
+                    "resolved_path": "",
+                    "confidence_score": 0.48,
+                    "confidence_reasons": ["base:medium", "no_resolved_path"],
+                    "confidence_explanation": "stdlib. Recommendation: harden import.",
+                    "diagnostic": {"category": "external_or_bare"},
+                    "resolution_metadata": {"strategy": "python-bare-or-external"},
+                },
+            ],
+        )
+        # Note: update_file_data may replace pairs — set explicitly
+        cache["app.py"]["resolved_pairs"] = [
+            {
+                "raw": "./util",
+                "resolved": "util.py",
+                "resolved_path": "util.py",
+                "confidence_score": 0.4,
+                "confidence_reasons": ["base:low"],
+                "confidence_explanation": "Project low. Recommendation: Review.",
+                "resolution_metadata": {"strategy": "relative-fs"},
+            },
+            {
+                "raw": "json",
+                "resolved": "json",
+                "confidence_score": 0.48,
+                "confidence_reasons": ["base:medium"],
+                "confidence_explanation": "stdlib noise. Recommendation: ignore.",
+                "diagnostic": {"category": "external_or_bare"},
+                "resolution_metadata": {"strategy": "python-bare-or-external"},
+            },
+        ]
+        summary = ic.compute_acs_summary(cache)
+        self.assertGreaterEqual(summary["low_conf_edges"], 1)
+        self.assertEqual(summary["actionable_low_conf_edges"], 1)
+        self.assertGreaterEqual(summary["external_noise_edges"], 1)
+        action = ic.get_low_confidence_edges(cache, actionable_only=True)
+        self.assertTrue(all(
+            (p.get("diagnostic") or {}).get("category") != "external_or_bare"
+            for p in action
+        ))
+
+
+class TestGhostAndDeletionG7(TempProjectTestCase):
+    def test_find_ghost_and_record_deletion(self):
+        health_mod = importlib.import_module("wikifier.health")
+        self.write("keep.py", "x=1\n")
+        self.write("gone.py", "y=1\n")
+        health_mod.upsert_entry(self.root, "keep.py", "🟢 Green", "ok")
+        health_mod.upsert_entry(self.root, "gone.py", "🟢 Green", "ok")
+        (self.root / "gone.py").unlink()
+
+        ghosts = health_mod.find_ghost_entries(self.root)
+        self.assertIn("gone.py", ghosts)
+        self.assertNotIn("keep.py", ghosts)
+
+        res = cli.record_deletion("gone.py", "removed in cleanup", project_root=self.root)
+        self.assertTrue(res.get("success"))
+        entries = health_mod.load_health(self.root)["entries"]
+        self.assertIn("🔴", entries["gone.py"]["status"])
+        self.assertIn("DELETED", entries["gone.py"]["reason"])
+
+
+if __name__ == "__main__":
+    unittest.main()

wikifier-4.5.4/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.4/tests/test_selftest_wrappers.py

@@ -0,0 +1,39 @@
+"""G12: run extracted selftest harnesses via unittest (no harness in prod modules)."""
+
+import runpy
+import unittest
+from pathlib import Path
+
+SELFTEST = Path(__file__).resolve().parent / "selftest"
+
+
+class TestExtractedSelftests(unittest.TestCase):
+    def _run(self, name: str):
+        path = SELFTEST / name
+        self.assertTrue(path.is_file(), f"missing {path}")
+        # Execute as __main__ so assert-based scripts raise on failure
+        try:
+            runpy.run_path(str(path), run_name="__main__")
+        except SystemExit as e:
+            if e.code not in (0, None):
+                self.fail(f"{name} exited with {e.code}")
+
+    def test_contracts_selftest(self):
+        self._run("run_contracts_selftest.py")
+
+    def test_python_parser_selftest(self):
+        self._run("run_python_parser_selftest.py")
+
+    def test_cdia_selftest(self):
+        self._run("run_cdia_selftest.py")
+
+    def test_resolution_selftest(self):
+        self._run("run_resolution_selftest.py")
+
+    def test_javascript_selftest(self):
+        # Heavier; still must pass for agent-navigable JS parser
+        self._run("run_javascript_selftest.py")
+
+
+if __name__ == "__main__":
+    unittest.main()