wikifier 4.5.5__tar.gz → 4.5.8__tar.gz

{wikifier-4.5.5/wikifier.egg-info → wikifier-4.5.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.5.5
+Version: 4.5.8
 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.5.5 → wikifier-4.5.8}/skills/run.md

@@ -10,12 +10,15 @@
 **Package 4.5.x + gap-closure notes (additive; protocol still v0.6):**
 - File Tree + `wikifier serve`; MCP status/attention use library + emoji (not `[GREEN]` tags).
 - **First-run:** `init` → `update-maps` → `health --summary` → `suggest_next_actions`. Map is automatic; wiki *prose* is agent-filled over time.
-- **Steady-state selective work:** only 🔴/🟡 (never re-wiki 🟢 unless required). ACS suggestions use `actionable_low_conf_edges` (stdlib/external bare demoted).
-- **Deletions:** `record-deletion` + check-changes ghost detection (missing paths → Red DELETED).
-- **Languages:** deep import maps = Python, JS/TS, Rust, Go, C/C++, C#, Java (regex; not full toolchain resolution). journal/pending = audit queue, not Jira.
-- **Huge monorepos:** lean `monitored_paths.txt` (package roots, not bare `.`). Optional `WIKIFIER_CHECK_CHANGES_MAX` (default 2000). `update-maps` seeds Yellow health stubs for newly parsed files (map-first).
-- **Monitor:** optional background `monitor`/`daemon` for mtime heartbeat; agents still own wiki/mark-green.
-- Health module: use `importlib.import_module("wikifier.health")` or `wikifier.health_module` — `from wikifier import health` is the *function*.
+- **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`.
+- **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.
+- **Deletions:** `record-deletion` + ghost detection. **Languages:** py/js/ts/rust/go/c/c#/java (regex). journal/pending = audit queue, not Jira.
+- **Huge monorepos:** lean `monitored_paths.txt` (not bare `.`). `WIKIFIER_CHECK_CHANGES_MAX` default 2000. Hygiene: `seed-health`, `prune-pending`, `prune-health`.
+- **Monitor/daemon:** mtime heartbeat; agents still own wiki/mark-green. `WIKIFIER_DAEMON_MAPS_INTERVAL` default 600s; `WIKIFIER_DAEMON_MAPS=0` for check-only.
+- Health module: `importlib.import_module("wikifier.health")` or `wikifier.health_module` — `from wikifier import health` is the *function*.
 
 **v0.6 migration notes (packages v4.2.0–v4.3.0)** — changes are additive or strictly-better defaults; v0.5 agent behavior keeps working:
 - `update-maps` (CLI) now runs the **pure-Python full pipeline**: every dirty file is parsed in-process, the canonical per-file cache is persisted, reverse deps + cycles + ACS are computed, and `library.md` is regenerated atomically. `--python-primary` is accepted but redundant; the in-shell first-pass was retired entirely (wikifier.sh's update-maps delegates to this pipeline; `--sh`/`--legacy-sh` are deprecated no-ops). Scoping is explicit via `--directory=`/`--max-files=` and reported in the result (`files_skipped`) — there are no silent caps.
@@ -39,11 +42,15 @@ 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` |
-| Steady-state | `check-changes` → edit 🔴/🟡 only → `record-change` → wiki → `mark-green` |
+| Steady-state | `check-changes` → edit 🔴/actionable 🟡 only → `record-change` → wiki → `mark-green` |
 | Lookup | MCP Core 6: status, check_changes, needing_attention, get_file_wiki, suggest, record/mark |
 | Deps / cycles | `get_dependencies`, `get_dependents`, `get_cycles` (json) |
 | Deletion | `record-deletion` |
-| Code entry | `wikifier/cli.py` (dispatch) + `wikifier/health.py` + parsers — self-tests live in `tests/` + `tests/selftest/` |
+| Long-horizon prep | `autonomous-status` / `readiness`; then `daemon start` with lean monitor |
+| Hygiene | `seed-health`, `prune-pending`, `prune-health`, `validate` |
+| Code entry | `cli.py` dispatch + `health.py` + parsers — self-tests in `tests/` + `tests/selftest/` |
+
+**Do not open megamodules** (`javascript.py` ~2.6k, `import_cache.py` ~2.3k, `bree.py` ~2k) for workflow decisions — use tools + this table.
 
 **CLI pure-Python vs shell:** mutators and maps prefer `python -m wikifier …`. Shell still owns `init`, `monitor`, `daemon`, `serve`, `journal`.  
 **Scope:** `monitored_paths` = change detection; `exclude_patterns` + optional `--directory` = map walk.  

