ltcai 9.6.0 → 9.7.0

package/latticeai/core/agent_eval.py

@@ -34,6 +34,7 @@ from latticeai.core.agent import (
     AgentState,
     SingleAgentRuntime,
 )
+from latticeai.tools import ToolError
 
 _AUTO_POLICY = {
     "auto_approve": True, "risk": "low", "shell": False, "network": False,
@@ -43,6 +44,43 @@ _DESTRUCTIVE_POLICY = {
     "auto_approve": False, "risk": "destructive", "shell": True, "network": False,
     "destructive": True, "sandbox": False, "rollback": "none",
 }
+# Mirrors production write-tool governance when the change governor is wired:
+# not auto-approved, so only the governor's additive/proposed verdicts (never
+# the model) decide whether a write runs or is staged for review.
+_GOVERNED_WRITE_POLICY = {
+    "auto_approve": False, "risk": "write", "shell": False, "network": False,
+    "destructive": False, "sandbox": "workspace", "rollback": "git",
+}
+
+
+class _EvalChangeGovernor:
+    """Deterministic stand-in for ChangeProposalService's governor port.
+
+    Mirrors the wire contract of
+    :meth:`latticeai.services.change_proposals.ChangeProposalService.review`:
+    ``None`` falls through, additive writes get ``allow_additive``, and
+    mutations of "existing" paths come back ``proposed`` with a proposal id —
+    exactly what the agent loop routes into the review queue.
+    """
+
+    governed_tools = frozenset({"write_file", "edit_file"})
+
+    def __init__(self) -> None:
+        self.proposals: List[Dict[str, Any]] = []
+
+    def review(self, name, args, *, policy=None, user_email=None, workspace_id=None, conversation_id=None):
+        if name not in self.governed_tools:
+            return None
+        path = str(args.get("path") or "")
+        if path.startswith("existing"):
+            proposal = {"id": f"eval-proposal-{len(self.proposals) + 1}", "path": path}
+            self.proposals.append(proposal)
+            return {
+                "decision": "proposed",
+                "classification": {"change_class": "mutation"},
+                "proposal": proposal,
+            }
+        return {"decision": "allow_additive", "classification": {"change_class": "additive"}}
 
 
 @dataclass
@@ -56,6 +94,11 @@ class Scenario:
     expect_min: Dict[str, int] = field(default_factory=dict)
     expect_exact: Dict[str, Any] = field(default_factory=dict)
     expect_tool_outcomes: Dict[str, int] = field(default_factory=dict)
+    # Exact ordered sequence of tool names that actually executed (successful
+    # execute_tool calls only — proposed/blocked/failed calls never run).
+    expect_tool_calls: List[str] = field(default_factory=list)
+    # Wire a change governor so governed tools follow the proposal path.
+    use_governor: bool = False
     max_steps: int = 8
 
 
@@ -69,7 +112,12 @@ class _Req:
         self.message = message
 
 
-def _build_deps(replies: List[str], tool_log: List[Dict[str, Any]]) -> AgentDeps:
+def _build_deps(
+    replies: List[str],
+    tool_log: List[Dict[str, Any]],
+    *,
+    governor: Any = None,
+) -> AgentDeps:
     queue = list(replies)
 
     async def generate_as(model_id, message, context, max_tokens, temperature):
@@ -83,14 +131,21 @@ def _build_deps(replies: List[str], tool_log: List[Dict[str, Any]]) -> AgentDeps
         return '{"action": "noop"}'
 
     def execute_tool(name: str, args: dict) -> dict:
+        # File-producing tools fail like the real dispatcher when the model
+        # forgets the target path — scenarios use this to exercise recovery.
+        if name in ("write_file", "generate_file") and not args.get("path"):
+            raise ToolError(f"{name} requires args.path")
         tool_log.append({"name": name, "args": args})
         return {"ok": True, "path": args.get("path", "")}
 
     def policy_for(name: str, args: dict) -> dict:
         if name == "delete_everything":
             return dict(_DESTRUCTIVE_POLICY)
+        if governor is not None and name in ("write_file", "edit_file"):
+            return dict(_GOVERNED_WRITE_POLICY)
         return dict(_AUTO_POLICY)
 
+    write_policy = dict(_GOVERNED_WRITE_POLICY) if governor is not None else dict(_AUTO_POLICY)
     return AgentDeps(
         generate_as=generate_as,
         generate=generate,
@@ -99,17 +154,19 @@ def _build_deps(replies: List[str], tool_log: List[Dict[str, Any]]) -> AgentDeps
         risk_level=lambda p: p["risk"],
         check_role=lambda name, user: None,
         tool_governance={
-            "write_file": dict(_AUTO_POLICY),
+            "write_file": write_policy,
             "read_file": dict(_AUTO_POLICY),
+            "generate_file": dict(_AUTO_POLICY),
             "delete_everything": dict(_DESTRUCTIVE_POLICY),
         },
-        file_create_actions=frozenset({"write_file"}),
+        file_create_actions=frozenset({"write_file", "generate_file"}),
         recent_chat_context=lambda **kw: "",
         clear_history=lambda keep: {"ok": True},
         knowledge_save=lambda *a, **kw: None,
         audit=lambda *a, **kw: None,
         planner_prompt="plan", executor_prompt="exec", critic_prompt="critic",
         memory_updater_prompt="mem", agent_root=Path("/tmp/agent-eval"),
+        change_governor=governor,
     )
 
 
@@ -193,12 +250,96 @@ def default_scenarios() -> List[Scenario]:
             expect_min={"parse_errors": 3},
             expect_exact={"tool_outcomes": {}},
         ),
