higpertext-cli 0.8.0__py3-none-any.whl

higpertext/capabilities/capabilities_runner.py

@@ -0,0 +1,216 @@
+"""Dispatcher único para todas las capabilities de higpertext."""
+
+import sys
+import importlib
+import importlib.util
+import json
+from pathlib import Path
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+# Asegurar que src/ esté en el path para importar higpertext.*
+_runner_dir = Path(__file__).resolve().parent.parent.parent  # src/
+if str(_runner_dir) not in sys.path:
+    sys.path.insert(0, str(_runner_dir))
+
+_CAPABILITIES_ROOT = Path(__file__).resolve().parent
+_PROJECT_EXTERNAL_CAPS = Path.cwd() / WORKSPACE_DIR_NAME / "capabilities"
+
+
+_MODULE_MAP = {
+    "git.committer": "higpertext.capabilities.git.scripts.commit_changes",
+    "git.diff": "higpertext.capabilities.git.scripts.git_diff",
+    "git.ls-files": "higpertext.capabilities.git.scripts.git_ls_files",
+    "git.rm": "higpertext.capabilities.git.scripts.git_rm",
+    "common.agent-builder": "higpertext.capabilities.common.scripts.agent_builder",
+    "common.agent-sync": "higpertext.capabilities.common.scripts.agent_sync",
+    "common.agile-planner": "higpertext.capabilities.common.scripts.agile_planner",
+    "common.architecture-drift-report": "higpertext.capabilities.common.scripts.architecture_drift_report", # noqa: E501
+    "common.code-skeletonizer": "higpertext.capabilities.common.scripts.code_skeletonizer",
+    "common.commit-rationale-log": "higpertext.capabilities.common.scripts.commit_rationale_log",
+    "common.commit-report": "higpertext.capabilities.common.scripts.commit_report",
+    "common.context-assembler": "higpertext.capabilities.common.scripts.context_assembler",
+    "common.context-budget-report": "higpertext.capabilities.common.scripts.context_budget_report",
+    "common.dep-manager": "higpertext.capabilities.common.scripts.dep_manager",
+    "common.diff-reviewer": "higpertext.capabilities.common.scripts.diff_reviewer",
+    "common.docs-sync": "higpertext.capabilities.common.scripts.docs_sync",
+    "common.doctor": "higpertext.capabilities.common.scripts.doctor",
+    "common.efficiency-meter": "higpertext.capabilities.common.scripts.efficiency_meter",
+    "common.env-catalog": "higpertext.capabilities.common.scripts.env_catalog",
+    "common.env-clean": "higpertext.capabilities.common.scripts.env_clean",
+    "common.env-logs": "higpertext.capabilities.common.scripts.env_logs",
+    "common.env-runner": "higpertext.capabilities.common.scripts.env_runner",
+    "common.env-status": "higpertext.capabilities.common.scripts.env_status",
+    "common.env-stop": "higpertext.capabilities.common.scripts.env_stop",
+    "common.env-template": "higpertext.capabilities.common.scripts.env_template",
+    "common.eval-agent": "higpertext.capabilities.common.scripts.eval_agent",
+    "common.error-context-locator": "higpertext.capabilities.common.scripts.error_context_locator",
+    "common.file-map": "higpertext.capabilities.common.scripts.file_map",
+    "common.governance-enforcer": "higpertext.capabilities.common.scripts.governance_enforcer",
+    "common.governance-exception": "higpertext.capabilities.common.scripts.governance_exception",
+    "common.graph-query": "higpertext.capabilities.common.scripts.graph_query",
+    "common.graph-rebuild": "higpertext.capabilities.common.scripts.graph_rebuild",
+    "common.graph-visualize": "higpertext.capabilities.common.scripts.graph_visualize",
+    "common.grep-search": "higpertext.capabilities.common.scripts.grep_search",
+    "common.hook-health": "higpertext.capabilities.common.scripts.hook_health",
+    "common.hook-sync-check": "higpertext.capabilities.common.scripts.hook_sync_check",
+    "common.guidelines-sync": "higpertext.capabilities.common.scripts.guidelines_sync",
+    "common.hooks-manager": "higpertext.capabilities.common.scripts.hooks_manager",
+    "common.html-presentation": "higpertext.capabilities.common.scripts.presentation_engine",
+    "common.knowledge-asker": "higpertext.capabilities.common.scripts.ask_higpertext",
+    "common.list-rules": "higpertext.capabilities.common.scripts.list_rules",
+    "common.llm-invoke": "higpertext.capabilities.common.scripts.llm_invoke",
+    "common.load-rules": "higpertext.capabilities.common.scripts.load_rules",
+    "common.memory-manager": "higpertext.capabilities.common.scripts.memory_manager",
+    "common.higpertext-tester": "higpertext.capabilities.common.scripts.higpertext_tester",
+    "common.mass-integrator": "higpertext.capabilities.common.scripts.mass_integrator",
+    "common.quality-updater": "higpertext.capabilities.common.scripts.quality_resolver",
+    "common.quality-scan": "higpertext.capabilities.common.scripts.quality_scan",
+    "common.report-viewer": "higpertext.capabilities.common.scripts.report_viewer",
+    "common.roadmap-report": "higpertext.capabilities.common.scripts.roadmap_report",
+    "common.semantic-diff": "higpertext.capabilities.common.scripts.semantic_diff",
+    "common.search-router": "higpertext.capabilities.common.scripts.search_router",
+    "common.session-clean": "higpertext.capabilities.common.scripts.session_control",
+    "common.session-start": "higpertext.capabilities.common.scripts.session_control",
+    "common.subagent-executor": "higpertext.capabilities.common.scripts.subagent_executor",
+    "common.smart-read": "higpertext.capabilities.common.scripts.smart_read",
+    "common.sync-agents": "higpertext.capabilities.common.scripts.sync_agents",
+    "common.task-decomposer": "higpertext.capabilities.common.scripts.task_decomposer",
+    "common.telemetry-report": "higpertext.capabilities.common.scripts.telemetry_report",
+    "common.wiki-manager": "higpertext.capabilities.common.scripts.wiki_manager",
+    "security.secret-scanner": "higpertext.capabilities.security.scripts.secret_scanner",
+}
+
+
+class CapabilityModuleRegistry:
+    """Registry que resuelve módulos de capabilities por estrategia de carga."""
+
+    def __init__(self, module_map: dict[str, str]):
+        self._module_map = module_map
+
+    def load(self, cap_id: str):
+        dynamic_module = _load_dynamic_module(cap_id)
+        if dynamic_module is not None:
+            return dynamic_module
+        module_path = self._module_map.get(cap_id)
+        if module_path:
+            return importlib.import_module(module_path)
+        return _load_legacy_external_module(cap_id)
+
+
+_REGISTRY = CapabilityModuleRegistry(_MODULE_MAP)
+
+
+def _load_json(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _candidate_capability_jsons(cap_id: str) -> list[Path]:
+    namespace, _, short_name = cap_id.partition(".")
+    if not short_name:
+        namespace, short_name = "common", cap_id
+    return [
+        _CAPABILITIES_ROOT / namespace / f"{short_name}.json",
+        _PROJECT_EXTERNAL_CAPS / namespace / f"{short_name}.json",
+    ]
+
+
+def _resolve_capability_definition(cap_id: str) -> dict:
+    for path in _candidate_capability_jsons(cap_id):
+        data = _load_json(path)
+        if data and data.get("id", cap_id) == cap_id:
+            data["_definition_path"] = str(path)
+            return data
+    return {}
+
+
+def _resolve_entrypoint_path(definition: dict) -> Path | None:
+    entrypoint = definition.get("entrypoint", "")
+    if not entrypoint:
+        return None
+    if entrypoint.startswith(("python ", "python3 ")):
+        entrypoint = entrypoint.split(maxsplit=1)[1]
+    raw = Path(entrypoint)
+    if raw.is_absolute() and raw.exists():
+        return raw
+    definition_path = Path(definition.get("_definition_path", ""))
+    bases = [
+        _runner_dir / entrypoint,
+        _CAPABILITIES_ROOT.parent / entrypoint,
+        Path.cwd() / entrypoint,
+    ]
+    if definition_path:
+        bases.append(definition_path.parents[1] / entrypoint)
+    return next((path for path in bases if path.exists()), None)
+
+
+def _module_from_script(script_path: Path):
+    module_name = f"higpertext_dynamic_{script_path.stem}"
+    sys.path.insert(0, str(script_path.parent))
+    spec = importlib.util.spec_from_file_location(module_name, script_path)
+    if not spec or not spec.loader:
+        raise ImportError(f"No se pudo cargar entrypoint: {script_path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def _load_dynamic_module(cap_id: str):
+    definition = _resolve_capability_definition(cap_id)
+    if not definition:
+        return None
+    if definition.get("language", "python") != "python":
+        return None
+    script_path = _resolve_entrypoint_path(definition)
+    if not script_path:
+        raise FileNotFoundError(
+            f"Entrypoint no encontrado para {cap_id}: {definition.get('entrypoint')}"
+        )
+    return _module_from_script(script_path)
+
+
+def _load_legacy_external_module(cap_id: str):
+    cap_stem = cap_id.split(".")[-1].replace("-", "_")
+    cap_namespace = cap_id.split(".")[0] if "." in cap_id else "common"
+    external_script = _PROJECT_EXTERNAL_CAPS / cap_namespace / "scripts" / f"{cap_stem}.py"
+    if not external_script.exists():
+        return None
+    return _module_from_script(external_script)
+
+
+def _load_module(cap_id: str):
+    return _REGISTRY.load(cap_id)
+
+
+def main():
+    if len(sys.argv) < 2:
+        _log.info("Usage: capabilities_runner.py <capability-id> [--param value ...]")
+        sys.exit(1)
+
+    cap_id = sys.argv[1]
+    sys.argv = [sys.argv[0]] + sys.argv[2:]
+
+    try:
+        module = _load_module(cap_id)
+    except (FileNotFoundError, ImportError) as exc:
+        _log.error(f"[ERROR] {exc}")
+        sys.exit(1)
+    if module is None:
+        _log.error(f"[ERROR] Capability no registrada en dispatcher: {cap_id}")
+        sys.exit(1)
+    import inspect
+
+    sig = inspect.signature(module.main)
+    if sig.parameters:
+        module.main(sys.argv[1:])
+    else:
+        module.main()
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/agent-builder.json

@@ -0,0 +1,54 @@
+{
+    "id": "common.agent-builder",
+    "version": "1.0.0",
+    "name": "Agent Builder",
+    "description": "Crea la estructura base de un nuevo agente higpertext independiente: scaffolding de carpetas, perfil inicial, htx.py launcher y ambiente .higpertext/ compilado. El agente generado usa el motor central sin copiar src/core/.",
+    "entrypoint": "capabilities/common/scripts/agent_builder.py",
+    "language": "python",
+    "parameters": [
+        {
+            "name": "profile",
+            "description": "Nombre del perfil inicial del agente (ej: content_creator). No puede ser un nombre reservado del motor.",
+            "required": true
+        },
+        {
+            "name": "target",
+            "description": "Ruta del directorio donde se creará el agente. Si no existe, se crea automáticamente.",
+            "required": true
+        },
+        {
+            "name": "description",
+            "description": "Descripción del agente para incluir en el perfil generado.",
+            "required": false,
+            "default": ""
+        }
+    ],
+    "contract": {
+        "rules": [
+            "Debe crear src/capabilities/, src/config/profiles/, src/config/governance/, src/config/environments/, src/config/templates/, src/workflows/, src/hooks/profiles/, src/hooks/custom/, content/.",
+            "Debe copiar agent_designer.json al directorio de perfiles del agente.",
+            "Debe generar htx.py launcher apuntando al motor central — nunca copiar src/core/.",
+            "Debe rechazar nombres de perfil reservados: base_agent, agent_designer, global, base_developer, base_operator, base_auditor.",
+            "Debe compilar las capas de hooks en .higpertext/config/hooks_config.json.",
+            "Debe generar el grafo semántico en .higpertext/state/semantic_graph.md.",
+            "Debe ser idempotente: no sobreescribir htx.py ni src/hooks/custom/ si ya existen.",
+            "El output debe indicar claramente la ruta del agente creado y el comando de verificación."
+        ],
+        "success_pattern": "\\[SUCCESS\\] Agente listo en:"
+    },
+    "examples": [
+        {
+            "description": "Crear un agente de análisis de datos",
+            "command": "htx task common.agent-builder --profile data_analyst --target ../data-analyst-agent"
+        },
+        {
+            "description": "Crear un agente con descripción",
+            "command": "htx task common.agent-builder --profile sre_bot --target ../sre-agent --description \"Agente SRE para monitoreo y alertas\""
+        }
+    ],
+    "related_docs": [
+        "docs/03-extending/agent-development.md",
+        "docs/03-extending/agent-hooks.md",
+        "docs/04-reference/agent-cli.md"
+    ]
+}

higpertext/capabilities/common/agent-sync.json

@@ -0,0 +1,34 @@
+{
+  "id": "common.agent-sync",
+  "version": "1.0.0",
+  "description": "Registra y sincroniza agentes externos con el motor higpertext: propaga hooks y perfiles actualizados.",
+  "entrypoint": "src/capabilities/common/scripts/agent_sync.py",
+  "parameters": [
+    {
+      "name": "action",
+      "description": "Acción: register | sync | list",
+      "required": true
+    },
+    {
+      "name": "name",
+      "description": "Nombre del agente",
+      "required": false
+    },
+    {
+      "name": "path",
+      "description": "Ruta absoluta al agente externo (para register)",
+      "required": false
+    },
+    {
+      "name": "profile",
+      "description": "Nombre del perfil del agente (para register)",
+      "required": false
+    },
+    {
+      "name": "assistant",
+      "description": "Asistente objetivo: claude|gemini|opencode|all (para sync)",
+      "default": "claude",
+      "required": false
+    }
+  ]
+}

higpertext/capabilities/common/code-skeletonizer.json

@@ -0,0 +1,35 @@
+{
+    "id": "common.code-skeletonizer",
+    "version": "1.0.0",
+    "name": "Code Skeletonizer",
+    "description": "Genera una versión 'esqueleto' de un archivo de código fuente (especialmente Python mediante AST, y otros lenguajes mediante expresiones regulares), extrayendo solo firmas de clases, funciones/métodos, docstrings e imports, omitiendo el código de implementación para ahorrar tokens de contexto.",
+    "entrypoint": "capabilities/common/scripts/code_skeletonizer.py",
+    "language": "python",
+    "parameters": [
+        {
+            "name": "path",
+            "description": "Ruta absoluta o relativa del archivo de código a esqueletizar.",
+            "required": true
+        },
+        {
+            "name": "output",
+            "description": "Ruta de destino opcional para guardar el archivo esqueletizado. Si no se especifica, se imprime en consola.",
+            "required": false
+        }
+    ],
+    "bash_intercept": {
+        "pattern": "\\bwc\\s+-l\\b|\\bfind\\s+.*\\.(py|ts|js|cs)\\b",
+        "description": "Explorar estructura de archivos de código",
+        "reason": "wc/find produce listas brutas. code-skeletonizer extrae firmas, clases e imports ahorrando tokens de contexto.",
+        "example": "htx task common.code-skeletonizer --path src/my_module.py"
+    },
+    "contract": {
+        "rules": [
+            "Debe validar que el archivo de entrada exista.",
+            "Debe extraer imports, nombres de clases, docstrings y firmas de métodos/funciones.",
+            "Debe reemplazar la implementación interna de métodos y funciones por el token '...'.",
+            "Para Python debe utilizar la biblioteca 'ast' para un parsing sintáctico robusto.",
+            "Debe imprimir en la salida estándar la representación del esqueleto si no se especifica un archivo de salida."
+        ]
+    }
+}

higpertext/capabilities/common/commit-report.json

@@ -0,0 +1,42 @@
+{
+    "id": "common.commit-report",
+    "version": "1.0.0",
+    "name": "Commit Report Explicativo",
+    "description": "Genera un reporte explicativo de un commit o rango de commits: resumen en lenguaje natural, archivos impactados por capa DDD, estadísticas y análisis de impacto. Soporta salida Markdown y HTML.",
+    "entrypoint": "capabilities/common/scripts/commit_report.py",
+    "language": "python",
+    "parameters": [
+        {
+            "name": "commit",
+            "description": "Hash del commit a analizar. Acepta HEAD, HEAD~N o hash corto. Default: HEAD.",
+            "required": false,
+            "default": "HEAD"
+        },
+        {
+            "name": "range",
+            "description": "Rango de commits en formato git (e.g. HEAD~5..HEAD). Si se especifica, sobreescribe --commit.",
+            "required": false
+        },
+        {
+            "name": "format",
+            "description": "Formato de salida: markdown o html. Default: markdown.",
+            "required": false,
+            "default": "markdown"
+        },
+        {
+            "name": "output",
+            "description": "Ruta de salida del reporte. Default: .higpertext/reports/commits/<hash>_report.<ext>.",
+            "required": false
+        }
+    ],
+    "contract": {
+        "rules": [
+            "Debe leer el historial git real del repositorio.",
+            "Debe mostrar resumen ejecutivo en lenguaje natural.",
+            "Debe agrupar archivos impactados por capa: domain, application, infrastructure, test, capability, other.",
+            "Debe mostrar estadísticas: archivos cambiados, líneas añadidas, líneas eliminadas.",
+            "Debe indicar si el commit incluye nuevos tests o nuevas capacidades.",
+            "Debe completar con [SUCCESS] o [ERROR] explícito."
+        ]
+    }
+}

higpertext/capabilities/common/context-assembler.json

@@ -0,0 +1,37 @@
+{
+    "id": "common.context-assembler",
+    "version": "1.0.0",
+    "name": "Context Assembler",
+    "description": "Ensambla un 'context pack' curado para una tarea concreta. Dado un objetivo y tipo, extrae keywords, selecciona del semantic graph solo los símbolos relevantes bajo un presupuesto de tokens, y genera un artefacto Markdown en .higpertext/state/context_packs/. Provee al agente el contexto mínimo-suficiente en vez de explorar el repo a ciegas.",
+    "entrypoint": "capabilities/common/scripts/context_assembler.py",
+    "language": "python",
+    "parameters": [
+        {
+            "name": "goal",
+            "description": "Objetivo de la tarea en lenguaje natural, ej: 'refactorizar el sistema de hooks de sesión'.",
+            "required": true
+        },
+        {
+            "name": "type",
+            "description": "Tipo de tarea: refactor|feature|bugfix|review. Default: feature.",
+            "required": false,
+            "default": "feature"
+        },
+        {
+            "name": "budget",
+            "description": "Presupuesto máximo de tokens del pack. Default: 8000.",
+            "required": false,
+            "default": "8000"
+        }
+    ],
+    "contract": {
+        "rules": [
+            "Debe extraer keywords del objetivo filtrando stopwords (ES/EN).",
+            "Debe seleccionar símbolos del semantic graph relevantes a los keywords.",
+            "El pack generado nunca debe exceder el presupuesto de tokens indicado.",
+            "Debe persistir el artefacto Markdown en .higpertext/state/context_packs/.",
+            "Debe reportar el número de símbolos seleccionados y los tokens estimados.",
+            "Si el semantic graph no existe, debe generar un pack vacío sin fallar."
+        ]
+    }
+}

higpertext/capabilities/common/context-budget-report.json

@@ -0,0 +1,15 @@
+{
+  "id": "common.context-budget-report",
+  "version": "1.0.0",
+  "name": "Context Budget Report",
+  "description": "Estima cuánto contexto consume una lectura, búsqueda o skeleton antes de ejecutarla y recomienda read range, skeleton, summary o grep.",
+  "entrypoint": "capabilities/common/scripts/context_budget_report.py",
+  "language": "python",
+  "parameters": [
+    {"name": "path", "description": "Archivo a estimar.", "required": true},
+    {"name": "operation", "description": "read, search o skeleton. Default: read.", "required": false, "default": "read"},
+    {"name": "budget", "description": "Presupuesto de tokens. Default: 4000.", "required": false, "default": "4000"},
+    {"name": "json", "description": "Emite JSON estructurado.", "required": false, "default": "false"}
+  ],
+  "contract": {"rules": ["Debe estimar tokens por tamaño de archivo.", "Debe recomendar una estrategia de contexto antes de leer blobs grandes.", "Debe soportar JSON."]}
+}

higpertext/capabilities/common/dep-manager.json

@@ -0,0 +1,43 @@
+{
+    "id": "common.dep-manager",
+    "version": "1.0.0",
+    "name": "Dependency Manager",
+    "description": "Gestiona dependencias del proyecto: instala, desinstala y lista paquetes usando el .venv activo. Valida que no se instale en el Python del sistema.",
+    "entrypoint": "capabilities/common/scripts/dep_manager.py",
+    "language": "python",
+    "parameters": [
+        {
+            "name": "action",
+            "type": "string",
+            "required": true,
+            "description": "Acción: install | uninstall | list"
+        },
+        {
+            "name": "packages",
+            "type": "string",
+            "required": false,
+            "description": "Paquete(s) separados por coma (requerido para install/uninstall)"
+        },
+        {
+            "name": "dev",
+            "type": "string",
+            "required": false,
+            "default": "false",
+            "description": "Si 'true', instala como dependencia de desarrollo"
+        }
+    ],
+    "contract": {
+        "rules": [
+            "Siempre usar .venv/bin/pip — nunca el pip del sistema.",
+            "Nunca instalar como root o con sudo.",
+            "Después de instalar, actualizar requirements.txt si existe."
+        ],
+        "required_patterns": ["\\[SUCCESS\\]"]
+    },
+    "bash_intercept": {
+        "pattern": "\\bpip\\s+(install|uninstall|freeze)\\b",
+        "description": "Gestionar dependencias del proyecto",
+        "reason": "pip directo puede instalar en el Python del sistema. dep-manager garantiza el uso del .venv del proyecto y actualiza requirements.txt.",
+        "example": "htx task common.dep-manager --action install --packages requests"
+    }
+}

higpertext/capabilities/common/docs-sync.json

@@ -0,0 +1,14 @@
+{
+    "id": "common.docs-sync",
+    "version": "1.0.0",
+    "description": "Analiza recursivamente todas las capacidades y perfiles JSON, regenera y actualiza automáticamente los archivos de catálogo de la documentación (capabilities-catalog.md y profiles-catalog.md).",
+    "entrypoint": "capabilities/common/scripts/docs_sync.py",
+    "language": "python",
+    "parameters": [],
+    "contract": {
+        "rules": [
+            "Actualizar docs/reference/capabilities-catalog.md con todas las capacidades encontradas.",
+            "Actualizar docs/reference/profiles-catalog.md con todos los perfiles de agente encontrados."
+        ]
+    }
+}

higpertext/capabilities/common/doctor.json

@@ -0,0 +1,18 @@
+{
+  "id": "common.doctor",
+  "version": "1.0.0",
+  "name": "Higpertext Doctor",
+  "description": "Ejecuta un diagnóstico integral del workspace: launcher, entorno, capabilities, hooks, caché y reportes.",
+  "entrypoint": "capabilities/common/scripts/doctor.py",
+  "language": "python",
+  "parameters": [
+    {"name": "json", "description": "Emite JSON estructurado.", "required": false, "default": "false"}
+  ],
+  "contract": {
+    "rules": [
+      "Debe validar launcher htx disponible.",
+      "Debe validar catálogo de capabilities y hooks críticos.",
+      "Debe revisar estado básico de caché y reportes."
+    ]
+  }
+}

higpertext/capabilities/common/efficiency-meter.json

@@ -0,0 +1,31 @@
+{
+    "id": "common.efficiency-meter",
+    "version": "1.0.0",
+    "name": "Efficiency Meter",
+    "description": "Mide la eficiencia de una sesión de agente cruzando telemetry.jsonl con los context packs generados. Calcula: tokens totales, costo estimado, exploration_waste_ratio (lecturas sin higpertext / total reads), context_hit_rate (archivos del pack realmente leídos) y hook_intercepts. Retroalimenta la calidad de los context packs.",
+    "entrypoint": "capabilities/common/scripts/efficiency_meter.py",
+    "language": "python",
+    "parameters": [
+        {
+            "name": "session",
+            "description": "ID de sesión a analizar. Si no se indica, usa la sesión activa.",
+            "required": false,
+            "default": ""
+        },
+        {
+            "name": "format",
+            "description": "Formato de salida: table|json|markdown. Default: table.",
+            "required": false,
+            "default": "table"
+        }
+    ],
+    "contract": {
+        "rules": [
+            "Si no se indica --session, debe leer la sesión activa de .higpertext/state/session.json.",
+            "context_hit_rate debe estar en el rango [0, 1].",
+            "exploration_waste_ratio debe estar en el rango [0, 1].",
+            "Si no hay eventos de telemetría para la sesión, debe devolver métricas en cero sin fallar.",
+            "El formato 'json' debe producir JSON válido serializable."
+        ]
+    }
+}

higpertext/capabilities/common/env-catalog.json

@@ -0,0 +1,13 @@
+{
+  "id": "common.env-catalog",
+  "version": "1.0.0",
+  "name": "Environment Catalog",
+  "description": "Lista templates locales/globales de entornos Docker/Podman y detecta motores disponibles.",
+  "entrypoint": "capabilities/common/scripts/env_catalog.py",
+  "language": "python",
+  "parameters": [
+    {"name": "engine", "description": "auto, docker o podman. Default: auto.", "required": false, "default": "auto"},
+    {"name": "json", "description": "Emite JSON estructurado.", "required": false, "default": "false"}
+  ],
+  "contract": {"rules": ["Debe listar templates de .higpertext/env/templates y templates del motor.", "Debe reportar disponibilidad Docker/Podman.", "Debe soportar JSON."]}
+}

higpertext/capabilities/common/env-clean.json

@@ -0,0 +1,14 @@
+{
+  "id": "common.env-clean",
+  "version": "1.0.0",
+  "name": "Environment Clean",
+  "description": "Limpia metadata local de runs finalizados o todos los runs si --all=true.",
+  "entrypoint": "capabilities/common/scripts/env_clean.py",
+  "language": "python",
+  "parameters": [
+    {"name": "all", "description": "Elimina todos los runs locales. Default: false.", "required": false, "default": "false"},
+    {"name": "older_than", "description": "Reservado para limpieza por antigüedad.", "required": false},
+    {"name": "json", "description": "Emite JSON estructurado.", "required": false, "default": "false"}
+  ],
+  "contract": {"rules": ["Debe limpiar .higpertext/env/runs según estado.", "No debe ejecutar comandos destructivos fuera del directorio de runs."]}
+}

higpertext/capabilities/common/env-logs.json

@@ -0,0 +1,16 @@
+{
+  "id": "common.env-logs",
+  "version": "1.0.0",
+  "name": "Environment Logs",
+  "description": "Obtiene logs compactos de un run Docker/Podman, con filtros por servicio, tail y errores.",
+  "entrypoint": "capabilities/common/scripts/env_logs.py",
+  "language": "python",
+  "parameters": [
+    {"name": "run_id", "description": "Run a consultar.", "required": true},
+    {"name": "service", "description": "Servicio opcional.", "required": false},
+    {"name": "tail", "description": "Cantidad de líneas. Default: 200.", "required": false, "default": "200"},
+    {"name": "errors_only", "description": "Filtra líneas con error/failed/exception.", "required": false, "default": "false"},
+    {"name": "json", "description": "Emite JSON estructurado.", "required": false, "default": "false"}
+  ],
+  "contract": {"rules": ["Debe usar el backend del run persistido.", "Debe limitar logs con tail.", "Debe soportar errors_only."]}
+}

higpertext/capabilities/common/env-runner.json

@@ -0,0 +1,23 @@
+{
+  "id": "common.env-runner",
+  "version": "1.0.0",
+  "name": "Environment Runner",
+  "description": "Levanta un entorno local Docker/Podman desde template, ejecuta una tarea/comando y persiste estado/logs por run_id.",
+  "entrypoint": "capabilities/common/scripts/env_runner.py",
+  "language": "python",
+  "parameters": [
+    {"name": "template", "description": "ID del template a ejecutar.", "required": true},
+    {"name": "engine", "description": "auto, docker o podman.", "required": false, "default": "auto"},
+    {"name": "task", "description": "Tarea definida por el template.", "required": false},
+    {"name": "command", "description": "Comando override a ejecutar dentro del servicio.", "required": false},
+    {"name": "service", "description": "Servicio donde ejecutar el comando.", "required": false},
+    {"name": "detach", "description": "Si true deja el entorno corriendo.", "required": false, "default": "false"},
+    {"name": "parallel", "description": "Reservado; cada run ya usa project_name único.", "required": false, "default": "false"},
+    {"name": "timeout", "description": "Timeout en segundos. Default: 300.", "required": false, "default": "300"},
+    {"name": "keep_alive", "description": "No ejecutar down al terminar.", "required": false, "default": "false"},
+    {"name": "cleanup", "description": "Ejecutar down al terminar si no keep_alive. Default: true.", "required": false, "default": "true"},
+    {"name": "env", "description": "Variables KEY=value separadas por coma.", "required": false},
+    {"name": "json", "description": "Emite JSON estructurado.", "required": false, "default": "false"}
+  ],
+  "contract": {"rules": ["Debe seleccionar Docker o Podman mediante --engine.", "Debe crear run_id y estado bajo .higpertext/env/runs.", "Debe capturar logs de up/command/down.", "Debe aplicar timeout y cleanup por defecto."]}
+}

higpertext/capabilities/common/env-status.json

@@ -0,0 +1,13 @@
+{
+  "id": "common.env-status",
+  "version": "1.0.0",
+  "name": "Environment Status",
+  "description": "Consulta runs de entornos locales ejecutados por env-runner.",
+  "entrypoint": "capabilities/common/scripts/env_status.py",
+  "language": "python",
+  "parameters": [
+    {"name": "run_id", "description": "Run específico; si se omite lista todos.", "required": false},
+    {"name": "json", "description": "Emite JSON estructurado.", "required": false, "default": "false"}
+  ],
+  "contract": {"rules": ["Debe leer .higpertext/env/runs.", "Debe soportar consulta por run_id y listado general."]}
+}