higpertext-cli 0.8.0__py3-none-any.whl

higpertext/capabilities/git/scripts/commit_changes.py

@@ -0,0 +1,1077 @@
+"""higpertext Committer — realiza commits Git leyendo reglas de formato desde gobernanza."""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess  # nosec B404
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+_HERE = Path(__file__).resolve()
+_PROJECT_ROOT = next(
+    (p for p in _HERE.parents if (p / "src/config/htx_config.json").exists()),
+    _HERE.parents[4],
+)
+sys.path.insert(0, str(_PROJECT_ROOT / "src"))
+try:
+    from higpertext.kernel.infrastructure.output_store import OutputStore as _OutputStore
+
+    _output_store: "_OutputStore | None" = _OutputStore(_PROJECT_ROOT)
+except ImportError:
+    _output_store = None
+
+# Telemetría — importación opcional para no romper si el módulo no está disponible
+try:
+    import importlib.util as _ilu
+
+    _telem_path = (
+        Path(__file__).resolve().parents[4]
+        / "src"
+        / "higpertext"
+        / "hooks"
+        / "hook_tasks"
+        / "higpertext.telemetry.telemetry_utils.py"
+    )
+    if not _telem_path.exists():
+        # Fallback: misma carpeta desplegada en hooks
+        _telem_path = Path(__file__).resolve().parent / "higpertext.telemetry.telemetry_utils.py"
+    _spec = _ilu.spec_from_file_location("telemetry_utils", _telem_path)
+    _telem = _ilu.module_from_spec(_spec)
+    _spec.loader.exec_module(_telem)
+except Exception:
+    _telem = None  # type: ignore
+
+_SEP = "─" * 54
+
+# ---------------------------------------------------------------------------
+# Version bumper — soporta Python, Java, .NET, Node, Python libs
+# ---------------------------------------------------------------------------
+
+import xml.etree.ElementTree as _ET  # noqa: E402
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def _detect_version_file(root: Path) -> tuple[str, Path] | tuple[None, None]:
+    """Detecta el archivo de versión del proyecto y retorna (tipo, path)."""
+    candidates = [
+        ("python", root / "pyproject.toml"),
+        ("python", root / "setup.py"),
+        ("python", root / "setup.cfg"),
+        ("node", root / "package.json"),
+        ("java", root / "pom.xml"),
+        ("dotnet", next(root.glob("**/*.csproj"), Path("__none__"))),
+        ("dotnet", next(root.glob("**/*.fsproj"), Path("__none__"))),
+    ]
+    for kind, path in candidates:
+        if path.exists():
+            return kind, path
+    return None, None
+
+
+def _read_version(kind: str, path: Path) -> str | None:
+    text = path.read_text(encoding="utf-8")
+    if kind == "python":
+        m = re.search(r'^version\s*=\s*["\']([^"\']+)["\']', text, re.MULTILINE)
+        if not m:
+            m = re.search(r'version\s*=\s*["\']([^"\']+)["\']', text)
+        return m.group(1) if m else None
+    if kind == "node":
+        try:
+            return json.loads(text).get("version")
+        except json.JSONDecodeError:
+            return None
+    if kind == "java":
+        try:
+            tree = _ET.parse(str(path))
+            ns = {"m": "http://maven.apache.org/POM/4.0.0"}
+            el = tree.getroot().find("m:version", ns) or tree.getroot().find("version")
+            return el.text if el is not None else None
+        except Exception:
+            return None
+    if kind == "dotnet":
+        m = re.search(r"<Version>([^<]+)</Version>", text)
+        return m.group(1) if m else None
+    return None
+
+
+def _bump_semver(version: str, bump: str) -> str:
+    parts = version.lstrip("v").split(".")
+    major = int(parts[0]) if len(parts) > 0 else 0
+    minor = int(parts[1]) if len(parts) > 1 else 0
+    patch = int(parts[2].split("-")[0]) if len(parts) > 2 else 0
+    if bump == "major":
+        return f"{major + 1}.0.0"
+    if bump == "minor":
+        return f"{major}.{minor + 1}.0"
+    return f"{major}.{minor}.{patch + 1}"
+
+
+def _bump_calver(version: str, bump: str) -> str:
+    from datetime import date
+
+    today = date.today()
+    return f"{today.year}.{today.month:02d}.{today.day:02d}"
+
+
+def _bump_calver_short(version: str, bump: str) -> str:
+    from datetime import date
+
+    today = date.today()
+    parts = version.split(".")
+    build = int(parts[2]) + 1 if len(parts) == 3 else 1
+    return f"{str(today.year)[2:]}.{today.month}.{build}"
+
+
+def _bump_sequential(version: str, bump: str) -> str:
+    try:
+        return str(int(version.lstrip("v")) + 1)
+    except ValueError:
+        return "1"
+
+
+def _bump_custom_regex(version: str, bump: str, pattern: str, template: str) -> str:
+    m = re.match(pattern, version)
+    if not m:
+        return version
+    groups = {k: int(v) if v.isdigit() else v for k, v in m.groupdict().items()}
+    if bump == "major" and "major" in groups:
+        groups["major"] += 1
+        groups.update({k: 0 for k in ("minor", "patch") if k in groups})
+    elif bump == "minor" and "minor" in groups:
+        groups["minor"] += 1
+        if "patch" in groups:
+            groups["patch"] = 0
+    elif "patch" in groups:
+        groups["patch"] += 1
+    return template.format(**groups)
+
+
+def _bump_version(
+    version: str,
+    bump: str,
+    scheme: str,
+    regex_pattern: str = "",
+    regex_template: str = "",
+) -> str:
+    if scheme == "calver":
+        return _bump_calver(version, bump)
+    if scheme == "calver_short":
+        return _bump_calver_short(version, bump)
+    if scheme == "sequential":
+        return _bump_sequential(version, bump)
+    if scheme == "custom_regex" and regex_pattern and regex_template:
+        return _bump_custom_regex(version, bump, regex_pattern, regex_template)
+    return _bump_semver(version, bump)
+
+
+def _write_version(kind: str, path: Path, old: str, new: str) -> None:
+    text = path.read_text(encoding="utf-8")
+    if kind == "python":
+        text = re.sub(
+            r'(^version\s*=\s*["\'])' + re.escape(old) + r'(["\'])',
+            lambda m: m.group(1) + new + m.group(2),
+            text,
+            flags=re.MULTILINE,
+        )
+    elif kind == "node":
+        data = json.loads(text)
+        data["version"] = new
+        text = json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+    elif kind == "java":
+        text = re.sub(
+            r"(<version>)" + re.escape(old) + r"(</version>)",
+            lambda m: m.group(1) + new + m.group(2),
+            text,
+            count=1,
+        )
+    elif kind == "dotnet":
+        text = re.sub(
+            r"(<Version>)" + re.escape(old) + r"(</Version>)",
+            lambda m: m.group(1) + new + m.group(2),
+            text,
+            count=1,
+        )
+    path.write_text(text, encoding="utf-8")
+
+
+def _create_tag(version: str, message: str, annotated: bool = True) -> str:
+    """Crea un tag git anotado o ligero. Retorna el nombre del tag."""
+    tag_name = f"v{version}" if not version.startswith("v") else version
+    if annotated:
+        _run(["git", "tag", "-a", tag_name, "-m", message])
+    else:
+        _run(["git", "tag", tag_name])
+    return tag_name
+
+
+# Defaults usados cuando guidelines_contract.json no tiene commit_format
+_DEFAULT_FORMAT = {
+    "types": [
+        "feat",
+        "fix",
+        "docs",
+        "style",
+        "refactor",
+        "perf",
+        "test",
+        "build",
+        "ci",
+        "chore",
+        "revert",
+    ],
+    "max_subject_length": 72,
+    "max_body_line_length": 100,
+    "require_scope_on_types": ["feat", "fix"],
+    "footer_tokens": ["Closes", "Refs", "BREAKING CHANGE", "Co-authored-by"],
+}
+
+
+# ---------------------------------------------------------------------------
+# Governance loader
+# ---------------------------------------------------------------------------
+
+_DEFAULT_TAG_CONFIG = {
+    "enabled": True,
+    "default_bump": "patch",
+    "commit_version_bump": True,
+    "bump_commit_message_template": "chore(release): bump version to {version}",
+    "tag_message_template": "chore(release): {version}",
+    "annotated": True,
+}
+
+
+def _load_commit_format() -> tuple[dict, dict]:
+    """Lee commit_format y tag_config desde guidelines_contract.json; fallback a defaults."""
+    candidates = [
+        Path(__file__).resolve().parents[4]
+        / "src"
+        / "config"
+        / "governance"
+        / "guidelines_contract.json",
+        Path.cwd() / "src" / "config" / "governance" / "guidelines_contract.json",
+    ]
+    for path in candidates:
+        if path.exists():
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                fmt = data.get("commit_format")
+                tag_cfg = data.get("tag_config")
+                return (
+                    {**_DEFAULT_FORMAT, **fmt} if fmt else _DEFAULT_FORMAT,
+                    ({**_DEFAULT_TAG_CONFIG, **tag_cfg} if tag_cfg else _DEFAULT_TAG_CONFIG),
+                )
+            except (OSError, json.JSONDecodeError):  # nosec B110
+                pass
+    return _DEFAULT_FORMAT, _DEFAULT_TAG_CONFIG
+
+
+# ---------------------------------------------------------------------------
+# Message parser
+# ---------------------------------------------------------------------------
+
+_FOOTER_PATTERN = re.compile(
+    r"^(Closes|Refs|BREAKING CHANGE|Co-authored-by|[A-Z][a-z]+-[a-z]+)\s*[:#]",
+    re.IGNORECASE,
+)
+
+
+def _parse_subject(subject: str) -> tuple[str, str, bool, str]:
+    """Extrae (type, scope, breaking, description) del subject de un commit."""
+    m = re.match(r"^([a-z]+)(\(([^)]+)\))?(!)?: (.+)$", subject)
+    if m:
+        return m.group(1), m.group(3) or "", bool(m.group(4)), m.group(5)
+    return "", "", False, ""
+
+
+def _split_body_footer(lines: list[str]) -> tuple[str, str]:
+    """Separa body y footer a partir de la línea 3 del mensaje."""
+    body_lines: list[str] = []
+    footer_lines: list[str] = []
+    in_footer = False
+    for line in lines[2:]:
+        if _FOOTER_PATTERN.match(line):
+            in_footer = True
+        if in_footer:
+            footer_lines.append(line)
+        else:
+            body_lines.append(line)
+    return "\n".join(body_lines).strip(), "\n".join(footer_lines).strip()
+
+
+def _parse_message(message: str) -> dict:
+    """Descompone un mensaje en subject, body y footer."""
+    lines = message.strip().splitlines()
+    subject = lines[0].strip() if lines else ""
+    commit_type, scope, breaking, description = _parse_subject(subject)
+    body, footer = _split_body_footer(lines)
+    return {
+        "subject": subject,
+        "type": commit_type,
+        "scope": scope,
+        "description": description,
+        "breaking": breaking,
+        "body": body,
+        "footer": footer,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Governance validator
+# ---------------------------------------------------------------------------
+
+
+def _check_type(commit_type: str, fmt: dict) -> str | None:
+    valid_types = fmt.get("types", [])
+    if commit_type and commit_type not in valid_types:
+        return f"Tipo '{commit_type}' no está en los tipos permitidos: {', '.join(valid_types)}\n  → Regla: commit_format.types" # noqa: E501
+    return None
+
+
+def _check_subject_length(subject: str, fmt: dict) -> str | None:
+    max_subj = fmt.get("max_subject_length", 72)
+    if len(subject) > max_subj:
+        return f"Subject tiene {len(subject)} caracteres (máximo {max_subj})\n  → Regla: commit_format.max_subject_length" # noqa: E501
+    return None
+
+
+def _check_scope_required(commit_type: str, scope: str, fmt: dict) -> str | None:
+    require_scope = fmt.get("require_scope_on_types", [])
+    if commit_type in require_scope and not scope:
+        return f"El tipo '{commit_type}' requiere scope: {commit_type}(scope): descripción\n  → Regla: commit_format.require_scope_on_types" # noqa: E501
+    return None
+
+
+def _check_body_line_lengths(body: str, fmt: dict) -> list[str]:
+    max_body = fmt.get("max_body_line_length", 100)
+    return [
+        f"Línea {i} del body tiene {
+            len(line)} caracteres (máximo {max_body})\n  → Regla: commit_format.max_body_line_length" # noqa: E501
+        for i, line in enumerate(body.splitlines(), 1)
+        if len(line) > max_body
+    ]
+
+
+def _validate_against_governance(parsed: dict, fmt: dict) -> list[str]:
+    """Valida el mensaje parseado contra las reglas de commit_format."""
+    checks = [
+        _check_type(parsed["type"], fmt),
+        _check_subject_length(parsed["subject"], fmt),
+        _check_scope_required(parsed["type"], parsed["scope"], fmt),
+    ]
+    warnings = [w for w in checks if w]
+    warnings += _check_body_line_lengths(parsed["body"], fmt)
+    return warnings
+
+
+# ---------------------------------------------------------------------------
+# Git helpers
+# ---------------------------------------------------------------------------
+
+
+def _run(cmd: list[str], check: bool = True) -> tuple[int, str, str]:
+    res = subprocess.run(cmd, shell=False, capture_output=True, text=True)  # nosec B603
+    if check and res.returncode != 0:
+        print(f"[ERROR] {' '.join(cmd)}\n{res.stderr}", file=sys.stderr)
+        sys.exit(res.returncode)
+    return res.returncode, res.stdout.strip(), res.stderr.strip()
+
+
+def _get_commit_stats() -> tuple[list[str], int, int]:
+    """Retorna (archivos, inserciones, eliminaciones) del último commit."""
+    _, out, _ = _run(["git", "show", "--stat", "--format=", "HEAD"], check=False)
+    files: list[str] = []
+    insertions = deletions = 0
+    for line in out.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        if "changed" in line:
+            m = re.search(r"(\d+) insertion", line)
+            if m:
+                insertions = int(m.group(1))
+            m = re.search(r"(\d+) deletion", line)
+            if m:
+                deletions = int(m.group(1))
+        elif "|" in line:
+            fname = line.split("|")[0].strip()
+            if fname:
+                files.append(fname)
+    return files, insertions, deletions
+
+
+# ---------------------------------------------------------------------------
+# Output printer
+# ---------------------------------------------------------------------------
+
+
+def _print_commit_subject(parsed: dict) -> None:
+    if parsed["type"]:
+        scope_str = f"({parsed['scope']})" if parsed["scope"] else ""
+        breaking_str = "  ⚠ BREAKING CHANGE" if parsed["breaking"] else ""
+        _log.info(f"  Tipo     : {parsed['type']}{breaking_str}")
+        if parsed["scope"]:
+            _log.info(f"  Scope    : {parsed['scope']}")
+        _log.info(f"  Subject  : {parsed['type']}{scope_str}: {parsed['description']}")
+    else:
+        _log.info(f"  Subject  : {parsed['subject']}")
+
+
+def _print_multiline_section(label: str, text: str) -> None:
+    if text:
+        _log.info(_SEP)
+        _log.info(f"  {label}:")
+        for line in text.splitlines():
+            _log.info(f"    {line}")
+
+
+def _print_governance_warnings(warnings: list[str]) -> None:
+    if warnings:
+        _log.info(_SEP)
+        _log.warning("  ⚠ Advertencias de gobernanza:")
+        for w in warnings:
+            for line in w.splitlines():
+                _log.info(f"    {line}")
+
+
+def _print_result(
+    parsed: dict,
+    branch: str,
+    commit_hash: str,
+    files: list[str],
+    insertions: int,
+    deletions: int,
+    warnings: list[str],
+) -> None:
+    _log.info()
+    _log.info("╔" + "═" * 54 + "╗")
+    _log.info("║  COMMIT REALIZADO" + " " * 36 + "║")
+    _log.info("╚" + "═" * 54 + "╝")
+    _log.info(f"  Branch   : {branch}")
+    _log.info(f"  Hash     : {commit_hash}")
+    _log.info(_SEP)
+    _print_commit_subject(parsed)
+    _print_multiline_section("Body     ", parsed["body"])
+    _print_multiline_section("Footer   ", parsed["footer"])
+    _print_governance_warnings(warnings)
+    _log.info(_SEP)
+    for f in files:
+        _log.info(f"  {f}")
+    if not files:
+        _log.info("  (sin detalle de archivos)")
+    _log.info(_SEP)
+    _log.info(f"  +{insertions} líneas  -{deletions} líneas  ({len(files)} archivo(s))")
+    _log.info()
+
+
+# ---------------------------------------------------------------------------
+# LT Commit Report — helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_commit_diff_summary() -> list[tuple[str, str, int, int]]:
+    """Retorna (filepath, mode, additions, deletions) del último commit por archivo."""
+    _, out, _ = _run(["git", "show", "--numstat", "--format=", "HEAD"], check=False)
+    result = []
+    for line in out.splitlines():
+        parts = line.split("\t")
+        if len(parts) == 3:
+            try:
+                add = int(parts[0]) if parts[0] != "-" else 0
+                delete = int(parts[1]) if parts[1] != "-" else 0
+                result.append((parts[2], "M", add, delete))
+            except ValueError:
+                continue
+    return result
+
+
+def _get_session_context(root: Path) -> dict:
+    """Lee session.json y environment.json para contexto de sesión."""
+    ctx: dict = {}
+    try:
+        s = json.loads(
+            (root / WORKSPACE_DIR_NAME / "state" / "session.json").read_text(encoding="utf-8")
+        )
+        ctx["session_id"] = s.get("session_id", "—")
+        ctx["profile"] = s.get("profile", "—")
+        ctx["skills"] = s.get("active_skills", [])
+        ctx["subagents"] = s.get("active_subagents", [])
+    except (OSError, json.JSONDecodeError):  # nosec B110
+        pass
+    try:
+        e = json.loads(
+            (root / WORKSPACE_DIR_NAME / "config" / "environment.json").read_text(encoding="utf-8")
+        )
+        ctx.setdefault("profile", e.get("active_profile", "—"))
+        ctx["project"] = e.get("project_name", "—")
+        ctx["assistant"] = e.get("assistant", "—")
+    except (OSError, json.JSONDecodeError):  # nosec B110
+        pass
+    return ctx
+
+
+_REVIEW_CHECKLIST: dict[str, list[str]] = {
+    "feat": [
+        "¿Se agregaron tests unitarios para la nueva funcionalidad?",
+        "¿Se actualizó la documentación relevante?",
+        "¿El PR cumple el umbral de cobertura (≥80%)?",
+        "¿Se ejecutó `ado_admin.code-quality` sobre los archivos nuevos?",
+    ],
+    "fix": [
+        "¿El bug fue reproducido antes del fix?",
+        "¿Se agregó un test de regresión que falla sin el fix?",
+        "¿Aplica a producción? Si sí, ¿hay hotfix branch?",
+        "¿Se verificó con `ado_admin.code-coverage` que la línea del bug está cubierta?",
+    ],
+    "refactor": [
+        "¿El comportamiento observable es idéntico antes y después?",
+        "¿Los tests existentes siguen en verde?",
+        "¿El score de calidad mejoró o se mantuvo (`ado_admin.code-quality`)?",
+        "¿Se actualizaron los docstrings afectados?",
+    ],
+    "perf": [
+        "¿Hay benchmark que demuestra la mejora?",
+        "¿Se midió impacto en memoria además de velocidad?",
+    ],
+    "docs": [
+        "¿Los enlaces internos del documento son relativos y verificados?",
+        "¿Se ejecutó `common.docs-sync` si se modificaron capacidades/perfiles?",
+    ],
+    "ci": [
+        "¿Se probó el pipeline en rama feature antes de mergear?",
+        "¿Los tiempos de ejecución del pipeline no aumentaron significativamente?",
+    ],
+}
+_DEFAULT_CHECKLIST = [
+    "¿El commit es atómico (un solo cambio lógico)?",
+    "¿Los tests del proyecto siguen en verde?",
+]
+
+_NEXT_STEP: dict[str, str] = {
+    "feat": "Abrir PR → `htx task ado_admin.pr-reviewer --pr_id <id>`",
+    "fix": "Verificar en staging → ejecutar `workflow.higpertext-build` sobre la rama",
+    "refactor": "Ejecutar quality gate → `htx task ado_admin.code-quality --path src/`",
+    "perf": "Ejecutar cobertura → `htx task ado_admin.code-coverage`",
+    "test": "Verificar cobertura global → `htx task ado_admin.code-coverage`",
+    "docs": "Sincronizar catálogos → `htx task common.docs-sync`",
+    "ci": "Monitorear pipeline → `htx task common.higpertext-tester`",
+    "chore": "Verificar integridad → `htx task common.higpertext-tester`",
+}
+
+
+# ---------------------------------------------------------------------------
+# LT Commit Report
+# ---------------------------------------------------------------------------
+
+_IMPACT_MAP: dict[str, str] = {
+    "feat": "🟢 Nueva funcionalidad — impacto directo en el producto",
+    "fix": "🔴 Corrección de bug — revisar si afecta producción",
+    "refactor": "🔵 Refactoring — sin cambio de comportamiento observable",
+    "perf": "🟡 Mejora de rendimiento",
+    "test": "⚪ Cobertura de tests — sin cambio funcional",
+    "docs": "⚪ Documentación — sin cambio funcional",
+    "build": "🟠 Cambio de build/infraestructura",
+    "ci": "🟠 Cambio de pipeline CI/CD",
+    "chore": "⚪ Tarea de mantenimiento",
+    "style": "⚪ Formato de código — sin cambio lógico",
+    "revert": "🔴 Reversión — revisar impacto en historial",
+}
+
+_RATIONALE_TEMPLATES: dict[str, str] = {
+    "feat": (
+        "Implementación de la funcionalidad '{desc}'. "
+        "Esta integración expande las capacidades técnicas del asistente "
+        "para dar soporte a nuevos flujos de trabajo de negocio."
+    ),
+    "fix": (
+        "Corrección del problema '{desc}'. "
+        "Resuelve fallos técnicos identificados en el flujo de ejecución, "
+        "estabilizando la infraestructura y minimizando el impacto en la operación."
+    ),
+    "refactor": (
+        "Refactorización de '{desc}'. "
+        "Mejora la legibilidad, modularidad y apego a los principios SOLID "
+        "sin alterar el comportamiento observable, reduciendo la deuda técnica."
+    ),
+    "docs": (
+        "Actualización de documentación: '{desc}'. "
+        "Sincroniza y documenta contratos, guías de usuario o reportes de integración "
+        "para mantener la transparencia operativa y gobernanza del proyecto."
+    ),
+}
+
+_RATIONALE_DEFAULT = (
+    "Cambio técnico asociado a '{desc}'. "
+    "Soporta la mantenibilidad del software de acuerdo a los estándares del framework."
+)
+
+
+def _deduce_rationale(commit_type: str, parsed: dict) -> str:
+    desc = parsed.get("description", parsed.get("subject", ""))
+    template = _RATIONALE_TEMPLATES.get(commit_type, _RATIONALE_DEFAULT)
+    return template.format(desc=desc) + " *(Deducido automáticamente)*"
+
+
+def _report_header_lines(
+    parsed: dict, commit_hash: str, branch: str, commit_type: str, breaking_flag: str
+) -> list[str]:
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    impact = _IMPACT_MAP.get(commit_type, "⚪ Tipo desconocido")
+    scope_row = f"| **Scope** | `{parsed['scope']}` |" if parsed["scope"] else "| **Scope** | — |"
+    return [
+        f"# Commit Report — `{commit_hash}`",
+        "",
+        "| Campo | Valor |",
+        "|-------|-------|",
+        f"| **Fecha** | {now} |",
+        f"| **Branch** | `{branch}` |",
+        f"| **Hash** | `{commit_hash}` |",
+        f"| **Tipo** | `{commit_type}`{breaking_flag} |",
+        scope_row,
+        f"| **Impacto** | {impact} |",
+    ]
+
+
+def _report_purpose_lines(parsed: dict, scope_str: str) -> list[str]:
+    subject_line = (
+        f"**{parsed['type']}{scope_str}: {parsed['description']}**"
+        if parsed["type"]
+        else f"**{parsed['subject']}**"
+    )
+    lines = ["", "## Propósito", "", subject_line]
+    if parsed["body"]:
+        lines += ["", parsed["body"]]
+    if parsed["footer"]:
+        lines += ["", f"_{parsed['footer']}_"]
+    return lines
+
+
+def _report_governance_lines(warnings: list[str]) -> list[str]:
+    if warnings:
+        lines = ["", "## ⚠️ Advertencias de gobernanza", ""]
+        for w in warnings:
+            lines.append(f"- {w.replace(chr(10), ' · ')}")
+        return lines
+    return [
+        "",
+        "## ✅ Gobernanza",
+        "",
+        "Sin advertencias — commit cumple todos los lineamientos.",
+    ]
+
+
+def _report_changes_lines(files: list[str], insertions: int, deletions: int) -> list[str]:
+    diff_detail = _get_commit_diff_summary()
+    lines = [
+        "",
+        "## Cambios técnicos",
+        "",
+        "| Métrica | Valor |",
+        "|---------|-------|",
+        f"| Archivos | {len(files)} |",
+        f"| Líneas añadidas | +{insertions} |",
+        f"| Líneas eliminadas | -{deletions} |",
+    ]
+    if diff_detail:
+        lines += [
+            "",
+            "### Detalle por archivo",
+            "",
+            "| Archivo | +añ | -el |",
+            "|---------|-----|-----|",
+        ]
+        for filepath, _, add, delete in diff_detail:
+            lines.append(f"| `{filepath}` | +{add} | -{delete} |")
+    elif files:
+        lines += ["", "### Archivos", ""]
+        for f in files:
+            lines.append(f"- `{f}`")
+    return lines
+
+
+def _report_session_lines(ctx: dict) -> list[str]:
+    if not ctx:
+        return []
+    lines = ["", "## Contexto de sesión", ""]
+    for key, label in [
+        ("project", "Proyecto"),
+        ("profile", "Perfil"),
+        ("assistant", "Asistente"),
+        ("session_id", "Sesión"),
+    ]:
+        if ctx.get(key):
+            lines.append(f"- **{label}**: `{ctx[key]}`")
+    if ctx.get("skills"):
+        lines.append(f"- **Skills activas**: {', '.join(f'`{s}`' for s in ctx['skills'])}")
+    if ctx.get("subagents"):
+        lines.append(f"- **Subagentes**: {', '.join(f'`{a}`' for a in ctx['subagents'])}")
+    return lines
+
+
+def _report_checklist_lines(commit_type: str) -> list[str]:
+    checklist = _REVIEW_CHECKLIST.get(commit_type, _DEFAULT_CHECKLIST)
+    return ["", "## Checklist de revisión", ""] + [f"- [ ] {item}" for item in checklist]
+
+
+def _report_next_step_lines(commit_type: str) -> list[str]:
+    next_step = _NEXT_STEP.get(
+        commit_type, "Verificar integridad → `htx task common.higpertext-tester`"
+    )
+    return ["", "## Siguiente paso sugerido", "", f"➡️ {next_step}", ""]
+
+
+def _generate_commit_report(
+    parsed: dict,
+    branch: str,
+    commit_hash: str,
+    files: list[str],
+    insertions: int,
+    deletions: int,
+    warnings: list[str],
+    rationale: str | None = None,
+) -> str:
+    """Genera un reporte Markdown orientado al Lead Tech con impacto y propósito del commit."""
+    commit_type = parsed["type"] or "unknown"
+    scope_str = f"({parsed['scope']})" if parsed["scope"] else ""
+    breaking_flag = " — ⚠️ BREAKING CHANGE" if parsed["breaking"] else ""
+    effective_rationale = rationale or _deduce_rationale(commit_type, parsed)
+
+    lines = _report_header_lines(parsed, commit_hash, branch, commit_type, breaking_flag)
+    lines += [
+        "",
+        "## 🎯 Justificación Técnica & Decisiones Arquitectónicas",
+        "",
+        effective_rationale,
+    ]
+    lines += _report_purpose_lines(parsed, scope_str)
+    lines += _report_governance_lines(warnings)
+    lines += _report_changes_lines(files, insertions, deletions)
+    lines += _report_checklist_lines(commit_type)
+    lines += _report_session_lines(_get_session_context(Path(__file__).resolve().parents[4]))
+    lines += _report_next_step_lines(commit_type)
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# HTML report + index
+# ---------------------------------------------------------------------------
+
+
+def _generate_html_report(commit_hash: str, root: Path) -> Path | None:
+    """Llama commit_report.py para generar HTML y actualiza el índice acumulativo."""
+    report_script = (
+        root / "src" / "higpertext" / "capabilities" / "common" / "scripts" / "commit_report.py"
+    )
+    python = root / ".venv" / "bin" / "python"
+    out_dir = root / WORKSPACE_DIR_NAME / "reports" / "commits"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / f"{commit_hash}_report.html"
+    try:
+        subprocess.run(  # nosec B603
+            [
+                str(python),
+                str(report_script),
+                "--commit",
+                "HEAD",
+                "--format",
+                "html",
+                "--output",
+                str(out_path),
+                "--diff",
+            ],
+            cwd=str(root),
+            capture_output=True,
+            timeout=30,
+        )
+    except Exception:
+        return None
+    if out_path.exists():
+        _update_commit_index(out_dir, root)
+    return out_path if out_path.exists() else None
+
+
+def _update_commit_index(reports_dir: Path, root: Path) -> None:
+    """Regenera index.html con todos los reportes HTML de commits ordenados por fecha."""
+    html_files = sorted(reports_dir.glob("*_report.html"), reverse=True)
+    rows = ""
+    for f in html_files:
+        name = f.stem.replace("_report", "")
+        rows += f'<tr><td><a href="{f.name}">{name}</a></td><td>{f.stat().st_mtime:.0f}</td></tr>\n'
+    index = f"""<!DOCTYPE html>
+<html lang="es"><head><meta charset="UTF-8">
+<title>higpertext — Índice de Commits</title>
+<style>body{{font-family:monospace;padding:2rem;background:#0d1117;color:#e6edf3}}
+a{{color:#58a6ff}}table{{border-collapse:collapse;width:100%}}
+th,td{{padding:.5rem 1rem;border:1px solid #30363d;text-align:left}}
+th{{background:#161b22}}</style></head>
+<body><h1>📋 Índice de Reportes de Commit</h1>
+<p>Proyecto: <code>{root.name}</code> — {len(html_files)} reporte(s)</p>
+<table><thead><tr><th>Commit</th><th>Timestamp</th></tr></thead>
+<tbody>{rows}</tbody></table></body></html>"""
+    (reports_dir / "index.html").write_text(index, encoding="utf-8")
+
+
+def _load_commit_history(json_path: Path) -> dict:
+    if json_path.exists():
+        try:
+            return json.loads(json_path.read_text(encoding="utf-8"))
+        except Exception:  # nosec B110
+            pass
+    return {}
+
+
+def _build_commit_entry(
+    commit_hash: str,
+    branch: str,
+    message: str,
+    parsed: dict,
+    files: list[str],
+    insertions: int,
+    deletions: int,
+    warnings: list,
+    rationale: str | None,
+) -> dict:
+    return {
+        "commit": commit_hash,
+        "branch": branch,
+        "message": message,
+        "type": parsed.get("type", ""),
+        "scope": parsed.get("scope", ""),
+        "description": parsed.get("description", ""),
+        "rationale": rationale or "",
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "stats": {
+            "files_changed": len(files),
+            "files_list": files,
+            "insertions": insertions,
+            "deletions": deletions,
+        },
+        "warnings": warnings,
+    }
+
+
+def _write_json_commit_report(
+    commit_hash: str,
+    root: Path,
+    message: str,
+    parsed: dict,
+    branch: str,
+    files: list[str],
+    insertions: int,
+    deletions: int,
+    warnings: list,
+    rationale: str | None,
+) -> None:
+    """Guarda un reporte JSON del commit en .higpertext/state/commits.json."""
+    state_dir = root / WORKSPACE_DIR_NAME / "state"
+    state_dir.mkdir(parents=True, exist_ok=True)
+    json_path = state_dir / "commits.json"
+    history = _load_commit_history(json_path)
+    history[commit_hash] = _build_commit_entry(
+        commit_hash,
+        branch,
+        message,
+        parsed,
+        files,
+        insertions,
+        deletions,
+        warnings,
+        rationale,
+    )
+    json_path.write_text(json.dumps(history, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def _resolve_files_to_add(files_arg: str) -> list[str]:
+    """Retorna lista de archivos a stagear.
+
+    Si files_arg es '.' (default), auto-detecta todos los archivos
+    modificados/nuevos del working tree vía git status --porcelain.
+    """
+    if files_arg != ".":
+        return [f.strip() for f in files_arg.replace(",", " ").split()]
+    _, status_out, _ = _run(["git", "status", "--porcelain"], check=False)
+    cwd_name = Path.cwd().name + "/"
+    detected: list[str] = []
+    for line in status_out.splitlines():
+        if len(line) >= 3:
+            path = line[3:].strip()
+            if path.startswith(cwd_name):
+                path = path[len(cwd_name) :]
+            detected.append(path)
+    return detected if detected else ["."]
+
+
+def _handle_tag(
+    bump: str,
+    tag_msg: str,
+    root: Path,
+    explicit_version: str | None = None,
+    tag_cfg: dict | None = None,
+) -> str | None:
+    """Detecta versión, la incrementa (o usa explicit_version), escribe el archivo y crea el tag."""
+    cfg = tag_cfg or _DEFAULT_TAG_CONFIG
+    kind, vfile = _detect_version_file(root)
+    if not vfile:
+        print("[WARN] No se detectó archivo de versión; tag no creado.", file=sys.stderr)
+        return None
+    old_ver = _read_version(kind, vfile)
+    if not old_ver:
+        print(
+            f"[WARN] No se pudo leer versión de {vfile}; tag no creado.",
+            file=sys.stderr,
+        )
+        return None
+    if explicit_version:
+        new_ver = explicit_version.lstrip("v")
+    else:
+        scheme = cfg.get("version_scheme", "semver")
+        new_ver = _bump_version(
+            old_ver,
+            bump,
+            scheme,
+            cfg.get("regex_pattern", ""),
+            cfg.get("regex_template", ""),
+        )
+    _write_version(kind, vfile, old_ver, new_ver)
+    _run(["git", "add", str(vfile)])
+    _log.info(f"  Versión  : {old_ver} → {new_ver}  ({vfile.name})")
+    tag_name = _create_tag(new_ver, tag_msg or f"chore(release): {new_ver}")
+    _log.info(f"  Tag      : {tag_name}")
+    return tag_name
+
+
+def _build_arg_parser():
+    import argparse
+
+    parser = argparse.ArgumentParser(description="higpertext ADO Git Committer")
+    parser.add_argument("--message", required=True)
+    parser.add_argument("--files", default=".")
+    parser.add_argument("--rationale")
+    parser.add_argument("--branch")
+    parser.add_argument("--tag", action="store_true", default=False)
+    parser.add_argument("--bump", choices=["patch", "minor", "major"], default="patch")
+    parser.add_argument("--tag-message", default="")
+    parser.add_argument("--version", default=None)
+    return parser
+
+
+def _do_commit(args) -> tuple[str, str, list[str], int, int]:
+    files_to_add = _resolve_files_to_add(args.files)
+    _run(["git", "add"] + files_to_add)
+    _run(["git", "commit", "-m", args.message])
+    _, branch, _ = _run(["git", "branch", "--show-current"], check=False)
+    _, commit_hash, _ = _run(["git", "rev-parse", "--short", "HEAD"], check=False)
+    files, insertions, deletions = _get_commit_stats()
+    return branch or "detached", commit_hash, files, insertions, deletions
+
+
+def _do_tag(args, tag_cfg: dict) -> None:
+    bump = args.bump if args.bump != "patch" else tag_cfg.get("default_bump", "patch")
+    tag_msg = args.tag_message or tag_cfg.get("tag_message_template", "chore(release): {version}")
+    tag_name = _handle_tag(bump, tag_msg, _PROJECT_ROOT, args.version, tag_cfg)
+    if not tag_name:
+        return
+    _, bump_status, _ = _run(["git", "status", "--porcelain"], check=False)
+    if bump_status.strip() and tag_cfg.get("commit_version_bump", True):
+        bump_msg = tag_cfg.get(
+            "bump_commit_message_template", "chore(release): bump version to {version}"
+        ).format(version=tag_name)
+        _run(["git", "commit", "-m", bump_msg])
+    _log.ok(f"[SUCCESS] Tag '{tag_name}' creado exitosamente.")
+
+
+def _do_reports(
+    args,
+    parsed: dict,
+    branch_name: str,
+    commit_hash: str,
+    files: list,
+    insertions: int,
+    deletions: int,
+    warnings: list,
+) -> None:
+    _generate_html_report(commit_hash, _PROJECT_ROOT)
+    _write_json_commit_report(
+        commit_hash,
+        _PROJECT_ROOT,
+        args.message,
+        parsed,
+        branch_name,
+        files,
+        insertions,
+        deletions,
+        warnings,
+        args.rationale,
+    )
+    report_md = _generate_commit_report(
+        parsed,
+        branch_name,
+        commit_hash,
+        files,
+        insertions,
+        deletions,
+        warnings,
+        args.rationale,
+    )
+    if _output_store:
+        _output_store.write("ado_admin.committer", report_md)
+
+
+def _do_telemetry(commit_hash: str, parsed: dict) -> None:
+    if not _telem:
+        return
+    try:
+        root = Path(__file__).resolve().parents[4]
+        session_data = json.loads(
+            (root / WORKSPACE_DIR_NAME / "state" / "session.json").read_text(encoding="utf-8")
+        )
+        env_data = json.loads(
+            (root / WORKSPACE_DIR_NAME / "config" / "environment.json").read_text(encoding="utf-8")
+        )
+        _telem.commit_event(
+            root,
+            session_id=session_data.get("session_id", "unknown"),
+            commit_hash=commit_hash,
+            commit_type=parsed.get("type", "unknown"),
+            scope=parsed.get("scope", ""),
+            profile=env_data.get("active_profile", "global"),
+        )
+    except Exception:  # nosec B110
+        pass
+
+
+def main() -> None:
+    args = _build_arg_parser().parse_args()
+    fmt, tag_cfg = _load_commit_format()
+    parsed = _parse_message(args.message)
+    warnings = _validate_against_governance(parsed, fmt)
+
+    _, status_out, _ = _run(["git", "status", "--porcelain"], check=False)
+    if not status_out:
+        _log.info("[*] No hay cambios pendientes para commitear.")
+        sys.exit(0)
+
+    branch_name, commit_hash, files, insertions, deletions = _do_commit(args)
+    _print_result(parsed, branch_name, commit_hash, files, insertions, deletions, warnings)
+    _log.ok("[SUCCESS] Commit realizado exitosamente.")
+
+    if args.tag:
+        _do_tag(args, tag_cfg)
+    if args.branch:
+        _run(["git", "push", "origin", args.branch])
+        _log.ok(f"[SUCCESS] Push realizado a origin/{args.branch}.")
+
+    _do_reports(args, parsed, branch_name, commit_hash, files, insertions, deletions, warnings)
+    _do_telemetry(commit_hash, parsed)
+
+
+if __name__ == "__main__":
+    main()