wikifier 4.5.1__tar.gz → 4.5.3__tar.gz

wikifier-4.5.3/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: wikifier
+Version: 4.5.3
+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
+License: MIT
+Project-URL: Homepage, https://github.com/IronAdamant/wikifier
+Project-URL: Repository, https://github.com/IronAdamant/wikifier
+Project-URL: Documentation, https://github.com/IronAdamant/wikifier#readme
+Project-URL: Bug Tracker, https://github.com/IronAdamant/wikifier/issues
+Keywords: wiki,documentation,llm,agent,mcp,codebase,health-matrix,zero-dependency,shell,token-efficient,autonomous,record-change,mark-green,agent-wiki,llm-tools,dependency-graph,monorepo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Dynamic: license-file
+
+# Wikifier
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://img.shields.io/pypi/v/wikifier.svg)](https://pypi.org/project/wikifier/)
+[![GitHub Stars](https://img.shields.io/github/stars/IronAdamant/wikifier?style=social)](https://github.com/IronAdamant/wikifier/stargazers)
+
+**A zero-dependency codebase wiki for AI agents** — token-efficient maps so LLMs look things up instead of re-reading full sources.
+
+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.
+
+## Why
+
+Context windows are finite. Re-reading a large file to answer “what is this and who depends on it?” wastes tokens.
+
+| 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** prose) |
+| `journal/` + `pending_updates.md` | Semantic *why* trail + work queue (audit, **not** a full issue tracker) |
+
+**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.
+
+## 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                   # 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: `WIKIFIER_PROJECT_ROOT=/abs/path wikifier …`
+
+## Steady state (only touch what needs it)
+
+Full protocol: [`skills/run.md`](skills/run.md).
+
+```bash
+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 only ...
+wikifier mark-green "path/file.py"
+wikifier update-maps            # only if imports/structure changed
+# removals:
+wikifier record-deletion "path/gone.py" "why removed"
+```
+
+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)
+- **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
+- **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)
+
+| Project | Scale | Full `update-maps` |
+|---------|-------|--------------------|
+| llama_index | ~3.8k Python files | ~8.5s |
+| Babylon.js | ~3.9k TS files, barrel-heavy | ~4.5 min (scoped re-runs ~80s) |
+| Large trees (e.g. LLVM-scale) | tens of thousands of files | candidate scan in seconds |
+
+Tests: `python -m unittest discover tests` (stdlib only).
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `wikifier init [--target DIR]` | Bootstrap project + human `index.html` |
+| `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_DAEMON_MAPS=0` for check-only) |
+| `wikifier serve` | Localhost dashboard with Run/Stop |
+
+Library: `from wikifier import check_changes, record_change, mark_green, suggest_next_actions, update_maps, health`.
+
+## MCP
+
+```bash
+WIKIFIER_PROJECT_ROOT=/abs/path/to/project wikifier-mcp
+# or: python3 -m wikifier.mcp.server
+```
+
+Setup and tool list: [`wikifier/mcp/README.md`](wikifier/mcp/README.md).
+
+## Human dashboard (secondary)
+
+![Wikifier dashboard — file tree, health pills, local Run/Stop](https://raw.githubusercontent.com/IronAdamant/wikifier/main/screenshot/front_page_review.png)
+
+`wikifier init` drops a single `index.html`. Prefer **`wikifier serve`** (e.g. http://localhost:8787/index.html) — `file://` can’t load project files. The markdown artifacts and CLI/MCP tools stay the source of truth; the UI is a read-only window.
+
+## Scope
+
+**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)
+- Agent protocol: [`skills/run.md`](skills/run.md)
+- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
+- Dogfood notes: `Findings/`

wikifier-4.5.3/README.md

@@ -0,0 +1,125 @@
+# Wikifier
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://img.shields.io/pypi/v/wikifier.svg)](https://pypi.org/project/wikifier/)
+[![GitHub Stars](https://img.shields.io/github/stars/IronAdamant/wikifier?style=social)](https://github.com/IronAdamant/wikifier/stargazers)
+
+**A zero-dependency codebase wiki for AI agents** — token-efficient maps so LLMs look things up instead of re-reading full sources.
+
+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.
+
+## Why
+
+Context windows are finite. Re-reading a large file to answer “what is this and who depends on it?” wastes tokens.
+
+| 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** prose) |
+| `journal/` + `pending_updates.md` | Semantic *why* trail + work queue (audit, **not** a full issue tracker) |
+
+**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.
+
+## 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                   # 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: `WIKIFIER_PROJECT_ROOT=/abs/path wikifier …`
+
+## Steady state (only touch what needs it)
+
+Full protocol: [`skills/run.md`](skills/run.md).
+
+```bash
+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 only ...
+wikifier mark-green "path/file.py"
+wikifier update-maps            # only if imports/structure changed
+# removals:
+wikifier record-deletion "path/gone.py" "why removed"
+```
+
+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)
+- **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
+- **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)
+
+| Project | Scale | Full `update-maps` |
+|---------|-------|--------------------|
+| llama_index | ~3.8k Python files | ~8.5s |
+| Babylon.js | ~3.9k TS files, barrel-heavy | ~4.5 min (scoped re-runs ~80s) |
+| Large trees (e.g. LLVM-scale) | tens of thousands of files | candidate scan in seconds |
+
+Tests: `python -m unittest discover tests` (stdlib only).
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `wikifier init [--target DIR]` | Bootstrap project + human `index.html` |
+| `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_DAEMON_MAPS=0` for check-only) |
+| `wikifier serve` | Localhost dashboard with Run/Stop |
+
+Library: `from wikifier import check_changes, record_change, mark_green, suggest_next_actions, update_maps, health`.
+
+## MCP
+
+```bash
+WIKIFIER_PROJECT_ROOT=/abs/path/to/project wikifier-mcp
+# or: python3 -m wikifier.mcp.server
+```
+
+Setup and tool list: [`wikifier/mcp/README.md`](wikifier/mcp/README.md).
+
+## Human dashboard (secondary)
+
+![Wikifier dashboard — file tree, health pills, local Run/Stop](https://raw.githubusercontent.com/IronAdamant/wikifier/main/screenshot/front_page_review.png)
+
+`wikifier init` drops a single `index.html`. Prefer **`wikifier serve`** (e.g. http://localhost:8787/index.html) — `file://` can’t load project files. The markdown artifacts and CLI/MCP tools stay the source of truth; the UI is a read-only window.
+
+## Scope
+
+**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)
+- Agent protocol: [`skills/run.md`](skills/run.md)
+- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
+- Dogfood notes: `Findings/`

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

@@ -2,10 +2,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)  
-**Date**: 2026-06-10  
+**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; 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/.
+**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. journal/pending = audit queue, not Jira.
+- **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.
@@ -22,33 +31,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.3/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.3/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()

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

