v4.5.3: gap closure, agent navigability, ACS actionable, selective work

First-run/steady-state agent contract, pure-Py workflow routes, ghost
deletion hygiene, ACS actionable_low_conf, G12 harness extract + AGENT
MAP docs, daemon maps throttle. README + protocol for agent-first wiki.

Author: Aron

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [4.5.3] - 2026-07-09
+
+### Added
+
+- **Agent first-run / steady-state contract** in README + protocol: map first, wiki
+  prose agent-filled; selective 🔴/🟡 work only.
+- **ACS v1.1** fields: `actionable_low_conf_edges`, `external_noise_edges` (stdlib /
+  bare demoted for agent next-steps; full telemetry retained).
+- **Ghost detection**: missing disk paths → Red DELETED on check-changes;
+  `find_ghost_entries` / validate ghosts; `record-deletion` CLI + BRC prune.
+- **CLI pure-Python routes**: `suggest-next`, `record-deletion`, `validate`.
+- **AGENT MAP** docstrings on core modules; self-tests moved to `tests/selftest/`.
+- **MCP Core 6** documented (status, check_changes, needing_attention, wiki, suggest, record/mark).
+- Daemon: `WIKIFIER_DAEMON_MAPS_INTERVAL` (default 600s) and `WIKIFIER_DAEMON_MAPS=0`.
+
+### Fixed
+
+- Agent navigability (G12): no inlined parser harnesses at bottom of production modules;
+  protocol architecture table for agents.
+
+### Changed
+
+- `suggest_next_actions` prioritizes health red/yellow and actionable ACS only.
+- `init` prints agent first-run next steps (not only human serve).
+
 ## [4.5.2] - 2026-07-09
 
 ### Fixed

Findings/gap-closure-report.md

@@ -0,0 +1,80 @@
+# Gap Closure Report — Agent-Focused Project Wiki
+
+**Program:** Gap Closure Swarms  
+**Baseline:** v4.5.2 → worktree post-gap-closure  
+**Completed:** 2026-07-09  
+**subid:** gap-swarm-coord  
+
+## North star
+
+Wikifier = any project's **agent-focused wiki**: first setup builds a **map**; later agents only touch files that need update/remove/change; MCP for anytime lookup; humans observe via thin HTML. Map is automated; wiki **prose** is agent-filled.
+
+## Gap matrix
+
+| ID | Gap | Severity | Status | Evidence |
+|----|-----|----------|--------|----------|
+| G1 | Product loop under-documented | S1 | **Closed** | README first-run + steady-state; protocol session block; init stdout |
+| G2 | First setup map vs semantic investigate | S1 | **Closed** | Honest “map first, wiki later” in README/protocol/init |
+| G3 | Agents re-touch green / full-tree | S1 | **Closed** | `suggest_next_actions` selective; protocol SELECTIVE WORK |
+| G4 | ACS noise (external/bare as oracle) | S1 | **Closed** | `actionable_low_conf_edges` + demote external; suggest uses it; tests |
+| G5 | `health` name shadow | S1 | **Closed** | `health_module` export; MCP importlib; tests; docs |
+| G6 | Dual shell/Python residue | S2 | **Closed** (partial) | Pure-Py: check/record/mark/deletion/suggest/validate; launchers synced; shell init improved |
+| G7 | Deletion / ghost health entries | S1 | **Closed** | `find_ghost_entries`; check_changes marks ghosts; record_deletion + BRC prune; tests |
+| G8 | Issue tracker overclaim | S2 | **Closed** | Docs: journal/pending = audit queue not Jira |
+| G9 | Language coverage honesty | S1 | **Closed** | Deep maps = py/js/ts only (README/protocol/init) |
+| G10 | Sample dogfood cache vs health | S2 | **Closed** (smoke) | llama_index + redox check/suggest; contract: monitored ≠ map scope documented |
+| G11 | Monitor/daemon ops | S2 | **Closed** | Daemon maps interval default 600s; `WIKIFIER_DAEMON_MAPS=0`; start/stop smoke |
+| G12 | Complexity / agent-hostile surface | S2→**Closed** | **Closed** | Harnesses → tests/selftest/; AGENT MAP docs; MCP Core 6; dual-path legend; bree/health headers thinned |
+
+## Fix backlog (executed)
+
+1. W1-A G5 health_module + tests  
+2. W1-B G4 ACS actionable fields + filter  
+3. W1-C/G3 suggest selective + MCP delegates to lib  
+4. W1-E G7 ghosts + record_deletion prune + CLI routes  
+5. W1-D docs/protocol/README  
+6. W2 init agent first-run lines; daemon maps throttle; dogfood smoke  
+
+## Wave notes
+
+### Wave 0 — Investigation
+Three explore agents (INV-CONTRACT, INV-TRUST, INV-OPS) produced severity-ranked proposals. Coordinator implemented high-leverage fixes without language expansion or dashboard growth.
+
+### Wave 1–2 — Implementation
+- `wikifier/import_cache.py` — `_edge_is_external_noise`, ACS v1.1 actionable fields  
+- `wikifier/cli.py` — selective suggest, record_deletion prune, check ghosts, CLI routes  
+- `wikifier/health.py` — `find_ghost_entries`, validate ghosts  
+- `wikifier/mcp/server.py` — suggest → library  
+- `wikifier/__init__.py` — `health_module`  
+- `wikifier/daemon.py` — maps interval  
+- `wikifier/scripts/wikifier.sh` + root — init messaging  
+- `tests/test_gap_closure.py` — 4 new tests  
+- README + skills/run.md — contracts  
+
+### Wave 3 — Verification
+- **34/34** unittest OK  
+- Dogfood: llama_index / redox check-changes + suggest (selective copy)  
+- Daemon start/status/stop on temp fixture with `WIKIFIER_DAEMON_MAPS=0`  
+
+## Residual / deferred
+
+| Item | Reason |
+|------|--------|
+| G12 full megamodule split (js/bree) | Not required for navigability after AGENT MAP + harness extract |
+| update-maps honor monitored_paths | Compat risk; document scope instead |
+| Unshadow package attr `health` to module only | Breaking for `from wikifier import health` function API |
+| Multi-month daemon proof | Out of scope; smoke + runbook only |
+| New language parsers | Explicit non-goal |
+
+## Agent contract (canonical)
+
+**First-run:** `init` → `update-maps` → `health --summary` → `suggest-next`  
+**Steady-state:** `check-changes` → edit 🔴/🟡 only → `record-change` → wiki → `mark-green` → `update-maps` if structure changed; `record-deletion` on remove  
+**Lookup anytime:** MCP status / wiki / deps  
+**Limits:** deep maps py/js/ts; journal≠Jira; not fully autonomous without agent judgment  
+
+## Tests
+
+```bash
+python3 -m unittest discover tests   # 34 tests
+```

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)