wikifier 4.6.3__tar.gz → 4.6.5__tar.gz

{wikifier-4.6.3/wikifier.egg-info → wikifier-4.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.6.3
+Version: 4.6.5
 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
@@ -109,8 +109,10 @@ 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+)** — zero-dirty fast path skips full graph/`library.md` rewrite when nothing reparsed; content-hash dirty so mtime thrash ≠ reparse; `--directory=` scopes the candidate walk (monorepo budgets)
-- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal` (`skip`|`investigate`); prefer `actionable_low_conf_edges` over raw low-conf noise
+- **Warm agent maps (4.6.3–4.6.5)** — zero-dirty fast path; **stdlib SQLite** cache; **candidate list reuse** + scoped/monitored-first walks (no whole-tree thrash); content-hash dirty
+- **Partial-map honesty** — `map_coverage` on `update_maps` / bootstrap / **`suggest_next`**; incomplete maps yield `update_maps_until_complete` actions
+- **Cache ops** — `wikifier cache-status` (backend, bytes, ACS, coverage, dual-write policy)
+- **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
 - **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

{wikifier-4.6.3 → wikifier-4.6.5}/README.md

@@ -77,8 +77,10 @@ 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+)** — zero-dirty fast path skips full graph/`library.md` rewrite when nothing reparsed; content-hash dirty so mtime thrash ≠ reparse; `--directory=` scopes the candidate walk (monorepo budgets)
-- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal` (`skip`|`investigate`); prefer `actionable_low_conf_edges` over raw low-conf noise
+- **Warm agent maps (4.6.3–4.6.5)** — zero-dirty fast path; **stdlib SQLite** cache; **candidate list reuse** + scoped/monitored-first walks (no whole-tree thrash); content-hash dirty
+- **Partial-map honesty** — `map_coverage` on `update_maps` / bootstrap / **`suggest_next`**; incomplete maps yield `update_maps_until_complete` actions
+- **Cache ops** — `wikifier cache-status` (backend, bytes, ACS, coverage, dual-write policy)
+- **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
 - **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

{wikifier-4.6.3 → wikifier-4.6.5}/skills/run.md

@@ -11,7 +11,9 @@
 - 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.
 - **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 uses `actionable_low_conf_edges`.
+- **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.
+- **Warm maps:** import cache prefers stdlib SQLite (`.wikifier_staging/import_cache.sqlite`); zero-dirty path uses mtime index + meta, not full pair payload. Candidate lists reuse when scope fingerprint is unchanged; prefer `--directory=` / lean `monitored_paths` (not bare `.`).
+- **Cache ops:** `wikifier cache-status` / `from wikifier import cache_status` — backend, sizes, `acs_version`, `map_coverage`. Dual-write JSON only ≤400 files or `WIKIFIER_CACHE_JSON=1` (set `0` to never dual-write).
 - **Dual scope:** `monitored_paths` = check-changes/health scope (keep lean). `update-maps --directory=` / `--max-files=` = map walk. Never set `project_root` to a multi-repo parent (e.g. `cloned_sample_projects`).
 - **CLI target:** `wikifier --target /abs/project health --summary` (flags stripped before the command). Or `WIKIFIER_PROJECT_ROOT=…`.
 - **Long-horizon:** `wikifier autonomous-status` (or `readiness`) before unattended runs; daemon writes `.wikifier_staging/daemon_heartbeat.json`. Soak ≥72h is still evidence work, not automatic.

wikifier-4.6.5/tests/test_cache_store.py

