higpertext-cli 0.8.0__py3-none-any.whl

higpertext/kernel/infrastructure/cli/router.py

@@ -0,0 +1,1110 @@
+"""higpertext Engine CLI — orquestador de capacidades, perfiles y workflows."""
+
+import sys
+import os
+import json
+import argparse
+import subprocess  # nosec B404
+import shutil
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from higpertext.kernel.infrastructure.cli.arguments import parse_kv_args, pop_bool_flag
+from higpertext.kernel.infrastructure.cli.capability_command_builder import (
+    build_command,
+    build_powershell_command,
+    extra_args,
+    resolve_entrypoint,
+)
+from higpertext.kernel.infrastructure.cli.capability_task_service import CapabilityTaskService
+from higpertext.kernel.infrastructure.cli.parser_builder import (
+    add_agent_subparser,
+    add_health_subparser,
+    add_profile_init_subparsers,
+    add_roadmap_subparser,
+    add_session_workflow_subparsers,
+    add_task_ask_subparsers,
+    build_parser,
+)
+from higpertext.kernel.infrastructure.cli.agent_commands import (
+    dispatch_agent,
+    dispatch_agent_list,
+    dispatch_agent_register,
+    dispatch_agent_sync,
+)
+from higpertext.kernel.infrastructure.cli.profile_commands import (
+    dispatch_profile,
+    dispatch_profile_learn,
+    dispatch_profile_validate,
+)
+from higpertext.kernel.infrastructure.cli.roadmap_commands import dispatch_roadmap
+from higpertext.kernel.infrastructure.cli.session_commands import (
+    parse_session_resources,
+    start_session,
+)
+from higpertext.kernel.infrastructure.cli.task_commands import dispatch_task
+from higpertext.kernel.infrastructure.cli.task_result_reporter import (
+    build_memory_notes,
+    print_task_failure,
+    report_task_result,
+)
+from higpertext.kernel.infrastructure.cli.workflow_commands import (
+    dispatch_workflow,
+    resolve_workflow_params,
+)
+from higpertext.kernel.infrastructure.logger import get_logger
+from higpertext.kernel.app_config import ASSISTANTS as _ASSISTANTS, RESERVED_PROFILES as _RESERVED_PROFILES_CFG
+from pathlib import Path
+
+_log = get_logger()
+
+# ROOT_DIR: project root for the user's workspace (CWD when installed as CLI).
+# PKG_DATA_DIR: where shipped static data lives (site-packages when installed, src/ in dev).
+
+
+def _resolve_root_dir() -> Path:
+    env_override = os.environ.get("HIGPERTEXT_ENGINE_ROOT")
+    if env_override:
+        return Path(env_override).resolve()
+    # router.py is nested 6 levels deep from the repo root in development.
+    this_file = Path(__file__).resolve()
+    if "site-packages" in this_file.parts:
+        return Path.cwd()
+    return this_file.parent.parent.parent.parent.parent.parent
+
+
+ROOT_DIR = _resolve_root_dir()
+
+
+def _resolve_pkg_data_dir() -> Path:
+    try:
+        import higpertext_data
+
+        return Path(higpertext_data.__path__[0]).resolve()
+    except (ImportError, AttributeError, IndexError):
+        return ROOT_DIR / "src"
+
+
+PKG_DATA_DIR = _resolve_pkg_data_dir()
+
+_router_file = Path(__file__).resolve()
+_kernel_core = str(_router_file.parent.parent.parent.parent)  # src/core when installed
+if _kernel_core not in sys.path:
+    sys.path.insert(0, _kernel_core)
+# In development, also add the repo's src/core
+_dev_candidate = _router_file.parent.parent.parent.parent.parent.parent
+if "site-packages" not in str(_dev_candidate):
+    _dev_core = str(_dev_candidate / "src" / "core")
+    if _dev_core not in sys.path:
+        sys.path.insert(0, _dev_core)
+
+# Helper for resolving mockable classes/functions — always via
+# kernel._compat so tests patch one place
+
+
+def _dep(name):
+    import higpertext.kernel._compat as _compat
+
+    if hasattr(_compat, name):
+        return getattr(_compat, name)
+    if name == "_start_session":
+        return _start_session
+    if name == "_parse_session_resources":
+        return _parse_session_resources
+    raise AttributeError(name)
+
+
+try:
+    if "htx" in sys.modules and hasattr(sys.modules["htx"], "HigpertextEngine"):
+        HigpertextEngine = sys.modules["htx"].HigpertextEngine  # noqa: F841
+    else:
+        from higpertext.kernel.engine import HigpertextEngine  # noqa: F401
+    from higpertext.kernel.infrastructure.cli.cli_search import HigpertextSearchMixin
+    from higpertext.adapters.gemini_adapter.gemini_adapter import GeminiAdapter
+    from higpertext.adapters.claude_adapter.claude_adapter import ClaudeAdapter
+    from higpertext.adapters.copilot_adapter.copilot_adapter import CopilotAdapter
+    from higpertext.adapters.open_code_adapter.open_code_adapter import OpenCodeAdapter
+except ImportError as e:
+    _log.warning(f"[!] Error cargando higpertext Engine en CLI: {e}")
+    sys.exit(1)
+
+POSTMORTEM_DIR = ROOT_DIR.parent.parent / "Test" / "postmortem"
+GOVERNANCE_DIR = ROOT_DIR.parent.parent / "Gobernanza"
+DOCS_DIR = ROOT_DIR / "docs"
+
+from higpertext.kernel.app_config import (
+    IGNORE_PATTERNS as _IGNORE_PATTERNS,
+    ASSISTANT_IGNORE_FILES as _ASSISTANT_IGNORE_FILES,
+    GITIGNORE_SECTION as _GITIGNORE_SECTION,
+    GUIDE_SPECS as _GUIDE_SPECS_RAW,
+    PROFILES_SECTION as _PROFILES_SECTION,
+    RULES_SECTION as _RULES_SECTION,
+)
+
+_IGNORE_CONTENT = "\n".join(_IGNORE_PATTERNS)
+_ASSISTANT_IGNORE: dict[str, tuple[str, ...]] = {
+    k: tuple(v) for k, v in _ASSISTANT_IGNORE_FILES.items()
+}
+_GUIDE_SPECS: dict[str, tuple[str, str, list[str]]] = {
+    k: (v["filename"], v["title"], v["intro"]) for k, v in _GUIDE_SPECS_RAW.items()
+}
+
+# --- Maps assistant id to its rule-generation adapter function ---
+_ADAPTER_MAP = {
+    "gemini": lambda ctx, root: GeminiAdapter.generate_rules(ctx, root),
+    "antigravity": lambda ctx, root: GeminiAdapter.generate_rules(ctx, root),
+    "claude": lambda ctx, root: ClaudeAdapter.generate_rules(ctx, root),
+    "copilot": lambda ctx, root: CopilotAdapter.generate_rules(ctx, root),
+    "github-copilot": lambda ctx, root: CopilotAdapter.generate_rules(ctx, root),
+    "opencode": lambda ctx, root: OpenCodeAdapter.generate_rules(ctx, root),
+}
+
+
+
+
+# --- CLI argument parsing helpers ---
+def _parse_kv_args(raw_args: list[str]) -> dict:
+    """Parsea una lista ['--key', 'val', ...] en un dict."""
+    return parse_kv_args(raw_args)
+
+
+class HigpertextHub(HigpertextSearchMixin):
+    """Orquestador principal del CLI de higpertext Engine."""
+
+    def __init__(self) -> None:
+        self.version = "5.0.0"
+        engine_cls = self._load_engine_cls()
+        self.engine = engine_cls(ROOT_DIR)
+
+    # Prefers already-loaded HigpertextEngine from htx.py module to avoid
+    # a double-import cycle when CLI is invoked via the launcher shim.
+    @staticmethod
+    def _load_engine_cls():
+        try:
+            if "htx" in sys.modules and hasattr(sys.modules["htx"], "HigpertextEngine"):
+                return sys.modules["htx"].HigpertextEngine
+            from higpertext.kernel.engine import HigpertextEngine as _NE  # noqa: F811
+
+            return _NE
+        except (ImportError, AttributeError):
+            from higpertext.kernel.engine import HigpertextEngine as _NE2  # noqa: F811
+
+            return _NE2
+
+    # --- Project initialization ---
+    # Creates htx.py launcher, writes ignore files, injects initial profile.
+
+    def init_project(
+        self, profile_name: str | None, assistant: str, target_dir: str | None = None
+    ) -> None:
+        """Inicializa la estructura del asistente en el proyecto destino."""
+        project_root = self._resolve_project_root(target_dir)
+        self._update_gitignore(project_root)
+
+        _log.info(f"[*] Inicializando entorno vacío para '{assistant}' en: " f"{project_root}")
+        if profile_name:
+            _log.warning(
+                f"    [!] 'init' inicializa el workspace en blanco. Para "
+                f"inyectar el rol '{profile_name}' ejecuta: htx"
+                f" profile load {profile_name} --assistant {assistant}"
+            )
+
+        self.generate_user_guide(project_root, assistant)
+
+        env_mgr = _dep("EnvironmentManager")(project_root)
+        env_data = env_mgr.initialize_environment(profile_name or "global", assistant)
+        initial_profile = profile_name or "global"
+        from higpertext.adapters.adapter_utils import get_adapter_class
+
+        adapter_cls = get_adapter_class(assistant)
+        try:
+            context = self.engine.get_agent_context(initial_profile, env_data=env_data)
+        except FileNotFoundError as e:
+            _log.warning(
+                f"[!] Perfil '{initial_profile}' no disponible en este entorno,"
+                f" omitiendo contexto: {e}"
+            )
+            context = None
+        if adapter_cls and hasattr(adapter_cls, "on_init") and context:
+            adapter_cls.on_init(context, project_root)
+        self._generate_dynamic_playbooks(project_root, assistant, copy_resources=False)
+        if context:
+            self._render_native_hooks(project_root, assistant, initial_profile, context)
+        self._refresh_semantic_graph(project_root)
+
+    @staticmethod
+    def _update_gitignore(project_root: Path) -> None:
+        """Añade los patrones de higpertext al .gitignore del proyecto destino.
+
+        Si el bloque ya existe (detectado por el encabezado), no lo duplica.
+        """
+        gitignore_path = project_root / ".gitignore"
+        marker = "# higpertext Engine - archivos generados (no versionar)"
+        existing = ""
+        if gitignore_path.exists():
+            try:
+                existing = gitignore_path.read_text(encoding="utf-8")
+            except OSError:  # nosec B110
+                pass
+        if marker in existing:
+            return
+        with gitignore_path.open("a", encoding="utf-8") as f:
+            f.write(_GITIGNORE_SECTION)
+        _log.ok(f"[*] .gitignore actualizado en: {gitignore_path}")
+
+    @staticmethod
+    def _resolve_project_root(target_dir: str | None) -> Path:
+        if target_dir:
+            root = Path(target_dir).expanduser().resolve()
+            root.mkdir(parents=True, exist_ok=True)
+            return root
+        return Path.cwd()
+
+    @staticmethod
+    def _refresh_semantic_graph(project_root: Path) -> None:
+        try:
+            from higpertext.kernel.infrastructure.parser.semantic_graph import (
+                SemanticGraphGenerator,
+            )
+
+            _log.info("[*] Generando grafo semántico inicial...")
+            SemanticGraphGenerator.generate(project_root)
+            _log.ok("[SUCCESS] Grafo semántico generado en " ".higpertext/state/semantic_graph.md")
+        except (ImportError, OSError) as e:
+            _log.warning(f"[WARNING] No se pudo generar el grafo semántico: {e}")
+
+    # --- Dynamic playbooks ---
+    # Reads session state and rebuilds playbook .md files with active
+    # skill/subagent links injected. Called after session-start and
+    # profile load to keep playbooks in sync with the active session.
+
+    def _generate_dynamic_playbooks(
+        self, project_root: Path, assistant: str, copy_resources: bool = True
+    ) -> None:
+        """Genera los playbooks primarios adaptados al asistente."""
+        from higpertext.kernel.infrastructure.compilers import CompilerFactory
+        CompilerFactory.create("playbook", project_root, engine_root=ROOT_DIR, pkg_data_dir=PKG_DATA_DIR, engine=self.engine).compile(assistant, copy_resources)
+
+    # --- User guide generation ---
+    # Generates a Markdown guide file for the selected assistant and writes
+    # it to the project root. Content is assembled from _GUIDE_SPECS and
+    # module-level section constants (_PROFILES_SECTION, _RULES_SECTION).
+
+    def generate_user_guide(self, target_path: Path, assistant: str) -> None:
+        """Genera la guía del asistente con capacidades globales."""
+        from higpertext.kernel.infrastructure.compilers import CompilerFactory
+        CompilerFactory.create("guide", target_path, engine=self.engine).compile(assistant)
+
+    # --- Profile loading ---
+    # Validates the environment is initialized, then delegates rule generation
+    # to the assistant-specific adapter from _ADAPTER_MAP.
+
+    def _check_assistant_initialized(
+        self, env_mgr: "EnvironmentManager", assistant: str, project_root: Path
+    ) -> "dict | None":
+        """Verifica inicialización y retorna env_data o None."""
+        if not env_mgr.is_initialized():
+            _log.warning(
+                f"[!] Proyecto en {project_root} no inicializado. "
+                f"Ejecuta: htx init --assistant {assistant}"
+            )
+            return None
+        env_data = env_mgr.load_environment()
+        if assistant not in env_data.get("assistants", []):
+            _log.warning(
+                f"[!] '{assistant}' no está inicializado. Ejecuta: "
+                f"htx init --assistant {assistant}"
+            )
+            return None
+        return env_data
+
+    def _inject_profile_rules(
+        self, context: dict, assistant: str, profile_name: str, project_root: Path
+    ) -> None:
+        _log.info(
+            f"\n[*] Inyectando perfil '{profile_name.upper()}' para "
+            f"'{assistant}' en: {project_root}"
+        )
+        _log.info(f"    {context['profile']['description']}")
+        generator = _ADAPTER_MAP.get(assistant)
+        if generator:
+            rule_file = generator(context, project_root)
+            _log.ok(f"[SUCCESS] Reglas inyectadas en: {rule_file}")
+        _log.info("\n    Capacidades activas del perfil:")
+        for cap in context["active_capabilities"]:
+            _log.info(f"    - {cap['id']}: {cap['description']}")
+
+    def _resolve_assistant_for_profile(self, env_mgr: "EnvironmentManager", assistant: str | None) -> str:
+        if assistant:
+            return assistant
+        env_data = env_mgr.load_environment() if env_mgr.is_initialized() else {}
+        return env_data.get("assistant") or "gemini"
+
+    def _print_profile_validation(self, profile_name: str) -> None:
+        success, errors, warnings = self.engine.validate_profile(profile_name)
+        if not success or warnings:
+            if errors:
+                _log.warning(
+                    f"[!] ADVERTENCIA: El perfil '{profile_name}'"
+                    " tiene inconsistencias o errores:"
+                )
+                for err in errors:
+                    _log.info(f"    - {err}")
+            if warnings:
+                _log.info(f"[*] ALERTA: Optimización del perfil '{profile_name}':")
+                for warn in warnings:
+                    _log.info(f"    - {warn}")
+            _log.warning("[!] Cargando el perfil de todos modos...\n")
+
+    def _get_assistants_to_render(self, assistant: str, env_data: dict) -> list[str]:
+        assistants_to_render = [assistant]
+        for a in env_data.get("assistants", []):
+            if a not in assistants_to_render:
+                assistants_to_render.append(a)
+        return assistants_to_render
+
+    def load_agent_profile(
+        self,
+        profile_name: str,
+        assistant: str | None = None,
+        target_dir: str | None = None,
+    ) -> None:
+        """Carga un perfil e inyecta sus reglas en el proyecto."""
+        try:
+            project_root = self._resolve_project_root(target_dir)
+            env_mgr = _dep("EnvironmentManager")(project_root)
+            assistant = self._resolve_assistant_for_profile(env_mgr, assistant)
+
+            env_data = self._check_assistant_initialized(env_mgr, assistant, project_root)
+            if env_data is None:
+                return
+
+            self._print_profile_validation(profile_name)
+
+            context = self.engine.get_agent_context(profile_name, env_data=env_data)
+            if not context:
+                return
+
+            self._inject_profile_rules(context, assistant, profile_name, project_root)
+            env_mgr.add_active_profile(profile_name)
+            self._generate_dynamic_playbooks(project_root, assistant, copy_resources=False)
+
+            for ast in self._get_assistants_to_render(assistant, env_data):
+                self._render_native_hooks(project_root, ast, profile_name, context)
+
+            self._auto_start_session(project_root, profile_name, assistant)
+        except (OSError, KeyError, ValueError) as e:
+            _log.warning(f"[!] Error gestionando perfil: {e}")
+
+    def _render_native_hooks(
+        self, project_root: Path, assistant: str, profile_name: str, context: dict
+    ) -> None:
+        """Compila hooks del perfil y regenera config nativa del asistente."""
+        from higpertext.kernel.infrastructure.compilers import CompilerFactory
+        compiler = CompilerFactory.create("hook", project_root, pkg_data_dir=PKG_DATA_DIR)
+        compiler.compile(profile_name, assistant, context)
+
+    def _auto_start_session(self, project_root: Path, profile_name: str, assistant: str) -> None:
+        """Inicia sesión automáticamente al cargar perfil si no hay una activa."""
+        try:
+            session_file = project_root / WORKSPACE_DIR_NAME / "state" / "session.json"
+            if session_file.exists():
+                data = json.loads(session_file.read_text(encoding="utf-8"))
+                # Si ya hay sesión activa para el mismo perfil y asistente, no relanzar
+                if (
+                    data.get("status") == "active"
+                    and data.get("profile") == profile_name
+                    and data.get("assistant") == assistant
+                ):
+                    return
+            session_mgr = _dep("SessionManager")(project_root, ROOT_DIR)
+            session_mgr.start_session(profile_name, assistant, None, None)
+        except Exception as e:
+            _log.warning(f"[WARNING] No se pudo iniciar sesión automáticamente: {e}")
+
+    # --- Agent lifecycle (no assistant) ---
+    # Initializes .higpertext/ from src/config + src/hooks without generating
+    # any assistant-specific files (.claude/, .opencode/, etc.)
+
+    _RESERVED_PROFILES = _RESERVED_PROFILES_CFG
+
+    def agent_init(self, profile_name: str, target_dir: str | None = None) -> None:
+        """Crea la estructura base del agente e inicializa su ambiente."""
+        if profile_name in self._RESERVED_PROFILES:
+            _log.error(f"[ERROR] '{profile_name}' es un perfil reservado del motor higpertext.")
+            _log.info(f"        Nombres reservados: {', '.join(sorted(self._RESERVED_PROFILES))}")
+            return None
+
+        project_root = self._resolve_project_root(target_dir)
+        _log.info(f"[*] Creando agente '{profile_name}' en: {project_root}")
+
+        self._scaffold_agent_structure(project_root)
+
+        env_mgr = _dep("EnvironmentManager")(project_root)
+        env_data = env_mgr.initialize_environment(profile_name, "agent")
+
+        self._compile_hook_layers(project_root, profile_name)
+        self._refresh_semantic_graph(project_root)
+
+        _log.ok(f"[SUCCESS] Agente listo en: {project_root}")
+        _log.info(f"          Perfil   : {profile_name}")
+        _log.info(f"          Ejecuta  : htx agent status")
+        return env_data
+
+    def _scaffold_agent_structure(self, project_root: Path) -> None:
+        """Crea la estructura de carpetas base e inyecta perfiles y hooks globales."""
+        dirs = [
+            "src/higpertext/capabilities",
+            "src/config/profiles",
+            "src/config/governance",
+            "src/config/environments",
+            "src/config/templates",
+            "src/config/workflows",
+            "src/config/hooks/profiles",
+            "src/config/hooks/custom",
+            "content",
+        ]
+        for d in dirs:
+            (project_root / d).mkdir(parents=True, exist_ok=True)
+
+        self._copy_base_profiles(project_root)
+        self._copy_base_governance(project_root)
+        _log.info(f"[*] Estructura base creada en: {project_root / 'src'}")
+
+    def _copy_base_governance(self, project_root: Path) -> None:
+        """Copia guidelines_contract.json y security_guardrails.json al agente."""
+        import shutil as _shutil
+
+        engine_gov = PKG_DATA_DIR / "config" / "governance"
+        dest_gov = project_root / "src" / "config" / "governance"
+        copied = []
+        for gov_file in ("guidelines_contract.json", "security_guardrails.json"):
+            src = engine_gov / gov_file
+            dst = dest_gov / gov_file
+            if src.exists() and not dst.exists():
+                _shutil.copy2(src, dst)
+                copied.append(gov_file)
+        if copied:
+            _log.info(f"[*] Gobernanza base copiada: {', '.join(copied)}")
+
+    def _copy_base_profiles(self, project_root: Path) -> None:
+        """Copia agent_designer.json al nuevo agente. base_agent es interno del motor."""
+        engine_profiles = PKG_DATA_DIR / "config" / "profiles"
+        dest_profiles = project_root / "src" / "config" / "profiles"
+        src = engine_profiles / "agent_designer.json"
+        dst = dest_profiles / "agent_designer.json"
+        if src.exists() and not dst.exists():
+            import shutil as _shutil
+
+            _shutil.copy2(src, dst)
+        _log.info(f"[*] Perfil base copiado: agent_designer")
+
+    @staticmethod
+    def _copy_resource_files(sub_src: Path, sub_dest: Path, label: str) -> None:
+        import shutil as _shutil
+
+        for f in sub_src.rglob("*"):
+            if not f.is_file():
+                continue
+            if f.suffix not in (".json", ".py"):
+                continue
+            rel = f.relative_to(sub_src)
+            dst = sub_dest / rel
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            _shutil.copy2(f, dst)
+            if f.suffix == ".json":
+                _log.info(f"[*] {label} instalada: {rel}")
+
+    def _install_source_resources(self, project_root: Path, source_path: Path) -> None:
+        src_root = source_path / "src"
+        for sub_src, sub_dest, label in [
+            (
+                src_root / "capabilities",
+                project_root / WORKSPACE_DIR_NAME / "capabilities",
+                "Capability",
+            ),
+            (
+                src_root / "config" / "hooks",
+                project_root / "src" / "config" / "hooks",
+                "Hook",
+            ),
+            (
+                src_root / "config" / "governance",
+                project_root / "src" / "config" / "governance",
+                "Governance",
+            ),
+        ]:
+            if sub_src.exists():
+                self._copy_resource_files(sub_src, sub_dest, label)
+
+    @staticmethod
+    def _install_profile_rules(project_root: Path, src_root: Path, profile_name: str) -> None:
+        import shutil as _shutil
+
+        profile_rules_src = (
+            src_root / "config" / "hooks" / "profiles" / profile_name / "profile_rules.json"
+        )
+        if not profile_rules_src.exists():
+            return
+        for assistant_hooks in (
+            project_root / ".claude" / "hooks" / "_rules",
+            project_root / ".gemini" / "hooks" / "_rules",
+        ):
+            if assistant_hooks.parent.parent.exists():
+                assistant_hooks.mkdir(parents=True, exist_ok=True)
+                _shutil.copy2(profile_rules_src, assistant_hooks / "profile_rules.json")
+                _log.info(f"[*] Profile rules instaladas en: {assistant_hooks}")
+
+    def install_profile(
+        self,
+        profile_name: str,
+        target_dir: str | None = None,
+        source: str | None = None,
+    ) -> None:
+        """Copia un perfil a .higpertext/profiles/ del proyecto activo."""
+        import shutil as _shutil
+
+        project_root = self._resolve_project_root(target_dir)
+        sub_path = "src/config/profiles" if source else "src/higpertext/profiles"
+        src = Path(source or ROOT_DIR) / sub_path / f"{profile_name}.json"
+        if not src.exists():
+            _log.error(f"[ERROR] Perfil '{profile_name}' no encontrado en: {src}")
+            return
+        dest = project_root / WORKSPACE_DIR_NAME / "profiles" / f"{profile_name}.json"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        _shutil.copy2(src, dest)
+        _log.ok(f"[SUCCESS] Perfil '{profile_name}' instalado en: {dest}")
+
+        if source:
+            source_path = Path(source)
+            self._install_source_resources(project_root, source_path)
+            self._install_profile_rules(project_root, source_path / "src", profile_name)
+            self._register_agent_dir(project_root, source_path)
+            self._copy_templates(source_path / "src", project_root)
+
+    def _copy_templates(self, src_root: Path, project_root: Path) -> None:
+        """Copia src/templates/ del agente externo al motor para resolución de skills."""
+        import shutil as _shutil
+
+        templates_src = src_root / "templates"
+        if not templates_src.exists():
+            return
+        templates_dst = project_root / WORKSPACE_DIR_NAME / "agent_templates"
+        templates_dst.mkdir(parents=True, exist_ok=True)
+        for f in templates_src.rglob("*"):
+            if f.is_file():
+                dst = templates_dst / f.relative_to(templates_src)
+                dst.parent.mkdir(parents=True, exist_ok=True)
+                _shutil.copy2(f, dst)
+        _log.info(f"[*] Templates del agente copiadas en: {templates_dst}")
+
+    def _register_agent_dir(self, project_root: Path, agent_dir: Path) -> None:
+        """Persiste agent_dir en environment.json para resolución de recursos externos."""
+        env_file = project_root / WORKSPACE_DIR_NAME / "config" / "environment.json"
+        try:
+            data = json.loads(env_file.read_text(encoding="utf-8"))
+            data["agent_dir"] = str(agent_dir.resolve())
+            env_file.write_text(json.dumps(data, indent=4, ensure_ascii=False), encoding="utf-8")
+            _log.info(f"[*] agent_dir registrado: {agent_dir.resolve()}")
+        except Exception as exc:
+            _log.warning(f"[!] No se pudo registrar agent_dir: {exc}")
+
+    def agent_status(self, target_dir: str | None = None) -> None:
+        """Muestra el estado del ambiente del agente."""
+        project_root = self._resolve_project_root(target_dir)
+        env_mgr = _dep("EnvironmentManager")(project_root)
+        if not env_mgr.is_initialized():
+            _log.warning("[!] Ambiente no inicializado. Ejecuta: htx agent init --profile <nombre>")
+            return
+        env_data = env_mgr.load_environment()
+        profiles = env_data.get("active_profiles", env_data.get("active_profile", "—"))
+        _log.info(f"\n── Agent Status ───────────────────────────")
+        _log.info(f"  Perfil(es) : {profiles}")
+        _log.info(f"  Entorno    : {project_root / WORKSPACE_DIR_NAME / 'config' / 'environment.json'}")
+        hooks_cfg = project_root / WORKSPACE_DIR_NAME / "config" / "hooks_config.json"
+        hooks_status = "compilados" if hooks_cfg.exists() else "no compilados"
+        _log.info(f"  Hooks      : {hooks_status}")
+        _log.info("")
+    def agent_clean(self, target_dir: str | None = None) -> None:
+        """Limpia el estado efímero del agente sin borrar configuración base."""
+        project_root = self._resolve_project_root(target_dir)
+        session_file = project_root / WORKSPACE_DIR_NAME / "state" / "session.json"
+        if session_file.exists():
+            session_file.unlink()
+            _log.ok("[SUCCESS] Sesión efímera eliminada.")
+        else:
+            _log.info("[*] No hay sesión activa que limpiar.")
+
+    @staticmethod
+    def _compile_hook_layers(project_root: Path, profile_name: str) -> None:
+        """Compila las capas de hooks (global + perfil + custom) en hooks_config.json."""
+        from higpertext.kernel.infrastructure.compilers import CompilerFactory
+        CompilerFactory.create("hook", project_root, pkg_data_dir=PKG_DATA_DIR).compile(profile_name)
+
+    # --- Knowledge search ---
+    # Delegates to HigpertextSearchMixin._walk_search which traverses governance,
+    # docs, .memory and src/config/governance paths. Results are capped at
+    # 5 files and 3 snippets per file to avoid context overflow.
+
+    def ask_knowledge(self, query: str) -> None:
+        """Busca respuestas en gobernanza, docs, memoria y grafo semántico."""
+        _log.info(f"[*] Buscando información sobre: '{query}'...")
+        query_terms = [t.lower() for t in query.split() if t]
+        if not query_terms:
+            _log.warning("[!] La consulta de búsqueda está vacía.")
+            return
+        project_dir = Path(os.getcwd()).resolve()
+        search_paths = [
+            GOVERNANCE_DIR,
+            DOCS_DIR,
+            ROOT_DIR / ".memory",
+            PKG_DATA_DIR / "config" / "governance",
+            project_dir / "src" / "config" / "governance",
+            project_dir / "docs",
+            project_dir / ".memory",
+        ]
+        search_paths = [p for p in search_paths if p.exists()]
+        matches = self._walk_search(search_paths, query_terms, project_dir)
+
+        # Búsqueda en el grafo semántico — proyecto primero, luego Engine
+        graph_path = project_dir / WORKSPACE_DIR_NAME / "state" / "semantic_graph.json"
+        if not graph_path.exists():
+            graph_path = ROOT_DIR / WORKSPACE_DIR_NAME / "state" / "semantic_graph.json"
+        graph_matches = self._search_semantic_graph(graph_path, query_terms, project_dir)
+        if graph_matches:
+            _log.info("\n🔍 Símbolos encontrados en el grafo semántico:")
+            self._print_search_results(graph_matches)
+
+        self._print_search_results(matches)
+
+    # --- Task runner ---
+    # Resolves capability → builds subprocess command → validates contract
+    # → persists result in .memory/ via memory-manager (skipped for itself).
+
+    @staticmethod
+    def _read_session_state(project_root: Path) -> tuple[bool, str | None]:
+        from higpertext.kernel.infrastructure.compilers.playbook_compiler import PlaybookCompiler
+        compiler = PlaybookCompiler(project_root, None, None, None)
+        return compiler._read_session_state()
+
+    @staticmethod
+    def _collect_skill_links(skills_dest: Path, project_root: Path) -> list[str]:
+        from higpertext.kernel.infrastructure.compilers.playbook_compiler import PlaybookCompiler
+        compiler = PlaybookCompiler(project_root, None, None, None)
+        return compiler._collect_skill_links(skills_dest)
+
+    @staticmethod
+    def _collect_subagent_links(subagents_dest: Path, project_root: Path) -> list[str]:
+        from higpertext.kernel.infrastructure.compilers.playbook_compiler import PlaybookCompiler
+        compiler = PlaybookCompiler(project_root, None, None, None)
+        return compiler._collect_subagent_links(subagents_dest)
+
+    def _build_playbook_strings(
+        self,
+        has_session: bool,
+        session_id: str | None,
+        skills_dest: Path,
+        subagents_dest: Path,
+        project_root: Path,
+    ) -> tuple[str, str]:
+        from higpertext.kernel.infrastructure.compilers.playbook_compiler import PlaybookCompiler
+        compiler = PlaybookCompiler(project_root, None, None, None)
+        return compiler._build_playbook_strings(has_session, session_id, skills_dest, subagents_dest)
+
+    def _task_service(self) -> CapabilityTaskService:
+        return CapabilityTaskService(self.engine, ROOT_DIR, PKG_DATA_DIR, _log, _dep)
+
+    # Capability resolution: profile search first, then custom fallback.
+    def _resolve_from_profiles(
+        self, task_name: str, profiles: list[str]
+    ) -> tuple[dict | None, str | None]:
+        return self._task_service().resolve_from_profiles(task_name, profiles)
+
+    def _resolve_custom_capability(self, task_name: str) -> tuple[dict | None, str | None]:
+        return self._task_service().resolve_custom_capability(task_name)
+
+    def _resolve_capability(
+        self, task_name: str, active_profile: str
+    ) -> tuple[dict | None, str | None]:
+        """Busca la capacidad en perfil activo, global y custom."""
+        return self._task_service().resolve_capability(task_name, active_profile)
+
+    @staticmethod
+    def _extra_args(params: dict, prefix: str = "--") -> list[str]:
+        return extra_args(params, prefix)
+
+    def _resolve_entrypoint(self, entrypoint: str, base_dir: str = "") -> Path:
+        """Resuelve el path del entrypoint con prioridad:
+        1. Absoluto y existente → se usa tal cual
+        2. Relativo a base_dir (capabilities custom con _base_dir anotado)
+        3. Relativo a cwd/{WORKSPACE_DIR_NAME}/capabilities/ (extensiones instaladas)
+        4. Relativo a ROOT_DIR/src (capabilities built-in)
+        """
+        return resolve_entrypoint(entrypoint, PKG_DATA_DIR, Path(os.getcwd()), base_dir)
+
+    def _build_cmd(
+        self,
+        entrypoint: str,
+        language: str,
+        params: dict,
+        base_dir: str = "",
+        cap_id: str = "",
+    ) -> list[str]:
+        return build_command(
+            entrypoint,
+            language,
+            params,
+            ROOT_DIR,
+            PKG_DATA_DIR,
+            Path(os.getcwd()),
+            base_dir=base_dir,
+            cap_id=cap_id,
+        )
+
+    def _build_ps_cmd(self, path_to_script: Path, params: dict) -> list[str]:
+        return build_powershell_command(path_to_script, params)
+
+    @staticmethod
+    def _build_memory_notes(
+        task_name: str,
+        params: dict,
+        result: subprocess.CompletedProcess,
+        contract_success: bool,
+        contract_errors: list,
+    ) -> str:
+        return build_memory_notes(task_name, params, result, contract_success, contract_errors)
+
+    def _save_memory(
+        self,
+        task_name: str,
+        params: dict,
+        result: subprocess.CompletedProcess,
+        contract_success: bool,
+        contract_errors: list,
+    ) -> None:
+        self._task_service().save_memory(
+            task_name, params, result, contract_success, contract_errors
+        )
+
+    def _get_active_profile(self) -> str:
+        return self._task_service().get_active_profile()
+
+    @staticmethod
+    def _stream_subprocess(cmd: list[str]) -> subprocess.CompletedProcess:
+        """Ejecuta un subproceso con streaming línea a línea hacia stdout."""
+        import io
+
+        stdout_lines: list[str] = []
+        stderr_lines: list[str] = []
+        try:
+            with subprocess.Popen(  # nosec B603 B607
+                cmd,
+                cwd=os.getcwd(),
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                bufsize=1,
+            ) as proc:
+                # Stream stdout en tiempo real
+                for line in proc.stdout or io.StringIO():
+                    _log.info(line, end="", flush=True)
+                    stdout_lines.append(line)
+                # Captura stderr al cerrar
+                stderr_data = proc.stderr.read() if proc.stderr else ""
+                if stderr_data:
+                    stderr_lines.append(stderr_data)
+                proc.wait()
+                returncode = proc.returncode
+        except OSError as e:
+            return subprocess.CompletedProcess(args=cmd, returncode=1, stdout="", stderr=str(e))
+        return subprocess.CompletedProcess(
+            args=cmd,
+            returncode=returncode,
+            stdout="".join(stdout_lines),
+            stderr="".join(stderr_lines),
+        )
+
+    def _execute_task_cmd(
+        self, task_name: str, target_cap: dict, params: dict, stream: bool = False
+    ) -> subprocess.CompletedProcess:
+        """Construye y ejecuta el comando de la tarea con cache + retry + streaming."""
+        return self._task_service().execute_task_cmd(
+            task_name, target_cap, params, self._stream_subprocess, stream=stream
+        )
+
+    def _validate_contract(
+        self, target_cap: dict, params: dict, result: subprocess.CompletedProcess
+    ) -> tuple[bool, list]:
+        if result.returncode != 0:
+            return True, []
+        return self._task_service().validate_contract(target_cap, params, result)
+
+    @staticmethod
+    def _warn_missing_pat(task_name: str) -> None:
+        CapabilityTaskService(None, ROOT_DIR, PKG_DATA_DIR, _log, _dep).warn_missing_pat(task_name)
+
+    def run_task(
+        self, task_name: str, params: dict, stream: bool = False, no_cache: bool = False
+    ) -> bool:
+        """Ejecuta una capacidad técnica validando el perfil activo."""
+        try:
+            active_profile = self._get_active_profile()
+            target_cap, found_profile = self._resolve_capability(task_name, active_profile)
+            if not target_cap:
+                _log.warning(
+                    f"[!] Capacidad '{task_name}' no disponible para el "
+                    f"perfil '{active_profile.upper()}'."
+                )
+                return False
+            _log.info(f"[*] Capacidad '{task_name}' resuelta: {found_profile.upper()}")
+            validation = _dep("normalize_and_validate_params")(target_cap, params)
+            if not validation.ok:
+                _log.error(f"[ERROR] Parámetros inválidos para '{task_name}':")
+                for err in validation.errors:
+                    _log.info(f"    - {err}")
+                return False
+            for warning in validation.warnings:
+                _log.warning(f"[PARAM] {warning}")
+            params = validation.params
+            self._warn_missing_pat(task_name)
+            _log.info(f"[*] Ejecutando tarea: {task_name}")
+
+            if no_cache:
+                cache = _dep("get_capability_cache")()
+                cache.invalidate(target_cap.get("id", task_name))
+
+            result = self._execute_task_cmd(task_name, target_cap, params, stream=stream)
+            ok, errs = self._validate_contract(target_cap, params, result)
+            status = self._report_task_result(task_name, result, ok, errs)
+            if task_name != "memory-manager":
+                self._save_memory(task_name, params, result, ok, errs)
+            return status
+        except (OSError, ValueError) as e:
+            _log.warning(f"[!] Error inesperado: {e}")
+            return False
+
+    @staticmethod
+    def _print_task_failure(
+        task_name: str,
+        result: subprocess.CompletedProcess,
+        contract_success: bool,
+        contract_errors: list,
+    ) -> None:
+        print_task_failure(task_name, result, contract_success, contract_errors, _log)
+
+    @staticmethod
+    def _report_task_result(
+        task_name: str,
+        result: subprocess.CompletedProcess,
+        contract_success: bool,
+        contract_errors: list,
+    ) -> bool:
+        return report_task_result(task_name, result, contract_success, contract_errors, _log)
+
+    # --- Workflow runner ---
+    # Loads a workflow definition, resolves its parameters from CLI args,
+    # and executes each step in the chain sequentially, aborting on failure
+    # unless the step specifies on_failure != "abort".
+
+    def run_workflow(self, workflow_id: str, cli_params: dict) -> bool:
+        """Ejecuta un flujo de trabajo cargándolo y ejecutando su cadena."""
+        try:
+            workflow = self.engine.workflows.load_workflow(workflow_id)
+        except FileNotFoundError as e:
+            _log.warning(f"[!] {e}")
+            return False
+
+        _log.info(f"[*] Ejecutando flujo: {workflow.get('name', workflow_id)}")
+        params = self._resolve_workflow_params(workflow, cli_params)
+        return self._execute_workflow_chain(workflow.get("execution_chain", []), params)
+
+    def list_workflows_cli(self) -> None:
+        _log.info("[*] Flujos de trabajo disponibles:")
+        for wf in self.engine.workflows.list_workflows():
+            _log.info(f"  - {wf['id']}: {wf['name']} ({wf['description']})")
+
+    @staticmethod
+    def _resolve_workflow_params(workflow: dict, cli_params: dict) -> dict:
+        return resolve_workflow_params(workflow, cli_params)
+
+    def _execute_workflow_chain(self, chain: list, params: dict) -> bool:
+        # --- Feature 2: Parallel Executor ---
+        executor = _dep("ParallelExecutor")(run_task_fn=self.run_task)
+        return executor.execute_chain(
+            chain=chain,
+            params=params,
+            interpolate_fn=self._interpolate_params,
+        )
+
+    def _interpolate_str(self, val: str, resolved_params: dict) -> str:
+        try:
+            return val.format(**resolved_params)
+        except KeyError as e:
+            _log.warning(f"[Warning] Placeholder {e} no provisto: {val}")
+            return val
+
+    def _interpolate_val(self, val: object, resolved_params: dict) -> object:
+        if isinstance(val, str):
+            return self._interpolate_str(val, resolved_params)
+        if isinstance(val, dict):
+            return {k: self._interpolate_val(v, resolved_params) for k, v in val.items()}
+        if isinstance(val, list):
+            return [self._interpolate_val(i, resolved_params) for i in val]
+        return val
+
+    def _interpolate_params(self, step_params: dict, resolved_params: dict) -> dict:
+        return {k: self._interpolate_val(v, resolved_params) for k, v in step_params.items()}
+
+
+# --- CLI subcommand builder helpers ---
+# Each helper registers one logical group of subcommands on the subparser.
+# Split to keep _build_parser() under 30 lines.
+def _add_task_ask_subparsers(subs: argparse.Action) -> None:
+    add_task_ask_subparsers(subs)
+
+
+def _add_profile_init_subparsers(subs: argparse.Action) -> None:
+    add_profile_init_subparsers(subs, _ASSISTANTS)
+
+
+def _add_session_workflow_subparsers(subs: argparse.Action) -> None:
+    add_session_workflow_subparsers(subs, _ASSISTANTS)
+
+
+def _add_health_subparser(subs: argparse.Action) -> None:
+    add_health_subparser(subs)
+
+
+def _add_agent_subparser(subs: argparse.Action) -> None:
+    add_agent_subparser(subs)
+
+
+def _add_roadmap_subparser(subs: argparse.Action) -> None:
+    add_roadmap_subparser(subs)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    return build_parser(_ASSISTANTS)
+
+
+# --- Session lifecycle dispatchers ---
+# Decoupled from HigpertextHub to keep the class focused on orchestration logic.
+def _parse_session_resources(
+    args: argparse.Namespace,
+) -> tuple[list | None, list | None]:
+    return parse_session_resources(args)
+
+
+def _start_session(
+    nexus: "HigpertextHub",
+    session_mgr: "SessionManager",
+    args: argparse.Namespace,
+    default_profile: str,
+    default_assistant: str,
+) -> None:
+    start_session(nexus, session_mgr, args, default_profile, default_assistant)
+
+
+def _dispatch_session(nexus: "HigpertextHub", args: argparse.Namespace) -> None:
+    session_mgr = _dep("SessionManager")(Path.cwd(), ROOT_DIR)
+    assistant, profile = session_mgr.get_assistant_and_profile()
+    if args.action == "start":
+        _dep("_start_session")(nexus, session_mgr, args, profile, assistant)
+    elif args.action == "clean":
+        session_mgr.clean_session()
+        nexus.load_agent_profile(profile, assistant)
+
+
+def _dispatch_workflow(nexus: "HigpertextHub", args: argparse.Namespace) -> None:
+    dispatch_workflow(nexus, args)
+
+
+def _pop_bool_flag(task_args: list[str], flag: str, default: bool) -> tuple[bool, list[str]]:
+    return pop_bool_flag(task_args, flag, default)
+
+
+def _dispatch_task(nexus: "HigpertextHub", args: argparse.Namespace) -> None:
+    dispatch_task(nexus, args)
+
+
+def _dispatch_health(args: argparse.Namespace) -> None:
+    from higpertext.kernel.infrastructure.diagnostics.health import run_health_check
+
+    sys.exit(run_health_check(verbose=getattr(args, "verbose", False)))
+
+
+def _dispatch_doctor(args: argparse.Namespace) -> None:
+    from higpertext.capabilities.common.scripts.doctor import main as doctor_main
+
+    doctor_main(["--json", "true"] if getattr(args, "json", False) else [])
+
+
+def _dispatch_command(
+    nexus: "HigpertextHub", args: argparse.Namespace, parser: argparse.ArgumentParser
+) -> None:
+    """Despacha el subcomando al handler correspondiente."""
+    handlers = {
+        "task": lambda: _dispatch_task(nexus, args),
+        "health": lambda: _dispatch_health(args),
+        "doctor": lambda: _dispatch_doctor(args),
+        "workflow": lambda: _dispatch_non_task(nexus, args),
+        "ask": lambda: _dispatch_non_task(nexus, args),
+        "profile": lambda: _dispatch_non_task(nexus, args),
+        "init": lambda: _dispatch_non_task(nexus, args),
+        "session": lambda: _dispatch_non_task(nexus, args),
+        "roadmap": lambda: _dispatch_non_task(nexus, args),
+        "agent": lambda: _dispatch_non_task(nexus, args),
+    }
+    handler = handlers.get(args.command)
+    if handler is None:
+        parser.print_help()
+        return
+    handler()
+
+
+def _dispatch_roadmap(args: argparse.Namespace) -> None:
+    """Gestiona roadmaps en .higpertext/config/roadmaps/."""
+    dispatch_roadmap(args, _log)
+
+
+def _dispatch_profile_learn(args: argparse.Namespace) -> None:
+    """Extrae patrones, calibra pesos y actualiza learned_profile.json."""
+    dispatch_profile_learn(args, ROOT_DIR)
+
+
+def _dispatch_profile_validate(nexus: "HigpertextHub", args: argparse.Namespace) -> None:
+    dispatch_profile_validate(nexus, args, _log)
+
+
+def _dispatch_agent_register(args: argparse.Namespace) -> None:
+    dispatch_agent_register(args, _log, ROOT_DIR)
+
+
+def _dispatch_agent_sync(args: argparse.Namespace) -> None:
+    dispatch_agent_sync(args, _log, ROOT_DIR)
+
+
+def _dispatch_agent_list() -> None:
+    dispatch_agent_list(_log, ROOT_DIR)
+
+
+def _dispatch_agent(nexus: "HigpertextHub", args: argparse.Namespace) -> None:
+    dispatch_agent(nexus, args, _log, ROOT_DIR)
+
+
+def _dispatch_non_task(nexus: "HigpertextHub", args: argparse.Namespace) -> None:
+    handlers = {
+        "workflow": lambda: _dispatch_workflow(nexus, args),
+        "ask": lambda: nexus.ask_knowledge(args.query),
+        "profile": lambda: dispatch_profile(nexus, args, _log, ROOT_DIR),
+        "init": lambda: nexus.init_project(args.profile, args.assistant, args.target),
+        "agent": lambda: _dispatch_agent(nexus, args),
+        "roadmap": lambda: _dispatch_roadmap(args),
+        "session": lambda: _dispatch_session(nexus, args),
+    }
+    handlers[args.command]()
+
+
+def main() -> None:
+    """Punto de entrada del CLI de higpertext Engine."""
+    parser = _build_parser()
+    args = parser.parse_args()
+    _dispatch_command(HigpertextHub(), args, parser)