wikifier 4.5.2__tar.gz → 4.5.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.5.2
+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
@@ -40,65 +40,63 @@ 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 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.
 
-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)
 - **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 +116,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 +147,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.3}/README.md

@@ -8,65 +8,63 @@
 
 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 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.
 
-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)
 - **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 +84,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 +115,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.3}/skills/run.md

@@ -3,11 +3,18 @@
 **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/.
+**See also**: `README.md`, `Findings/gap-closure-report.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`.
+**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.
@@ -24,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.2 → 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.2"
+__version__ = "4.5.3"