{wikifier-4.5.5 → wikifier-4.5.8}/tests/test_gap_closure.py

@@ -190,5 +190,163 @@ class TestPendingAndPollutionHygiene(TempProjectTestCase):
         self.assertIn("gone_real.py", entries2)
 
 
+class TestMapFirstTaxonomyAndReadiness(TempProjectTestCase):
+    def test_stub_yellow_is_map_ready_not_needs_attention(self):
+        health_mod = importlib.import_module("wikifier.health")
+        health_mod.upsert_entry(
+            self.root, "a.py", "🟡 Yellow",
+            "Initial stub — present in dependency map; agent should wiki + mark-green when editing",
+        )
+        health_mod.upsert_entry(
+            self.root, "b.py", "🟡 Yellow",
+            "Initial stub — parseable source under monitored_paths; agent should wiki + mark-green when editing",
+        )
+        s = health_mod.get_summary(self.root)
+        self.assertEqual(s.get("stub_yellow"), 2)
+        self.assertEqual(s.get("actionable_yellow"), 0)
+        self.assertEqual(s.get("health_score"), "Map Ready")
+
+    def test_actionable_yellow_needs_attention(self):
+        health_mod = importlib.import_module("wikifier.health")
+        health_mod.upsert_entry(
+            self.root, "a.py", "🟡 Yellow",
+            "mtime changed since last check-changes (Python primary auto-detected)",
+        )
+        s = health_mod.get_summary(self.root)
+        self.assertEqual(s.get("actionable_yellow"), 1)
+        self.assertEqual(s.get("health_score"), "Needs Attention")
+
+    def test_suggest_does_not_bulk_wiki_stubs(self):
+        health_mod = importlib.import_module("wikifier.health")
+        health_mod.upsert_entry(self.root, "a.py", "🟡 Yellow", "Initial stub — present in dependency map")
+        text = cli.suggest_next_actions(project_root=self.root, format="text")
+        self.assertIn("Map-first", text)
+        self.assertNotIn("Review the 1 🟡 Yellow file(s) only", text)
+
+    def test_detect_multi_project_container(self):
+        health_mod = importlib.import_module("wikifier.health")
+        for name in ("proj_a", "proj_b", "proj_c"):
+            d = self.root / name
+            d.mkdir()
+            (d / ".git").mkdir()
+        scope = health_mod.detect_scope_risks(self.root)
+        self.assertGreaterEqual(scope.get("child_project_count"), 3)
+        self.assertFalse(scope.get("ok"))
+        self.assertTrue(any("multi-project" in w.lower() for w in scope.get("warnings") or []))
+
+    def test_autonomous_readiness_shape(self):
+        health_mod = importlib.import_module("wikifier.health")
+        (self.root / "monitored_paths.txt").write_text("src\n", encoding="utf-8")
+        self.write("src/app.py", "x=1\n")
+        health_mod.upsert_entry(self.root, "src/app.py", "🟡 Yellow", "Initial stub — present in dependency map")
+        r = health_mod.assess_autonomous_readiness(self.root)
+        self.assertTrue(r.get("success"))
+        self.assertIn(r.get("readiness"), (
+            "blocked", "map_ok_scope_risk", "ready_for_daemon",
+            "ready_with_agent_wiki_work", "not_ready",
+        ))
+        self.assertIn("long_horizon_note", r)
+        self.assertIn("metrics", r)
+
+    def test_write_metrics_snapshot_history(self):
+        health_mod = importlib.import_module("wikifier.health")
+        (self.root / "monitored_paths.txt").write_text("src\n", encoding="utf-8")
+        self.write("src/app.py", "x=1\n")
+        health_mod.upsert_entry(self.root, "src/app.py", "🟢 Green", "ok")
+        s1 = health_mod.write_metrics_snapshot(self.root, source="test1")
+        self.assertTrue(s1.get("success"))
+        latest = self.root / ".wikifier_staging" / "metrics_latest.json"
+        hist = self.root / ".wikifier_staging" / "metrics_history.jsonl"
+        self.assertTrue(latest.exists())
+        self.assertTrue(hist.exists())
+        s2 = health_mod.write_metrics_snapshot(self.root, source="test2")
+        self.assertTrue(s2.get("success"))
+        rows = health_mod.read_metrics_history(self.root, limit=10)
+        self.assertGreaterEqual(len(rows), 2)
+        self.assertEqual(rows[-1].get("source"), "test2")
+        self.assertIn("staging_bytes", rows[-1])
+        self.assertIn("health_score", rows[-1])
+
+
+class TestMapFirstHealthAndValidate(TempProjectTestCase):
+    def test_deep_relative_keys_are_under_root(self):
+        """Regression: deep monorepo rel paths must not be treated as abs pollution."""
+        health_mod = importlib.import_module("wikifier.health")
+        deep = "airflow-core/src/airflow/api/client/local_client.py"
+        self.assertTrue(health_mod._entry_is_under_root(self.root, deep))
+        self.assertTrue(health_mod._entry_is_under_root(self.root, "pkg/a.py"))
+
+    def test_seed_health_from_map_creates_stubs(self):
+        health_mod = importlib.import_module("wikifier.health")
+        from wikifier import import_cache as ic
+
+        self.write("pkg/a.py", "import b\n")
+        self.write("pkg/b.py", "x=1\n")
+        self.write("README.md", "# hi\n")
+        cache = {}
+        ic.update_file_data(cache, "pkg/a.py", mtime=1, imports=["b"], resolved_pairs=[])
+        ic.update_file_data(cache, "pkg/b.py", mtime=1, imports=[], resolved_pairs=[])
+        ic.save_cache(self.root, cache)
+
+        # No health file yet
+        self.assertFalse((self.root / "file_health.json").exists())
+        res = health_mod.seed_health_from_map(self.root)
+        self.assertTrue(res.get("success"))
+        self.assertGreaterEqual(res.get("seeded"), 2)
+        entries = health_mod.load_health(self.root)["entries"]
+        self.assertIn("pkg/a.py", entries)
+        self.assertIn("pkg/b.py", entries)
+        self.assertTrue(entries["pkg/a.py"]["status"].startswith("🟡"))
+
+    def test_validate_ignores_non_source_and_reports_mapped_gaps(self):
+        health_mod = importlib.import_module("wikifier.health")
+        from wikifier import import_cache as ic
+
+        self.write("src/app.py", "print(1)\n")
+        self.write("src/notes.md", "docs\n")
+        self.write("src/logo.png", "x")
+        (self.root / "monitored_paths.txt").write_text("src\n", encoding="utf-8")
+        cache = {}
+        ic.update_file_data(cache, "src/app.py", mtime=1, imports=[], resolved_pairs=[])
+        ic.update_file_data(cache, "src/other.py", mtime=1, imports=[], resolved_pairs=[])
+        ic.save_cache(self.root, cache)
+
+        # No health yet — in-scope mapped + monitored parseable gaps
+        v = health_mod.validate_health(self.root)
+        self.assertTrue(v.get("map_first"))
+        self.assertGreaterEqual(v.get("mapped_in_scope_without_health_count", 0), 1)
+        self.assertGreaterEqual(v.get("missing_count", 0), 1)
+        # notes.md / logo.png must not appear as monitored-source gaps
+        mon_missing = v.get("missing_monitored_source") or []
+        self.assertTrue(all(not m.endswith(".md") and not m.endswith(".png") for m in mon_missing))
+
+        health_mod.seed_health_from_map(self.root)  # only_monitored default
+        # Seed in-scope map keys; app.py on disk + mapped in-scope covered
+        v2 = health_mod.validate_health(self.root)
+        self.assertEqual(v2.get("mapped_in_scope_without_health_count"), 0)
+        # missing_count may still include on-disk sources not in map (ok if 0 after seed of map keys only)
+        self.assertEqual(v2.get("mapped_in_scope_without_health_count"), 0)
+
+    def test_prune_pending_and_health_to_monitored(self):
+        health_mod = importlib.import_module("wikifier.health")
+        (self.root / "monitored_paths.txt").write_text("src\n", encoding="utf-8")
+        self.write("src/keep.py", "k=1\n")
+        self.write("other/out.py", "o=1\n")
+        health_mod.upsert_entry(self.root, "src/keep.py", "🟡 Yellow", "in scope")
+        health_mod.upsert_entry(self.root, "other/out.py", "🟡 Yellow", "out of scope")
+        health_mod.add_to_pending(self.root, "src/keep.py", "need wiki")
+        health_mod.add_to_pending(self.root, "other/out.py", "noise")
+
+        pr = health_mod.prune_pending_to_monitored(self.root)
+        self.assertEqual(pr.get("removed"), 1)
+        self.assertEqual(health_mod.count_pending(self.root), 1)
+
+        hr = health_mod.prune_health_outside_monitored(self.root)
+        self.assertEqual(hr.get("removed"), 1)
+        entries = health_mod.load_health(self.root)["entries"]
+        self.assertIn("src/keep.py", entries)
+        self.assertNotIn("other/out.py", entries)
+
+
 if __name__ == "__main__":
     unittest.main()