@@ -13,14 +13,18 @@ Zero-dependency, agent-to-agent codebase wiki. Provides:
 
 The flat library API below (check_changes, record_change, mark_green,
 health, update_maps, ...) is the preferred surface for agents calling
-Wikifier directly from Python. Note: `from wikifier import health` binds the
-convenience function; the module is still reachable via
-`from wikifier.health import upsert_entry, ...`.
+Wikifier directly from Python.
+
+**Health import hygiene (G5):** `from wikifier import health` is the *convenience
+function* (cli). The real module is always `importlib.import_module("wikifier.health")`
+or `from wikifier.health import upsert_entry, get_summary, ...`. Prefer
+`wikifier.health_module` (alias below) over `import wikifier.health as …`, which
+binds the function under CPython because the package attribute is shadowed.
 """
 
 from . import parsers
 from . import mcp  # exposes wikifier.mcp.mcp (None when the optional extra is absent)
-from . import health
+from . import health as health_module  # submodule — keep this name for agents/tools
 from . import locking
 from . import import_cache
 from . import resolution
@@ -40,6 +44,12 @@ from .cli import (
     health,  # flat convenience func (delegates to the health module + adds scoping)
 )
 
+# Re-export module under a non-shadowed name (G5). sys.modules['wikifier.health']
+# remains the real module; package attribute `health` is intentionally the function.
+import sys as _sys
+if "wikifier.health" not in _sys.modules:
+    _sys.modules["wikifier.health"] = health_module
+
 # Shared frozen data contracts (single source of truth for shapes used by
 # parsers, cache, MCP, and diagnostics).
 from . import contracts
@@ -61,4 +71,4 @@ from .contracts import (
     compute_acs_confidence,
 )
 
-__version__ = "4.5.1"
+__version__ = "4.5.3"