higpertext-cli 0.8.0__py3-none-any.whl

higpertext/capabilities/common/scripts/docs_sync.py

@@ -0,0 +1,981 @@
+"""higpertext Docs Sync — regenera documentación completa en docs/reference/ y docs/guides/."""
+
+import json
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+from higpertext.kernel.app_config import INDEX_LINK as _INDEX_LINK
+_log = get_logger()
+
+
+def _resolve_project_root(start: Path | None = None) -> Path:
+    """Encuentra la raíz del proyecto que contiene capacidades y perfiles fuente."""
+    current = (start or Path.cwd()).resolve()
+    if current.is_file():
+        current = current.parent
+    for candidate in (current, *current.parents):
+        capabilities = candidate / "src" / "higpertext" / "capabilities"
+        profiles = candidate / "src" / "config" / "profiles"
+        if capabilities.exists() and profiles.exists():
+            return candidate
+    return current
+
+
+def _load_governance(project_root: Path) -> dict:
+    path = project_root / "src" / "config" / "governance" / "guidelines_contract.json"
+    if path.exists():
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):  # nosec B110
+            pass
+    return {}
+
+
+# ---------------------------------------------------------------------------
+# Loaders
+# ---------------------------------------------------------------------------
+
+
+def _load_capabilities(capabilities_dir: Path) -> tuple[list, dict]:
+    capabilities, cap_dict = [], {}
+    for json_file in capabilities_dir.rglob("*.json"):
+        try:
+            data = json.loads(json_file.read_text(encoding="utf-8"))
+            cap_id = data.get("id")
+            if cap_id:
+                capabilities.append(data)
+                cap_dict[cap_id] = data.get("description", "Sin descripción")
+        except (OSError, json.JSONDecodeError) as e:
+            _log.warning(f"[!] Error leyendo capacidad {json_file.name}: {e}")
+    capabilities.sort(key=lambda x: x.get("id", ""))
+    return capabilities, cap_dict
+
+
+def _load_profiles(profiles_dir: Path) -> list:
+    profiles = []
+    for json_file in profiles_dir.glob("*.json"):
+        try:
+            data = json.loads(json_file.read_text(encoding="utf-8"))
+            if data.get("name"):
+                profiles.append(data)
+        except (OSError, json.JSONDecodeError) as e:
+            _log.warning(f"[!] Error leyendo perfil {json_file.name}: {e}")
+    return sorted(profiles, key=lambda x: x.get("name", ""))
+
+
+def _group_by_area(capabilities: list) -> dict:
+    areas: dict = {}
+    for cap in capabilities:
+        cap_id = cap.get("id", "")
+        area = cap_id.split(".")[0] if "." in cap_id else "global"
+        areas.setdefault(area, []).append(cap)
+    return areas
+
+
+# ---------------------------------------------------------------------------
+# Reference: capabilities-catalog.md
+# ---------------------------------------------------------------------------
+
+
+def _render_cap_entry(cap: dict) -> list[str]:
+    cap_id = cap.get("id", "")
+    description = cap.get("description", "Sin descripción.")
+    entrypoint = cap.get("entrypoint", "N/A")
+    params = cap.get("parameters", [])
+    rules = cap.get("contract", {}).get("rules", [])
+    intercept = cap.get("bash_intercept")
+
+    lines = [
+        f"### `{cap_id}`",
+        f"**Propósito**: {description}",
+        "",
+        f"- **Entrypoint**: `{entrypoint}`",
+    ]
+
+    if params:
+        lines += [
+            "- **Parámetros**:",
+            "  | Parámetro | Requerido | Descripción |",
+            "  |---|---|---|",
+        ]
+        for p in params:
+            req = "Sí" if p.get("required") else "No"
+            lines.append(f"  | `--{p['name']}` | {req} | {p.get('description', '')} |")
+    else:
+        lines.append("- **Parámetros**: No requiere parámetros.")
+
+    if rules:
+        lines.append("- **Contrato técnico**:")
+        for rule in rules:
+            lines.append(f"  - {rule}")
+
+    if intercept:
+        lines += [
+            "- **Hook de intercepción bash**:",
+            f"  - Patrón: `{intercept.get('pattern', '')}`",
+            f"  - Acción: {intercept.get('description', '')}",
+            f"  - Comando correcto: `{intercept.get('example', '')}`",
+        ]
+
+    lines += ["", "---", ""]
+    return lines
+
+
+def _build_capabilities_catalog(capabilities: list, areas: dict) -> list[str]:
+    total_caps = len(capabilities)
+    areas_list = ", ".join(f"`{a}`" for a in sorted(areas.keys()))
+    intercepted = [c for c in capabilities if c.get("bash_intercept")]
+
+    lines = [
+        "# Catálogo de Capacidades",
+        "",
+        "Referencia técnica exhaustiva de cada capacidad del higpertext Engine.",
+        "",
+        f"**Total**: {total_caps} capacidades | **Áreas**: {areas_list}",
+        "",
+        "---",
+        "",
+        "## Índice de áreas",
+        "",
+    ]
+    for area in sorted(areas.keys()):
+        lines.append(f"- [`{area}`](#{area})")
+    lines += ["", "---", ""]
+
+    # Hook intercepts summary table
+    if intercepted:
+        lines += [
+            "## Resumen de Hook Intercepts",
+            "",
+            "Comandos bash interceptados automáticamente y redirigidos a su capacidad higpertext.",
+            "",
+            "| Patrón bash | Capacidad | Comando correcto |",
+            "|---|---|---|",
+        ]
+        for cap in intercepted:
+            i = cap["bash_intercept"]
+            lines.append(
+                f"| `{i.get('pattern', '')}` " f"| `{cap['id']}` " f"| `{i.get('example', '')}` |"
+            )
+        lines += ["", "---", ""]
+
+    for area in sorted(areas.keys()):
+        lines.append(f"## Área: `{area}` {{#{area}}}")
+        lines.append("")
+        for cap in areas[area]:
+            lines += _render_cap_entry(cap)
+
+    lines.append(_INDEX_LINK)
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Reference: profiles-catalog.md
+# ---------------------------------------------------------------------------
+
+
+def _build_profiles_catalog(profiles: list, cap_dict: dict) -> list[str]:
+    lines = [
+        "# Catálogo de Perfiles",
+        "",
+        "Los perfiles definen el rol, system prompt y capacidades disponibles para cada agente.",
+        "Se cargan desde `src/config/profiles/*.json`.",
+        "",
+        "## Resumen",
+        "",
+        "| Perfil | Rol | Caps | Gobernanza | Skills sesión | Subagentes sesión |",
+        "|---|---|---|---|---|---|",
+    ]
+    for prof in profiles:
+        name = prof.get("name", "")
+        desc = prof.get("description", "")
+        num_caps = len(prof.get("capabilities", []))
+        gov = "✅" if prof.get("governance_access") else "❌"
+        skills = ", ".join(f"`{s}`" for s in prof.get("session_skills", [])) or "—"
+        subagents = ", ".join(f"`{sa}`" for sa in prof.get("session_subagents", [])) or "—"
+        lines.append(f"| `{name}` | {desc} | {num_caps} | {gov} | {skills} | {subagents} |")
+
+    lines += ["", "---", ""]
+
+    for prof in profiles:
+        name = prof.get("name", "")
+        desc = prof.get("description", "")
+        prompt = prof.get("system_prompt", "")
+        caps = prof.get("capabilities", [])
+        raw_hooks = prof.get("hooks", [])
+        hooks = raw_hooks if isinstance(raw_hooks, list) else []
+
+        lines += [
+            f"## `{name}`",
+            "",
+            f"**Descripción**: {desc}",
+            "",
+            f"**System Prompt**: {prompt}",
+            "",
+        ]
+
+        if caps:
+            lines += ["**Capacidades**:", "| ID | Propósito |", "|---|---|"]
+            for c in sorted(caps):
+                c_desc = cap_dict.get(c, "_No encontrada en el catálogo_")
+                lines.append(f"| `{c}` | {c_desc} |")
+        else:
+            lines.append("**Capacidades**: No tiene capacidades explícitas.")
+
+        if hooks:
+            lines += ["", "**Hooks activos**:", "| ID | Evento |", "|---|---|"]
+            for h in hooks:
+                lines.append(f"| `{h.get('id', '')}` | `{h.get('event', '')}` |")
+
+        lines += [
+            "",
+            "**Cargar perfil**:",
+            "```bash",
+            f"htx profile load {name} --assistant claude",
+            f"htx profile load {name} --assistant gemini",
+            "```",
+            "",
+            "---",
+            "",
+        ]
+
+    lines += [
+        "## Cómo agregar un nuevo perfil",
+        "",
+        "1. Crea `src/config/profiles/<nombre>.json`:",
+        "   ```json",
+        "   {",
+        '     "name": "mi-perfil",',
+        '     "description": "Descripción del rol.",',
+        '     "system_prompt": "Instrucciones base del agente.",',
+        '     "capabilities": ["common.memory-manager"],',
+        '     "governance_access": false,',
+        '     "session_skills": [],',
+        '     "session_subagents": []',
+        "   }",
+        "   ```",
+        "2. Ejecuta `htx task common.docs-sync` para regenerar este catálogo.",
+        "3. Verifica con `htx profile load mi-perfil --assistant claude`.",
+        "",
+        "---",
+        "",
+        _INDEX_LINK,
+    ]
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Reference: hooks-reference.md  (nuevo — técnico)
+# ---------------------------------------------------------------------------
+
+
+def _build_hooks_reference(capabilities: list) -> list[str]:
+    intercepted = [c for c in capabilities if c.get("bash_intercept")]
+
+    lines = [
+        "# Referencia de Hooks — higpertext Engine",
+        "",
+        "Documentación técnica del sistema de hooks: arquitectura, flujo de ejecución,",
+        "intercepción de comandos bash y cómo extender las reglas.",
+        "",
+        "---",
+        "",
+        "## Arquitectura del Sistema de Hooks",
+        "",
+        "```",
+        "Usuario / Agente IA",
+        "       │",
+        '       │  tool_call: Bash(command="git status")',
+        "       ▼",
+        "┌─────────────────────┐",
+        "│  Claude Code / IDE  │",
+        "│   PreToolUse hook   │──── stdin (JSON) ───▶ higpertext_enforcer.py",
+        "└─────────────────────┘                              │",
+        "                                           Lee bash_intercept",
+        "                                        de cada capability JSON",
+        "                                                      │",
+        "                              ┌───────────────────────┴──────────────────────┐",
+        "                              │ ¿coincide algún patrón?                       │",
+        "                              │                                               │",
+        "                           SÍ │                                            NO │",
+        "                              ▼                                               ▼",
+        "                 continue:true + additionalContext            continue:true (pasa)",
+        "                 (feedback al modelo, no corta el turno)",
+        "                              │",
+        "                 Modelo recibe feedback y auto-corrige",
+        "                 usando la capacidad higpertext correcta",
+        "```",
+        "",
+        "---",
+        "",
+        "## Tipos de Hook",
+        "",
+        "| Tipo | Comportamiento | Cuándo se usa |",
+        "|---|---|---|",
+        "| **Redirección** | `continue: true` + `additionalContext` | Comando bash con capacidad higpertext equivalente |", # noqa: E501
+        "| **Bloqueo duro** | `continue: false` | Violaciones de seguridad (`sudo`, comandos destructivos) |", # noqa: E501
+        "",
+        "> **Clave**: las redirecciones usan `continue: true` para que el modelo reciba",
+        "> el feedback sin cortar el turno ni la cadena de pensamiento.",
+        "",
+        "---",
+        "",
+        "## Whitelist — Comandos que nunca se interceptan",
+        "",
+        "```python",
+        "htx | .venv/bin/htx  # el propio higpertext",
+        "git add | git push | git checkout            # operaciones git de usuario",
+        "git merge | git rebase | git stash | git tag",
+        "```",
+        "",
+        "---",
+        "",
+        "## Reglas Dinámicas — `bash_intercept`",
+        "",
+        "El `higpertext_enforcer.py` **no tiene reglas hardcodeadas**. En cada ejecución escanea",
+        "todos los `*.json` de capacidades y extrae el campo `bash_intercept`:",
+        "",
+        "```json",
+        "{",
+        '  "bash_intercept": {',
+        '    "pattern": "\\\\bgit\\\\s+ls-files\\\\b",',
+        '    "description": "Listar archivos trackeados en el índice git",',
+        '    "example": "htx task ado_admin.git-ls-files --pattern \\"<filtro>\\"" ',
+        "  }",
+        "}",
+        "```",
+        "",
+        "**Flujo de carga**:",
+        "```",
+        "higpertext_enforcer.py arranca",
+        "       │",
+        "       └─ _find_capabilities_root()  → localiza src/capabilities/",
+        "              │",
+        '              └─ rglob("*.json")  → itera todos los JSONs',
+        "                     │",
+        "                     └─ extrae bash_intercept.{pattern, description, example}",
+        "                            │",
+        "                            └─ construye lista de reglas en memoria",
+        "```",
+        "",
+        "**Ventaja**: agregar una nueva capacidad con `bash_intercept` activa",
+        "automáticamente su intercepción sin tocar el hook.",
+        "",
+        "---",
+        "",
+        "## Hook Intercepts activos",
+        "",
+        "| Capacidad | Patrón interceptado | Descripción | Comando correcto |",
+        "|---|---|---|---|",
+    ]
+
+    for cap in intercepted:
+        i = cap["bash_intercept"]
+        lines.append(
+            f"| `{cap['id']}` "
+            f"| `{i.get('pattern', '')}` "
+            f"| {i.get('description', '')} "
+            f"| `{i.get('example', '')}` |"
+        )
+
+    lines += [
+        "",
+        "---",
+        "",
+        "## Cómo agregar una nueva regla de intercepción",
+        "",
+        "1. Abre el JSON de tu capacidad en `src/capabilities/<area>/<id>.json`",
+        "2. Agrega el campo `bash_intercept`:",
+        "   ```json",
+        "   {",
+        '     "bash_intercept": {',
+        '       "pattern": "\\\\bmi-comando\\\\b",',
+        '       "description": "Descripción de qué hace",',
+        '       "example": "htx task mi-area.mi-cap --param valor"',
+        "     }",
+        "   }",
+        "   ```",
+        "3. Re-despliega los hooks: `htx profile load <perfil> --assistant claude`",
+        "4. La regla estará activa en el siguiente turno del agente.",
+        "",
+        "> No es necesario editar `higpertext_enforcer.py`.",
+        "",
+        "---",
+        "",
+        "## Cómo agregar un bloqueo duro",
+        "",
+        "Los bloqueos duros (como `sudo`) se definen directamente en `_HARD_BLOCKS`",
+        "dentro de `src/core/hooks/hook_tasks/higpertext_enforcer.py`:",
+        "",
+        "```python",
+        "_HARD_BLOCKS = [",
+        '    (r"\\bsudo\\b", "sudo no está permitido por política de seguridad"),',
+        '    (r"\\brm\\s+-rf\\b", "rm -rf está bloqueado — usa ado_admin.git-rm"),',
+        "]",
+        "```",
+        "",
+        "---",
+        "",
+        "## Archivos relevantes",
+        "",
+        "| Archivo | Rol |",
+        "|---|---|",
+        "| `src/core/hooks/hook_tasks/higpertext_enforcer.py` | Hook principal — carga reglas y evalúa comandos |", # noqa: E501
+        "| `src/core/hooks/hook_tasks/hook_utils.py` | Utilidades: `get_project_root()`, `run_higpertext_task()` |", # noqa: E501
+        "| `src/core/hooks/hook_registry.py` | Filtra hooks por asistente y perfil |",
+        "| `src/core/hooks/hook_renderer.py` | Genera config nativa por asistente (Claude, Gemini, Copilot) |", # noqa: E501
+        "| `src/core/hooks/config_loader.py` | Carga `.higpertext/hooks_config.json` |",
+        "| `.higpertext/hooks_config.json` | Registro de hooks activos con filtros por asistente/perfil |", # noqa: E501
+        "",
+        "---",
+        "",
+        _INDEX_LINK,
+    ]
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Guide: hooks-guide.md  (nuevo — usuario)
+# ---------------------------------------------------------------------------
+
+
+def _build_hooks_guide(capabilities: list) -> list[str]:
+    intercepted = [c for c in capabilities if c.get("bash_intercept")]
+
+    lines = [
+        "# Guía de Hooks — Para el Agente y el Usuario",
+        "",
+        "Los hooks de higpertext actúan como un **guardia inteligente** entre el agente IA",
+        "y el sistema. Cuando el agente intenta usar un comando bash que tiene una",
+        "capacidad higpertext equivalente, el hook lo intercepta y le indica el comando correcto.",
+        "",
+        "---",
+        "",
+        "## ¿Por qué existen los hooks?",
+        "",
+        "El objetivo es que **todo pase por higpertext** en lugar de bash directo:",
+        "",
+        "| Sin hooks | Con hooks |",
+        "|---|---|",
+        "| `grep pattern ./src` | `htx task common.grep-search --pattern ...` |",
+        "| `git status` | `htx task ado_admin.git-diff` |",
+        "| `git ls-files` | `htx task ado_admin.git-ls-files` |",
+        "",
+        "**Ventaja**: el output de cada capacidad está formateado y controlado,",
+        "lo que permite mejorar la respuesta que recibe el agente sin tocar el código del modelo.",
+        "",
+        "---",
+        "",
+        "## ¿Cómo funciona para el agente?",
+        "",
+        "1. El agente intenta ejecutar `git status`",
+        "2. El hook intercepta antes de ejecutar",
+        "3. El agente recibe feedback con el comando correcto",
+        "4. El agente **no pierde el hilo de la conversación** — el turno continúa",
+        "5. El agente re-ejecuta con `htx task ado_admin.git-diff`",
+        "",
+        "---",
+        "",
+        "## Comandos interceptados actualmente",
+        "",
+        "| Si intentas... | Usa en su lugar... |",
+        "|---|---|",
+    ]
+
+    for cap in intercepted:
+        i = cap["bash_intercept"]
+        lines.append(f"| `{
+                i.get(
+                    'pattern',
+                    '').replace(
+                    chr(92) +
+                    'b',
+                    '').replace(
+                    chr(92) +
+                    's+',
+                    '  ').replace(
+                        chr(92),
+                        '').strip()}` | `{
+                            i.get(
+                                'example',
+                                '')}` |")
+
+    lines += [
+        "",
+        "---",
+        "",
+        "## Comandos que NUNCA se interceptan",
+        "",
+        "Estos comandos git los ejecuta el **usuario**, no el agente:",
+        "",
+        "```bash",
+        "git push          # solo el usuario hace push al remoto",
+        "git checkout      # cambio de rama — decisión del usuario",
+        "git merge         # merges — requieren revisión humana",
+        "git add           # staging — parte del flujo del committer",
+        "```",
+        "",
+        "---",
+        "",
+        "## ¿Cómo se activan los hooks?",
+        "",
+        "Los hooks se despliegan automáticamente al cargar un perfil:",
+        "",
+        "```bash",
+        "htx profile load software_developer --assistant claude",
+        "```",
+        "",
+        "Esto copia los scripts de hook a `.claude/hooks/` y actualiza `.claude/settings.json`.",
+        "",
+        "---",
+        "",
+        "## ¿Qué pasa si el hook bloquea algo por error?",
+        "",
+        "Si un comando legítimo es interceptado y no tiene capacidad equivalente,",
+        "puedes agregarlo a la whitelist en `higpertext_enforcer.py` o crear una nueva",
+        "capacidad con su `bash_intercept`. Ver la [Referencia Técnica de Hooks](../reference/hooks-reference.md).", # noqa: E501
+        "",
+        "---",
+        "",
+        _INDEX_LINK,
+    ]
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Guide: capability-development.md  (actualizado con bash_intercept)
+# ---------------------------------------------------------------------------
+
+
+def _build_capability_dev_guide() -> list[str]:
+    return [
+        "# Desarrollo de Capacidades",
+        "",
+        "Cómo crear una nueva capacidad para el higpertext Engine.",
+        "",
+        "---",
+        "",
+        "## Estructura de una capacidad",
+        "",
+        "```",
+        "src/capabilities/<area>/",
+        "├── mi-capacidad.json       ← registro: metadatos, parámetros, contrato",
+        "└── scripts/",
+        "    └── mi_capacidad.py     ← script ejecutable",
+        "```",
+        "",
+        "---",
+        "",
+        "## Paso 1 — Crear el script",
+        "",
+        "```python",
+        '"""higpertext Mi Capacidad — descripción breve."""',
+        "import argparse, sys",
+        "",
+        "def main():",
+        "    parser = argparse.ArgumentParser()",
+        '    parser.add_argument("--param", required=True)',
+        "    args = parser.parse_args()",
+        '    print(f"[OK] {args.param}")',
+        "",
+        'if __name__ == "__main__":',
+        "    main()",
+        "```",
+        "",
+        "---",
+        "",
+        "## Paso 2 — Crear el JSON de registro",
+        "",
+        "```json",
+        "{",
+        '  "id": "mi-area.mi-capacidad",',
+        '  "version": "1.0.0",',
+        '  "description": "Qué hace esta capacidad.",',
+        '  "entrypoint": "capabilities/mi-area/scripts/mi_capacidad.py",',
+        '  "language": "python",',
+        '  "parameters": [',
+        "    {",
+        '      "name": "param",',
+        '      "description": "Descripción del parámetro.",',
+        '      "required": true',
+        "    }",
+        "  ],",
+        '  "contract": {',
+        '    "rules": [',
+        '      "El output debe incluir [OK] al completarse."',
+        "    ]",
+        "  }",
+        "}",
+        "```",
+        "",
+        "---",
+        "",
+        "## Paso 3 — Agregar intercepción bash (opcional)",
+        "",
+        "Si tu capacidad reemplaza un comando bash, declara `bash_intercept`",
+        "en el JSON. El hook del agente lo detectará automáticamente:",
+        "",
+        "```json",
+        "{",
+        '  "bash_intercept": {',
+        '    "pattern": "\\\\bmi-comando\\\\b",',
+        '    "description": "Descripción de qué intercepta",',
+        '    "example": "htx task mi-area.mi-capacidad --param valor"',
+        "  }",
+        "}",
+        "```",
+        "",
+        "No necesitas editar `higpertext_enforcer.py` — el hook carga las reglas",
+        "dinámicamente desde los JSONs en cada ejecución.",
+        "",
+        "---",
+        "",
+        "## Paso 4 — Registrar en el perfil",
+        "",
+        "Agrega el ID al array `capabilities` del perfil en `src/config/profiles/<perfil>.json`:",
+        "",
+        "```json",
+        '{  "capabilities": ["...", "mi-area.mi-capacidad"]  }',
+        "```",
+        "",
+        "---",
+        "",
+        "## Paso 5 — Verificar",
+        "",
+        "```bash",
+        "htx task mi-area.mi-capacidad --param valor",
+        "htx task common.docs-sync   # actualiza el catálogo",
+        "```",
+        "",
+        "---",
+        "",
+        _INDEX_LINK,
+    ]
+
+
+# ---------------------------------------------------------------------------
+# README.md  (índice principal)
+# ---------------------------------------------------------------------------
+
+
+def _build_readme(capabilities: list, profiles: list) -> list[str]:
+    total_caps = len(capabilities)
+    total_profiles = len(profiles)
+    intercepted = len([c for c in capabilities if c.get("bash_intercept")])
+
+    return [
+        "# Documentación — higpertext Engine v5.0",
+        "",
+        "Framework de orquestación de agentes IA para DevSecOps.",
+        f"**{total_caps}** capacidades · **{total_profiles}** perfiles · **{intercepted}** hook intercepts activos", # noqa: E501
+        "",
+        "---",
+        "",
+        "## Primeros pasos (`01-getting-started/`)",
+        "",
+        "| Doc | Contenido |",
+        "|---|---|",
+        "| [Instalación](01-getting-started/installation.md) | Requisitos, `.venv`, `.env` |",
+        "| [Primer arranque](01-getting-started/first-run.md) | `init`, `profile load`, `session-start` |", # noqa: E501
+        "| [Conceptos clave](01-getting-started/concepts.md) | Perfiles, capacidades, hooks, sesiones, workflows |", # noqa: E501
+        "",
+        "---",
+        "",
+        "## Guías de uso (`02-guides/`)",
+        "",
+        "| Doc | Contenido |",
+        "|---|---|",
+        "| [Sesiones de Desarrollo](02-guides/sessions.md) | Ciclo de vida de sesiones, skills y subagentes |", # noqa: E501
+        "| [Hooks — Guía de uso](02-guides/hooks-guide.md) | Qué interceptan los hooks y por qué existen |", # noqa: E501
+        "| [Gobernanza](02-guides/governance.md) | Lineamientos obligatorios: PRs, seguridad, deployments |", # noqa: E501
+        "| [Memoria del Agente](02-guides/agent-memory.md) | Cómo persiste y consulta el historial de acciones |", # noqa: E501
+        "| [FAQ](02-guides/faq.md) | Portabilidad, entornos virtuales, secretos |",
+        "",
+        "---",
+        "",
+        "## Extender el framework (`03-extending/`)",
+        "",
+        "| Doc | Contenido |",
+        "|---|---|",
+        "| [Desarrollo de Capacidades](03-extending/capability-development.md) | Crear nueva capacidad con contrato y hook |", # noqa: E501
+        "| [Workflows Personalizados](03-extending/custom-workflows.md) | Cómo crear flujos YAML por proyecto |", # noqa: E501
+        "| [Gobernanza Personalizada](03-extending/custom-guidelines.md) | Cómo estructurar lineamientos propios |", # noqa: E501
+        "",
+        "---",
+        "",
+        "## Referencia técnica (`04-reference/`)",
+        "",
+        "Especificaciones exhaustivas — qué existe y cómo funciona internamente.",
+        "",
+        "| Doc | Contenido |",
+        "|---|---|",
+        "| [Arquitectura](04-reference/architecture.md) | Kernel, perfiles, capacidades, adaptadores LLM y flujo de ejecución |", # noqa: E501
+        f"| [Catálogo de Capacidades](04-reference/capabilities-catalog.md) | {total_caps} capacidades con parámetros, contratos y hook intercepts |", # noqa: E501
+        f"| [Catálogo de Perfiles](04-reference/profiles-catalog.md) | {total_profiles} perfiles con capacidades y recursos de sesión |", # noqa: E501
+        "| [Hooks — Referencia técnica](04-reference/hooks-reference.md) | Arquitectura de hooks, reglas dinámicas, cómo extender |", # noqa: E501
+        "| [Gobernanza — Referencia](04-reference/governance-reference.md) | Lineamientos, formato de commit, reglas activas |", # noqa: E501
+        "| [Módulos del Kernel](04-reference/kernel-modules.md) | API interna de cada módulo Python del kernel |", # noqa: E501
+        "| [Adaptadores LLM](04-reference/llm-adapters.md) | Cómo cada adaptador genera reglas para su asistente IA |", # noqa: E501
+        "| [Telemetría](04-reference/telemetry.md) | Métricas de uso, tokens y productividad |",
+        "",
+        "---",
+        "",
+        "## Flujos de Trabajo (`workflows/`)",
+        "",
+        "| Doc | Dominio |",
+        "|---|---|",
+        "| [Spec → Plan → Sesión](workflows/how-to/spec-plan-session.md) | Ciclo de desarrollo |",
+        "| [Motor de Playbooks](workflows/engine/playbooks-reference.md) | Técnico |",
+        "| [De Incidente a Presentación](workflows/sre/postmortem-to-presentation.md) | SRE |",
+        "| [Monitoreo Continuo](workflows/sre/continuous-monitoring.md) | SRE |",
+        "| [Bootstrap Multi-Proyecto](workflows/ops/multi-project-migration.md) | Ops |",
+        "",
+        "Ver criterio workflow vs capacidad: [workflows/README.md](workflows/README.md)",
+        "",
+        "---",
+        "",
+        "## Inicio rápido",
+        "",
+        "```bash",
+        "# 1. Entorno",
+        "python -m venv .venv && source .venv/bin/activate",
+        "pip install -r requirements.txt",
+        "",
+        "# 2. Inicializar asistente",
+        "htx init --assistant claude",
+        "",
+        "# 3. Cargar perfil",
+        "htx profile load software_developer --assistant claude",
+        "",
+        "# 4. Verificar integridad",
+        "htx task common.higpertext-tester",
+        "",
+        "# 5. Ejecutar una tarea",
+        "htx task ado_admin.code-quality --path ./src",
+        "```",
+        "",
+        "---",
+        "",
+        "## Mapa de la documentación",
+        "",
+        "```",
+        "docs/",
+        "├── README.md                          ← este archivo",
+        "├── 01-getting-started/                ← empieza aquí",
+        "│   ├── installation.md",
+        "│   ├── first-run.md",
+        "│   └── concepts.md",
+        "├── 02-guides/                         ← uso diario",
+        "│   ├── sessions.md",
+        "│   ├── hooks-guide.md                 ← auto-generado",
+        "│   ├── governance.md",
+        "│   ├── agent-memory.md",
+        "│   └── faq.md",
+        "├── 03-extending/                      ← extender el framework",
+        "│   ├── capability-development.md      ← auto-generado",
+        "│   ├── custom-workflows.md",
+        "│   └── custom-guidelines.md",
+        "├── 04-reference/                      ← técnico / exhaustivo",
+        "│   ├── architecture.md",
+        "│   ├── capabilities-catalog.md        ← auto-generado",
+        "│   ├── profiles-catalog.md            ← auto-generado",
+        "│   ├── hooks-reference.md             ← auto-generado",
+        "│   ├── kernel-modules.md",
+        "│   ├── llm-adapters.md",
+        "│   ├── telemetry.md",
+        "│   └── governance-reference.md",
+        "└── workflows/",
+        "    ├── README.md                      ← criterio workflow vs capacidad",
+        "    ├── how-to/",
+        "    ├── engine/",
+        "    ├── sre/",
+        "    └── ops/",
+        "```",
+        "",
+        "---",
+        "",
+        "*higpertext Engine v5.0 · auto-generado por `common.docs-sync`*",
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Reference: governance-reference.md  (técnico — auto-generado)
+# ---------------------------------------------------------------------------
+
+
+def _build_governance_reference(governance: dict) -> list[str]:
+    guidelines = governance.get("guidelines", {})
+    commit_fmt = governance.get("commit_format", {})
+
+    lines = [
+        "# Referencia de Gobernanza — higpertext Engine",
+        "",
+        "Lineamientos obligatorios cargados desde `src/config/governance/guidelines_contract.json`.", # noqa: E501
+        "Este archivo es **auto-generado** — no editar manualmente.",
+        "",
+        "---",
+        "",
+    ]
+
+    # Secciones de lineamientos
+    section_titles = {
+        "pull_requests": "Pull Requests",
+        "security": "Seguridad",
+        "deployments": "Deployments",
+        "code_quality": "Calidad de Código",
+        "doc_as_code": "Documentación como Código",
+        "gitflow_commits": "Gitflow y Commits",
+    }
+    for key, title in section_titles.items():
+        rules = guidelines.get(key, [])
+        if not rules:
+            continue
+        lines += [f"## {title}", ""]
+        for rule in rules:
+            lines.append(f"- {rule}")
+        lines += ["", "---", ""]
+
+    # Sección especial: formato de commit
+    if commit_fmt:
+        types = commit_fmt.get("types", [])
+        max_subj = commit_fmt.get("max_subject_length", 72)
+        max_body = commit_fmt.get("max_body_line_length", 100)
+        require_scope = commit_fmt.get("require_scope_on_types", [])
+        footer_tokens = commit_fmt.get("footer_tokens", [])
+
+        lines += [
+            "## Formato de Commit (`commit_format`)",
+            "",
+            "Leído en runtime por `ado_admin.committer` para validar cada mensaje.",
+            "",
+            "| Campo | Valor |",
+            "|---|---|",
+            f"| Tipos permitidos | {', '.join(f'`{t}`' for t in types)} |",
+            f"| Longitud máxima del subject | `{max_subj}` caracteres |",
+            f"| Longitud máxima de línea en body | `{max_body}` caracteres |",
+            f"| Scope requerido en tipos | {', '.join(f'`{t}`' for t in require_scope) or '—'} |",
+            f"| Tokens de footer reconocidos | {
+                ', '.join(
+                    f'`{t}`' for t in footer_tokens) or '—'} |",
+            "",
+            "### Anatomía de un mensaje bien formado",
+            "",
+            "```",
+            "feat(hooks): add dynamic bash_intercept rules from capability JSONs",
+            "│    │       │",
+            "│    │       └─ description: imperativo, sin punto final, ≤ 72 chars",
+            "│    └─────── scope: módulo o área afectada (requerido en feat/fix)",
+            "└──────────── type: uno de los tipos permitidos",
+            "",
+            "Replace hardcoded _RULES list in higpertext_enforcer.py with runtime",
+            "loading from bash_intercept field in each capability JSON.",
+            "│",
+            "└─ body: explicación del porqué, ≤ 100 chars por línea",
+            "",
+            "Closes #42",
+            "│",
+            "└─ footer: referencias, breaking changes, co-autores",
+            "```",
+            "",
+            "### Ejemplos correctos",
+            "",
+            "```bash",
+            "# Mínimo válido",
+            "chore: update .gitignore",
+            "",
+            "# Con scope (requerido para feat/fix)",
+            "fix(committer): parse multiline messages correctly",
+            "",
+            "# Con body y footer",
+            "feat(hooks): block git push from agent",
+            "",
+            "Add git push to _HARD_BLOCKS so the agent cannot publish",
+            "changes to the remote without user approval.",
+            "",
+            "Closes #15",
+            "```",
+            "",
+            "### Cómo modificar las reglas",
+            "",
+            "Edita `src/config/governance/guidelines_contract.json` sección `commit_format`.",
+            "Los cambios aplican en el siguiente commit — no requiere redeploy.",
+            "",
+            "---",
+            "",
+            _INDEX_LINK,
+        ]
+    else:
+        lines.append("> `commit_format` no definido en guidelines_contract.json.")
+        lines += ["", _INDEX_LINK]
+
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def run(project_root: Path) -> None:
+    project_root = _resolve_project_root(project_root)
+    capabilities_dir = project_root / "src" / "higpertext" / "capabilities"
+    profiles_dir = project_root / "src" / "config" / "profiles"
+    docs_ref_dir = project_root / "docs" / "04-reference"
+    docs_guides_dir = project_root / "docs" / "02-guides"
+    docs_extending_dir = project_root / "docs" / "03-extending"
+    docs_dir = project_root / "docs"
+
+    docs_ref_dir.mkdir(parents=True, exist_ok=True)
+    docs_guides_dir.mkdir(parents=True, exist_ok=True)
+    docs_extending_dir.mkdir(parents=True, exist_ok=True)
+
+    capabilities, cap_dict = _load_capabilities(capabilities_dir)
+    profiles = _load_profiles(profiles_dir)
+    areas = _group_by_area(capabilities)
+    governance = _load_governance(project_root)
+
+    # reference/capabilities-catalog.md
+    cap_lines = _build_capabilities_catalog(capabilities, areas)
+    (docs_ref_dir / "capabilities-catalog.md").write_text("\n".join(cap_lines), encoding="utf-8")
+    _log.ok(f"[SUCCESS] capabilities-catalog.md regenerado con {len(capabilities)} capacidades.")
+
+    # reference/profiles-catalog.md
+    prof_lines = _build_profiles_catalog(profiles, cap_dict)
+    (docs_ref_dir / "profiles-catalog.md").write_text("\n".join(prof_lines), encoding="utf-8")
+    _log.ok(f"[SUCCESS] profiles-catalog.md regenerado con {len(profiles)} perfiles.")
+
+    # reference/hooks-reference.md  (técnico)
+    hooks_ref_lines = _build_hooks_reference(capabilities)
+    (docs_ref_dir / "hooks-reference.md").write_text("\n".join(hooks_ref_lines), encoding="utf-8")
+    intercepted_count = len([c for c in capabilities if c.get("bash_intercept")])
+    _log.ok(f"[SUCCESS] hooks-reference.md regenerado con {intercepted_count} intercepts activos.")
+
+    # 02-guides/hooks-guide.md  (usuario)
+    hooks_guide_lines = _build_hooks_guide(capabilities)
+    (docs_guides_dir / "hooks-guide.md").write_text("\n".join(hooks_guide_lines), encoding="utf-8")
+    _log.ok("[SUCCESS] hooks-guide.md regenerado.")
+
+    # 03-extending/capability-development.md  (actualizado)
+    cap_dev_lines = _build_capability_dev_guide()
+    (docs_extending_dir / "capability-development.md").write_text(
+        "\n".join(cap_dev_lines), encoding="utf-8"
+    )
+    _log.ok("[SUCCESS] capability-development.md actualizado con sección bash_intercept.")
+
+    # reference/governance-reference.md  (auto-generado)
+    gov_lines = _build_governance_reference(governance)
+    (docs_ref_dir / "governance-reference.md").write_text("\n".join(gov_lines), encoding="utf-8")
+    _log.ok("[SUCCESS] governance-reference.md regenerado.")
+
+    # docs/README.md  (índice principal)
+    readme_lines = _build_readme(capabilities, profiles)
+    (docs_dir / "README.md").write_text("\n".join(readme_lines), encoding="utf-8")
+    _log.ok("[SUCCESS] docs/README.md regenerado.")
+
+
+def main():
+    run(_resolve_project_root(Path(__file__)))
+
+
+if __name__ == "__main__":
+    main()