{wikifier-4.5.5 → wikifier-4.5.8}/wikifier/__init__.py

@@ -71,4 +71,4 @@ from .contracts import (
     compute_acs_confidence,
 )
 
-__version__ = "4.5.5"
+__version__ = "4.5.8"

{wikifier-4.5.5 → wikifier-4.5.8}/wikifier/cli.py

@@ -616,23 +616,6 @@ def run_full_update(
             result["parse_errors"] = parse_errors[:10]
             result["parse_error_count"] = len(parse_errors)
 
-        # Seed health stubs for newly parsed files (map-first wiki: agents fill prose later)
-        health_seeded = 0
-        if _health_mod is not None and new_entries:
-            try:
-                existing = (_health_mod.load_health(root) or {}).get("entries") or {}
-                for rel in new_entries:
-                    if rel in existing:
-                        continue
-                    _health_mod.upsert_entry(
-                        root, rel, "🟡 Yellow",
-                        "Initial stub — parsed into map; agent should wiki + mark-green when editing"
-                    )
-                    health_seeded += 1
-            except Exception:
-                health_seeded = 0
-        result["health_stubs_seeded"] = health_seeded
-
         # === 4. Persist (single save; reload first to pick up the barrel flush) ===
         cache = ic.load_cache(root) or {}
         cache.update(new_entries)
@@ -669,6 +652,27 @@ def run_full_update(
         except Exception:
             pass
 
+        # === 5b. Map-first health stubs (always backfill; warm cache safe) ===
+        # 0-dirty incremental runs never used to create file_health.json — fixed here.
+        health_seeded = 0
+        if _health_mod is not None and hasattr(_health_mod, "seed_health_from_map"):
+            try:
+                max_seed = int(os.environ.get("WIKIFIER_HEALTH_SEED_MAX", "20000") or "20000")
+                map_keys = [k for k in cache if isinstance(k, str) and k and not k.startswith("_")]
+                seed_res = _health_mod.seed_health_from_map(
+                    root, map_keys=map_keys, max_new=max_seed,
+                )
+                health_seeded = int(seed_res.get("seeded") or 0)
+                if hasattr(_health_mod, "seed_health_for_monitored_sources"):
+                    disk_res = _health_mod.seed_health_for_monitored_sources(
+                        root, max_new=max_seed,
+                    )
+                    health_seeded += int(disk_res.get("seeded") or 0)
+            except Exception as se:
+                result["health_seed_error"] = str(se)
+                health_seeded = 0
+        result["health_stubs_seeded"] = health_seeded
+
         # === 6. library.md (atomic; pure Python) ===
         try:
             from .library import write_library_md
@@ -724,18 +728,20 @@ def main():
     i = 0
     while i < len(argv):
         arg = argv[i]
+        # Consume --target / --project-root so the *command* remains filtered_argv[0]
+        # (previously left --target as argv[0] → "Unknown command: --target").
         if arg in ("--target", "--project-root") and i + 1 < len(argv):
             project_root = argv[i + 1]
-            filtered_argv.append(arg)
-            filtered_argv.append(argv[i + 1])
             i += 2
             continue
         elif arg.startswith("--target="):
             project_root = arg.split("=", 1)[1]
-            filtered_argv.append(arg)
+            i += 1
+            continue
         elif arg.startswith("--project-root="):
             project_root = arg.split("=", 1)[1]
-            filtered_argv.append(arg)
+            i += 1
+            continue
         elif arg in ("--use-canonical", "--use_canonical"):
             use_canonical = True
             filtered_argv.append(arg)
@@ -857,13 +863,64 @@ def main():
                 if _health_mod is not None:
                     root = _get_effective_root(project_root)
                     res = _health_mod.validate_health(root)
-                    ghosts = []
-                    if hasattr(_health_mod, "find_ghost_entries"):
-                        ghosts = _health_mod.find_ghost_entries(root)
-                    res["ghost_count"] = len(ghosts)
-                    res["ghosts"] = ghosts[:50]
                     print(_json.dumps(res, indent=2, default=str))
+                    # Map-first: exit 0 when map is covered (or no map + no monitored source gaps)
                     return 0 if res.get("missing_count", 0) == 0 else 1
+            if _cmd0 in ("seed-health", "seed-health-from-map"):
+                import json as _json
+                if _health_mod is None:
+                    print("[wikifier] health module unavailable", file=sys.stderr)
+                    return 1
+                root = _get_effective_root(project_root)
+                res = _health_mod.seed_health_from_map(root)
+                if hasattr(_health_mod, "seed_health_for_monitored_sources"):
+                    disk = _health_mod.seed_health_for_monitored_sources(root)
+                    res["disk_seeded"] = disk.get("seeded")
+                    res["seeded_total"] = int(res.get("seeded") or 0) + int(disk.get("seeded") or 0)
+                print(_json.dumps(res, indent=2, default=str))
+                return 0 if res.get("success") else 1
+            if _cmd0 in ("prune-pending", "prune-pending-monitored"):
+                import json as _json
+                if _health_mod is None:
+                    print("[wikifier] health module unavailable", file=sys.stderr)
+                    return 1
+                root = _get_effective_root(project_root)
+                res = _health_mod.prune_pending_to_monitored(root)
+                print(_json.dumps(res, indent=2, default=str))
+                return 0 if res.get("success") else 1
+            if _cmd0 in ("prune-health-monitored", "prune-health"):
+                import json as _json
+                if _health_mod is None:
+                    print("[wikifier] health module unavailable", file=sys.stderr)
+                    return 1
+                root = _get_effective_root(project_root)
+                res = _health_mod.prune_health_outside_monitored(root)
+                print(_json.dumps(res, indent=2, default=str))
+                return 0 if res.get("success") else 1
+            if _cmd0 in (
+                "autonomous-status",
+                "autonomous_status",
+                "readiness",
+                "long-horizon",
+            ):
+                import json as _json
+                if _health_mod is None or not hasattr(_health_mod, "assess_autonomous_readiness"):
+                    print("[wikifier] health.assess_autonomous_readiness unavailable", file=sys.stderr)
+                    return 1
+                root = _get_effective_root(project_root)
+                res = _health_mod.assess_autonomous_readiness(root)
+                print(_json.dumps(res, indent=2, default=str))
+                # exit 0 only when not blocked
+                return 0 if res.get("readiness") != "blocked" else 2
+            if _cmd0 in ("metrics-snapshot", "metrics_snapshot", "metrics"):
+                import json as _json
+                if _health_mod is None or not hasattr(_health_mod, "write_metrics_snapshot"):
+                    print("[wikifier] write_metrics_snapshot unavailable", file=sys.stderr)
+                    return 1
+                root = _get_effective_root(project_root)
+                res = _health_mod.write_metrics_snapshot(root, source="cli")
+                print(_json.dumps(res, indent=2, default=str))
+                return 0 if res.get("success") else 1
         except Exception as e:
             print(f"[wikifier] Python-primary {_cmd0} failed: {e}", file=sys.stderr)
             return 1
@@ -1197,6 +1254,8 @@ def check_changes(project_root: Optional[Union[str, Path]] = None) -> Dict[str,
             ghosts_marked = 0
             if _health_mod is not None:
                 root_res = root.resolve()
+                # Prefer unlocked helpers while we already hold project lock
+                _upsert = getattr(_health_mod, "_do_upsert_entry", None) or _health_mod.upsert_entry
                 for p in dirty_batch:
                     try:
                         pr = Path(p).resolve()
@@ -1205,13 +1264,20 @@ def check_changes(project_root: Optional[Union[str, Path]] = None) -> Dict[str,
                         rel = str(pr.relative_to(root_res))
                     except Exception:
                         continue
-                    _health_mod.upsert_entry(
+                    _upsert(
                         root, rel, "🟡 Yellow",
                         "mtime changed since last check-changes (Python primary auto-detected)"
                     )
                     _add_to_pending(root, rel, "Auto-detected modification — review and run mark-green after wiki update")
                     _ensure_journal_entry(root, "auto-detected", rel, "File mtime changed (check_changes Python primary)")
                     changed_count += 1
+                # Keep pending queue aligned with lean monitored_paths (no flood outside scope)
+                if hasattr(_health_mod, "prune_pending_to_monitored"):
+                    try:
+                        pr = _health_mod.prune_pending_to_monitored(root)
+                        result["pending_pruned"] = pr.get("removed", 0)
+                    except Exception:
+                        pass
 
                 # G7: surface ghost health entries (tracked path missing on disk, not already DELETED)
                 try:
@@ -1379,12 +1445,14 @@ def suggest_next_actions(
     """
     root = _get_effective_root(project_root)
     try:
-        red = yellow = 0
+        red = yellow = stub_y = action_y = 0
         health_sum: Dict[str, Any] = {}
         if _health_mod is not None:
             health_sum = _health_mod.get_summary(root, directory) or {}
-            red = health_sum.get("red", 0)
-            yellow = health_sum.get("yellow", 0)
+            red = int(health_sum.get("red", 0) or 0)
+            yellow = int(health_sum.get("yellow", 0) or 0)
+            stub_y = int(health_sum.get("stub_yellow", 0) or 0)
+            action_y = int(health_sum.get("actionable_yellow", yellow - stub_y) or 0)
 
         suggestions: List[str] = []
         n = 1
@@ -1394,10 +1462,23 @@ def suggest_next_actions(
                 "Do not re-wiki 🟢 Green files."
             )
             n += 1
-        if yellow > 0:
+        if action_y > 0:
             suggestions.append(
-                f"{n}. Review the {yellow} 🟡 Yellow file(s) only — record-change intent, refresh wiki, mark-green. "
-                "Skip green unless a dependent of a yellow/red requires it."
+                f"{n}. Review {action_y} *actionable* 🟡 Yellow file(s) "
+                "(mtime/record-change/barrel — not Initial stubs). "
+                "record-change → wiki that file → mark-green. Skip green."
+            )
+            n += 1
+        if stub_y > 0 and action_y == 0 and red == 0:
+            suggestions.append(
+                f"{n}. Map-first OK: {stub_y} 🟡 Initial stubs mean \"on the map\", "
+                "NOT \"wiki this tree now\". Lookup via get_file_wiki/deps; "
+                "write prose only when you edit a file, then mark-green."
+            )
+            n += 1
+        elif stub_y > 0 and action_y > 0:
+            suggestions.append(
+                f"{n}. Ignore {stub_y} map-first stubs for bulk work; only actionable yellows need wiki."
             )
             n += 1
         if red == 0 and yellow == 0:
@@ -1405,6 +1486,15 @@ def suggest_next_actions(
                 f"{n}. Health is clean (no red/yellow). Do not re-summarize the tree; use the map for lookup only."
             )
             n += 1
+        # Scope hygiene
+        if _health_mod is not None and hasattr(_health_mod, "detect_scope_risks"):
+            try:
+                scope = _health_mod.detect_scope_risks(root) or {}
+                for w in (scope.get("warnings") or [])[:2]:
+                    suggestions.append(f"{n}. SCOPE: {w}")
+                    n += 1
+            except Exception:
+                pass
         suggestions.append(
             f"{n}. Run `update_maps(directory=...)` only if imports/structure changed (not for wiki-only edits)."
         )
@@ -1413,7 +1503,10 @@ def suggest_next_actions(
             f"{n}. On yellow/red hotspots, query dependents (get_dependents) before editing callers."
         )
         n += 1
-        suggestions.append(f"{n}. Review journal/ for recent record-change intent (self-audit).")
+        suggestions.append(
+            f"{n}. Long-horizon: `wikifier autonomous-status` before unattended daemon; "
+            "lean monitored_paths; never parent multi-repo folders as project_root."
+        )
 
         acs_note = ""
         if _ic_mod is not None:
@@ -1448,10 +1541,14 @@ def suggest_next_actions(
                 "project_root": str(root),
                 "red": red,
                 "yellow": yellow,
+                "stub_yellow": stub_y,
+                "actionable_yellow": action_y,
+                "health_score": health_sum.get("health_score"),
                 "suggestions": suggestions,
                 "health_summary": health_sum,
                 "acs_note": acs_note,
                 "selective_work": True,
+                "map_first": True,
             }
         return "\n".join(suggestions) + (acs_note or "")
     except Exception as e: