codrspot-processor-mcp 0.1.0__py3-none-any.whl

codepreproc_client/layer1_business/mcp/tools.py

@@ -0,0 +1,1665 @@
+"""MCP tool implementations."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import re
+import subprocess
+import uuid
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from git import Repo
+from pydantic import BaseModel, Field
+
+from codepreproc_client.layer2_tooling.condensation.chunking.ast_chunker import AstChunker
+from codepreproc_client.layer2_tooling.coupling.domain import CouplingExpandRequest, CouplingProjectRequest, CouplingReport
+from codepreproc_client.layer2_tooling.coupling.graph import CouplingGraph
+from codepreproc_client.layer2_tooling.coupling.projector import CouplingProjector
+from codepreproc_client.layer1_business.git_utils import get_current_branch, get_current_sha, get_dirty_files
+from codepreproc_client.layer2_tooling.condensation.ast_graph import AstGraph
+from codepreproc_client.layer2_tooling.condensation.bm25_store import BM25Store
+from codepreproc_client.layer2_tooling.condensation.scanning.repo_mapper import NeedsMonorepoConfig, RepoMapAnnotator, RepoMapper
+from codepreproc_client.layer2_tooling.condensation.embeddings import Embedder
+from codepreproc_client.layer2_tooling.condensation.indexer import ProjectIndexer
+from codepreproc_client.layer2_tooling.condensation.qdrant_store import QdrantStore
+from codepreproc_client.layer1_business.api_client.reasoning_client import LLMRuntime
+from codepreproc_client.layer2_tooling.condensation.extract.compactor import ContextCompactor
+from codepreproc_client.layer1_business.api_client.reasoning_client import IntentExtractor
+from codepreproc_client.layer1_business.mcp.action_monitor import ActionMonitor, ToolExecutionError
+from contracts.dtos import (
+    ProjectConfig,
+    Settings as SettingsModel,
+    StoredAssemblyTask,
+    StoredFilesystemTask,
+    StoredSemanticTask,
+)
+from codepreproc_client.layer2_tooling.materialization.pipeline.filesystem_reorg import FilesystemReorganizationPipeline
+from codepreproc_client.layer2_tooling.materialization.pipeline.execute_semantic import SemanticExecutionPipeline
+from codepreproc_client.layer2_tooling.materialization.snippet.loader import SnippetLoader
+from codepreproc_client.layer2_tooling.materialization.snippet.assembler import SnippetAssembler
+from codepreproc_client.layer2_tooling.materialization.semantic.target_locator import TargetLocator
+from codepreproc_client.layer1_business.project_registry import ProjectRegistry
+from codepreproc_client.layer2_tooling.retrieval.graph_walk import GraphWalker
+from codepreproc_client.layer2_tooling.retrieval.hybrid import HybridRetriever
+from codepreproc_client.layer2_tooling.retrieval.reranker import Reranker
+from codepreproc_client.layer2_tooling.materialization.semantic import ApplicabilityChecker, RegionResolver, SemanticEditPlanner, SemanticSynthesizer
+from contracts.ir import BusinessLogicDiff, bld_from_plan
+from codepreproc_client.layer1_business.api_client.superkg_client import EnrichResult, SuperKGClient
+
+_CONTEXT_MAP_SYSTEM_PROMPT = """\
+You are a code architecture analyst. Given a set of retrieved code components and their dependency relationships, \
+produce a concise narrative (3-8 sentences) explaining how these components collaborate to implement the queried \
+functionality. Focus on data flow, call chains, and architectural boundaries — not on re-describing each function. \
+Use exact symbol names from the context. Output plain text only, no Markdown headers or code fences.\
+"""
+
+_DOC_GENERATION_SYSTEM_PROMPT = """\
+You are a technical documentation expert specializing in software architecture documentation.
+Using ONLY the code context provided, produce the requested document as raw Markdown.
+
+Apply ALL of the following structural patterns where applicable:
+
+REQUIRED SECTIONS (include every section that has supporting evidence in the context):
+1. **Visión general + principios**: 2–3 sentences on what the system does, then 4–6 bullet points \
+on guiding design principles extracted from the code philosophy (e.g. "Estado sobre patch", thresholds as contracts).
+2. **Component inventory table**: | Componente | Tipo | Ruta | Rol | — one row per package/module, \
+"Tipo" is Package/App/Specs/etc., "Rol" is a one-line description.
+3. **End-to-end flow diagram**: ASCII art with boxes (┌─┐ │ └─┘), arrows (→ ▼ ▲), \
+and numbered step labels (PASO 1: …, PASO 2: …). Show the full lifecycle from input to output.
+4. **Per-component sections**: For EACH component include:
+   - Exact file path, internal dependencies (package names only)
+   - Exported functions/classes listed verbatim from the code (not paraphrased)
+   - Constants, thresholds, enum values with EXACT numeric values (e.g. score ≥ 0.72)
+   - Input/output types using exact type names from the code
+   - Sub-file breakdown if the component has multiple source files
+5. **Contracts section**: State machine transitions (e.g. `draft → ready → reflecting → canonicalized → committed`), \
+numeric thresholds table with exact values, validation dimensions, blocking conditions.
+6. **External integrations table**: | Integration | Protocol | Detail |
+7. **Directed dependency graph**: ASCII diagram with directed arrows (◄ ▲) showing dependency direction. \
+Higher-level packages at top depending on lower-level ones at bottom.
+8. **Entry/exit points table**: | Canal | Punto de entrada | Tipo | for inputs; same for outputs.
+
+EXTRACTION RULES (critical — the expensive approach always does these):
+- Extract EXACT function/method names from exports, never paraphrase them.
+- Include EXACT numeric constants: scores, thresholds, limits, port numbers, counts.
+- Include EXACT TypeScript/Python type names for inputs and outputs.
+- Include ALL enum/union values (e.g. `os_spec | state_config | idea_state | seed_pack`).
+- Group MCP tools / REST endpoints by category in tables.
+- Use the same technical terminology as the codebase — do not translate or simplify.
+- When listing required artifacts, list ALL of them by name.
+
+OUTPUT: Raw Markdown only. No preamble. No trailing explanation. No code fence wrapping the whole document.\
+"""
+
+_BUSINESS_LOGIC_SYSTEM_PROMPT = """\
+You are a business analyst and domain expert. Given code context from a software repository, \
+extract and document the BUSINESS LOGIC — what the system does, not how it is implemented technically.
+
+Produce a Markdown document with the following sections (include only those with evidence in the context):
+
+1. **Overview**: 2–4 sentences describing what this system does from a business perspective.
+2. **Domain Model**: Named business entities, their attributes, and relationships. Use a table: | Entity | Key Attributes | Relationships |
+3. **Business Rules**: Numbered list of explicit invariants, constraints, and validations enforced by the code \
+(e.g. "An order cannot be shipped if payment is not confirmed"). Extract exact thresholds and enum values.
+4. **Workflows / Processes**: For each significant workflow or use case, describe the steps as a numbered list \
+or state-machine diagram (states and transitions). Use exact state/status names from the code.
+5. **Entry Points**: How the system receives requests (REST endpoints, MCP tools, CLI commands, events). \
+Table: | Entry Point | Input | Trigger | Output |
+6. **External Integrations**: Services, databases, or APIs the system relies on. \
+Table: | Integration | Purpose | Protocol |
+7. **Error Conditions & Edge Cases**: Explicit failure modes and how the system handles them.
+
+RULES:
+- Focus on WHAT the business logic does, not HOW the code implements it.
+- Use exact names from the code for entities, statuses, and operations — do not paraphrase.
+- Extract exact numeric thresholds and enum values verbatim.
+- Do NOT describe implementation details like classes, imports, or algorithms unless they encode a business rule.
+- If a rule is enforced by a constant or threshold in the code, state both the rule and the exact value.
+
+OUTPUT: Raw Markdown only. No preamble. No trailing explanation. No code fence wrapping the whole document.\
+"""
+
+_BUSINESS_LOGIC_QUERIES = [
+    "business logic domain rules validation services workflows",
+    "domain models entities state machine transitions status",
+    "business rules invariants constraints validation error handling",
+    "service layer use cases commands queries operations",
+    "API endpoints entry points request handling",
+]
+
+
+class SwitchProjectInput(BaseModel):
+    project: str
+
+
+class AnalyzeRequestInput(BaseModel):
+    prompt: str
+    project: str | None = None
+
+
+class AnalyzeFilesystemReorgInput(BaseModel):
+    prompt: str
+    project: str | None = None
+
+
+class PreviewTaskInput(BaseModel):
+    task_id: str
+
+
+class DisambiguateInput(BaseModel):
+    task_id: str
+    chosen_region_id: str
+
+
+class ApplyPatchInput(BaseModel):
+    task_id: str
+    patch_index: int | None = None
+
+
+class ApplyFilesystemPlanInput(BaseModel):
+    task_id: str
+
+
+class UsageReportInput(BaseModel):
+    project: str | None = None
+    since_days: int = 30
+
+
+class SetPolicyInput(BaseModel):
+    project: str
+    policy: str
+
+
+class SearchContextInput(BaseModel):
+    query: str
+    project: str | None = None
+    top_k: int = 10
+
+
+class MapContextInput(BaseModel):
+    query: str
+    project: str | None = None
+    top_k: int = 10
+    include_bodies: bool = True
+    synthesize: bool = True
+
+
+class GenerateDocumentInput(BaseModel):
+    prompt: str
+    output_path: str
+    project: str | None = None
+    top_k: int = 15
+
+
+class GenerateBusinessLogicInput(BaseModel):
+    project: str | None = None
+    output_path: str = "BUSINESS_LOGIC.md"
+    top_k: int = 20
+
+
+class ProjectPseudocodeInput(BaseModel):
+    project: str | None = None
+    file_pattern: str | None = None
+    include_bodies: bool = False
+    exclude_tests: bool = True
+    max_files: int = 200
+
+
+class ListSnippetsInput(BaseModel):
+    framework: str | None = None
+    language: str | None = None
+    layer: str | None = None
+
+
+class AssembleFromSnippetsInput(BaseModel):
+    prompt: str
+    project: str | None = None
+
+
+class ReindexInput(BaseModel):
+    project: str | None = None
+    full: bool = False
+
+
+class ProjectStatusInput(BaseModel):
+    project: str | None = None
+
+
+class InitProjectInput(BaseModel):
+    path: str | None = None
+
+
+class CouplingProjectInput(BaseModel):
+    anchors: list[str] = Field(default_factory=list)
+    intent: str | None = None
+
+
+class CouplingExpandInput(BaseModel):
+    handle_id: str
+    edge_id: str | None = None
+    offset: int = 0
+    limit: int = 50
+
+
+@dataclass
+class SessionState:
+    """Per-client session cache."""
+
+    active_project: str | None = None
+    user_id: str | None = field(default_factory=lambda: os.environ.get("CODEPREPROC_USER_ID"))
+    roots: list[Path] = field(default_factory=list)
+    loaded_indexers: dict[str, ProjectIndexer] = field(default_factory=dict)
+    semantic_tasks: dict[str, StoredSemanticTask] = field(default_factory=dict)
+    filesystem_tasks: dict[str, StoredFilesystemTask] = field(default_factory=dict)
+    assembly_tasks: dict[str, StoredAssemblyTask] = field(default_factory=dict)
+    coupling_reports: dict[str, CouplingReport] = field(default_factory=dict)
+    policy_overrides: dict[str, str] = field(default_factory=dict)
+
+
+class GenerateRepoMapInput(BaseModel):
+    project: str | None = None
+    artifacts_folder: str | None = None
+    modules_folder: str | None = None
+
+
+class KGContextInput(BaseModel):
+    project: str | None = None
+    mode: str = "narrative"
+
+
+class KGInsightsInput(BaseModel):
+    project: str | None = None
+
+
+class CorrectGraphInput(BaseModel):
+    change: str
+    before: list[str] = Field(default_factory=list)
+    after: list[str] = Field(default_factory=list)
+    rules_added: list[str] = Field(default_factory=list)
+    rules_removed: list[str] = Field(default_factory=list)
+    rules_modified: list[str] = Field(default_factory=list)
+    project: str | None = None
+
+
+class CodepreprocTools:
+    """Concrete MCP tool handlers."""
+
+    def __init__(
+        self,
+        settings: SettingsModel,
+        registry: ProjectRegistry,
+        qdrant_store: QdrantStore,
+        llm_runtime: LLMRuntime,
+        logger: logging.Logger,
+        superkg: SuperKGClient | None = None,
+        snippet_loader: SnippetLoader | None = None,
+        coupling_graph: CouplingGraph | None = None,
+        jwt_provider: Callable[[str], Awaitable[str]] | None = None,
+    ) -> None:
+        self.settings = settings
+        self.registry = registry
+        self.qdrant_store = qdrant_store
+        self.llm_runtime = llm_runtime
+        self.logger = logger
+
+        async def _disabled_jwt_provider(project_id: str) -> str:
+            raise RuntimeError("no jwt_provider configured - SuperKG proxy calls are unavailable")
+
+        self._jwt_provider = jwt_provider or _disabled_jwt_provider
+        self.superkg = superkg or SuperKGClient(
+            base_url="http://localhost:8443", jwt_provider=self._jwt_provider, enabled=False
+        )
+        self.embedder = Embedder.get(settings.defaults)
+        self.reranker = Reranker.get(settings.defaults)
+        if snippet_loader is None:
+            raise ValueError("snippet_loader is required — pass SnippetLoader.from_api() result")
+        self._snippet_loader = snippet_loader
+        self._coupling_graph = coupling_graph or CouplingGraph(
+            settings.indexes_dir / "coupling.db"
+        )
+        self._coupling_projector = CouplingProjector()
+
+    async def list_projects(self, session: SessionState) -> dict:
+        projects = []
+        for project in self.registry.list_projects():
+            indexer = self._get_indexer(session, project)
+            state = indexer.get_index_status()
+            projects.append(
+                {
+                    "id": project.project_id,
+                    "root": str(project.root),
+                    "languages": project.languages,
+                    "llm_policy": session.policy_overrides.get(project.project_id, project.llm_policy),
+                    "indexed": indexer.ast_graph.get_last_indexed_sha() is not None and state["index_state"] == "ready",
+                    "last_indexed_sha": indexer.ast_graph.get_last_indexed_sha(),
+                    "chunk_count": indexer.ast_graph.get_chunk_count(),
+                    "index_state": state["index_state"],
+                    "last_index_error": state.get("last_index_error"),
+                }
+            )
+        return {"projects": projects}
+
+    async def switch_project(self, session: SessionState, arguments: dict) -> dict:
+        payload = SwitchProjectInput.model_validate(arguments)
+        status = "ok" if payload.project in self.registry.registry.projects else "not_found"
+        if status == "ok":
+            session.active_project = payload.project
+        return {"active_project": session.active_project, "status": status}
+
+    async def analyze_request(self, session: SessionState, arguments: dict, monitor: ActionMonitor | None = None) -> dict:
+        payload = AnalyzeRequestInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        pipeline = self._make_pipeline(session, project)
+        stored = await pipeline.run(
+            payload.prompt,
+            policy_override=session.policy_overrides.get(project.project_id),
+            monitor=monitor,
+        )
+        session.semantic_tasks[stored.pack.task_id] = stored
+        return stored.pack.model_dump(mode="json")
+
+    async def analyze_filesystem_reorg(self, session: SessionState, arguments: dict, monitor: ActionMonitor | None = None) -> dict:
+        payload = AnalyzeFilesystemReorgInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        pipeline = self._make_filesystem_pipeline(project)
+        stored = await pipeline.run(
+            payload.prompt,
+            policy_override=session.policy_overrides.get(project.project_id),
+            monitor=monitor,
+        )
+        session.filesystem_tasks[stored.pack.task_id] = stored
+        return stored.pack.model_dump(mode="json")
+
+    async def preview_semantic_plan(self, session: SessionState, arguments: dict) -> dict:
+        payload = PreviewTaskInput.model_validate(arguments)
+        self._prune_tasks(session)
+        item = session.semantic_tasks.get(payload.task_id)
+        if item is None:
+            return {"error": "not_found"}
+        return {"semantic_plan": item.pack.semantic_plan.model_dump(mode="json") if item.pack.semantic_plan else None}
+
+    async def preview_filesystem_plan(self, session: SessionState, arguments: dict) -> dict:
+        payload = PreviewTaskInput.model_validate(arguments)
+        self._prune_tasks(session)
+        item = session.filesystem_tasks.get(payload.task_id)
+        if item is None:
+            return {"error": "not_found"}
+        return {
+            "filesystem_plan": item.pack.filesystem_plan.model_dump(mode="json") if item.pack.filesystem_plan else None,
+            "validation": item.pack.validation.model_dump(mode="json") if item.pack.validation else None,
+            "failure": item.pack.failure.model_dump(mode="json") if item.pack.failure else None,
+        }
+
+    async def preview_patch(self, session: SessionState, arguments: dict) -> dict:
+        payload = PreviewTaskInput.model_validate(arguments)
+        self._prune_tasks(session)
+        item = session.semantic_tasks.get(payload.task_id)
+        if item is None:
+            return {"error": "not_found"}
+        return {
+            "patches": [
+                {"file_path": patch.file_path, "diff": patch.unified_diff}
+                for patch in sorted(item.pack.patches, key=lambda patch: patch.file_path)
+            ]
+        }
+
+    async def validate_patch(self, session: SessionState, arguments: dict) -> dict:
+        payload = PreviewTaskInput.model_validate(arguments)
+        self._prune_tasks(session)
+        item = session.semantic_tasks.get(payload.task_id)
+        if item is None:
+            return {"error": "not_found"}
+        if item.pack.validation is None:
+            return {"valid": False, "errors": ["missing_validation"], "warnings": []}
+        errors = [error for layer in item.pack.validation.layers for error in layer.errors]
+        warnings = [warning for layer in item.pack.validation.layers for warning in layer.warnings]
+        return {"valid": item.pack.validation.valid, "errors": errors, "warnings": warnings}
+
+    async def disambiguate_region(self, session: SessionState, arguments: dict) -> dict:
+        payload = DisambiguateInput.model_validate(arguments)
+        self._prune_tasks(session)
+        item = session.semantic_tasks.get(payload.task_id)
+        if item is None:
+            return {"error": "not_found"}
+        project = self.registry.get(item.project_id)
+        pipeline = self._make_pipeline(session, project)
+        stored = await pipeline.continue_with_region(item, payload.chosen_region_id)
+        session.semantic_tasks[payload.task_id] = stored
+        return stored.pack.model_dump(mode="json")
+
+    async def apply_patch(self, session: SessionState, arguments: dict) -> dict:
+        payload = ApplyPatchInput.model_validate(arguments)
+        self._prune_tasks(session)
+        item = session.semantic_tasks.get(payload.task_id)
+        if item is None:
+            return {"applied": False, "files_changed": [], "error": "not_found"}
+        patches = item.pack.patches
+        if payload.patch_index is not None:
+            if payload.patch_index < 0 or payload.patch_index >= len(patches):
+                return {"applied": False, "files_changed": [], "error": "patch_index_out_of_range"}
+            patches = [patches[payload.patch_index]]
+        combined = "".join(patch.unified_diff for patch in patches)
+        project = self.registry.get(item.project_id)
+        proc = subprocess.run(
+            ["git", "apply", "--ignore-whitespace", "--whitespace=nowarn", "-"],
+            input=combined,
+            text=True,
+            encoding="utf-8",
+            capture_output=True,
+            cwd=project.root,
+            check=False,
+        )
+        if proc.returncode != 0:
+            return {"applied": False, "files_changed": [], "error": (proc.stderr or proc.stdout).strip() or "git apply failed"}
+        touched = [patch.file_path for patch in patches]
+        for file_path in touched:
+            newline_style = item.newline_styles.get(file_path)
+            if newline_style == "crlf":
+                full_path = project.root / file_path
+                full_path.write_text(full_path.read_text(encoding="utf-8").replace("\n", "\r\n"), encoding="utf-8", newline="")
+
+        # Transactional SuperKG write: fires only after disk mutation succeeds
+        superkg_system_id = await self._ensure_superkg_system(project)
+        if superkg_system_id:
+            plan = item.pack.semantic_plan
+            bld = bld_from_plan(plan) if plan else None
+            intent_text = getattr(item.pack.intent, "intent", "") if item.pack.intent else ""
+            await self.superkg.record_decision(
+                project_id=project.project_id,
+                system_id=superkg_system_id,
+                session_id=None,
+                intent=intent_text,
+                plan_summary={"task_id": item.pack.task_id, "applied": True},
+                bld=bld,
+            )
+
+        return {"applied": True, "files_changed": touched, "error": None}
+
+    async def apply_filesystem_plan(self, session: SessionState, arguments: dict, monitor: ActionMonitor | None = None) -> dict:
+        payload = ApplyFilesystemPlanInput.model_validate(arguments)
+        self._prune_tasks(session)
+        item = session.filesystem_tasks.get(payload.task_id)
+        if item is None:
+            return {"applied": False, "operations_applied": [], "error": "not_found"}
+        project = self.registry.get(item.project_id)
+        pipeline = self._make_filesystem_pipeline(project)
+        result = await pipeline.apply(item, monitor=monitor)
+        if result.get("applied"):
+            session.filesystem_tasks.pop(payload.task_id, None)
+        return result
+
+    async def usage_report(self, session: SessionState, arguments: dict) -> dict:
+        payload = UsageReportInput.model_validate(arguments)
+        return self.llm_runtime.cost_tracker.usage_report(project=payload.project, since_days=payload.since_days)
+
+    async def set_llm_policy(self, session: SessionState, arguments: dict) -> dict:
+        payload = SetPolicyInput.model_validate(arguments)
+        project = self.registry.get(payload.project)
+        previous = session.policy_overrides.get(project.project_id, project.llm_policy)
+        session.policy_overrides[project.project_id] = payload.policy
+        return {"applied": True, "previous_policy": previous}
+
+    async def reindex(self, session: SessionState, arguments: dict, monitor: ActionMonitor | None = None) -> dict:
+        payload = ReindexInput.model_validate(arguments)
+
+        # Reload the local project registry mirror so config changes (e.g. languages)
+        # take effect without restart - no server round trip needed to list projects.
+        from codepreproc_client.layer1_business.config import apply_env_overrides, get_home_dir
+        from codepreproc_client.layer1_business.local_registry import load_local_projects
+        from contracts.dtos import Registry as _Registry
+        new_data = apply_env_overrides(
+            _Registry(defaults=self.registry.registry.defaults, projects=load_local_projects(get_home_dir()))
+        )
+        self.registry.registry = new_data
+
+        project = self._resolve_project(session, payload.project)
+        # Drop any cached indexer so it is rebuilt with the refreshed project config
+        session.loaded_indexers.pop(project.project_id, None)
+
+        if monitor is not None:
+            await monitor.stage("health_check", f"reindex: verificando Qdrant para {project.project_id}")
+        try:
+            await asyncio.to_thread(self.qdrant_store.health_check)
+        except Exception as exc:
+            raise ToolExecutionError(
+                "qdrant_unavailable",
+                f"Qdrant no responde en {self.qdrant_store._host}: {exc}",
+                details={"host": self.qdrant_store._host, "grpc_port": self.qdrant_store._grpc_port},
+            ) from exc
+        indexer = self._get_indexer(session, project)
+        stats = await (indexer.full_reindex(monitor=monitor) if payload.full else indexer.incremental_reindex(monitor=monitor))
+        result = stats.model_dump(mode="json")
+
+        # Log indexing activity in SuperKG (fire-and-forget)
+        superkg_system_id = await self._ensure_superkg_system(project)
+        if superkg_system_id:
+            await self.superkg.log_activity(
+                project_id=project.project_id,
+                system_id=superkg_system_id,
+                activity_type="reindex",
+                details={
+                    "mode": result.get("mode", "full" if payload.full else "incremental"),
+                    "files_indexed": result.get("files_indexed", 0),
+                    "chunks_created": result.get("chunks_created", 0),
+                    "duration_ms": result.get("duration_ms", 0),
+                    "project_id": project.project_id,
+                },
+            )
+
+        return result
+
+    async def project_status(self, session: SessionState, arguments: dict) -> dict:
+        payload = ProjectStatusInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        indexer = self._get_indexer(session, project)
+        repo = Repo(project.root)
+        current_sha = get_current_sha(repo)
+        status = indexer.get_index_status()
+        result: dict = {
+            "project": project.project_id,
+            "git_sha": current_sha,
+            "branch": get_current_branch(repo),
+            "dirty_files": len(get_dirty_files(repo)),
+            "last_indexed_sha": indexer.ast_graph.get_last_indexed_sha(),
+            "drift": indexer.ast_graph.get_last_indexed_sha() != current_sha,
+            "llm_policy": session.policy_overrides.get(project.project_id, project.llm_policy),
+            "index_state": status["index_state"],
+            "last_index_error": status.get("last_index_error"),
+            "superkg_system_id": project.superkg_system_id,
+            "kg_snapshot": None,
+        }
+        if project.superkg_system_id:
+            result["kg_snapshot"] = await self.superkg.get_snapshot(project.project_id, project.superkg_system_id)
+        return result
+
+    async def search_context(self, session: SessionState, arguments: dict, monitor: ActionMonitor | None = None) -> dict:
+        payload = SearchContextInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        indexer = self._get_indexer(session, project)
+        retriever = HybridRetriever(
+            self.embedder,
+            self.qdrant_store,
+            indexer.bm25_store,
+            self.settings.defaults.retrieval,
+        )
+        if monitor is not None:
+            await monitor.stage("retrieve", "search_context: recuperando chunks relevantes")
+        retrieved = await retriever.retrieve(
+            project,
+            payload.query,
+            overlay_collection=None,
+            collection_name=indexer.active_collection_name(),
+            user_collection_name=indexer.active_user_collection_name(),
+            monitor=monitor,
+            ast_graph=indexer.ast_graph,
+        )
+        if monitor is not None:
+            await monitor.stage("rerank", "search_context: reranking")
+        top_k = max(1, min(payload.top_k, 30))
+        reranked = await self.reranker.rerank(payload.query, retrieved, top_k)
+
+        enrich_result: EnrichResult | None = None
+        superkg_system_id = await self._ensure_superkg_system(project)
+        if superkg_system_id:
+            candidates = [
+                {"chunk_id": item.chunk.chunk_id, "file_path": item.chunk.file_path, "score": item.score}
+                for item in reranked
+            ]
+            enrich_result = await self.superkg.enrich(project.project_id, superkg_system_id, payload.query, candidates)
+
+        kg_scores = enrich_result.kg_scores if enrich_result else {}
+        trace_id = enrich_result.trace_id if enrich_result else None
+
+        def _final_score(item) -> float:
+            kg = kg_scores.get(item.chunk.chunk_id)
+            if kg:
+                return item.score * 0.7 + kg.kg_score * 0.3
+            return item.score
+
+        if kg_scores:
+            reranked = sorted(reranked, key=_final_score, reverse=True)
+
+        snippets = []
+        for item in reranked:
+            chunk = item.chunk
+            kg = kg_scores.get(chunk.chunk_id)
+            entry: dict = {
+                "file_path": chunk.file_path,
+                "symbol": chunk.symbol,
+                "signature": chunk.signature or "",
+                "score": round(_final_score(item), 4),
+                "body": chunk.body,
+            }
+            if kg:
+                entry["kg_score"] = round(kg.kg_score, 4)
+                entry["kg_signals"] = kg.signals
+            snippets.append(entry)
+
+        result: dict = {
+            "query": payload.query,
+            "project": project.project_id,
+            "chunks": snippets,
+            "total": len(snippets),
+        }
+        if trace_id:
+            result["trace_id"] = trace_id
+        if enrich_result and enrich_result.pattern_suggestions:
+            result["pattern_suggestions"] = enrich_result.pattern_suggestions
+        if enrich_result and enrich_result.warnings:
+            result["kg_warnings"] = enrich_result.warnings
+        return result
+
+    async def map_context(self, session: SessionState, arguments: dict, monitor: ActionMonitor | None = None) -> dict:
+        payload = MapContextInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        indexer = self._get_indexer(session, project)
+        top_k = max(1, min(payload.top_k, 20))
+        active_collection = indexer.active_collection_name()
+
+        retriever = HybridRetriever(
+            self.embedder,
+            self.qdrant_store,
+            indexer.bm25_store,
+            self.settings.defaults.retrieval,
+        )
+
+        if monitor is not None:
+            await monitor.stage("retrieve", "map_context: recuperando chunks relevantes")
+        retrieved = await retriever.retrieve(
+            project,
+            payload.query,
+            overlay_collection=None,
+            collection_name=active_collection,
+            user_collection_name=indexer.active_user_collection_name(),
+            monitor=monitor,
+            ast_graph=indexer.ast_graph,
+        )
+
+        if monitor is not None:
+            await monitor.stage("rerank", "map_context: reranking")
+        reranked = await self.reranker.rerank(payload.query, retrieved, top_k)
+
+        enrich_result: EnrichResult | None = None
+        superkg_system_id = await self._ensure_superkg_system(project)
+        if superkg_system_id:
+            candidates = [
+                {"chunk_id": item.chunk.chunk_id, "file_path": item.chunk.file_path, "score": item.score}
+                for item in reranked
+            ]
+            enrich_result = await self.superkg.enrich(project.project_id, superkg_system_id, payload.query, candidates)
+
+        if enrich_result and enrich_result.kg_scores:
+            kg_scores = enrich_result.kg_scores
+
+            def _merged(item) -> float:
+                kg = kg_scores.get(item.chunk.chunk_id)
+                return item.score * 0.7 + kg.kg_score * 0.3 if kg else item.score
+
+            reranked = sorted(reranked, key=_merged, reverse=True)
+
+        if monitor is not None:
+            await monitor.stage("graph_walk", "map_context: expandiendo grafo de dependencias")
+        seed_chunks = [item.chunk for item in reranked]
+        expanded = GraphWalker().expand(
+            seed_chunks,
+            indexer.ast_graph,
+            lambda ids: indexer.qdrant_store.get_chunks_by_ids(active_collection, ids) if active_collection else [],
+            depth=self.settings.defaults.retrieval.graph_walk_depth,
+        )
+
+        seed_ids = {c.chunk_id for c in seed_chunks}
+        seed_scores = {item.chunk.chunk_id: item.score for item in reranked}
+
+        # Build dependency graph and per-chunk caller/callee info — batch SQL + single Qdrant fetch
+        seed_symbols = [c.symbol for c in seed_chunks]
+        seed_chunk_ids_list = [c.chunk_id for c in seed_chunks]
+        callers_by_symbol = indexer.ast_graph.find_callers_batch(seed_symbols)
+        callees_by_chunk = indexer.ast_graph.find_callees_batch(seed_chunk_ids_list)
+
+        all_resolve_ids = list(dict.fromkeys(
+            cid
+            for ids in (*callees_by_chunk.values(), *callers_by_symbol.values())
+            for cid in ids
+        ))
+        id_to_symbol: dict[str, str] = {}
+        if all_resolve_ids and active_collection:
+            fetched = indexer.qdrant_store.get_chunks_by_ids(active_collection, all_resolve_ids)
+            id_to_symbol = {c.chunk_id: c.symbol for c in fetched}
+
+        dependency_graph: dict[str, list[str]] = {}
+        chunk_callers: dict[str, list[str]] = {}
+        chunk_callees: dict[str, list[str]] = {}
+        for chunk in seed_chunks:
+            callee_ids = callees_by_chunk.get(chunk.chunk_id, [])
+            callee_symbols = [id_to_symbol[cid] for cid in callee_ids if cid in id_to_symbol]
+            caller_ids = callers_by_symbol.get(chunk.symbol, [])
+            caller_symbols = [id_to_symbol[cid] for cid in caller_ids if cid in id_to_symbol]
+            dependency_graph[chunk.symbol] = callee_symbols
+            chunk_callers[chunk.chunk_id] = caller_symbols
+            chunk_callees[chunk.chunk_id] = callee_symbols
+
+        # Build file index
+        file_index: dict[str, list[str]] = defaultdict(list)
+        seen_ids: set[str] = set()
+        all_chunks = []
+        for chunk in seed_chunks + expanded:
+            if chunk.chunk_id not in seen_ids:
+                seen_ids.add(chunk.chunk_id)
+                all_chunks.append(chunk)
+                if chunk.symbol not in file_index[chunk.file_path]:
+                    file_index[chunk.file_path].append(chunk.symbol)
+
+        # Assemble component list
+        components = []
+        for chunk in all_chunks:
+            is_seed = chunk.chunk_id in seed_ids
+            entry: dict = {
+                "file_path": chunk.file_path,
+                "symbol": chunk.symbol,
+                "kind": chunk.kind,
+                "signature": chunk.signature or "",
+                "start_line": chunk.start_line,
+                "end_line": chunk.end_line,
+                "relevance_score": round(seed_scores[chunk.chunk_id], 4) if is_seed else None,
+                "calls": chunk_callees.get(chunk.chunk_id, []),
+                "called_by": chunk_callers.get(chunk.chunk_id, []),
+            }
+            if payload.include_bodies and is_seed:
+                entry["body"] = chunk.body
+            components.append(entry)
+
+        # Optional LLM synthesis (always local, never remote)
+        summary = ""
+        if payload.synthesize:
+            if monitor is not None:
+                await monitor.stage("synthesize", "map_context: sintetizando mapa arquitectónico")
+            context_lines = []
+            for chunk in seed_chunks:
+                sig = chunk.signature or chunk.symbol
+                callee_list = ", ".join(chunk_callees.get(chunk.chunk_id, [])) or "none"
+                caller_list = ", ".join(chunk_callers.get(chunk.chunk_id, [])) or "none"
+                context_lines.append(
+                    f"{chunk.file_path}::{chunk.symbol} ({chunk.kind})\n"
+                    f"  signature: {sig}\n"
+                    f"  calls: {callee_list}\n"
+                    f"  called_by: {caller_list}\n"
+                    f"  body_preview: {chunk.body[:400]}"
+                )
+            context_text = "\n\n".join(context_lines)
+            try:
+                result, _ = await self.llm_runtime.router.chat(
+                    task_type="context_map",
+                    policy="local_only",
+                    messages=[
+                        {"role": "system", "content": _CONTEXT_MAP_SYSTEM_PROMPT},
+                        {"role": "user", "content": f"Query: {payload.query}\n\nComponents:\n{context_text}"},
+                    ],
+                    project_id=project.project_id,
+                    task_id=uuid.uuid4().hex,
+                )
+                summary = result.strip()
+            except Exception:
+                summary = ""
+
+        map_result: dict = {
+            "query": payload.query,
+            "project": project.project_id,
+            "summary": summary,
+            "components": components,
+            "dependency_graph": dependency_graph,
+            "file_index": dict(file_index),
+            "total_components": len(components),
+        }
+        if enrich_result:
+            if enrich_result.trace_id:
+                map_result["trace_id"] = enrich_result.trace_id
+            if enrich_result.pattern_suggestions:
+                map_result["pattern_suggestions"] = enrich_result.pattern_suggestions
+            if enrich_result.warnings:
+                map_result["kg_warnings"] = enrich_result.warnings
+        return map_result
+
+    async def generate_document(self, session: SessionState, arguments: dict, monitor: ActionMonitor | None = None) -> dict:
+        payload = GenerateDocumentInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        indexer = self._get_indexer(session, project)
+        effective_policy = session.policy_overrides.get(project.project_id, project.llm_policy)
+        task_id = uuid.uuid4().hex
+
+        retriever = HybridRetriever(
+            self.embedder,
+            self.qdrant_store,
+            indexer.bm25_store,
+            self.settings.defaults.retrieval,
+        )
+        active_collection = indexer.active_collection_name()
+
+        if monitor is not None:
+            await monitor.stage("retrieve", "generate_document: recuperando chunks relevantes")
+        retrieved = await retriever.retrieve(
+            project,
+            payload.prompt,
+            overlay_collection=None,
+            collection_name=active_collection,
+            user_collection_name=indexer.active_user_collection_name(),
+            monitor=monitor,
+        )
+
+        if monitor is not None:
+            await monitor.stage("rerank", "generate_document: reranking")
+        top_k = max(1, min(payload.top_k, 30))
+        reranked = await self.reranker.rerank(payload.prompt, retrieved, top_k)
+
+        if monitor is not None:
+            await monitor.stage("graph_walk", "generate_document: expandiendo grafo de dependencias")
+        seed_chunks = [item.chunk for item in reranked]
+        expanded = GraphWalker().expand(
+            seed_chunks,
+            indexer.ast_graph,
+            lambda ids: indexer.qdrant_store.get_chunks_by_ids(active_collection, ids) if active_collection else [],
+            depth=self.settings.defaults.retrieval.graph_walk_depth,
+        )
+        seen: set[str] = set()
+        all_chunks = []
+        for chunk in seed_chunks + expanded:
+            if chunk.chunk_id not in seen:
+                seen.add(chunk.chunk_id)
+                all_chunks.append(chunk)
+
+        context_text = self._format_doc_context(all_chunks)
+
+        # Enrich with SuperKG narrative context if available (fire-and-forget)
+        kg_narrative = ""
+        superkg_system_id = await self._ensure_superkg_system(project)
+        if superkg_system_id:
+            kg_data = await self.superkg.get_context(project.project_id, superkg_system_id, mode="narrative")
+            if isinstance(kg_data, dict):
+                kg_narrative = kg_data.get("content") or kg_data.get("narrative") or kg_data.get("text") or ""
+                if not kg_narrative and "context" in kg_data:
+                    kg_narrative = str(kg_data["context"])
+
+        if monitor is not None:
+            await monitor.stage("generate", "generate_document: generando contenido con LLM")
+
+        kg_section = f"\n\nSuperKG project context:\n{kg_narrative}" if kg_narrative else ""
+        result, usage = await self.llm_runtime.router.chat(
+            task_type="document_generation",
+            policy=effective_policy,  # type: ignore[arg-type]
+            messages=[
+                {"role": "system", "content": _DOC_GENERATION_SYSTEM_PROMPT},
+                {
+                    "role": "user",
+                    "content": (
+                        f"Request: {payload.prompt}\n\n"
+                        f"Output file: {payload.output_path}\n\n"
+                        f"Code context ({len(all_chunks)} chunks from {len({c.file_path for c in all_chunks})} files):\n\n"
+                        f"{context_text}{kg_section}"
+                    ),
+                },
+            ],
+            schema=None,
+            max_tokens=6000,
+            temperature=0.2,
+            project_id=project.project_id,
+            task_id=task_id,
+        )
+
+        content: str = result["content"] if isinstance(result, dict) else str(result)
+
+        output_path = Path(payload.output_path)
+        if output_path.is_absolute():
+            full_path = output_path
+        else:
+            full_path = project.root / output_path
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+        full_path.write_text(content, encoding="utf-8")
+
+        return {
+            "success": True,
+            "file_path": str(full_path),
+            "bytes_written": len(content.encode("utf-8")),
+            "chunks_used": len(all_chunks),
+            "llm_usage": usage.model_dump(mode="json"),
+        }
+
+    async def generate_business_logic(self, session: SessionState, arguments: dict, monitor: ActionMonitor | None = None) -> dict:
+        payload = GenerateBusinessLogicInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        indexer = self._get_indexer(session, project)
+        effective_policy = session.policy_overrides.get(project.project_id, project.llm_policy)
+        task_id = uuid.uuid4().hex
+
+        retriever = HybridRetriever(
+            self.embedder,
+            self.qdrant_store,
+            indexer.bm25_store,
+            self.settings.defaults.retrieval,
+        )
+        active_collection = indexer.active_collection_name()
+
+        if monitor is not None:
+            await monitor.stage("retrieve", "generate_business_logic: recuperando chunks de lógica de negocio")
+
+        seen: set[str] = set()
+        all_chunks = []
+        top_k_per_query = max(5, payload.top_k // len(_BUSINESS_LOGIC_QUERIES))
+        for query in _BUSINESS_LOGIC_QUERIES:
+            retrieved = await retriever.retrieve(
+                project,
+                query,
+                overlay_collection=None,
+                collection_name=active_collection,
+                user_collection_name=indexer.active_user_collection_name(),
+                monitor=None,
+            )
+            reranked = await self.reranker.rerank(query, retrieved, top_k_per_query)
+            for item in reranked:
+                if item.chunk.chunk_id not in seen:
+                    seen.add(item.chunk.chunk_id)
+                    all_chunks.append(item.chunk)
+
+        if monitor is not None:
+            await monitor.stage("graph_walk", "generate_business_logic: expandiendo grafo")
+        expanded = GraphWalker().expand(
+            all_chunks,
+            indexer.ast_graph,
+            lambda ids: indexer.qdrant_store.get_chunks_by_ids(active_collection, ids) if active_collection else [],
+            depth=self.settings.defaults.retrieval.graph_walk_depth,
+        )
+        for chunk in expanded:
+            if chunk.chunk_id not in seen:
+                seen.add(chunk.chunk_id)
+                all_chunks.append(chunk)
+
+        context_text = self._format_doc_context(all_chunks)
+
+        kg_narrative = ""
+        superkg_system_id = await self._ensure_superkg_system(project)
+        if superkg_system_id:
+            kg_data = await self.superkg.get_context(project.project_id, superkg_system_id, mode="narrative")
+            if isinstance(kg_data, dict):
+                kg_narrative = kg_data.get("content") or kg_data.get("narrative") or kg_data.get("text") or ""
+                if not kg_narrative and "context" in kg_data:
+                    kg_narrative = str(kg_data["context"])
+
+        if monitor is not None:
+            await monitor.stage("generate", "generate_business_logic: sintetizando lógica de negocio con LLM")
+
+        kg_section = f"\n\nSuperKG project context:\n{kg_narrative}" if kg_narrative else ""
+        result, usage = await self.llm_runtime.router.chat(
+            task_type="document_generation",
+            policy=effective_policy,  # type: ignore[arg-type]
+            messages=[
+                {"role": "system", "content": _BUSINESS_LOGIC_SYSTEM_PROMPT},
+                {
+                    "role": "user",
+                    "content": (
+                        f"Repository: {project.root}\n\n"
+                        f"Code context ({len(all_chunks)} chunks from {len({c.file_path for c in all_chunks})} files):\n\n"
+                        f"{context_text}{kg_section}"
+                    ),
+                },
+            ],
+            schema=None,
+            max_tokens=8000,
+            temperature=0.1,
+            project_id=project.project_id,
+            task_id=task_id,
+        )
+
+        content: str = result["content"] if isinstance(result, dict) else str(result)
+
+        output_path = Path(payload.output_path)
+        full_path = output_path if output_path.is_absolute() else project.root / output_path
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+        full_path.write_text(content, encoding="utf-8")
+
+        return {
+            "success": True,
+            "file_path": str(full_path),
+            "bytes_written": len(content.encode("utf-8")),
+            "chunks_used": len(all_chunks),
+            "overwritten": full_path.exists(),
+            "llm_usage": usage.model_dump(mode="json"),
+        }
+
+    async def list_snippets(self, session: SessionState, arguments: dict) -> dict:
+        payload = ListSnippetsInput.model_validate(arguments)
+        snippets = self._snippet_loader.list_snippets(
+            framework=payload.framework,
+            language=payload.language,
+            layer=payload.layer,
+        )
+        return {
+            "snippets": [
+                {
+                    "id": s.id,
+                    "framework": s.framework,
+                    "language": s.language,
+                    "layer": s.layer,
+                    "tags": s.tags,
+                    "produces": s.produces,
+                    "requires": s.requires,
+                }
+                for s in snippets
+            ],
+            "total": len(snippets),
+        }
+
+    async def assemble_from_snippets(
+        self, session: SessionState, arguments: dict, monitor: ActionMonitor | None = None
+    ) -> dict:
+        payload = AssembleFromSnippetsInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        effective_policy = session.policy_overrides.get(project.project_id, project.llm_policy)
+        task_id = uuid.uuid4().hex
+
+        assembler = SnippetAssembler(
+            loader=self._snippet_loader,
+            router=self.llm_runtime.router,
+            project=project,
+            logger=self.logger,
+        )
+
+        if monitor is not None:
+            await monitor.stage("intent", "assemble_from_snippets: resolviendo intent")
+        pack = await assembler.assemble(
+            user_prompt=payload.prompt,
+            task_id=task_id,
+            policy=effective_policy,  # type: ignore[arg-type]
+        )
+
+        stored = StoredAssemblyTask(
+            pack=pack,
+            user_prompt=payload.prompt,
+            project_id=project.project_id,
+            effective_policy=effective_policy,  # type: ignore[arg-type]
+            expires_at=datetime.now(timezone.utc).replace(microsecond=0) + timedelta(hours=2),
+        )
+        session.assembly_tasks[task_id] = stored
+
+        result: dict = {
+            "success": pack.success,
+            "task_id": task_id,
+            "project": project.project_id,
+        }
+        if pack.intent:
+            result["intent"] = pack.intent.model_dump()
+        if pack.selection:
+            result["selected_snippets"] = pack.selection.selected_snippet_ids
+        if pack.variables:
+            result["variables"] = pack.variables.model_dump(exclude={"extra"})
+        if pack.result:
+            result["files_created"] = pack.result.files_created
+            result["files_modified"] = pack.result.files_modified
+            result["integration_notes"] = pack.result.integration_notes
+        if pack.failure:
+            result["failure"] = pack.failure.model_dump()
+        result["llm_usage"] = [u.model_dump(mode="json") for u in pack.llm_usage]
+        return result
+
+    @staticmethod
+    def _format_doc_context(all_chunks: list) -> str:
+        """Group chunks by package/module and extract invariants for richer LLM context."""
+        # Group by top-level package or module (first 2 path segments)
+        groups: dict[str, list] = defaultdict(list)
+        for chunk in all_chunks[:32]:
+            parts = Path(chunk.file_path).parts
+            group_key = "/".join(parts[:2]) if len(parts) >= 2 else parts[0]
+            groups[group_key].append(chunk)
+
+        # Extract invariants: constants, thresholds, exports, state values
+        _INVARIANT_RE = re.compile(
+            r"^\s*(?:"
+            r"(?:export\s+(?:const|function|class|type|interface|enum)\s+\w+)"  # TS exports
+            r"|(?:[A-Z][A-Z0-9_]{2,}\s*=\s*.+)"                               # UPPERCASE_CONSTANTS
+            r"|(?:.*=\s*0\.\d{2,})"                                             # score thresholds
+            r"|(?:status[:\s]+['\"]?\w+['\"]?)"                                 # status values
+            r")",
+            re.MULTILINE,
+        )
+
+        sections: list[str] = []
+        for group_key in sorted(groups):
+            chunks = groups[group_key]
+            section_lines = [f"## `{group_key}`\n"]
+
+            invariants: list[str] = []
+            for chunk in chunks:
+                for line in chunk.body.splitlines():
+                    if _INVARIANT_RE.match(line):
+                        stripped = line.strip()
+                        if stripped and stripped not in invariants:
+                            invariants.append(stripped)
+
+            if invariants:
+                section_lines.append("**Exports / constants / thresholds:**")
+                section_lines.extend(f"  - `{inv}`" for inv in invariants[:20])
+                section_lines.append("")
+
+            for chunk in chunks:
+                header = f"### `{chunk.symbol}` — `{chunk.file_path}`"
+                if chunk.signature:
+                    header += f"\n*{chunk.signature}*"
+                body_preview = "\n".join(chunk.body.splitlines()[:60])
+                section_lines.append(f"{header}\n```\n{body_preview}\n```")
+
+            sections.append("\n".join(section_lines))
+
+        return "\n\n---\n\n".join(sections)
+
+    async def init_project(self, session: SessionState, arguments: dict) -> dict:
+        payload = InitProjectInput.model_validate(arguments)
+
+        if payload.path:
+            target = Path(payload.path)
+        elif session.roots:
+            target = session.roots[0]
+        else:
+            return {"success": False, "message": "No path provided and no session root available."}
+
+        from codepreproc_client.layer1_business.cli.init import init_project as _cli_init
+        from codepreproc_client.layer1_business.config import apply_env_overrides, get_home_dir
+        from codepreproc_client.layer1_business.local_registry import load_local_projects
+        from contracts.dtos import Registry as _Registry
+
+        # verbose=False avoids any print() calls that would corrupt MCP stdio
+        exit_code = await asyncio.to_thread(_cli_init, path=target, verbose=False)
+
+        if exit_code != 0:
+            return {"success": False, "message": f"Failed to register project at '{target}'. Check that the path exists and is accessible."}
+
+        # Hot-reload the local registry mirror so the new project is immediately
+        # available (cli.init.init_project already registered it server-side).
+        new_data = apply_env_overrides(
+            _Registry(defaults=self.registry.registry.defaults, projects=load_local_projects(get_home_dir()))
+        )
+        self.registry.registry = new_data
+
+        target_resolved = str(target.resolve())
+        for pid, pconf in new_data.projects.items():
+            if str(pconf.root) == target_resolved:
+                return {
+                    "success": True,
+                    "project_id": pid,
+                    "root": str(pconf.root),
+                    "languages": pconf.languages,
+                    "qdrant_collection": pconf.qdrant_collection,
+                    "message": f"Project '{pid}' registered. Run reindex to build the index.",
+                }
+
+        return {"success": True, "project_id": None, "message": "Project was already registered. No changes made."}
+
+    async def generate_repo_map(self, session: SessionState, arguments: dict, monitor: ActionMonitor | None = None) -> dict:
+        payload = GenerateRepoMapInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        indexer = self._get_indexer(session, project)
+
+        if monitor is not None:
+            await monitor.stage("build_map", "generate_repo_map: construyendo mapa del repositorio")
+
+        db_path = indexer.ast_graph.db_path
+        mapper = RepoMapper(project, db_path)
+
+        try:
+            repo_map = await asyncio.to_thread(
+                mapper.build,
+                artifacts_folder=payload.artifacts_folder,
+                modules_folder=payload.modules_folder,
+            )
+        except NeedsMonorepoConfig as exc:
+            return {
+                "success": False,
+                "needs_clarification": True,
+                "project_id": project.project_id,
+                "questions": [
+                    {
+                        "param": "artifacts_folder",
+                        "question": (
+                            "Which top-level folder contains the deployable artifacts (apps)? "
+                            f"Available root directories: {exc.root_dirs}"
+                        ),
+                    },
+                    {
+                        "param": "modules_folder",
+                        "question": (
+                            "Which top-level folder contains the reusable shared modules (packages)? "
+                            f"Available root directories: {exc.root_dirs}"
+                        ),
+                    },
+                ],
+                "hint": (
+                    "Re-invoke generate_repo_map with artifacts_folder and modules_folder set "
+                    "to the correct directory names."
+                ),
+            }
+
+        if monitor is not None:
+            await monitor.stage("annotate", "generate_repo_map: enriqueciendo con KG y LLM")
+
+        superkg_system_id = await self._ensure_superkg_system(project)
+        policy = session.policy_overrides.get(project.project_id, project.llm_policy)
+        annotator = RepoMapAnnotator(
+            router=self.llm_runtime.router,
+            superkg=self.superkg,
+            cache_path=db_path.parent / "repo_map_cache.json",
+        )
+        final_map = await annotator.annotate(
+            raw_map=repo_map,
+            policy=policy,
+            project_id=project.project_id,
+            project=project,
+            superkg_system_id=superkg_system_id,
+        )
+
+        if monitor is not None:
+            await monitor.stage("write_json", "generate_repo_map: escribiendo repo_map.json")
+
+        output_path = project.root / "repo_map.json"
+        output_path.write_text(json.dumps(final_map, ensure_ascii=False, indent=2), encoding="utf-8")
+
+        if superkg_system_id:
+            await self.superkg.ingest_repo_map(
+                project_id=project.project_id,
+                system_id=superkg_system_id,
+                repo_map=final_map,
+                output_path=str(output_path),
+            )
+            await self.superkg.log_activity(
+                project_id=project.project_id,
+                system_id=superkg_system_id,
+                activity_type="repo_map_generated",
+                details={
+                    "project_id": project.project_id,
+                    "output_path": str(output_path),
+                    **final_map["stats"],
+                },
+            )
+
+        return {
+            "success": True,
+            "project_id": project.project_id,
+            "output_path": str(output_path),
+            "stats": final_map["stats"],
+        }
+
+    async def kg_context(self, session: SessionState, arguments: dict) -> dict:
+        payload = KGContextInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        superkg_system_id = await self._ensure_superkg_system(project)
+        if not superkg_system_id:
+            return {"error": "project_not_registered_in_superkg", "project": project.project_id}
+        data = await self.superkg.get_context(project.project_id, superkg_system_id, mode=payload.mode)
+        return {
+            "project": project.project_id,
+            "system_id": superkg_system_id,
+            "mode": payload.mode,
+            "context": data,
+        }
+
+    async def kg_insights(self, session: SessionState, arguments: dict) -> dict:
+        payload = KGInsightsInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        superkg_system_id = await self._ensure_superkg_system(project)
+        if not superkg_system_id:
+            return {"error": "project_not_registered_in_superkg", "project": project.project_id, "insights": []}
+        items = await self.superkg.get_insights(project.project_id, superkg_system_id)
+        return {
+            "project": project.project_id,
+            "system_id": superkg_system_id,
+            "insights": items,
+            "total": len(items),
+        }
+
+    async def kg_patterns(self, session: SessionState, arguments: dict) -> dict:
+        # Patterns aren't really project-scoped (SuperKG observes them across all
+        # systems), but the /v1/superkg/query proxy authorizes every call against
+        # one owned project+system_id - callers must have at least one active,
+        # SuperKG-registered project to see cross-project patterns at all.
+        project = self._resolve_project(session, None)
+        superkg_system_id = await self._ensure_superkg_system(project)
+        if not superkg_system_id:
+            return {"patterns": [], "total": 0}
+        items = await self.superkg.get_patterns(project.project_id, superkg_system_id)
+        return {"patterns": items, "total": len(items)}
+
+    async def correct_graph(self, session: SessionState, arguments: dict) -> dict:
+        payload = CorrectGraphInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        superkg_system_id = await self._ensure_superkg_system(project)
+        if not superkg_system_id:
+            return {"recorded": False, "error": "project_not_registered_in_superkg"}
+        bld = BusinessLogicDiff(
+            change=payload.change,
+            before=payload.before,
+            after=payload.after,
+            rules_added=payload.rules_added,
+            rules_removed=payload.rules_removed,
+            rules_modified=payload.rules_modified,
+        )
+        await self.superkg.record_decision(
+            project_id=project.project_id,
+            system_id=superkg_system_id,
+            session_id=None,
+            intent=f"graph_correction: {payload.change}",
+            plan_summary={"source": "human_correction"},
+            bld=bld,
+        )
+        return {"recorded": True, "system_id": superkg_system_id, "change": payload.change}
+
+    async def project_pseudocode(self, session: SessionState, arguments: dict) -> dict:
+        import fnmatch
+
+        from codepreproc_client.layer1_business.git_utils import get_current_sha
+        from codepreproc_client.layer2_tooling.condensation.ppl.emitter import PPLEmitter
+        from git import Repo
+
+        payload = ProjectPseudocodeInput.model_validate(arguments)
+        project = self._resolve_project(session, payload.project)
+        indexer = self._get_indexer(session, project)
+
+        rows = indexer.ast_graph.get_all_symbols()
+
+        if payload.file_pattern:
+            pat = payload.file_pattern
+            rows = [r for r in rows if fnmatch.fnmatch(r[2].replace("\\", "/"), pat)]
+        if payload.exclude_tests:
+            _TEST_MARKERS = ("/test/", "/tests/", "\\test\\", "\\tests\\", "_test.py", "test_.py")
+            rows = [r for r in rows if not any(m in r[2] for m in _TEST_MARKERS)]
+
+        by_file: dict[str, list[tuple[str, str, str, str | None]]] = defaultdict(list)
+        for chunk_id, symbol, file_path, kind, signature in rows:
+            by_file[file_path].append((chunk_id, symbol, kind, signature))
+
+        all_files = sorted(by_file.keys())
+        truncated = len(all_files) > payload.max_files
+        files = all_files[: payload.max_files]
+
+        # Always fetch bodies — needed for @bind hash computation
+        active_collection = indexer.active_collection_name()
+        all_ids = [r[0] for fp in files for r in by_file[fp]]
+        chunk_map: dict[str, object] = {}
+        if all_ids and active_collection:
+            fetched = indexer.qdrant_store.get_chunks_by_ids(active_collection, all_ids)
+            chunk_map = {c.chunk_id: c for c in fetched}
+
+        # Fetch caller/callee cross-references from AST graph (batch)
+        chunk_ids_list = list(chunk_map.keys())
+        symbols_list = [sym for fp in files for _, sym, _, _ in by_file[fp]]
+        callees_by_chunk = indexer.ast_graph.find_callees_batch(chunk_ids_list)
+        callers_by_symbol = indexer.ast_graph.find_callers_batch(symbols_list)
+        id_to_symbol = {r[0]: r[1] for r in indexer.ast_graph.get_all_symbols()}
+
+        # Build ordered CodeChunk list for PPL emission
+        ordered_chunks = []
+        for fp in files:
+            file_chunks = [
+                chunk_map[cid]
+                for cid, *_ in by_file[fp]
+                if cid in chunk_map
+            ]
+            file_chunks.sort(key=lambda c: c.start_line)
+            ordered_chunks.extend(file_chunks)
+
+        repo = Repo(project.root)
+        try:
+            git_sha = get_current_sha(repo)
+        finally:
+            repo.close()
+
+        ppl_document = PPLEmitter().emit(
+            project_id=project.project_id,
+            git_sha=git_sha,
+            chunks=ordered_chunks,
+            callers_by_symbol=callers_by_symbol,
+            callees_by_chunk_id=callees_by_chunk,
+            id_to_symbol=id_to_symbol,
+        )
+
+        return {
+            "project": project.project_id,
+            "total_files": len(files),
+            "total_symbols": sum(len(by_file[f]) for f in files),
+            "truncated": truncated,
+            "ppl_document": ppl_document,
+            # Legacy key kept for backward compatibility
+            "pseudocode": ppl_document,
+        }
+
+    async def _ensure_superkg_system(self, project: ProjectConfig) -> str | None:
+        if project.superkg_system_id:
+            return project.superkg_system_id
+        if not getattr(self.superkg, "enabled", False):
+            return None
+
+        system_id = await self.superkg.bootstrap(
+            project_id=project.project_id,
+            name=project.root.name or project.project_id,
+            description=project.project_context or f"Codepreproc project at {project.root}",
+        )
+        if not system_id:
+            return None
+
+        project.superkg_system_id = system_id
+        registered = self.registry.registry.projects.get(project.project_id)
+        if registered is not None:
+            registered.superkg_system_id = system_id
+
+        try:
+            from codepreproc_client.layer1_business.api_client.registry_client import set_superkg_id
+            from codepreproc_client.layer1_business.config import get_home_dir, get_server_url
+            from codepreproc_client.layer1_business.local_registry import load_local_projects, save_local_project
+
+            jwt = await self._jwt_provider(project.project_id)
+            await set_superkg_id(
+                base_url=get_server_url(), jwt=jwt, project_id=project.project_id, system_id=system_id
+            )
+            home_dir = get_home_dir()
+            local = load_local_projects(home_dir)
+            local_project = local.get(project.project_id)
+            if local_project is not None:
+                save_local_project(home_dir, local_project.model_copy(update={"superkg_system_id": system_id}))
+        except Exception as exc:
+            self.logger.debug("superkg_system_id persistence failed for %s: %s", project.project_id, exc)
+
+        return system_id
+
+    def _resolve_project(self, session: SessionState, explicit_project: str | None) -> ProjectConfig:
+        try:
+            return self.registry.resolve_project(
+                explicit_project=explicit_project,
+                active_project=session.active_project,
+                roots=session.roots,
+                fallback_path=session.roots[0] if session.roots else None,
+            )
+        except KeyError as exc:
+            available = [project.project_id for project in self.registry.list_projects()]
+            raise ValueError({"error": str(exc), "available_projects": available}) from exc
+
+    def _get_indexer(self, session: SessionState, project: ProjectConfig) -> ProjectIndexer:
+        if project.project_id not in session.loaded_indexers:
+            project_dir = self.settings.indexes_dir / project.project_id
+            session.loaded_indexers[project.project_id] = ProjectIndexer(
+                project=project,
+                settings=self.settings,
+                qdrant_store=self.qdrant_store,
+                bm25_store=BM25Store(project_dir / "bm25.pkl"),
+                ast_graph=AstGraph(project_dir / "ast_graph.sqlite"),
+                chunker=AstChunker(self.settings.defaults.chunking),
+                embedder=self.embedder,
+                coupling_graph=self._coupling_graph,
+                user_id=session.user_id,
+            )
+        return session.loaded_indexers[project.project_id]
+
+    def _make_pipeline(self, session: SessionState, project: ProjectConfig) -> SemanticExecutionPipeline:
+        indexer = self._get_indexer(session, project)
+        return SemanticExecutionPipeline(
+            project=project,
+            settings=self.settings,
+            indexer=indexer,
+            retriever=HybridRetriever(self.embedder, self.qdrant_store, indexer.bm25_store, self.settings.defaults.retrieval),
+            reranker=self.reranker,
+            graph_walker=GraphWalker(),
+            intent_extractor=IntentExtractor(self.llm_runtime.router),
+            context_compactor=ContextCompactor(self.llm_runtime.router),
+            target_locator=TargetLocator(
+                primary_limit=self.settings.defaults.semantic_editing.max_primary_targets,
+                secondary_limit=self.settings.defaults.semantic_editing.max_secondary_targets,
+            ),
+            region_resolver=RegionResolver(),
+            planner=SemanticEditPlanner(self.llm_runtime.router),
+            applicability_checker=ApplicabilityChecker(),
+            synthesizer=SemanticSynthesizer(
+                self.llm_runtime.router,
+                micro_editor_temperature=self.settings.defaults.semantic_editing.micro_editor_temperature,
+            ),
+            logger=self.logger,
+        )
+
+    def _make_filesystem_pipeline(self, project: ProjectConfig) -> FilesystemReorganizationPipeline:
+        return FilesystemReorganizationPipeline(
+            project=project,
+            settings=self.settings,
+            router=self.llm_runtime.router,
+        )
+
+    async def coupling_project(
+        self, session: SessionState, arguments: dict, monitor: ActionMonitor | None = None
+    ) -> dict:
+        """Project cross-repo coupling structure for a set of repos in one call."""
+        payload = CouplingProjectInput.model_validate(arguments)
+        req = CouplingProjectRequest(anchors=payload.anchors, intent=payload.intent)
+
+        # Resolve intent → project_ids when anchors not given
+        if not req.is_concrete():
+            if not req.intent:
+                return {"error": "provide anchors (project_id list) or intent string"}
+            all_ids = [p.project_id for p in self.registry.list_projects()]
+            intent_lower = req.intent.lower()
+            anchors = [pid for pid in all_ids if intent_lower in pid.lower()]
+            if not anchors:
+                anchors = all_ids
+        else:
+            anchors = payload.anchors
+
+        # Validate all anchors are registered projects
+        known = {p.project_id for p in self.registry.list_projects()}
+        unknown = [a for a in anchors if a not in known]
+        if unknown:
+            return {"error": f"unknown project_ids: {unknown}", "known": sorted(known)}
+
+        if monitor is not None:
+            await monitor.stage("hydrate", "coupling_project: hidratando edges")
+
+        # Hydrate edge superset from coupling graph (Layer 1 — candidate level)
+        edges = await asyncio.to_thread(
+            self._coupling_graph.get_edges_for_projects, anchors
+        )
+
+        # Apply Layer 2 gate: disambiguate ambiguous edges and revalidate stale ones.
+        # Uses export_surface_hash rather than last_indexed_sha so body-only commits
+        # in dst projects do not trigger re-resolution.
+        if monitor is not None:
+            await monitor.stage("revalidate", "coupling_project: aplicando gate Layer 2")
+        from codepreproc_client.layer2_tooling.coupling.layer2_gate import apply_layer2_gate
+        edges, stale_count = await asyncio.to_thread(
+            apply_layer2_gate, edges, self.settings.indexes_dir, self._coupling_graph
+        )
+
+        if monitor is not None:
+            await monitor.stage("project", "coupling_project: proyectando métricas")
+
+        summary = await asyncio.to_thread(
+            self._coupling_projector.project, anchors, edges, stale_count
+        )
+
+        handle_id = uuid.uuid4().hex
+        report = CouplingReport(
+            handle_id=handle_id,
+            anchors=anchors,
+            edges=edges,
+            summary=summary,
+        )
+        session.coupling_reports[handle_id] = report
+
+        from codepreproc_client.layer2_tooling.coupling.domain import CouplingHandle
+        handle = CouplingHandle(
+            handle_id=handle_id,
+            summary=summary,
+            provenance_level="resolved",
+        )
+        return handle.model_dump(mode="json")
+
+    async def coupling_expand(self, session: SessionState, arguments: dict) -> dict:
+        """Expand a coupling handle to retrieve edge details on demand."""
+        payload = CouplingExpandInput.model_validate(arguments)
+        report = session.coupling_reports.get(payload.handle_id)
+        if report is None:
+            return {"error": "handle_not_found", "handle_id": payload.handle_id}
+
+        if payload.edge_id:
+            # Single edge detail
+            edge = next((e for e in report.edges if e.edge_id == payload.edge_id), None)
+            if edge is None:
+                return {"error": "edge_not_found", "edge_id": payload.edge_id}
+            # Enrich with file paths from local AstGraph
+            from codepreproc_client.layer2_tooling.coupling.domain import EdgeDetail
+            src_file = ""
+            dst_file = ""
+            src_project = self.registry.registry.projects.get(edge.src_project_id)
+            dst_project = self.registry.registry.projects.get(edge.dst_project_id)
+            if src_project:
+                src_indexer_dir = self.settings.indexes_dir / edge.src_project_id
+                try:
+                    import sqlite3 as _sqlite3
+                    conn = _sqlite3.connect(str(src_indexer_dir / "ast_graph.sqlite"))
+                    row = conn.execute("SELECT file_path FROM symbols WHERE chunk_id = ?", (edge.src_chunk_id,)).fetchone()
+                    conn.close()
+                    src_file = row[0] if row else ""
+                except Exception:
+                    pass
+            if dst_project:
+                dst_indexer_dir = self.settings.indexes_dir / edge.dst_project_id
+                try:
+                    import sqlite3 as _sqlite3
+                    conn = _sqlite3.connect(str(dst_indexer_dir / "ast_graph.sqlite"))
+                    row = conn.execute("SELECT file_path FROM symbols WHERE chunk_id = ?", (edge.dst_chunk_id,)).fetchone()
+                    conn.close()
+                    dst_file = row[0] if row else ""
+                except Exception:
+                    pass
+            detail = EdgeDetail(edge=edge, src_file_path=src_file, dst_file_path=dst_file)
+            return detail.model_dump(mode="json")
+
+        # Paginated edge list
+        total = len(report.edges)
+        page = report.edges[payload.offset: payload.offset + payload.limit]
+        return {
+            "handle_id": payload.handle_id,
+            "anchors": report.anchors,
+            "total_edges": total,
+            "offset": payload.offset,
+            "limit": payload.limit,
+            "edges": [e.model_dump(mode="json") for e in page],
+        }
+
+    @staticmethod
+    def _prune_tasks(session: SessionState) -> None:
+        now = datetime.now(timezone.utc)
+        expired = [task_id for task_id, item in session.semantic_tasks.items() if item.expires_at <= now]
+        for task_id in expired:
+            session.semantic_tasks.pop(task_id, None)
+        expired_filesystem = [task_id for task_id, item in session.filesystem_tasks.items() if item.expires_at <= now]
+        for task_id in expired_filesystem:
+            session.filesystem_tasks.pop(task_id, None)
+        expired_assembly = [task_id for task_id, item in session.assembly_tasks.items() if item.expires_at <= now]
+        for task_id in expired_assembly:
+            session.assembly_tasks.pop(task_id, None)