+        # ── file generation ─────────────────────────────────────────────
+        Scenario(
+            name="file-generation-happy-path",
+            replies=[
+                '{"action": "plan", "goal": "generate landing page", '
+                '"steps": [{"action": "generate_file"}]}',
+                # Small local models wrap the payload in reasoning + fences;
+                # the loop must still extract one clean tool call.
+                "<think>layout first, then hero copy</think>\n"
+                '```json\n{"thoughts": "produce the full document", '
+                '"action": "generate_file", "args": {"path": "site/index.html", '
+                '"content": "<!DOCTYPE html><html><body>hello</body></html>"}}\n```',
+                _FINAL,
+                _PASS,
+            ],
+            expect_exact={"parse_errors": 0},
+            expect_tool_outcomes={"ok": 1},
+            expect_tool_calls=["generate_file"],
+        ),
+        Scenario(
+            name="file-generation-bad-args-recovers",
+            replies=[
+                '{"action": "plan", "goal": "generate report", '
+                '"steps": [{"action": "generate_file"}]}',
+                # Malformed tool call: the model forgot the target path, the
+                # tool port fails like the real dispatcher would…
+                '{"thoughts": "write it", "action": "generate_file", '
+                '"args": {"content": "<html></html>"}}',
+                # …and the next turn recovers with a complete call.
+                '{"thoughts": "add the missing path", "action": "generate_file", '
+                '"args": {"path": "reports/q3.html", "content": "<html></html>"}}',
+                _FINAL,
+                _PASS,
+            ],
+            expect_tool_outcomes={"error": 1, "ok": 1},
+            expect_tool_calls=["generate_file"],
+        ),
+        # ── multi-step workflow ─────────────────────────────────────────
+        Scenario(
+            name="multi-step-workflow-chain",
+            replies=[
+                '{"action": "plan", "goal": "read spec, generate report, save summary", '
+                '"steps": [{"action": "read_file"}, {"action": "generate_file"}, '
+                '{"action": "write_file"}]}',
+                '{"thoughts": "step 1: read the source spec", '
+                '"action": "read_file", "args": {"path": "spec.md"}}',
+                '{"thoughts": "step 2: the spec asks for an HTML report", '
+                '"action": "generate_file", "args": {"path": "report.html", '
+                '"content": "<html><body>report</body></html>"}}',
+                '{"thoughts": "step 3: persist a short summary next to it", '
+                '"action": "write_file", "args": {"path": "summary.txt", '
+                '"content": "report generated"}}',
+                _FINAL,
+                _PASS,
+            ],
+            expect_exact={"parse_errors": 0},
+            expect_min={"llm_calls": 6},
+            expect_tool_outcomes={"ok": 3},
+            expect_tool_calls=["read_file", "generate_file", "write_file"],
+        ),
+        # ── governed-tool proposal path ─────────────────────────────────
+        Scenario(
+            name="governed-write-proposal-path",
+            use_governor=True,
+            replies=[
+                # write_file is NOT auto-approved here, but it is governed —
+                # approve() must not hard-block the plan (core invariant:
+                # governed tools are excluded from the non-auto set).
+                '{"action": "plan", "goal": "update existing page, add new note", '
+                '"steps": [{"action": "write_file"}]}',
+                # Mutation of existing content → staged as proposal, not written.
+                '{"thoughts": "rewrite the existing page", "action": "write_file", '
+                '"args": {"path": "existing/site.html", "content": "<new>"}}',
+                # Additive create → governor allows it to run immediately.
+                '{"thoughts": "add a fresh note", "action": "write_file", '
+                '"args": {"path": "fresh/new-note.md", "content": "hello"}}',
+                _FINAL,
+                _PASS,
+            ],
+            expect_exact={"parse_errors": 0},
+            expect_tool_outcomes={"proposed": 1, "ok": 1},
+            expect_tool_calls=["write_file"],
+        ),
     ]
 
 
 async def _run_scenario(scenario: Scenario) -> Dict[str, Any]:
     tool_log: List[Dict[str, Any]] = []
