wikifier 4.5.6__tar.gz → 4.5.9__tar.gz

{wikifier-4.5.6/wikifier.egg-info → wikifier-4.5.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.5.6
+Version: 4.5.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.5.6 → wikifier-4.5.9}/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.6 → wikifier-4.5.9}/tests/test_gap_closure.py

@@ -103,6 +103,85 @@ class TestAcsActionableG4(TempProjectTestCase):
             for p in action
         ))
 
+    def test_dynamic_literal_noise_demoted_from_actionable(self):
+        """ACS v1.2: importlib.import_module(\"pkg\") static dynamics are not actionable."""
+        dyn_lit = {
+            "raw": "\"wikifier.health\"",
+            "resolved": "wikifier.health",
+            "resolved_path": None,
+            "is_dynamic": True,
+            "dynamic_type": "static",
+            "confidence_score": 0.05,
+            "confidence_reasons": [
+                "base:low", "conditional_context", "dynamic",
+                "detector:TernaryDetector",
+            ],
+            "confidence_explanation": (
+                'Base low (0.05). TernaryDetector=importlib.import_module("wikifier.health"). '
+                "Recommendation: Runtime optional load is expected noise."
+            ),
+            "resolution_metadata": {"strategy": "python-dynamic"},
+        }
+        project_fragile = {
+            "raw": "./missing_local",
+            "resolved": "missing_local",
+            "resolved_path": None,
+            "is_dynamic": False,
+            "confidence_score": 0.35,
+            "confidence_reasons": ["base:low", "no_resolved_path"],
+            "confidence_explanation": "Unresolved project-local. Recommendation: fix path.",
+            "diagnostic": {"category": "project"},
+            "resolution_metadata": {"strategy": "relative-fs"},
+        }
+        cache = {
+            "mod.py": {
+                "mtime": 1,
+                "resolved_pairs": [dyn_lit, project_fragile],
+            }
+        }
+        self.assertTrue(ic._edge_is_dynamic_literal_noise(dyn_lit))
+        self.assertFalse(ic._edge_is_dynamic_literal_noise(project_fragile))
+        summary = ic.compute_acs_summary(cache)
+        self.assertEqual(summary.get("acs_version"), "1.2")
+        self.assertGreaterEqual(summary["low_conf_edges"], 2)
+        self.assertEqual(summary["actionable_low_conf_edges"], 1)
+        self.assertGreaterEqual(summary.get("dynamic_literal_noise_edges", 0), 1)
+        action = ic.get_low_confidence_edges(cache, actionable_only=True)
+        self.assertEqual(len(action), 1)
+        self.assertIn("missing_local", str(action[0].get("raw") or action[0].get("resolved")))
+
+
+class TestLoadSafetyNoImportCycle(unittest.TestCase):
+    """Load-time safety: core modules import without circular-import failure."""
+
+    def test_import_wikifier_and_cycle_trio(self):
+        import importlib
+        import wikifier
+        self.assertTrue(hasattr(wikifier, "discover_project_root"))
+        # Fresh submodule loads (project_root breaks former cli↔cache↔bree SCC)
+        for name in (
+            "wikifier.project_root",
+            "wikifier.cli",
+            "wikifier.import_cache",
+            "wikifier.parsers.bree",
+        ):
+            mod = importlib.import_module(name)
+            self.assertIsNotNone(mod)
+        from wikifier.project_root import discover_project_root as dpr
+        from wikifier.cli import discover_project_root as dpr_cli
+        self.assertIs(dpr, dpr_cli)
+        root = dpr()
+        self.assertTrue(root.exists())
+
+    def test_bree_does_not_import_cli_at_module_level(self):
+        """Static check: bree source must not load-time import wikifier.cli."""
+        from pathlib import Path
+        bree_src = Path(__file__).resolve().parents[1] / "wikifier" / "parsers" / "bree.py"
+        text = bree_src.read_text(encoding="utf-8")
+        self.assertNotIn("from ..cli import", text)
+        self.assertNotIn("from wikifier.cli import", text)
+        self.assertIn("from ..project_root import", text)
+
 
 class TestGhostAndDeletionG7(TempProjectTestCase):
     def test_find_ghost_and_record_deletion(self):