@@ -0,0 +1,193 @@
+"""SQLite cache store + map_coverage + warm path (shipped APIs, zero-dep)."""
+
+from __future__ import annotations
+
+import os
+import time
+import unittest
+from pathlib import Path
+
+from tests._base import TempProjectTestCase
+
+from wikifier import cli
+from wikifier import import_cache as ic
+from wikifier import cache_store as cs
+
+
+class TestSqliteCacheRoundTrip(TempProjectTestCase):
+    def test_save_load_sqlite_primary(self):
+        self.write("a.py", "import os\n")
+        r = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r.get("success"), r)
+        self.assertTrue(cs.has_sqlite(self.root), "sqlite should exist after save")
+        cache = ic.load_cache(self.root)
+        self.assertIn("a.py", cache)
+        self.assertIsInstance(cache["a.py"].get("mtime"), int)
+        # light index works without requiring pairs field presence
+        idx = ic.load_mtime_index(self.root)
+        self.assertIn("a.py", idx)
+        self.assertEqual(idx["a.py"]["mtime"], cache["a.py"]["mtime"])
+
+    def test_legacy_json_dual_read_then_migrate(self):
+        # Plant legacy JSON only (no sqlite)
+        staging = self.root / ".wikifier_staging"
+        staging.mkdir(parents=True, exist_ok=True)
+        import json
+        legacy = {
+            "x.py": {
+                "mtime": 1,
+                "content_hash": "sha256:abc",
+                "imports": ["os"],
+                "resolved": [],
+                "resolved_pairs": [{"raw": "os", "resolved": "", "confidence_score": 0.48}],
+            },
+            "_acs_summary": {
+                "acs_version": "1.2",
+                "total_scored_edges": 1,
+                "actionable_low_conf_edges": 0,
+                "low_conf_edges": 1,
+            },
+        }
+        (staging / "import_cache.json").write_text(
+            json.dumps(legacy), encoding="utf-8"
+        )
+        loaded = ic.load_cache(self.root)
+        self.assertIn("x.py", loaded)
+        # update_maps migrates
+        self.write("x.py", "import os\n")
+        r = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r.get("success"), r)
+        self.assertTrue(cs.has_sqlite(self.root))
+
+
+class TestWarmPathNoFullJsonTax(TempProjectTestCase):
+    def test_zero_dirty_reports_sqlite_backend_and_coverage(self):
+        self.write("m.py", "print(1)\n")
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        r2 = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r2.get("success"), r2)
+        self.assertTrue(r2.get("zero_dirty_fast_path"), r2)
+        self.assertIn(r2.get("cache_backend"), ("sqlite", "sqlite+json", "json"))
+        cov = r2.get("map_coverage") or {}
+        self.assertTrue(cov.get("complete"), cov)
+        self.assertIn("files_remaining_dirty", cov)
+        self.assertEqual(int(cov["files_remaining_dirty"]), 0)
+
+    def test_zero_dirty_skips_full_payload_load_cache_dict(self):
+        """Shipped warm path must not deserialize full file payloads on 0-dirty.
+
+        Criterion: after SQLite is warm, zero-dirty update_maps must not call
+        cache_store.load_cache_dict (full pairs) or ic.load_cache (legacy full).
+        Light index + meta only.
+        """
+        self.write("warm.py", "print(0)\n")
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        self.assertTrue(cs.has_sqlite(self.root))
+        # Second run seeds zero-dirty + sqlite
+        r_seed = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r_seed.get("zero_dirty_fast_path"), r_seed)
+
+        full_loads = {"load_cache_dict": 0, "load_cache": 0}
+        real_lcd = cs.load_cache_dict
+        real_lc = ic.load_cache
+
+        def counting_lcd(root):
+            full_loads["load_cache_dict"] += 1
+            return real_lcd(root)
+
+        def counting_lc(root):
+            full_loads["load_cache"] += 1
+            return real_lc(root)
+
+        # Patch at the modules the shipped path imports from
+        import wikifier.cache_store as cs_mod
+        import wikifier.import_cache as ic_mod
+        orig_cs = cs_mod.load_cache_dict
+        orig_ic = ic_mod.load_cache
+        cs_mod.load_cache_dict = counting_lcd  # type: ignore
+        ic_mod.load_cache = counting_lc  # type: ignore
+        try:
+            r2 = cli.update_maps(project_root=self.root, full=False)
+        finally:
+            cs_mod.load_cache_dict = orig_cs  # type: ignore
+            ic_mod.load_cache = orig_ic  # type: ignore
+
+        self.assertTrue(r2.get("success"), r2)
+        self.assertTrue(r2.get("zero_dirty_fast_path"), r2)
+        self.assertEqual(
+            full_loads["load_cache_dict"],
+            0,
+            f"warm 0-dirty must not call load_cache_dict; counts={full_loads}",
+        )
+        self.assertEqual(
+            full_loads["load_cache"],
+            0,
+            f"warm 0-dirty must not call load_cache; counts={full_loads}",
+        )
+
+    def test_max_files_coverage_incomplete(self):
+        for i in range(6):
+            self.write(f"f{i}.py", f"v={i}\n")
+        r = cli.update_maps(project_root=self.root, full=True, max_files=2)
+        self.assertTrue(r.get("success"), r)
+        cov = r.get("map_coverage") or {}
+        self.assertFalse(cov.get("complete"), cov)
+        self.assertEqual(int(cov.get("files_skipped") or 0), 4)
+        self.assertGreaterEqual(int(cov.get("files_remaining_dirty") or 0), 4)
+        self.assertIn("agent_note", cov)
+
+    def test_mtime_index_skips_content_stable(self):
+        p = self.write("s.py", "x=1\n")
+        cli.update_maps(project_root=self.root, full=True)
+        cache = ic.load_cache(self.root)
+        ent = cache["s.py"]
+        ent["mtime"] = 1
+        ic.save_cache(self.root, cache)
+        time.sleep(0.05)
+        os.utime(p, None)
+        updates = []
+        need = ic.compute_files_needing_reparse(
+            self.root, [p], content_stable_mtime_updates=updates
+        )
+        # content_hash should make this stable once hash stored
+        if ent.get("content_hash"):
+            self.assertEqual(need, [])
+            self.assertGreaterEqual(len(updates), 1)
+
+
+class TestBootstrapCoverageAndAcsGuidance(TempProjectTestCase):
+    def test_bootstrap_surfaces_acs_guidance(self):
+        self.write("h.py", "import os\n")
+        cli.update_maps(project_root=self.root, full=True)
+        boot = cli.session_bootstrap(project_root=self.root)
+        self.assertTrue(boot.get("success"), boot)
+        self.assertIn("acs_guidance", boot)
+        self.assertIn("actionable_low_conf_edges", boot["acs_guidance"])
+        acs = boot.get("acs") or {}
+        self.assertIn("acs_version", acs)
+
+
+class TestGoModResolve(TempProjectTestCase):
+    def test_same_module_import_resolves(self):
+        from wikifier.parsers import go_lang as go
+
+        self.write(
+            "go.mod",
+            "module example.com/demo\n\ngo 1.21\n",
+        )
+        self.write("pkg/util/util.go", "package util\nfunc X() {}\n")
+        main = self.write(
+            "cmd/main.go",
+            'package main\nimport "example.com/demo/pkg/util"\n',
+        )
+        edges = go.parse_go_imports(str(main))
+        self.assertTrue(edges)
+        resolved = [e for e in edges if e.get("resolved_path")]
+        self.assertTrue(resolved, msg=f"edges={edges}")
+        self.assertIn("util", resolved[0]["resolved_path"])
+
+
+if __name__ == "__main__":
+    unittest.main()

