wikifier 4.6.7__tar.gz → 4.6.9__tar.gz

{wikifier-4.6.7/wikifier.egg-info → wikifier-4.6.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.6.7
+Version: 4.6.9
 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
@@ -52,7 +52,14 @@ Works from small scripts to large monorepos. **Deep import/include maps** (zero-
 | 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.
+Health/journal still work for any monitored path. Parsers are **pragmatic regex** (not full cargo/`go.mod`/classpath/`-I` resolution). On huge monorepos, split scope deliberately:
+
+| File | Surface |
+|------|---------|
+| **`map_paths.txt`** | Package roots for **import maps** (`update-maps` walk). Prefer package dirs (`src/`, `packages/foo/`) — not a wiki-only file list. |
+| **`monitored_paths.txt`** | **Wiki / health** watch list (can be individual `.md` files). Does **not** define the map. |
+
+Or pass `--directory=pkg/` / `--max-files=N` per run. Raise dirty cap with `WIKIFIER_CHECK_CHANGES_MAX` (default 2000) only when needed. Never set `project_root` to a multi-repo parent of clones.
 
 ## Why
 
@@ -74,7 +81,8 @@ 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 init                   # seeds index.html + lean path-list templates
+# Edit monitored_paths.txt + map_paths.txt to package roots (not bare ".") on real trees
 wikifier update-maps            # full structural map → library.md + import cache
 wikifier health --summary       # matrix counts
 wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only
@@ -82,6 +90,8 @@ wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only
 
 Always set an explicit root for external trees: `WIKIFIER_PROJECT_ROOT=/abs/path wikifier …`
 
+**MCP `session_bootstrap` → `readiness: blocked`?** That means lean scope and/or the map are missing (often bare `.` monitor + never ran `update-maps`) — not a broken install. Fix: write lean `monitored_paths.txt` / `map_paths.txt`, then `update-maps`. Agent contract: **`skills/run.md`** § *Readiness blocked*; dogfood: `Findings/readiness-blocked-bare-monitor-2026-07.md`.
+
 ## Steady state (only touch what needs it)
 
 Full protocol: [`skills/run.md`](skills/run.md) (Agent Protocol v0.6 — package **4.6.x**).
@@ -109,11 +119,11 @@ Advanced intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`, ba
 
 - **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust (`use`/`mod` + best-effort `crate::` paths), Go, C/C++ includes, C# usings; per-edge confidence; barrel expansion for TS/JS
 - **Incremental pipeline** — pure-Python `update-maps`: dirty parse → import cache → reverse deps → cycles → `library.md`
-- **Warm agent maps (4.6.3–4.6.6)** — zero-dirty + **index-first** candidates (re-list only on fingerprint/index disagreement); **stdlib SQLite**; content-hash dirty
-- **Two path lists** — `map_paths.txt` = map package roots; `monitored_paths.txt` = wiki/health watch (independent)
+- **Warm agent maps (4.6.3–4.6.7)** — zero-dirty + **index-first** candidates (re-list only when fingerprint / map-scoped index / live count disagree); **MapScope** keeps collect, live count, index filter, and prune aligned; **stdlib SQLite**; content-hash dirty
+- **Two path lists** — `map_paths.txt` = map package roots; `monitored_paths.txt` = wiki/health watch (**independent** — wiki file lists never collapse the map)
 - **Partial-map honesty** — `map_coverage` on `update_maps` / bootstrap / **`suggest_next`**; `update_maps_until_complete` when incomplete
-- **Cache ops** — `wikifier cache-status`; JSON dual-write **opt-in only** (`WIKIFIER_CACHE_JSON=1`); dual-read for migrate
-- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` alone
+- **Cache ops** — `wikifier cache-status`; JSON dual-write **deprecated default-off** (`WIKIFIER_CACHE_JSON=1` opt-in); dual-read for migrate
+- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` averages alone
 - **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
@@ -127,18 +137,21 @@ Full / heavy runs (historical order-of-magnitude):
 |---------|-------|----------------------------|
 | llama_index | ~3.8k Python files | ~8.5s class full |
 | Babylon.js | ~3.9k TS files, barrel-heavy | minutes full; scoped re-runs tens of seconds |
-| Large trees (e.g. LLVM-scale) | tens of thousands of files | use lean monitor + `--directory` / `--max-files` |
+| Large trees (e.g. LLVM-scale) | tens of thousands of files | `map_paths` / `--directory` / `--max-files` — never unscoped one-shot |
+
+Warm **0-dirty** re-runs after **4.6.7** (same machine class; scoped; candidates **reused** — agent session path):
 
-Warm **0-dirty** re-runs after 4.6.3 (same machine; scoped where noted) — agent session path:
+| Project | Scope | Warm `update-maps` | n |
+|---------|-------|--------------------|---|
+| Wikifier (self) | `map_paths`: `wikifier/` + `tests/` | **~30 ms** | 50 |
+| llama_index | `llama-index-core` | **~76 ms** | 724 |
+| rust | `library/std` | **~79 ms** | 719 |
+| airflow | `airflow-core` | **~180 ms** | 1920 |
+| Babylon.js | `packages` | **~400 ms** | 3895 |
 
-| Project | Scope | Warm2 `update-maps` |
-|---------|-------|---------------------|
-| Wikifier (self) | incremental full | ~43 ms |
-| redox | `src` | ~17 ms |
-| llama_index | `llama-index-core` | ~0.6 s |
-| rust | `library/std/src` (budgeted) | ~0.7 s (vs multi-second full-tree walk before scoped collect) |
+Residual floor on large scopes is mtime/stat + live count under MapScope (not full JSON re-walk). Sub-100ms is not a hard SLA on every 1k+ tree.
 
-Tests: `python -m unittest discover tests` (stdlib only; 86+ cases including agent-scale edges).
+Tests: `python -m unittest discover tests` (stdlib only; **125** cases including MapScope / index-first / dual-write).
 
 ## Commands
 
@@ -152,7 +165,8 @@ Tests: `python -m unittest discover tests` (stdlib only; 86+ cases including age
 | `wikifier mark-green <file>` | Mark wiki current + source content-hash baseline |
 | `wikifier record-deletion <file> "reason"` | Mark removed paths 🔴 + prune barrel refs |
 | `wikifier suggest-next` | Next actions (🔴/actionable 🟡 only; `--json` for `actions[]`) |
-| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` (warm 0-dirty is fast) |
+| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` (warm 0-dirty is fast; honors `map_paths.txt`) |
+| `wikifier cache-status` | SQLite/JSON backend, dual-write policy, coverage snapshot (no full pair load) |
 | `wikifier health [--summary\|--json]` | Health matrix (machine-friendly flags) |
 | `wikifier validate` | Missing wiki rows + ghost paths |
 | `wikifier cycles` | Circular deps + break hints |

{wikifier-4.6.7 → wikifier-4.6.9}/README.md

@@ -20,7 +20,14 @@ Works from small scripts to large monorepos. **Deep import/include maps** (zero-
 | 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.
+Health/journal still work for any monitored path. Parsers are **pragmatic regex** (not full cargo/`go.mod`/classpath/`-I` resolution). On huge monorepos, split scope deliberately:
+
+| File | Surface |
+|------|---------|
+| **`map_paths.txt`** | Package roots for **import maps** (`update-maps` walk). Prefer package dirs (`src/`, `packages/foo/`) — not a wiki-only file list. |
+| **`monitored_paths.txt`** | **Wiki / health** watch list (can be individual `.md` files). Does **not** define the map. |
+
+Or pass `--directory=pkg/` / `--max-files=N` per run. Raise dirty cap with `WIKIFIER_CHECK_CHANGES_MAX` (default 2000) only when needed. Never set `project_root` to a multi-repo parent of clones.
 
 ## Why
 
@@ -42,7 +49,8 @@ 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 init                   # seeds index.html + lean path-list templates
+# Edit monitored_paths.txt + map_paths.txt to package roots (not bare ".") on real trees
 wikifier update-maps            # full structural map → library.md + import cache
 wikifier health --summary       # matrix counts
 wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only
@@ -50,6 +58,8 @@ wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only
 
 Always set an explicit root for external trees: `WIKIFIER_PROJECT_ROOT=/abs/path wikifier …`
 
+**MCP `session_bootstrap` → `readiness: blocked`?** That means lean scope and/or the map are missing (often bare `.` monitor + never ran `update-maps`) — not a broken install. Fix: write lean `monitored_paths.txt` / `map_paths.txt`, then `update-maps`. Agent contract: **`skills/run.md`** § *Readiness blocked*; dogfood: `Findings/readiness-blocked-bare-monitor-2026-07.md`.
+
 ## Steady state (only touch what needs it)
 
 Full protocol: [`skills/run.md`](skills/run.md) (Agent Protocol v0.6 — package **4.6.x**).
@@ -77,11 +87,11 @@ Advanced intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`, ba
 
 - **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust (`use`/`mod` + best-effort `crate::` paths), Go, C/C++ includes, C# usings; per-edge confidence; barrel expansion for TS/JS
 - **Incremental pipeline** — pure-Python `update-maps`: dirty parse → import cache → reverse deps → cycles → `library.md`
-- **Warm agent maps (4.6.3–4.6.6)** — zero-dirty + **index-first** candidates (re-list only on fingerprint/index disagreement); **stdlib SQLite**; content-hash dirty
-- **Two path lists** — `map_paths.txt` = map package roots; `monitored_paths.txt` = wiki/health watch (independent)
+- **Warm agent maps (4.6.3–4.6.7)** — zero-dirty + **index-first** candidates (re-list only when fingerprint / map-scoped index / live count disagree); **MapScope** keeps collect, live count, index filter, and prune aligned; **stdlib SQLite**; content-hash dirty
+- **Two path lists** — `map_paths.txt` = map package roots; `monitored_paths.txt` = wiki/health watch (**independent** — wiki file lists never collapse the map)
 - **Partial-map honesty** — `map_coverage` on `update_maps` / bootstrap / **`suggest_next`**; `update_maps_until_complete` when incomplete
-- **Cache ops** — `wikifier cache-status`; JSON dual-write **opt-in only** (`WIKIFIER_CACHE_JSON=1`); dual-read for migrate
-- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` alone
+- **Cache ops** — `wikifier cache-status`; JSON dual-write **deprecated default-off** (`WIKIFIER_CACHE_JSON=1` opt-in); dual-read for migrate
+- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` averages alone
 - **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
@@ -95,18 +105,21 @@ Full / heavy runs (historical order-of-magnitude):
 |---------|-------|----------------------------|
 | llama_index | ~3.8k Python files | ~8.5s class full |
 | Babylon.js | ~3.9k TS files, barrel-heavy | minutes full; scoped re-runs tens of seconds |
-| Large trees (e.g. LLVM-scale) | tens of thousands of files | use lean monitor + `--directory` / `--max-files` |
+| Large trees (e.g. LLVM-scale) | tens of thousands of files | `map_paths` / `--directory` / `--max-files` — never unscoped one-shot |
+
+Warm **0-dirty** re-runs after **4.6.7** (same machine class; scoped; candidates **reused** — agent session path):
 
-Warm **0-dirty** re-runs after 4.6.3 (same machine; scoped where noted) — agent session path:
+| Project | Scope | Warm `update-maps` | n |
+|---------|-------|--------------------|---|
+| Wikifier (self) | `map_paths`: `wikifier/` + `tests/` | **~30 ms** | 50 |
+| llama_index | `llama-index-core` | **~76 ms** | 724 |
+| rust | `library/std` | **~79 ms** | 719 |
+| airflow | `airflow-core` | **~180 ms** | 1920 |
+| Babylon.js | `packages` | **~400 ms** | 3895 |
 
-| Project | Scope | Warm2 `update-maps` |
-|---------|-------|---------------------|
-| Wikifier (self) | incremental full | ~43 ms |
-| redox | `src` | ~17 ms |
-| llama_index | `llama-index-core` | ~0.6 s |
-| rust | `library/std/src` (budgeted) | ~0.7 s (vs multi-second full-tree walk before scoped collect) |
+Residual floor on large scopes is mtime/stat + live count under MapScope (not full JSON re-walk). Sub-100ms is not a hard SLA on every 1k+ tree.
 
-Tests: `python -m unittest discover tests` (stdlib only; 86+ cases including agent-scale edges).
+Tests: `python -m unittest discover tests` (stdlib only; **125** cases including MapScope / index-first / dual-write).
 
 ## Commands
 
@@ -120,7 +133,8 @@ Tests: `python -m unittest discover tests` (stdlib only; 86+ cases including age
 | `wikifier mark-green <file>` | Mark wiki current + source content-hash baseline |
 | `wikifier record-deletion <file> "reason"` | Mark removed paths 🔴 + prune barrel refs |
 | `wikifier suggest-next` | Next actions (🔴/actionable 🟡 only; `--json` for `actions[]`) |
-| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` (warm 0-dirty is fast) |
+| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` (warm 0-dirty is fast; honors `map_paths.txt`) |
+| `wikifier cache-status` | SQLite/JSON backend, dual-write policy, coverage snapshot (no full pair load) |
 | `wikifier health [--summary\|--json]` | Health matrix (machine-friendly flags) |
 | `wikifier validate` | Missing wiki rows + ghost paths |
 | `wikifier cycles` | Circular deps + break hints |

{wikifier-4.6.7 → wikifier-4.6.9}/skills/run.md

@@ -2,16 +2,17 @@
 
 **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; gap-closure contract 2026-07-09)  
+**Version**: v0.6 (v4.2.0 real-pipeline + reliability update; package current **4.6.x**, live `__version__` in `wikifier/__init__.py`)  
+**Date**: 2026-06-10 (package notes refreshed 2026-08-01; gap-closure contract 2026-07-09)  
 **Status**: Active. Supersedes v0.5.  
-**See also**: `README.md`, `Findings/gap-closure-report.md`, and the library in wikifier/.
+**See also**: `README.md`, `Findings/gap-closure-report.md`, `Findings/gap-amendment-plan-2026-08-01.md`, and the library in wikifier/.
 
-**Package 4.5.x + gap-closure notes (additive; protocol still v0.6):**
+**Package 4.6.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.
+- **First-run:** `init` → lean `monitored_paths.txt` + `map_paths.txt` (default active root `src/`, not bare `.`) → `update-maps` → `health --summary` → `suggest_next_actions`. Map is automatic; wiki *prose* is agent-filled over time.
+- **`session_bootstrap` readiness:** message embeds the readiness tier. `blocked` is not a crash — see **§ Readiness blocked**. Hard blockers = missing map/health (or severe ghosts). Bare `.` monitor alone → `map_ok_scope_risk` when map+health exist (scope warnings / fix_scope), not the same tier as missing map. Unattended ops require **`readiness=ready_for_daemon`**, not `health_score=Map Ready` alone.
 - **Map-first ≠ wiki-done:** `health_score` **Map Ready** + many 🟡 *Initial stubs* means structural coverage only. Do **not** bulk-wiki stubs. Wiki a file when you edit it, then `mark-green`. Prefer `actionable_yellow` / 🔴 over raw yellow counts.
-- **Steady-state selective work:** only 🔴 and *actionable* 🟡 (never re-wiki 🟢; never re-wiki the whole stub set). **ACS v1.3:** use `actionable_low_conf_edges` + `reason_code_counts` / `agent_signal` (`skip`|`investigate`). Do **not** thrash on raw `low_conf_edges` (includes external/bare scores ~0.48). Prefer `map_coverage.complete` / `files_remaining_dirty` after budgeted `update-maps` — `success: true` ≠ map complete.
+- **Steady-state selective work:** only 🔴 and *actionable* 🟡 (never re-wiki 🟢; never bulk-wiki Initial/map stubs). **ACS v1.3:** use `actionable_low_conf_edges` + `reason_code_counts` / `agent_signal` (`skip`|`investigate`). Do **not** thrash on raw `low_conf_edges` (includes external/bare scores ~0.48). Prefer `map_coverage.complete` / `map_ready` / `files_remaining_dirty` after budgeted `update-maps` — `success: true` ≠ map complete.
 - **Warm maps:** SQLite primary; zero-dirty uses mtime index + meta. **Index-first:** re-list candidates only when fingerprint / map-scoped index / live count disagree (`index_first_dirty` / `candidates_reused` on `update_maps`). Prefer `--directory=` or `map_paths.txt` package roots (not bare `.`). Collect, live count, index filter, and prune share **MapScope** so full-tree→`map_paths` narrow does not thrash.
 - **map_paths vs monitored_paths:** `map_paths.txt` = import-map package roots; `monitored_paths.txt` = wiki/health thrash bound. Independent. Wiki-only monitored lists do **not** define the map.
 - **Cache ops:** `wikifier cache-status`. Dual-write JSON **deprecated default-off** (`WIKIFIER_CACHE_JSON=1` to opt in). Dual-read legacy JSON for migrate remains.
@@ -45,8 +46,9 @@ Do **not** open megamodules (`javascript.py`, `import_cache.py`, `bree.py`) to d
 
 | Need | Use |
 |------|-----|
-| First-run map | `init` → `update-maps` → `health --summary` → `suggest-next` |
-| **Session start (4.6+)** | `session_bootstrap` (or CLI `session-bootstrap`) — one shot: root, health, attention, `actions[]` |
+| First-run map | `init` → lean paths (not bare `.`) → `update-maps` → `health --summary` → `suggest-next` |
+| **Session start (4.6+)** | `session_bootstrap` (or CLI `session-bootstrap`) — one shot: root, health, attention, `actions[]`. If `readiness` is `blocked`, fix `actions[]` / `blockers[]` first (usually scope + maps). |
+| **Unblock readiness** | Write lean `monitored_paths.txt` + `map_paths.txt` → `update_maps` (full once) → re-`session_bootstrap` until **`readiness=ready_for_daemon`** (not Map Ready alone) |
 | **Core tool list** | `list_core_tools` / bootstrap `core_surface` — prefer Core 6; advanced is non-core |
 | Steady-state | `check-changes` (content-honest) → edit 🔴/actionable 🟡 only → `record-change` → wiki → `mark-green` |
 | **Hash migration** | `seed_source_content_hashes` / CLI `seed-source-hashes` — baseline Greens without mass Yellow |
@@ -65,6 +67,74 @@ Do **not** open megamodules (`javascript.py`, `import_cache.py`, `bree.py`) to d
 **Scope:** `monitored_paths` = change detection; `exclude_patterns` + optional `--directory` = map walk.  
 **Human HTML** is secondary observation only.
 
+## Readiness blocked (`session_bootstrap` / external projects)
+
+When MCP `session_bootstrap` (or CLI `session-bootstrap`) returns:
+
+```text
+readiness: "blocked"
+scope.ok: false
+blockers: [ ... ]
+actions: [ { "action": "fix_scope", ... }, ... ]
+```
+
+**this is expected on a project that has never been scoped/mapped**, not a Wikifier install failure.
+
+### Readiness tiers (code truth — `assess_autonomous_readiness`)
+
+| Tier | When |
+|------|------|
+| `blocked` | Hard **blockers[]**: no import map and/or no file_health (or severe ghost flood). |
+| `map_ok_scope_risk` | Map+health present but **scope warnings** (often bare `.` monitor or multi-repo parent) and clean red/actionable yellow. |
+| `ready_for_daemon` | Map Ready/Good **and** not bare_dot_monitor — only safe unattended tier. |
+| `ready_with_agent_wiki_work` | Needs Attention, red=0 — daemon OK but agents still have wiki work. |
+| `not_ready` | Other (e.g. reds). |
+
+Bare `.` is a **scope warning** (`scope.warnings` / `fix_scope`), not always a hard blocker. Missing map/health **are** hard blockers and emit priority-1 `update_maps` / `seed_health` in `actions[]`.
+
+### Why it happens (Grok-Bevy 2026-07 dogfood)
+
+On **Grok-Bevy** (Rust workspace), first bootstrap reported:
+
+| Signal | Field / tier | Meaning |
+|--------|--------------|---------|
+| `No import map (run update-maps first)` | `blockers[]` → `blocked` | No dependency/import map yet. Action: **`update_maps`**. |
+| `No file_health` | `blockers[]` → `blocked` | Health matrix not seeded. Action: **`seed_health` / update-maps**. |
+| `monitored_paths is bare '.'` | `scope.warnings` (often `map_ok_scope_risk` once map exists) | check-changes thrash risk. Action: **`fix_scope`**. |
+
+Also: `bare_dot_monitor: true` and `scope.ok: false` until `monitored_paths.txt` lists **lean package roots**, not bare `.`.
+
+### Fix once per project (agents must do this, not ignore blockers)
+
+1. **Scope (wiki/health thrash bound)** — create/edit **`monitored_paths.txt`** at project root with *specific* dirs/files, e.g.:
+   ```text
+   crates/foo/src/
+   crates/bar/src/
+   README.md
+   docs/
+   ```
+   Never leave only `.` on non-tiny trees.
+2. **Map roots** — create/edit **`map_paths.txt`** (import-map package roots; independent of monitored):
+   ```text
+   crates/foo/src/
+   crates/bar/src/
+   ```
+3. **Build map + health** — from the target project (or with `project_root=` / `WIKIFIER_PROJECT_ROOT=`):
+   ```bash
+   wikifier update-maps --full    # or MCP update_maps full=true
+   # re-run session_bootstrap until readiness == ready_for_daemon
+   ```
+4. **Do not** bulk-re-wiki 🟡 *Initial stubs* after maps land — stubs = map coverage only.
+
+After a successful fix, bootstrap looks like: `scope.ok: true`, `blockers: []`, `health_score: Map Ready` (stubs OK), **`readiness: ready_for_daemon`**. Map Ready without `ready_for_daemon` is **not** unattended-ready.
+
+### Product note for Wikifier maintainers
+
+- Default bare `.` is a footgun for real repos; agents must treat **`fix_scope` as P0** when scope warns bare-dot, and **update_maps/seed_health as P0** when readiness is `blocked`.
+- **`wikifier init` (4.6.8+ / 4.6.9 templates)** seeds comment-guided lean templates with active default **`src/`** (bare `.` is commented opt-in for tiny toys only). Multi-crate / monorepo agents must replace with package roots before map-ready work.
+
+See also: Findings note `Findings/readiness-blocked-bare-monitor-2026-07.md`.
+
 ## 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:**
@@ -74,7 +144,7 @@ You are now operating inside a Wikifier-managed codebase (Agent Protocol v0.6
 
 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.
 
-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. check-changes is content-honest (mtime-only thrash does not re-Yellow when source hash matches mark-green baseline).
+SELECTIVE WORK (mandatory): Only update/remove/re-wiki 🔴 Red and *actionable* 🟡 Yellow files. Do **not** re-summarize 🟢 Green files, and do **not** bulk-wiki 🟡 Initial/map stubs (map coverage only — wiki a stub only when you edit that file). First-run builds the structural map; wiki depth is filled as you touch files. check-changes is content-honest (mtime-only thrash does not re-Yellow when source hash matches mark-green baseline).
 
 FIRST ACTIONS:
 1. Prefer MCP Core: session_bootstrap, check_changes, prepare_edit, suggest_next_actions (use actions[]), record_change, mark_green. Always pass project_root= for external projects.
@@ -131,10 +201,11 @@ However, if you are doing low-level direct writes to Wikifier state files (e.g.
 ### Limitations (Final M2-Rem-07 Assessment)
 - Locks are **advisory** — a broken or malicious process can ignore them.
 - Currently **project-level** (one lock for the entire project). This is the right tradeoff for current needs (including heavy multi-agent + monitor dogfooding) and keeps the implementation simple and fast.
-- Non-blocking / timeout queries and per-file locking are not implemented yet (advanced agents can use `wikifier.locking.is_project_locked()` for diagnostics).
+- **Finite timeout** is supported: `file_lock(root, timeout=seconds)` raises `LockTimeoutError` if the lock is not free in time (`timeout=None` still blocks). `is_project_locked()` remains a diagnostic non-blocking probe.
+- Per-file / sharded locking is a permanent non-goal unless extreme concurrency pressure appears.
 - Best-effort portability on non-Unix systems.
 
-The locking system (Python `file_lock` + shell `with_project_lock`) has received final polish. It is now considered production-ready for the M2 scope. Future extensions (fine-grained locking) can be added when real usage pressure appears on extremely large concurrent setups.
+The locking system (Python `file_lock` + shell `with_project_lock`) is production-ready for the M2 scope.
 
 ## Protocol v0.4 Additions: I/O Contracts, Error Handling, Structured Output, Versioning
 
@@ -168,7 +239,7 @@ Pending/journal/health side effects are observable via the returned messages + d
 ### Error Handling Expectations
 - **Operational failures** (e.g., partial scan on huge tree, lock edge): return `{"success": False, "error": "...", "project_root": "...", ...partial_data }`. Agent must handle gracefully and log; continue where safe.
 - **Programming / contract errors** (bad types, missing required): raise (standard Python exceptions) — these indicate agent bug.
-- **Locking**: Mutators block on project lock (production default). Future non-blocking/timeout will be additive.
+- **Locking**: Mutators block on project lock by default; optional finite `timeout=` raises on contention.
 - Never assume text output parsability. Always use structured returns + explicit format="json".
 - On external/packaged installs: discovery is robust; pass explicit project_root if cwd is ambiguous.
 
@@ -219,7 +290,7 @@ This project exposes a first-class MCP server (wikifier-mcp or python -m wikifie
 
 **M5.1+ reality (from dogfood on external 5k-79k+ projects)**: MCP tools are preferred when available (get_project_status, get_file_wiki, get_barrel_reports for deep BRC, check_changes, record_change, mark_green, suggest_next_actions, health equivalents, etc.). **Always pass project_root= (or use WIKIFIER_PROJECT_ROOT env)** for external/user projects (RecipeLab_alt BRC stress, ConsistencyHub, llvm subs, etc.). 
 
-MCP timeouts are rare since v4.2.0 (the library workflow-call deadlock is fixed and barrel persistence is batched), but on very large/BRC-heavy targets they can still happen. In that case, **immediately fall back to CLI/library** (python -m wikifier health --summary or the library health(..., format="summary")) — these are reliable and were the workhorse in M5 sustained/monitor work.
+**CLI-at-scale policy (G15):** On barrel-heavy or large monorepos (BRC stress, multi-k source trees), treat **CLI/library as the primary reliability path** for `update_maps`, barrel reports, and long health/suggest loops. MCP subprocess tools use a ~60s cap and may still time out; that is **not** a product failure — **immediately fall back** to `python -m wikifier …` / library calls. Do not claim DoD2 (<30s MCP on alt/Consistency/llama) closed without a fresh measured pack; default operator policy is CLI for scale.
 
 The server implements hardened external discovery (delegates to cli.py discover_project_root / _get_effective_root), 60s timeouts, actionable errors, and parity with library.
 

wikifier-4.6.9/tests/test_gap_amendment_2026_08.py

@@ -0,0 +1,238 @@
+"""Real-path tests for gap amendment plan G1–G13/G15 closed-when bars.
+
+Drives shipped library functions (session_bootstrap, build_structured_actions,
+file_lock, build_map_coverage / run_full_update, library ACS section, protocol
+strings). No theater: asserts against live code outputs.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+import unittest
+
+from tests._base import REPO_ROOT, TempProjectTestCase
+
+from wikifier import __version__
+from wikifier.agent_loop import build_structured_actions, session_bootstrap
+from wikifier import cli
+from wikifier import locking
+from wikifier.library import _generate_acs_section
+
+health_mod = importlib.import_module("wikifier.health")
+
+
+class TestProtocolVersionPointers(unittest.TestCase):
+    """G1: operator package pointers match live major.minor."""
+
+    def test_version_is_4_6(self):
+        self.assertTrue(
+            __version__.startswith("4.6."),
+            f"expected 4.6.x package, got {__version__}",
+        )
+
+    def test_skills_run_header_not_4_5(self):
+        text = (REPO_ROOT / "skills" / "run.md").read_text(encoding="utf-8")
+        # Header / package-notes must not claim current 4.5.x
+        first_30 = "\n".join(text.splitlines()[:30])
+        self.assertNotIn("package current **4.5.x**", first_30)
+        self.assertIn("4.6.x", first_30)
+        # SELECTIVE WORK excludes Initial stubs (G3)
+        self.assertIn("actionable", text)
+        self.assertIn("Initial", text)
+        self.assertRegex(
+            text,
+            r"SELECTIVE WORK.*actionable.*Initial",
+        )
+        # G15 CLI-at-scale policy present
+        self.assertIn("CLI-at-scale policy", text)
+        # G8 ready_for_daemon not Map Ready alone
+        self.assertIn("ready_for_daemon", text)
+        self.assertIn("not Map Ready alone", text)
+
+    def test_claude_md_not_4_5(self):
+        for name in ("Claude.md", "CLAUDE.md"):
+            p = REPO_ROOT / name
+            if not p.is_file():
+                continue
+            t = p.read_text(encoding="utf-8")
+            self.assertNotIn("currently 4.5.x", t)
+            self.assertIn("4.6.x", t)
+
+
+class TestBootstrapMessageAndActions(TempProjectTestCase):
+    """G2/G5/G6: bootstrap message + blocker actions."""
+
+    def test_bootstrap_message_blocked_never_says_ready(self):
+        # Fresh temp root: no cache, no health → blocked
+        boot = session_bootstrap(project_root=self.root)
+        self.assertTrue(boot.get("success"))
+        readiness = boot.get("readiness")
+        msg = str(boot.get("message") or "")
+        if readiness == "blocked":
+            self.assertIn("readiness=blocked", msg)
+            self.assertNotRegex(msg, r"^session_bootstrap ready")
+            self.assertNotIn("session_bootstrap ready —", msg)
+        # Always embeds readiness=
+        self.assertIn("readiness=", msg)
+
+    def test_blockers_produce_priority_leq_2_map_or_health(self):
+        acts = build_structured_actions(
+            blockers=[
+                "No import map (run update-maps first).",
+                "No file_health — run seed-health or update-maps.",
+            ],
+            scope_warnings=["monitored_paths is bare '.' — thrash risk"],
+            red=0,
+            actionable_yellow=0,
+            clean=True,
+        )
+        kinds = {a["action"] for a in acts}
+        self.assertIn("update_maps", kinds)
+        self.assertIn("seed_health", kinds)
+        self.assertIn("fix_scope", kinds)
+        for a in acts:
+            if a["action"] in ("update_maps", "seed_health"):
+                self.assertLessEqual(int(a["priority"]), 2, a)
+            if a["action"] == "fix_scope":
+                self.assertLessEqual(int(a["priority"]), 2, a)
+
+    def test_map_incomplete_action_priority(self):
+        acts = build_structured_actions(
+            map_coverage={
+                "complete": False,
+                "files_remaining_dirty": 12,
+                "files_skipped": 12,
+                "budget_max_files": 5,
+            },
+            red=0,
+            actionable_yellow=0,
+        )
+        incomplete = [a for a in acts if a["action"] == "update_maps_until_complete"]
+        self.assertTrue(incomplete)
+        self.assertLessEqual(int(incomplete[0]["priority"]), 2)
+        self.assertIn("success alone", incomplete[0]["reason"].lower())
+
+    def test_stub_only_map_first_ok_no_wiki_refresh(self):
+        acts = build_structured_actions(
+            stub_yellow=100,
+            actionable_yellow=0,
+            red=0,
+            actionable_yellow_files=[],
+            clean=False,
+        )
+        kinds = {a["action"] for a in acts}
+        self.assertIn("map_first_ok", kinds)
+        self.assertNotIn("wiki_refresh", kinds)
+
+
+class TestMapCoverageHonesty(TempProjectTestCase):
+    """G5: update_maps surfaces map_complete / map_ready."""
+
+    def test_run_full_update_exposes_map_ready_flags(self):
+        self.write("pkg/a.py", "import os\n")
+        (self.root / "monitored_paths.txt").write_text("pkg/\n", encoding="utf-8")
+        (self.root / "map_paths.txt").write_text("pkg/\n", encoding="utf-8")
+        res = cli.run_full_update(root=self.root, directory="pkg/")
+        self.assertTrue(res.get("success"), res)
+        self.assertIn("map_coverage", res)
+        self.assertIn("map_complete", res)
+        self.assertIn("map_ready", res)
+        # map_ready must track complete + remaining dirty
+        mc = res["map_coverage"]
+        expected_ready = bool(mc.get("complete")) and int(
+            mc.get("files_remaining_dirty") or 0
+        ) == 0
+        self.assertEqual(res["map_ready"], expected_ready)
+        self.assertEqual(res["map_complete"], bool(mc.get("complete")))
+
+    def test_budgeted_max_files_incomplete_flags(self):
+        for i in range(6):
+            self.write(f"src/m{i}.py", f"x={i}\n")
+        (self.root / "monitored_paths.txt").write_text("src/\n", encoding="utf-8")
+        (self.root / "map_paths.txt").write_text("src/\n", encoding="utf-8")
+        res = cli.run_full_update(
+            root=self.root, directory="src/", max_files=2
+        )
+        self.assertTrue(res.get("success"), res)
+        self.assertIn("map_coverage", res)
+        # With budget, remaining dirty may be > 0
+        rem = int((res.get("map_coverage") or {}).get("files_remaining_dirty") or 0)
+        if rem > 0 or (res.get("map_coverage") or {}).get("complete") is False:
+            self.assertFalse(res.get("map_ready"))
+            acts = build_structured_actions(map_coverage=res["map_coverage"])
+            self.assertTrue(
+                any(a["action"] == "update_maps_until_complete" for a in acts)
+            )
+
+
+class TestLockTimeout(TempProjectTestCase):
+    """G13: file_lock honors finite timeout."""
+
+    def test_timeout_raises_when_held(self):
+        """Hold exclusive lock on a second fd; finite timeout must raise (G13)."""
+        if locking.fcntl is None:
+            self.skipTest("fcntl not available")
+        lock_path = self.root / locking.LOCK_FILE_NAME
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        holder_fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR, 0o644)
+        try:
+            locking.fcntl.flock(holder_fd, locking.fcntl.LOCK_EX)
+            contender_fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR, 0o644)
+            try:
+                with self.assertRaises(locking.LockTimeoutError):
+                    locking._acquire_exclusive(contender_fd, 0.25)
+            finally:
+                os.close(contender_fd)
+        finally:
+            locking.fcntl.flock(holder_fd, locking.fcntl.LOCK_UN)
+            os.close(holder_fd)
+
+    def test_reentrant_still_works(self):
+        with locking.file_lock(self.root):
+            with locking.file_lock(self.root):
+                pass  # nested re-entrant
+
+
+class TestAcsLibrarySection(unittest.TestCase):
+    """G9: library ACS prefers actionable."""
+
+    def test_acs_section_prefers_actionable(self):
+        cache = {
+            "_acs_summary": {
+                "total_scored_edges": 100,
+                "avg_confidence": 0.7,
+                "low_conf_edges": 40,
+                "actionable_low_conf_edges": 5,
+                "low_conf_threshold": 0.65,
+                "reason_code_counts": {
+                    "external_or_bare": 30,
+                    "unresolved_project": 5,
+                },
+                "sample_low_conf_explanations": ["raw sample"],
+            }
+        }
+        lines = _generate_acs_section(cache)
+        text = "\n".join(lines)
+        self.assertIn("actionable_low_conf", text)
+        self.assertIn("reason_code_counts", text)
+        self.assertIn("thrash", text.lower())
+        self.assertIn("actionable_low_conf_edges", text)
+        self.assertIn("actionable", text.lower())
+
+
+class TestReadinessTiersDocShape(TempProjectTestCase):
+    """G4: readiness tiers match code for missing map/health."""
+
+    def test_no_map_is_blocked(self):
+        ready = health_mod.assess_autonomous_readiness(self.root)
+        self.assertEqual(ready.get("readiness"), "blocked")
+        blockers = " ".join(ready.get("blockers") or [])
+        self.assertTrue(
+            "import map" in blockers.lower() or "file_health" in blockers.lower(),
+            blockers,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()