-    deps = _build_deps(scenario.replies, tool_log)
+    governor = _EvalChangeGovernor() if scenario.use_governor else None
+    deps = _build_deps(scenario.replies, tool_log, governor=governor)
     runtime = SingleAgentRuntime(deps)
     ctx = AgentRunContext()
     ctx.state = AgentState.PLANNING
@@ -226,6 +367,14 @@ async def _run_scenario(scenario: Scenario) -> Dict[str, Any]:
             failures.append(
                 f"tool_outcomes[{outcome}]={summary['tool_outcomes'].get(outcome, 0)} != {count}"
             )
+    executed = [call["name"] for call in tool_log]
+    if scenario.expect_tool_calls and executed != scenario.expect_tool_calls:
+        failures.append(f"tool_calls={executed} != {scenario.expect_tool_calls}")
+    if governor is not None and summary["tool_outcomes"].get("proposed", 0) != len(governor.proposals):
+        failures.append(
+            f"governor proposals={len(governor.proposals)} != "
+            f"traced proposed={summary['tool_outcomes'].get('proposed', 0)}"
+        )
     return {
         "name": scenario.name,
         "ok": not failures,
@@ -233,6 +382,8 @@ async def _run_scenario(scenario: Scenario) -> Dict[str, Any]:
         "final_state": ctx.state.value,
         "summary": summary,
         "tool_calls": len(tool_log),
+        "executed_tools": executed,
+        "proposals": len(governor.proposals) if governor is not None else 0,
     }
 
 

package/latticeai/core/legacy_compatibility.py

@@ -14,7 +14,7 @@ from pathlib import Path
 from typing import Any, Dict, List
 
 
-LEGACY_COMPATIBILITY_VERSION = "9.6.0"
+LEGACY_COMPATIBILITY_VERSION = "9.7.0"
 
 
 @dataclass(frozen=True)
@@ -82,6 +82,20 @@ LEGACY_SHIMS: List[LegacyShim] = [
         reason="Old gardener scripts referenced the root reinforcement helper.",
         removal_phase="major-release-after-8.x",
     ),