wikifier-4.6.5/tests/test_walk_coverage_resolvers.py

@@ -0,0 +1,203 @@
+"""Walk cost, Core map_coverage, thin C#/C++ resolve, cache-status (shipped APIs)."""
+
+from __future__ import annotations
+
+import os
+import time
+import unittest
+from pathlib import Path
+
+from tests._base import TempProjectTestCase
+
+from wikifier import cli
+from wikifier import cache_store as cs
+from wikifier.candidates import (
+    collect_candidate_source_files,
+    try_cached_candidate_rels,
+    candidate_list_meta,
+)
+from wikifier.agent_loop import build_structured_actions
+
+
+class TestScopedCollect(TempProjectTestCase):
+    def test_directory_scope_limits_candidates(self):
+        self.write("pkg/a.py", "x=1\n")
+        self.write("other/b.py", "y=1\n")
+        cands = collect_candidate_source_files(self.root, directory="pkg")
+        rels = []
+        for p in cands:
+            try:
+                rels.append(str(Path(p).resolve().relative_to(self.root.resolve())))
+            except Exception:
+                rels.append(os.path.realpath(str(p)))
+        self.assertTrue(any("pkg" in r and r.endswith("a.py") for r in rels), rels)
+        self.assertFalse(any("other" in r for r in rels), rels)
+
+    def test_wiki_monitored_paths_do_not_collapse_map(self):
+        """monitored_paths with only wiki files must not yield a 1-file map."""
+        self.write("pkg/a.py", "x=1\n")
+        self.write("pkg/b.py", "y=1\n")
+        self.write("skills/run.md", "# wiki\n")
+        self.write(
+            "monitored_paths.txt",
+            "# wiki only\nskills/run.md\nREADME.md\npkg/a.py\n",
+        )
+        self.write("README.md", "# r\n")
+        cands = collect_candidate_source_files(self.root, directory=None, use_monitored=True)
+        # Must walk full tree, not just a.py from monitored
+        py = [p for p in cands if p.suffix == ".py"]
+        self.assertGreaterEqual(len(py), 2, [str(p) for p in py])
+
+    def test_candidate_reuse_true_when_git_clean(self):
+        """Second warm reuses candidate list when scope clean — honest assert."""
+        self.write("m.py", "print(1)\n")
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        n1 = int(r1.get("parseable_files") or 0)
+        self.assertGreaterEqual(n1, 1)
+        r2 = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r2.get("success"), r2)
+        r3 = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r3.get("success"), r3)
+        self.assertTrue(
+            r3.get("candidates_reused") is True,
+            f"expected reuse on third warm; r2={r2.get('candidates_reused')} r3={r3}",
+        )
+        self.assertEqual(int(r3.get("parseable_files") or 0), n1)
+
+    def test_nested_new_file_invalidates_reuse(self):
+        """Adding a nested source file must expand candidates (not stale reuse)."""
+        self.write("pkg/a.py", "x=1\n")
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        n1 = int(r1.get("parseable_files") or 0)
+        # Nested new file under existing package
+        self.write("pkg/nested/b.py", "y=2\n")
+        time.sleep(0.05)
+        r2 = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r2.get("success"), r2)
+        n2 = int(r2.get("parseable_files") or 0)
+        self.assertGreater(
+            n2, n1,
+            f"nested add must expand parseable_files: before={n1} after={n2} reused={r2.get('candidates_reused')}",
+        )
+        # Must not have reused stale list of size n1
+        if r2.get("candidates_reused"):
+            self.fail("must not reuse candidate list after nested source add")
+
+    def test_poisoned_one_file_blob_not_reused(self):
+        """Plant 1-file candidate blob with matching fp; live tree has 2 sources → no reuse."""
+        self.write("pkg/a.py", "x=1\n")
+        self.write("pkg/b.py", "y=2\n")
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        live_n = int(r1.get("parseable_files") or 0)
+        self.assertGreaterEqual(live_n, 2)
+        # Poison meta: same directory scope, current fp, but only one rel
+        from wikifier.candidates import scope_fingerprint, candidate_list_meta
+        from wikifier import cache_store as cs
+        fp = scope_fingerprint(self.root, None)
+        poison = {
+            "fp": fp,
+            "directory": None,
+            "count": 1,
+            "rels": ["pkg/a.py"],
+        }
+        cs.save_meta_key(self.root, "_candidate_list", poison)
+        # Direct API: try_cached must return None
+        meta = cs.load_meta(self.root, keys=("_candidate_list",))
+        from wikifier.candidates import try_cached_candidate_rels
+        cached = try_cached_candidate_rels(meta, self.root, None)
+        self.assertIsNone(
+            cached,
+            f"poisoned 1-file blob must not reuse when live has {live_n} sources",
+        )
+        # Shipped update_maps must not report parseable_files=1 with reused=true
+        r2 = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r2.get("success"), r2)
+        self.assertGreaterEqual(int(r2.get("parseable_files") or 0), 2, r2)
+        self.assertFalse(
+            r2.get("candidates_reused") is True and int(r2.get("parseable_files") or 0) == 1,
+            r2,
+        )
+
+
+class TestCoverageInCore(TempProjectTestCase):
+    def test_suggest_surfaces_incomplete_map_action(self):
+        for i in range(5):
+            self.write(f"f{i}.py", f"v={i}\n")
+        r = cli.update_maps(project_root=self.root, full=True, max_files=2)
+        self.assertTrue(r.get("success"), r)
+        cov = r.get("map_coverage") or {}
+        self.assertFalse(cov.get("complete"), cov)
+        sug = cli.suggest_next_actions(project_root=self.root, format="json")
+        self.assertTrue(sug.get("success"), sug)
+        self.assertIn("map_coverage", sug)
+        self.assertFalse((sug.get("map_coverage") or {}).get("complete"))
+        actions = sug.get("actions") or []
+        kinds = [a.get("action") for a in actions]
+        self.assertIn("update_maps_until_complete", kinds, actions)
+        text = " ".join(sug.get("suggestions") or [])
+        self.assertIn("INCOMPLETE", text.upper())
+
+    def test_build_structured_actions_incomplete(self):
+        acts = build_structured_actions(
+            clean=True,
+            map_coverage={"complete": False, "files_remaining_dirty": 9},
+        )
+        self.assertTrue(any(a["action"] == "update_maps_until_complete" for a in acts))
+
+
+class TestCacheStatus(TempProjectTestCase):
+    def test_cache_status_shape(self):
+        self.write("z.py", "z=1\n")
+        cli.update_maps(project_root=self.root, full=True)
+        st = cli.cache_status(project_root=self.root)
+        self.assertTrue(st.get("success"), st)
+        self.assertIn(st.get("cache_backend"), ("sqlite", "sqlite+json", "json"))
+        self.assertIn("sqlite_bytes", st)
+        self.assertIn("dual_write_policy", st)
+        self.assertIn("migrate_note", st)
+        st2 = cs.cache_status(self.root)
+        self.assertEqual(st2.get("cache_backend"), st.get("cache_backend"))
+
+
+class TestCsharpProjectResolve(TempProjectTestCase):
+    def test_project_namespace_resolves(self):
+        from wikifier.parsers import csharp as cs_parser
+
+        self.write(
+            "Demo.csproj",
+            "<Project><PropertyGroup><RootNamespace>Demo</RootNamespace></PropertyGroup></Project>\n",
+        )
+        self.write("Util/Helper.cs", "namespace Demo.Util { class Helper {} }\n")
+        main = self.write(
+            "Program.cs",
+            "using Demo.Util;\nnamespace Demo { class Program {} }\n",
+        )
+        edges = cs_parser.parse_csharp_imports(str(main))
+        self.assertTrue(edges)
+        resolved = [e for e in edges if e.get("resolved_path")]
+        self.assertTrue(resolved, msg=f"edges={edges}")
+        self.assertTrue(
+            any("Util" in (e.get("resolved_path") or "") for e in resolved),
+            resolved,
+        )
+
+
+class TestCCppLocalInclude(TempProjectTestCase):
+    def test_include_dir_resolve(self):
+        from wikifier.parsers import c_cpp as cc
+
+        self.write("include/foo.h", "#pragma once\n")
+        src = self.write("src/main.c", '#include "foo.h"\nint main(){return 0;}\n')
+        edges = cc.parse_c_cpp_imports(str(src))
+        self.assertTrue(edges)
+        self.assertTrue(
+            any(e.get("resolved_path") and "foo.h" in e["resolved_path"] for e in edges),
+            edges,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

{wikifier-4.6.3 → wikifier-4.6.5}/wikifier/__init__.py

@@ -48,6 +48,7 @@ from .cli import (
     why_file,
     seed_source_content_hashes,
     list_core_tools,
+    cache_status,
 )
 from . import agent_loop
 
@@ -78,4 +79,4 @@ from .contracts import (
     compute_acs_confidence,
 )
 
-__version__ = "4.6.3"
+__version__ = "4.6.5"

{wikifier-4.6.3 → wikifier-4.6.5}/wikifier/agent_loop.py

@@ -176,6 +176,7 @@ def build_structured_actions(
     scope_warnings: Optional[List[str]] = None,
     clean: bool = False,
     max_file_actions: int = 12,
+    map_coverage: Optional[Dict[str, Any]] = None,
 ) -> List[Dict[str, Any]]:
     """Build dispatchable action objects for agents (not prose-only).
 
@@ -183,6 +184,28 @@ def build_structured_actions(
     """
     actions: List[Dict[str, Any]] = []
     prio = 1
+    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
+    if complete is False or remaining > 0:
+        actions.append({
+            "action": "update_maps_until_complete",
+            "file": None,
+            "priority": 3,
+            "reason": (
+                f"Map incomplete: files_remaining_dirty={remaining}, complete={complete}. "
+                "Re-run update_maps (same directory/max_files) until map_coverage.complete=true; "
+                "success alone does not mean the map is done."
+            ),
+            "preflight": ["update_maps"],
+            "map_coverage": {
+                "complete": complete,
+                "files_remaining_dirty": remaining,
+                "files_skipped": cov.get("files_skipped"),
+                "budget_max_files": cov.get("budget_max_files"),
+            },
+        })
     for f in (red_files or [])[:max_file_actions]:
         actions.append({
             "action": "investigate_red",
@@ -201,7 +224,7 @@ def build_structured_actions(
             "preflight": ["prepare_edit", "why_file"],
         })
         prio = min(prio + 1, 9)
-    if red == 0 and actionable_yellow == 0 and clean:
+    if red == 0 and actionable_yellow == 0 and clean and remaining == 0:
         actions.append({
             "action": "lookup_only",
             "file": None,
@@ -222,7 +245,10 @@ def build_structured_actions(
             "action": "review_acs",
             "file": None,
             "priority": 4,
-            "reason": f"{acs_actionable} actionable low-confidence project edges (not external noise)",
+            "reason": (
+                f"{acs_actionable} actionable low-confidence project edges "
+                "(prefer actionable_low_conf_edges + reason_code_counts; not raw low_conf_edges)"
+            ),
             "preflight": ["get_dependencies"],
         })
     for w in (scope_warnings or [])[:2]:
@@ -233,7 +259,10 @@ def build_structured_actions(
             "reason": str(w),
             "preflight": [],
         })
-    if not any(a["action"] == "update_maps" for a in actions):
+    if not any(
+        a["action"] in ("update_maps", "update_maps_until_complete", "update_maps_if_structure")
+        for a in actions
+    ):
         actions.append({
             "action": "update_maps_if_structure",
             "file": None,
@@ -548,8 +577,33 @@ def session_bootstrap(
     acs_actionable = 0
     try:
         from . import import_cache as ic
-        cache = ic.load_cache(root) or {}
-        acs = ic.ensure_acs_summary_persisted(cache, root) or {}
+        try:
+            from . import cache_store as cs
+        except Exception:
+            cs = None  # type: ignore
+        # Prefer light meta read (SQLite) over full multi-MB pair deserialize
+        acs: Dict[str, Any] = {}
+        cyc: Dict[str, Any] = {}
+        if cs is not None:
+            meta = cs.load_meta(root, keys=("_acs_summary", "_cycles", "_map_coverage"))
+            acs = meta.get("_acs_summary") if isinstance(meta.get("_acs_summary"), dict) else {}
+            cyc = meta.get("_cycles") if isinstance(meta.get("_cycles"), dict) else {}
+            cov = meta.get("_map_coverage") if isinstance(meta.get("_map_coverage"), dict) else {}
+            if cov:
+                out["map_coverage"] = cov
+            out["cache_backend"] = cs.backend_name(root)
+        needs_full = (
+            not acs
+            or str(acs.get("acs_version") or "") < "1.3"
+            or "reason_code_counts" not in acs
+            or "actionable_low_conf_edges" not in acs
+        )
+        if needs_full:
+            cache = ic.load_cache(root) or {}
+            acs = ic.ensure_acs_summary_persisted(cache, root) or {}
+            cyc = cache.get("_cycles") or {}
+            if cs is not None and not out.get("cache_backend"):
+                out["cache_backend"] = cs.backend_name(root)
         acs_actionable = int(acs.get("actionable_low_conf_edges") or 0)
         out["acs"] = {
             "acs_version": acs.get("acs_version"),
@@ -557,12 +611,22 @@ def session_bootstrap(
             "low_conf_edges": acs.get("low_conf_edges"),
             "dynamic_literal_noise_edges": acs.get("dynamic_literal_noise_edges"),
             "avg_confidence": acs.get("avg_confidence"),
+            "reason_code_counts": acs.get("reason_code_counts"),
+            "agent_signal_counts": acs.get("agent_signal_counts"),
         }
-        cyc = cache.get("_cycles") or {}
+        # Agents must not thrash on raw low_conf_edges (ACS v1.3 scores more edges)
+        out["acs_guidance"] = (
+            "Prefer actionable_low_conf_edges + reason_code_counts "
+            "(skip external_or_bare/dynamic_literal); do not use low_conf_edges alone as a work queue."
+        )
         out["cycles"] = {
             "cyclic_scc_count": (cyc.get("stats") or {}).get("cyclic_scc_count"),
             "all_cycle_files_sample": (cyc.get("all_cycle_files") or [])[:10],
         }
+        if "map_coverage" not in out and cs is not None:
+            snap = cs.get_map_coverage_from_meta(root)
+            if snap.get("map_coverage"):
+                out["map_coverage"] = snap["map_coverage"]
     except Exception as e:
         out["acs_error"] = str(e)
 
@@ -574,6 +638,7 @@ def session_bootstrap(
     if isinstance(out.get("scope"), dict):
         scope_warnings = list(out["scope"].get("warnings") or [])
 
+    map_cov = out.get("map_coverage") if isinstance(out.get("map_coverage"), dict) else {}
     out["actions"] = build_structured_actions(
         red_files=red_files,
         actionable_yellow_files=actionable_yellow_files,
@@ -583,12 +648,19 @@ def session_bootstrap(
         acs_actionable=acs_actionable,
         scope_warnings=scope_warnings,
         clean=clean,
+        map_coverage=map_cov,
     )
     out["work_items"] = out["actions"]  # alias
     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 ""
+        )
     )
     return out