@@ -190,6 +269,84 @@ 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."""

{wikifier-4.5.6 → wikifier-4.5.9}/wikifier/__init__.py

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

{wikifier-4.5.6 → wikifier-4.5.9}/wikifier/cli.py

@@ -21,136 +21,9 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 from contextlib import nullcontext as _nullcontext
 
-
-def discover_project_root() -> Path:
-    """
-    Unified discovery helper for the *target project root* (user codebase / monorepo).
-
-    This is the canonical implementation for CLI, MCP, direct Python use, and
-    is mirrored (same priority + markers) by the shell script's discover_project_root().
-
-    Highest-leverage fix for External / Packaged Full-Update Robustness (Gap #1):
-    Makes `pip install wikifier` + `wikifier ...` (or direct packaged sh) reliable
-    from any external monorepo cwd without requiring manual WIKIFIER_PROJECT_ROOT
-    or --target on every invocation. Zero-dependency.
-
-    Wave 3 hardening (symlinks + pnpm/yarn stores):
-    - Consults $PWD (and $OLDPWD) logical cwd in addition to Path.cwd() / .resolve().
-    - Walks parent chains from *logical* start points first; this ensures that when
-      cwd is deep inside a pnpm symlinked store layout (e.g. monorepo/node_modules/.pnpm/pkg@1/.../pkg
-      whose physical target is /global-store/...), the logical ancestor chain still reaches
-      the real project root markers (.git, package.json etc.) outside the store.
-    - Falls back to resolved physical; returns the outermost marker root found.
-    - Prevents packaged/parser/daemon from accidentally using a store dir as PROJECT_ROOT.
-
-    Wave 4 further hardening for complex monorepo layouts:
-    - Collects *all* candidate marker roots across logical/physical/realpath chains (no early return).
-    - Selects the outermost (shallowest fs path) preferring .git roots, then lockfiles (pnpm/yarn), then other.
-      This correctly picks true monorepo root even when deep sub-packages have their own package.json / yarn workspaces.
-    - Expanded common markers: pnpm-lock.yaml, yarn.lock, lerna.json, nx.json, turbo.json, rush.json, workspace yamls.
-    - Explicit skipping of node_modules/.pnpm / .yarn / .pnp internals as candidate roots (even on logical paths).
-    - Additional os.path.realpath chains for nested/broken symlink monorepo layouts.
-    - Daemon, parsers (via _get_*_fallback), run_full_update all inherit automatically.
-    """
-    # 1. Explicit env var (highest priority, supports all the R6 --target flows)
-    env_root = os.environ.get("WIKIFIER_PROJECT_ROOT")
-    if env_root:
-        p = Path(env_root).expanduser().resolve()
-        if p.exists():
-            return p
-
-    # Wave 3/4: logical cwd (PWD/OLDPWD) + physical + realpath fallbacks for symlink/pnpm/yarn/nested
-    cwd = Path.cwd()
-    logical_cwd_str = os.environ.get("PWD") or os.environ.get("OLDPWD") or str(cwd)
-    try:
-        logical_cwd = Path(logical_cwd_str).expanduser()
-    except Exception:
-        logical_cwd = cwd
-
-    start_points: List[Path] = []
-    for start in (logical_cwd, cwd, cwd.resolve()):
-        if start and start not in start_points:
-            start_points.append(start)
-
-    # Wave 4: realpath variants for deeper symlink nest robustness (e.g. git submodules + pnpm links)
-    for sp in list(start_points):
-        try:
-            rp = Path(os.path.realpath(str(sp)))
-            if rp not in start_points:
-                start_points.append(rp)
-        except Exception:
-            continue
-
-    # 2/3. Markers: wikifier-specific + expanded common monorepo (Wave 4)
-    wikifier_specific = [".wikifier", "monitored_paths.txt", ".wikifier/config"]
-    common_markers = [
-        ".git", "package.json", "pyproject.toml", "setup.py", "setup.cfg",
-        "Cargo.toml", "go.mod", ".hg",
-        # Wave 4 monorepo root indicators (for workspace/subpkg layouts + yarn/pnpm detection)
-        "pnpm-lock.yaml", "yarn.lock", "lerna.json", "nx.json", "turbo.json",
-        "rush.json", "workspace.json", "pnpm-workspace.yaml", ".yarnrc.yml"
-    ]
-    store_indicators = (".pnpm", ".yarn", ".pnp", ".pnp.cjs", "virtual-store", ".store")
-
-    candidates: List[Path] = []
-    for start in start_points:
-        try:
-            parent_chain = [start] + list(start.parents)
-        except Exception:
-            parent_chain = [start]
-
-        # Wikifier markers (post-init)
-        for parent in parent_chain:
-            try:
-                pstr = str(parent)
-                if any(ind in pstr for ind in store_indicators) and "node_modules" in pstr:
-                    continue  # never treat deep pnpm/yarn store paths as project root
-                if ((parent / ".wikifier").is_dir() or
-                        (parent / "monitored_paths.txt").exists() or
-                        (parent / ".wikifier/config").exists()):
-                    if parent not in candidates:
-                        candidates.append(parent)
-            except Exception:
-                continue
-
-        # Common + monorepo markers (any-scale external)
-        for parent in parent_chain:
-            try:
-                pstr = str(parent)
-                if any(ind in pstr for ind in store_indicators) and "node_modules" in pstr:
-                    continue
-                for marker in common_markers:
-                    if (parent / marker).exists():
-                        if parent not in candidates:
-                            candidates.append(parent)
-            except Exception:
-                continue
-
-    if candidates:
-        # Wave 4: pick outermost/shallowest, with strong preference for .git (true monorepo root)
-        # even if a deeper packages/*/package.json also matches. Solves workspace subdir case.
-        def _root_key(p: Path):
-            try:
-                rp = p.resolve()
-                has_git = (rp / ".git").exists() or (rp / ".git").is_file()  # worktree support
-                depth = len(rp.parts)
-                return (0 if has_git else 1, depth, str(rp))
-            except Exception:
-                return (99, 99999, str(p))
-
-        best = min(candidates, key=_root_key)
-        try:
-            return best.resolve() if best.exists() else best
-        except Exception:
-            return best
-
-    # 4. Last-resort sensible default: the directory the user is running from.
-    #    This is the key robustness fix vs. old "fall back to package dir".
-    #    Prefer resolved for the final fallback.
-    try:
-        return cwd.resolve()
-    except Exception:
-        return cwd
+# Canonical discovery lives in project_root (no cli↔cache↔bree load cycle).
+# Re-export for public API: `from wikifier.cli import discover_project_root`.
+from .project_root import discover_project_root  # noqa: F401
 
 
 # =============================================================================
@@ -728,18 +601,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)
@@ -895,6 +770,30 @@ def main():
                 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
@@ -1419,12 +1318,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
@@ -1434,10 +1335,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 {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}. 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}. 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:
@@ -1445,6 +1359,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)."
         )
@@ -1453,7 +1376,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:
@@ -1488,10 +1414,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: