wikifier 4.6.8__tar.gz → 4.6.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.6.8
+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

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

@@ -2,17 +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` → lean `monitored_paths.txt` + `map_paths.txt` (not bare `.`) → `update-maps` → `health --summary` → `suggest_next_actions`. Map is automatic; wiki *prose* is agent-filled over time.
-- **`session_bootstrap` readiness `blocked`:** not a crash — see **§ Readiness blocked** below. Typical causes: bare `.` monitor and/or no map/health yet. Fix scope → `update-maps` before treating the project as map-ready.
+- **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.
@@ -48,7 +48,7 @@ Do **not** open megamodules (`javascript.py`, `import_cache.py`, `bree.py`) to d
 |------|-----|
 | 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 `ready_for_daemon` / Map Ready |
+| **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 |
@@ -80,15 +80,27 @@ 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:
 
-| Blocker | Meaning |
-|---------|---------|
-| `monitored_paths is bare '.'` | Default/missing lean list → `check-changes` would walk the whole tree (`target/`, caches, etc.) and thrash. Action: **`fix_scope`**. |
-| `No import map (run update-maps first)` | No dependency/import map yet → map-first tools have nothing to trust. |
-| `No file_health` | Health matrix not seeded (comes with map/health pipeline). |
+| 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 `.`.
 
@@ -110,16 +122,16 @@ Also: `bare_dot_monitor: true` and `scope.ok: false` until `monitored_paths.txt`
 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 is ready_for_daemon / Map Ready
+   # 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`.
+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 convenient for tiny toys and a footgun for real repos; agents must treat **`fix_scope` as P0** when `session_bootstrap` says blocked.
-- **`wikifier init` (4.6.8+)** seeds comment-guided lean templates for `monitored_paths.txt` and `map_paths.txt` (examples for `src/`, `crates/*/src/`, etc.) instead of a silent single-dot file. Tiny toys may keep `.`; multi-crate / monorepo agents must replace with package roots before map-ready work.
+- 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`.
 
@@ -132,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.
@@ -189,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
 
@@ -226,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.
 
@@ -277,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()

{wikifier-4.6.8 → wikifier-4.6.9}/tests/test_init_seed.py

@@ -64,13 +64,22 @@ class TestInitSeedTemplates(TempProjectTestCase):
             r"(?i)(lean|package root|thrash|map_paths)",
             "monitored_paths.txt should mention lean roots / thrash / map_paths",
         )
-        # Active path may still be bare "." for tiny toys, but only with comments above.
+        # G7: active default is lean src/ — bare "." is opt-in comment only.
         active_mon = [
             ln.strip()
             for ln in mon_text.splitlines()
             if ln.strip() and not ln.strip().startswith("#")
         ]
         self.assertTrue(active_mon, "expected at least one non-comment monitored path")
+        self.assertNotIn(
+            ".",
+            active_mon,
+            "monitored_paths must not activate bare '.' by default (opt-in comment only)",
+        )
+        self.assertTrue(
+            any(p == "src/" or p == "src" for p in active_mon),
+            f"expected lean src/ active default, got {active_mon}",
+        )
 
         self.assertIn("#", map_text, "map_paths.txt must include guidance comments")
         self.assertRegex(

{wikifier-4.6.8 → wikifier-4.6.9}/wikifier/__init__.py

@@ -79,4 +79,4 @@ from .contracts import (
     compute_acs_confidence,
 )
 
-__version__ = "4.6.8"
+__version__ = "4.6.9"

{wikifier-4.6.8 → wikifier-4.6.9}/wikifier/agent_loop.py

@@ -174,6 +174,7 @@ def build_structured_actions(
     red: int = 0,
     acs_actionable: int = 0,
     scope_warnings: Optional[List[str]] = None,
+    blockers: Optional[List[str]] = None,
     clean: bool = False,
     max_file_actions: int = 12,
     map_coverage: Optional[Dict[str, Any]] = None,
@@ -181,18 +182,56 @@ def build_structured_actions(
     """Build dispatchable action objects for agents (not prose-only).
 
     Each item: action, file?, priority (1=highest), reason, optional preflight.
+    Priority ≤2 is reserved for readiness blockers (scope + missing map/health).
     """
     actions: List[Dict[str, Any]] = []
-    prio = 1
+    prio = 3  # file work starts after readiness fix actions (priority 1–2)
     cov = map_coverage if isinstance(map_coverage, dict) else {}
     remaining = int(cov.get("files_remaining_dirty") or 0)
     complete = cov.get("complete")
-    # Incomplete map under budget — higher priority than ACS thrash
+    blocker_list = [str(b) for b in (blockers or []) if b]
+    # G6: missing map / file_health always get priority ≤2
+    for b in blocker_list:
+        bl = b.lower()
+        # Prefer seed_health before generic update-maps (blocker text often mentions both)
+        if "file_health" in bl or "seed-health" in bl or "seed_health" in bl:
+            actions.append({
+                "action": "seed_health",
+                "file": None,
+                "priority": 1,
+                "reason": b,
+                "preflight": ["seed_health", "update_maps"],
+            })
+        elif "import map" in bl or "update-maps" in bl or "update_maps" in bl:
+            actions.append({
+                "action": "update_maps",
+                "file": None,
+                "priority": 1,
+                "reason": b,
+                "preflight": ["update_maps"],
+            })
+        else:
+            actions.append({
+                "action": "fix_blocker",
+                "file": None,
+                "priority": 2,
+                "reason": b,
+                "preflight": [],
+            })
+    for w in (scope_warnings or [])[:3]:
+        actions.append({
+            "action": "fix_scope",
+            "file": None,
+            "priority": 2,
+            "reason": str(w),
+            "preflight": [],
+        })
+    # Incomplete map under budget — agents must not treat success alone as done (G5)
     if complete is False or remaining > 0:
         actions.append({
             "action": "update_maps_until_complete",
             "file": None,
-            "priority": 3,
+            "priority": 2,
             "reason": (
                 f"Map incomplete: files_remaining_dirty={remaining}, complete={complete}. "
                 "Re-run update_maps (same directory/max_files) until map_coverage.complete=true; "
@@ -224,7 +263,7 @@ def build_structured_actions(
             "preflight": ["prepare_edit", "why_file"],
         })
         prio = min(prio + 1, 9)
-    if red == 0 and actionable_yellow == 0 and clean and remaining == 0:
+    if red == 0 and actionable_yellow == 0 and clean and remaining == 0 and not blocker_list:
         actions.append({
             "action": "lookup_only",
             "file": None,
@@ -232,12 +271,16 @@ def build_structured_actions(
             "reason": "Health clean — do not re-summarize tree; use prepare_edit/get_file_wiki for lookup",
             "preflight": [],
         })
+    # G10: stub-only yellows are map coverage — never bulk wiki_refresh
     if stub_yellow > 0 and actionable_yellow == 0 and red == 0:
         actions.append({
             "action": "map_first_ok",
             "file": None,
             "priority": 6,
-            "reason": f"{stub_yellow} Initial stubs are map coverage only — not bulk wiki work",
+            "reason": (
+                f"{stub_yellow} Initial stubs are map coverage only — not bulk wiki work. "
+                "Wiki a file only when you edit it, then mark-green."
+            ),
             "preflight": [],
         })
     if acs_actionable > 0:
@@ -251,16 +294,12 @@ def build_structured_actions(
             ),
             "preflight": ["get_dependencies"],
         })
-    for w in (scope_warnings or [])[:2]:
-        actions.append({
-            "action": "fix_scope",
-            "file": None,
-            "priority": 2,
-            "reason": str(w),
-            "preflight": [],
-        })
     if not any(
-        a["action"] in ("update_maps", "update_maps_until_complete", "update_maps_if_structure")
+        a["action"] in (
+            "update_maps",
+            "update_maps_until_complete",
+            "update_maps_if_structure",
+        )
         for a in actions
     ):
         actions.append({
@@ -639,6 +678,7 @@ def session_bootstrap(
         scope_warnings = list(out["scope"].get("warnings") or [])
 
     map_cov = out.get("map_coverage") if isinstance(out.get("map_coverage"), dict) else {}
+    blockers = list(out.get("blockers") or [])
     out["actions"] = build_structured_actions(
         red_files=red_files,
         actionable_yellow_files=actionable_yellow_files,
@@ -647,6 +687,7 @@ def session_bootstrap(
         red=red_n,
         acs_actionable=acs_actionable,
         scope_warnings=scope_warnings,
+        blockers=blockers,
         clean=clean,
         map_coverage=map_cov,
     )
@@ -654,13 +695,51 @@ def session_bootstrap(
     out["selective_work"] = True
     out["map_first"] = True
     rem = int(map_cov.get("files_remaining_dirty") or 0) if map_cov else 0
-    out["message"] = (
-        "session_bootstrap ready — use actions[] / attention; "
-        "prepare_edit(file) before large edits; record_change after edits."
-        + (
-            f" MAP INCOMPLETE: files_remaining_dirty={rem} — re-run update_maps until complete."
-            if rem > 0 or map_cov.get("complete") is False
-            else ""
+    readiness = out.get("readiness") or "unknown"
+    map_incomplete = rem > 0 or map_cov.get("complete") is False
+    # G2: never claim "ready" when readiness is blocked
+    if readiness == "blocked":
+        out["message"] = (
+            f"session_bootstrap readiness=blocked — fix actions[] / blockers[] first "
+            f"(typically fix_scope + update_maps / seed_health); do not treat project as map-ready."
+            + (
+                f" MAP INCOMPLETE: files_remaining_dirty={rem}."
+                if map_incomplete
+                else ""
+            )
+        )
+    elif readiness == "map_ok_scope_risk":
+        out["message"] = (
+            f"session_bootstrap readiness=map_ok_scope_risk — map/health present but scope risk "
+            f"(often bare '.' monitor); fix_scope before unattended daemon. "
+            f"Use actions[] / attention; prepare_edit(file) before large edits; record_change after."
+            + (
+                f" MAP INCOMPLETE: files_remaining_dirty={rem} — re-run update_maps until "
+                f"map_coverage.complete=true."
+                if map_incomplete
+                else ""
+            )
+        )
+    elif readiness == "ready_for_daemon":
+        out["message"] = (
+            "session_bootstrap readiness=ready_for_daemon — use actions[] / attention; "
+            "prepare_edit(file) before large edits; record_change after edits."
+            + (
+                f" MAP INCOMPLETE: files_remaining_dirty={rem} — re-run update_maps until "
+                f"map_coverage.complete=true (success alone is not map-ready)."
+                if map_incomplete
+                else ""
+            )
+        )
+    else:
+        out["message"] = (
+            f"session_bootstrap readiness={readiness} — use actions[] / attention; "
+            "prepare_edit(file) before large edits; record_change after edits. "
+            "Unattended ops require readiness=ready_for_daemon (not Map Ready alone)."
+            + (
+                f" MAP INCOMPLETE: files_remaining_dirty={rem} — re-run update_maps until complete."
+                if map_incomplete
+                else ""
+            )
         )
-    )
     return out

{wikifier-4.6.8 → wikifier-4.6.9}/wikifier/cli.py

@@ -424,6 +424,11 @@ def run_full_update(
                 cache_backend=backend,
                 directory=directory,
             )
+            _mc0 = result["map_coverage"] if isinstance(result["map_coverage"], dict) else {}
+            result["map_complete"] = bool(_mc0.get("complete"))
+            result["map_ready"] = bool(_mc0.get("complete")) and int(
+                _mc0.get("files_remaining_dirty") or 0
+            ) == 0
             try:
                 if cs is not None:
                     cs.save_meta_key(root, "_map_coverage", result["map_coverage"])
@@ -669,6 +674,10 @@ def run_full_update(
             cache_backend=backend,
             directory=directory,
         )
+        # G5: success alone is not map-ready — surface complete flag at top level
+        _mc = result["map_coverage"] if isinstance(result["map_coverage"], dict) else {}
+        result["map_complete"] = bool(_mc.get("complete"))
+        result["map_ready"] = bool(_mc.get("complete")) and int(_mc.get("files_remaining_dirty") or 0) == 0
         try:
             cache["_map_coverage"] = result["map_coverage"]
             if cands:

{wikifier-4.6.8 → wikifier-4.6.9}/wikifier/library.py

@@ -312,6 +312,7 @@ def _generate_cycles_section(cache: Dict[str, Any]) -> List[str]:
 # ---------------------------------------------------------------------------
 
 def _generate_acs_section(cache: Dict[str, Any]) -> List[str]:
+    """ACS section for library.md — prefer actionable + reason codes (G9)."""
     lines = ["## ACS Risk Snapshot", ""]
     acs = cache.get("_acs_summary") or {}
     if not isinstance(acs, dict) or not acs.get("total_scored_edges"):
@@ -319,17 +320,48 @@ def _generate_acs_section(cache: Dict[str, Any]) -> List[str]:
                      "to score edge confidence.)")
         lines.append("")
         return lines
-    lines.append("**Scored edges**: {0} | **avg_confidence**: {1} | **low-confidence**: {2}"
-                 " (threshold {3})".format(
-                     acs.get("total_scored_edges"), acs.get("avg_confidence"),
-                     acs.get("low_conf_edges", 0), acs.get("low_conf_threshold", 0.65)))
+    actionable = acs.get("actionable_low_conf_edges")
+    if actionable is None:
+        actionable = acs.get("low_conf_edges", 0)
+    lines.append(
+        "**Scored edges**: {0} | **avg_confidence**: {1} | "
+        "**actionable_low_conf**: {2} | raw low-conf (telemetry): {3} "
+        "(threshold {4})".format(
+            acs.get("total_scored_edges"),
+            acs.get("avg_confidence"),
+            actionable,
+            acs.get("low_conf_edges", 0),
+            acs.get("low_conf_threshold", 0.65),
+        )
+    )
+    lines.append(
+        "**Agent work queue**: use `actionable_low_conf_edges` + "
+        "`reason_code_counts` / `agent_signal=investigate` only — "
+        "do **not** thrash on raw `low_conf_edges` (includes external/bare)."
+    )
+    rcc = acs.get("reason_code_counts") or {}
+    if isinstance(rcc, dict) and rcc:
+        lines.append(
+            "**reason_code_counts**: "
+            + ", ".join("{0}:{1}".format(k, v) for k, v in list(rcc.items())[:8])
+        )
     top_reasons = acs.get("top_risk_reasons") or {}
     if top_reasons:
         lines.append("**Top risk reasons**: " + ", ".join(
             "{0}:{1}".format(k, v) for k, v in list(top_reasons.items())[:4]))
-    samples = acs.get("sample_low_conf_explanations") or []
+    # Prefer actionable samples when present
+    samples = (
+        acs.get("sample_actionable_explanations")
+        or acs.get("sample_low_conf_explanations")
+        or []
+    )
     if samples:
-        lines.append("**Sample low-confidence edges**:")
+        label = (
+            "Sample actionable edges"
+            if acs.get("sample_actionable_explanations")
+            else "Sample low-confidence edges (telemetry; prefer actionable)"
+        )
+        lines.append("**{0}**:".format(label))
         for i, sample in enumerate(samples[:3], 1):
             lines.append("  {0}. {1}".format(i, sample))
     lines.append("")

{wikifier-4.6.8 → wikifier-4.6.9}/wikifier/locking.py

@@ -47,14 +47,18 @@ Limitations (Honest Assessment)
 -------------------------------
 - Advisory only.
 - Project-level (not per-file or per-agent yet).
-- Non-blocking check / timeout is not yet implemented (current behavior = blocking acquire).
-- Fine-grained (per-file) or sharded locking is a planned future extension for extreme concurrency on very large codebases.
+- Finite ``timeout`` (seconds) is honored on Unix (non-blocking poll loop);
+  ``timeout=None`` still blocks until free. Per-file / sharded locks remain
+  out of scope for M2 scale.
+- Fine-grained (per-file) locking is a permanent non-goal unless extreme
+  concurrency pressure appears on very large multi-agent setups.
 
 For the current scale (including heavy multi-agent dogfooding), project-level
 advisory locking is sufficient, safe, and has been battle-tested.
 """
 
 import os
+import time
 from contextlib import contextmanager
 from pathlib import Path
 from typing import Optional
@@ -79,6 +83,57 @@ LOCK_FILE_NAME = ".wikifier_staging/.lock"
 _HELD_LOCKS: dict = {}  # {resolved_root_str: {"fd": int, "depth": int}}
 
 
+class LockTimeoutError(TimeoutError):
+    """Raised when file_lock cannot acquire within the given timeout."""
+
+
+def _acquire_exclusive(lock_fd: int, timeout: Optional[float]) -> None:
+    """Acquire exclusive lock; honor finite timeout on Unix (G13)."""
+    if fcntl is not None:
+        if timeout is None:
+            fcntl.flock(lock_fd, fcntl.LOCK_EX)
+            return
+        if timeout < 0:
+            raise ValueError("timeout must be None or >= 0")
+        deadline = time.monotonic() + float(timeout)
+        while True:
+            try:
+                fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                return
+            except (BlockingIOError, OSError):
+                if time.monotonic() >= deadline:
+                    raise LockTimeoutError(
+                        "project lock not acquired within {0}s".format(timeout)
+                    )
+                # Short sleep to avoid busy-spin; remaining time may be < sleep.
+                remaining = deadline - time.monotonic()
+                time.sleep(min(0.05, max(0.001, remaining)))
+    elif msvcrt is not None:
+        # Windows: LK_LOCK retries ~10s then OSError; loop for blocking.
+        if timeout is None:
+            while True:
+                try:
+                    os.lseek(lock_fd, 0, os.SEEK_SET)
+                    msvcrt.locking(lock_fd, msvcrt.LK_LOCK, 1)
+                    return
+                except OSError:
+                    continue
+        deadline = time.monotonic() + float(timeout)
+        while True:
+            try:
+                os.lseek(lock_fd, 0, os.SEEK_SET)
+                msvcrt.locking(lock_fd, msvcrt.LK_NBLCK, 1)
+                return
+            except OSError:
+                if time.monotonic() >= deadline:
+                    raise LockTimeoutError(
+                        "project lock not acquired within {0}s".format(timeout)
+                    )
+                remaining = deadline - time.monotonic()
+                time.sleep(min(0.05, max(0.001, remaining)))
+    # If neither primitive exists, proceed unlocked (advisory best-effort).
+
+
 @contextmanager
 def file_lock(root: Path, timeout: Optional[float] = None):
     """
@@ -86,13 +141,15 @@ def file_lock(root: Path, timeout: Optional[float] = None):
 
     This is the primary locking primitive used by health.py and import_cache.py.
 
-    Behavior: blocking acquire (waits until the lock is free), re-entrant
-    within the same process (nested acquires on the same root are refcounted).
-    Timeout support is planned for a future iteration.
+    Behavior: blocking acquire when ``timeout is None``; with a finite
+    ``timeout`` (seconds) raises ``LockTimeoutError`` if the lock is not free
+    in time. Re-entrant within the same process (nested acquires refcounted).
 
     Usage (agents rarely need this directly):
         with file_lock(Path(project_root)):
             ... critical section ...
+        with file_lock(Path(project_root), timeout=5.0):
+            ... fail fast on contention ...
     """
     lock_path = root / LOCK_FILE_NAME
     lock_path.parent.mkdir(parents=True, exist_ok=True)
@@ -114,19 +171,7 @@ def file_lock(root: Path, timeout: Optional[float] = None):
     lock_fd = None
     try:
         lock_fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o644)
-        if fcntl is not None:
-            fcntl.flock(lock_fd, fcntl.LOCK_EX)
-        elif msvcrt is not None:
-            # Windows: lock the first byte of the lock file. msvcrt LK_LOCK
-            # retries for ~10s then raises OSError, so loop until acquired
-            # to match the blocking semantics of flock.
-            while True:
-                try:
-                    os.lseek(lock_fd, 0, os.SEEK_SET)
-                    msvcrt.locking(lock_fd, msvcrt.LK_LOCK, 1)
-                    break
-                except OSError:
-                    continue
+        _acquire_exclusive(lock_fd, timeout)
         # If neither primitive exists, proceed unlocked (advisory best-effort).
         _HELD_LOCKS[key] = {"fd": lock_fd, "depth": 1}
         yield

{wikifier-4.6.8 → wikifier-4.6.9}/wikifier/scripts/wikifier.sh

@@ -684,18 +684,15 @@ cmd_init() {
 # node_modules, build/, dist/, caches, etc.
 # This is NOT the import map — see map_paths.txt for package roots used by update-maps.
 #
-# Examples (uncomment or add paths that match THIS project):
-# src/
+# Active default: src/ (lean). Multi-crate / monorepo: replace with package roots first.
+# Tiny single-file toys only: uncomment bare "." below (explicit opt-in — not default).
+src/
+# .
 # lib/
 # crates/my_crate/src/
 # packages/core/src/
 # README.md
 # docs/
-#
-# Tiny single-package toys only may keep bare "." below.
-# Multi-crate / monorepo / anything with build output: REPLACE with lean roots first
-# (session_bootstrap readiness "blocked" / fix_scope until you do).
-.
 EOT
     fi
     MAP_PATHS_FILE="$PROJECT_ROOT/map_paths.txt"
@@ -705,13 +702,13 @@ EOT
 # List directories that contain parseable source for the dependency map.
 # Do not use bare "." on large trees; do not list only wiki/docs files here.
 #
-# Examples (uncomment or add paths that match THIS project):
-# src/
+# Active default: src/ (replace with this project's package roots).
+src/
 # crates/my_crate/src/
 # packages/core/src/
 #
 # Leave empty (comments only) to fall back to monitored directory roots / full collect.
-# After editing: wikifier update-maps  (then session_bootstrap until ready_for_daemon)
+# After editing: wikifier update-maps  (then session_bootstrap until readiness=ready_for_daemon)
 EOT
     fi
     [[ ! -f "$EXCLUDE_PATTERNS_FILE" ]] && cat > "$EXCLUDE_PATTERNS_FILE" << 'EOT'

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.6.8
+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

{wikifier-4.6.8 → wikifier-4.6.9}/wikifier.egg-info/SOURCES.txt

@@ -44,6 +44,7 @@ tests/test_agent_loop.py
 tests/test_agent_scale.py
 tests/test_barrel_invalidation.py
 tests/test_cache_store.py
+tests/test_gap_amendment_2026_08.py
 tests/test_gap_closure.py
 tests/test_health.py
 tests/test_import_cache.py