+    LegacyShim(
+        path="mcp_registry.py",
+        owner="latticeai.core.mcp_registry",
+        replacement="import latticeai.core.mcp_registry",
+        reason="Older integrations imported the MCP registry from the repo root.",
+        removal_phase="major-release-after-9.x",
+    ),
+    LegacyShim(
+        path="llm_router.py",
+        owner="latticeai.models.router",
+        replacement="import latticeai.models.router",
+        reason="Historical scripts and tests imported the LLM router from the repo root.",
+        removal_phase="major-release-after-9.x",
+    ),
     LegacyShim(
         path="server.py",
         owner="latticeai.server_app",

package/latticeai/core/marketplace.py

@@ -11,7 +11,7 @@ from copy import deepcopy
 from typing import Any, Dict, List, Optional
 
 
-MARKETPLACE_VERSION = "9.6.0"
+MARKETPLACE_VERSION = "9.7.0"
 TEMPLATE_KINDS = ("plugin", "workflow", "agent", "ingestion_bridge")
 
 

package/latticeai/core/workspace_os.py

@@ -49,7 +49,7 @@ __all__ = [
     "remove_skill_directory",
 ]
 
-WORKSPACE_OS_VERSION = "9.6.0"
+WORKSPACE_OS_VERSION = "9.7.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/latticeai/runtime/router_registration.py

@@ -604,6 +604,7 @@ def register_review_and_brain_tail_routers(
     gardener: Any,
     create_setup_router: Any,
     model_router: Any,
+    change_proposals: Any = None,
 ) -> Any:
     """Register the final review/browser/brain tail routes in legacy order."""
 
@@ -616,6 +617,7 @@ def register_review_and_brain_tail_routers(
             gate_write=gate_write,
             run_review_item=run_review_item,
             append_audit_event=append_audit_event,
+            change_proposals=change_proposals,
         ),
         create_browser_router(
             pipeline=ingestion_pipeline,

package/latticeai/services/architecture_readiness.py

@@ -17,7 +17,7 @@ from typing import Any, Dict, List
 from latticeai.core.legacy_compatibility import legacy_shim_report
 
 
-ARCHITECTURE_VERSION_TARGET = "9.6.0"
+ARCHITECTURE_VERSION_TARGET = "9.7.0"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",

package/latticeai/services/brain_intelligence.py

@@ -65,6 +65,23 @@ class BrainIntelligenceService:
         self._enable_graph = bool(enable_graph and knowledge_graph is not None)
         self._memory_quality = MemoryQualityManager()
         self._edge_quality = GraphEdgeQualityManager()
+        self._proactive_brain: Any = None
+
+    def _proactive(self) -> Any:
+        """Lazy graph-layer ProactiveBrain over the injected store (or None)."""
+        if not self._enable_graph:
+            return None
+        if self._proactive_brain is None:
+            try:
+                from lattice_brain.graph.proactive import ProactiveBrain
+
+                self._proactive_brain = ProactiveBrain(
+                    self._kg, sample_limit=_GRAPH_SAMPLE_LIMIT
+                )
+            except Exception:
+                LOGGER.exception("proactive brain initialization failed")
+                return None
+        return self._proactive_brain
 
     # ── shared graph sampling ─────────────────────────────────────────────
 
@@ -302,6 +319,56 @@ class BrainIntelligenceService:
             "generated_at": _now(),
         }
 
+    # ── graph-layer proactive quality (v9.6.x) ───────────────────────────
+
+    def graph_duplicates(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Duplicate graph nodes (exact groups + near pairs) — read only."""
+        proactive = self._proactive()
+        if proactive is None:
+            return {
+                "available": False,
+                "exact_groups": [],
+                "near_pairs": [],
+                "exact_duplicate_nodes": 0,
+                "nodes_scanned": 0,
+                "generated_at": _now(),
+            }
+        try:
+            result = dict(proactive.find_duplicates(workspace_id=workspace_id))
+        except Exception as exc:
+            LOGGER.exception("graph duplicates scan failed")
+            return {
+                "available": False,
+                "error": str(exc),
+                "exact_groups": [],
+                "near_pairs": [],
+                "exact_duplicate_nodes": 0,
+                "nodes_scanned": 0,
+                "generated_at": _now(),
+            }
+        result["available"] = True
+        result["generated_at"] = _now()
+        return result
+
+    def quality_report(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Combined graph quality report: duplicates, contradictions, stale
+        nodes, edge quality — one workspace-scoped graph sample."""
+        proactive = self._proactive()
+        if proactive is None:
+            return {"available": False, "generated_at": _now()}
+        try:
+            result = dict(proactive.quality_report(workspace_id=workspace_id))
+        except Exception as exc:
+            LOGGER.exception("graph quality report failed")
+            return {"available": False, "error": str(exc), "generated_at": _now()}
+        result["available"] = True
+        result["generated_at"] = _now()
+        return result
+
     # ── contradictions ───────────────────────────────────────────────────
 
     def contradictions(
@@ -365,7 +432,21 @@ class BrainIntelligenceService:
                     "signal": "contradicts_edge",
                 })
 
-        items = conflicts + temporal_items + edge_items
+        # v9.6.x additive: graph-layer node-content contradictions (proactive
+        # detector over node title/summary), on top of the memory + edge scans.
+        graph_pair_items: List[Dict[str, Any]] = []
+        proactive = self._proactive()
+        if proactive is not None:
+            try:
+                graph_result = proactive.detect_contradictions(workspace_id=workspace_id)
+                graph_pair_items = [
+                    {"kind": "graph_node_pair", **pair}
+                    for pair in graph_result.get("node_pairs") or []
+                ]
+            except Exception:
+                LOGGER.exception("graph contradiction scan failed")
+
+        items = conflicts + temporal_items + edge_items + graph_pair_items
         return {
             "items": items,
             "count": len(items),
@@ -373,6 +454,7 @@ class BrainIntelligenceService:
                 "memory_pairs": len(conflicts),
                 "temporal": len(temporal_items),
                 "graph_edges": len(edge_items),
+                "graph_node_pairs": len(graph_pair_items),
             },
             "memories_scanned": len(memory_rows),
             "generated_at": _now(),
@@ -422,6 +504,19 @@ class BrainIntelligenceService:
             except Exception:
                 LOGGER.exception("consolidation prune failed")
 
+        # v9.6.x additive: graph-layer node merge plan. Always dry-run from
+        # this service — graph content changes stay proposal-first; the plan
+        # is surfaced so a governed apply path can adopt it later.
+        graph_consolidation: Optional[Dict[str, Any]] = None
+        proactive = self._proactive()
+        if proactive is not None:
+            try:
+                graph_consolidation = proactive.consolidate_duplicates(
+                    workspace_id=workspace_id, dry_run=True
+                )
+            except Exception:
+                LOGGER.exception("graph consolidation plan failed")
+
         return {
             "mode": "applied" if apply else "dry_run",
             "memories_scanned": len(memory_rows),
@@ -432,6 +527,7 @@ class BrainIntelligenceService:
             # mutates graph content directly.
             "duplicate_edges": duplicate_edge_ids[:50],
             "duplicate_edge_count": len(duplicate_edge_ids),
+            "graph_consolidation": graph_consolidation,
             "generated_at": _now(),
         }
 

package/latticeai/services/change_proposals.py

@@ -71,6 +71,7 @@ class ChangeProposalService:
         policy: Optional[Dict[str, Any]] = None,
         user_email: Optional[str] = None,
         workspace_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
     ) -> Optional[Dict[str, Any]]:
         """Governor port for the agent loop.
 
@@ -102,6 +103,15 @@ class ChangeProposalService:
                 reason=verdict["reason"],
                 user_email=user_email,
                 workspace_id=workspace_id,
+                context={
+                    # Full provenance for the Review Center: which tool asked,
+                    # how the governor classified it, and the policy risk.
+                    "tool": name,
+                    "change_class": verdict.get("change_class"),
+                    "risk": (policy or {}).get("risk"),
+                    "conversation_id": conversation_id,
+                    "source_detail": "agent change governor",
+                },
             )
         except Exception:
             LOGGER.exception("change proposal staging failed")
@@ -152,10 +162,15 @@ class ChangeProposalService:
         reason: str = "",
         user_email: Optional[str] = None,
         workspace_id: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None,
     ) -> Dict[str, Any]:
         before = self._read_before(path)
         diff = _unified_diff(before, new_content, path)
         tier = "small" if len(diff) <= _SMALL_TIER_DIFF_LINES else "large"
+        provenance: Dict[str, Any] = {"proposed_by": proposed_by, "reason": reason}
+        for key, value in (context or {}).items():
+            if value is not None and key not in provenance:
+                provenance[key] = value
         item = self._review_queue.create(
             title=f"파일 수정 제안: {path}",
             summary=reason or "기존 파일을 변경하는 작업이라 검토 후 적용됩니다.",
@@ -169,7 +184,7 @@ class ChangeProposalService:
                 "before_bytes": len(before.encode("utf-8")),
                 "after_bytes": len(new_content.encode("utf-8")),
             },
-            provenance={"proposed_by": proposed_by, "reason": reason},
+            provenance=provenance,
             user_email=user_email,
             workspace_id=workspace_id,
         )
@@ -232,11 +247,36 @@ class ChangeProposalService:
             },
         }
 
+    def counts(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Pending proposal count for the Review Center badge."""
+        listed = self._review_queue.list(
+            workspace_id=workspace_id, user_email=user_email,
+            status="pending", source="change_proposal",
+        )
+        return {"pending": len(listed.get("items") or [])}
+
+    def get_proposal(
+        self, item_id: str, *, workspace_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Full proposal detail (diff + staged content) for the preview UI.
+
+        Raises ``KeyError`` when the id exists but is not a change proposal,
+        so the API surface cannot leak arbitrary review items.
+        """
+        item = self._review_queue.get(item_id, workspace_id=workspace_id)
+        if item.get("source") != "change_proposal":
+            raise KeyError(f"not a change proposal: {item_id}")
+        return item
+
     def approve_and_apply(
         self, item_id: str, *, user_email: Optional[str] = None,
         workspace_id: Optional[str] = None,
     ) -> Dict[str, Any]:
         item = self._review_queue.get(item_id, workspace_id=workspace_id)
+        if item.get("source") != "change_proposal":
+            raise KeyError(f"not a change proposal: {item_id}")
         payload = item.get("payload") or {}
         kind = item.get("kind")
         path = str(payload.get("path") or "")
@@ -258,13 +298,25 @@ class ChangeProposalService:
 
     def reject(
         self, item_id: str, *, user_email: Optional[str] = None,
-        workspace_id: Optional[str] = None,
+        workspace_id: Optional[str] = None, reason: str = "",
     ) -> Dict[str, Any]:
-        dismissed = self._review_queue.dismiss(item_id, workspace_id=workspace_id)
+        self.get_proposal(item_id, workspace_id=workspace_id)  # source guard
+        reason = str(reason or "").strip()[:500]
+        if reason:
+            try:
+                dismissed = self._review_queue.dismiss(
+                    item_id, workspace_id=workspace_id, reason=reason
+                )
+            except TypeError:
+                # Older/fake queues without reason support still dismiss.
+                dismissed = self._review_queue.dismiss(item_id, workspace_id=workspace_id)
+        else:
+            dismissed = self._review_queue.dismiss(item_id, workspace_id=workspace_id)
         self._audit(
             "change_proposal_rejected", user_email=user_email, proposal_id=item_id,
+            reason=reason or None,
         )
-        return {"item": dismissed, "applied": False}
+        return {"item": dismissed, "applied": False, "reason": reason}
 
 
 __all__ = ["ChangeProposalService"]

package/latticeai/services/product_readiness.py

@@ -18,7 +18,7 @@ from typing import Any, Dict, List
 
 from latticeai.services.architecture_readiness import architecture_readiness
 
-PRODUCT_VERSION_TARGET = "9.6.0"
+PRODUCT_VERSION_TARGET = "9.7.0"
 
 
 @dataclass(frozen=True)

package/latticeai/services/review_queue.py

@@ -141,8 +141,49 @@ class ReviewQueueService:
         updated = self._store.update_review_item(item_id, workspace_id=workspace_id, **patch)
         return self._view(updated)
 
-    def dismiss(self, item_id: str, *, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        return self._transition(item_id, "dismiss", "dismissed", workspace_id=workspace_id)
+    def dismiss(
+        self, item_id: str, *, workspace_id: Optional[str] = None,
+        reason: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Dismiss an item; an optional ``reason`` is kept in provenance.
+
+        The reason matters most for ``change_proposal`` items — the review
+        timeline doubles as the change audit log, so "why was this rejected"
+        should survive next to the staged diff.
+        """
+        if not reason:
+            return self._transition(item_id, "dismiss", "dismissed", workspace_id=workspace_id)
+        item = self._store.get_review_item(item_id, workspace_id=workspace_id)
+        self._guard("dismiss", item)
+        provenance = dict(item.get("provenance") or {})
+        provenance["dismiss_reason"] = str(reason)[:500]
+        patch: Dict[str, Any] = {"status": "dismissed", "provenance": provenance}
+        if item.get("snoozed_until") is not None:
+            patch["snoozed_until"] = None
+        updated = self._store.update_review_item(item_id, workspace_id=workspace_id, **patch)
+        return self._view(updated)
+
+    def counts(
+        self, *, workspace_id: Optional[str] = None, user_email: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Badge-friendly effective-status counts (pending includes expired snoozes)."""
+        items = [
+            self._view(it)
+            for it in self._store.list_review_items(
+                workspace_id=workspace_id, user_email=user_email,
+            )
+        ]
+        pending = [it for it in items if it["effective_status"] == "pending"]
+        snoozed = [it for it in items if it["effective_status"] == "snoozed"]
+        by_source: Dict[str, int] = {}
+        for it in pending:
+            source = str(it.get("source") or "workflow_run")
+            by_source[source] = by_source.get(source, 0) + 1
+        return {
+            "pending": len(pending),
+            "snoozed": len(snoozed),
+            "pending_by_source": by_source,
+        }
 
     def snooze(
         self, item_id: str, *, until: str, workspace_id: Optional[str] = None,

package/llm_router.py

@@ -5,7 +5,16 @@ monkeypatching keep working through the old import path.
 """
 
 import sys
+import warnings
 
-import latticeai.models.router as _impl
+warnings.warn(
+    "Importing 'llm_router' from the repository root is deprecated; "
+    "use 'import latticeai.models.router' instead. "
+    "The root shim will be removed in a future major release.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+import latticeai.models.router as _impl  # noqa: E402
 
 sys.modules[__name__] = _impl

package/local_knowledge_api.py

@@ -1,7 +1,16 @@
 """Compatibility shim for :mod:`latticeai.services.local_knowledge`."""
 
 import sys
+import warnings
 
-from latticeai.services import local_knowledge as _impl
+warnings.warn(
+    "Importing 'local_knowledge_api' from the repository root is deprecated; "
+    "use 'from latticeai.services import local_knowledge' instead. "
+    "The root shim will be removed in a future major release.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from latticeai.services import local_knowledge as _impl  # noqa: E402
 
 sys.modules[__name__] = _impl