@cristiancorreau/forge 2.9.5 → 2.9.7

package/assets/scripts/forge-audit.py

@@ -1,1061 +0,0 @@
-#!/usr/bin/env python3
-# Copyright 2026 Cristian Correa — Apache License 2.0
-# https://github.com/cristiancorreau/forge
-"""
-forge-audit.py — Auditoría del estado actual de un proyecto vs el estándar forge.
-
-Usage:
-  python3 .agentic/scripts/forge-audit.py
-  python3 .agentic/scripts/forge-audit.py --json    # output JSON para integrar en CI
-
-Qué reporta:
-  1. Health check por agente (.claude/agents/): frontmatter, secciones, modelo
-  2. Gap analysis vs forge: diferencia entre el agente del proyecto y la versión de forge
-  3. Oportunidades: profiles y skills disponibles en forge que el proyecto no usa
-  4. Huérfanos: agentes en .claude/ que no están declarados en project.yaml
-
-Requiere: pyyaml  →  pip3 install -r .agentic/requirements.txt
-"""
-import json
-import os
-import re
-import sys
-from difflib import SequenceMatcher
-from pathlib import Path
-
-try:
-    import yaml
-except ImportError:
-    print("ERROR: pip3 install -r .agentic/requirements.txt", file=sys.stderr)
-    sys.exit(1)
-
-# ── ANSI colors (desactivar si no es TTY) ─────────────────────────────────────
-USE_COLOR = sys.stdout.isatty()
-def c(code: str, text: str) -> str:
-    return f"\033[{code}m{text}\033[0m" if USE_COLOR else text
-OK  = lambda t: c("32", t)   # verde
-WARN= lambda t: c("33", t)   # amarillo
-ERR = lambda t: c("31", t)   # rojo
-INFO= lambda t: c("36", t)   # cyan
-BOLD= lambda t: c("1",  t)   # negrita
-DIM = lambda t: c("2",  t)   # gris
-
-# ── Secciones requeridas por el estándar ──────────────────────────────────────
-REQUIRED_SECTIONS = ["## Reglas", "## No hagas"]
-OPTIONAL_SECTIONS = ["## Workflow", "## Stack", "## Tu trabajo", "## Anti-patterns"]
-
-REQUIRED_FRONTMATTER = ["name", "description", "model", "tools", "tier"]
-
-STANDARD_VERSION = "1.0"
-
-VALID_MODELS = {"opus", "sonnet", "haiku"}
-# Tier 1 reviewers deben usar opus
-OPUS_ROLES = {"compliance-reviewer", "security-auditor", "orchestrator"}
-
-# Umbrales de similitud de texto (SequenceMatcher.ratio, escala 0-1).
-# Calibración: agentes Tier 1 sin modificar tienen ratio ~0.95-1.0 vs forge.
-# Agentes con especialización moderada (añadir 20-40 líneas) caen a ~0.65-0.80.
-# Agentes reescritos para un dominio específico (Tier 3) caen a <0.40.
-# Ajustar SIMILARITY_WARN a 0.70 para proyectos con fuerte especialización.
-SIMILARITY_WARN     = 0.80  # <80% → posibles mejoras disponibles en forge
-SIMILARITY_OUTDATED = 0.50  # <50% → probablemente desactualizado o fork intencional
-
-
-# ── Parsing ───────────────────────────────────────────────────────────────────
-
-def find_project_root() -> Path:
-    here = Path.cwd()
-    for p in [here] + list(here.parents):
-        if (p / "project.yaml").exists():
-            return p
-    raise FileNotFoundError("No se encontró project.yaml")
-
-
-def find_forge_dir() -> Path:
-    root = find_project_root()
-    for candidate in [root / ".agentic", root / "forge", Path(__file__).parent.parent]:
-        if (candidate / "core").exists():
-            return candidate
-    raise FileNotFoundError("No se encontró el directorio forge con core/")
-
-
-def load_project(root: Path) -> dict:
-    with open(root / "project.yaml") as f:
-        return yaml.safe_load(f)
-
-
-def parse_frontmatter(content: str) -> dict:
-    """Extrae el bloque --- ... --- del inicio del archivo."""
-    m = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
-    if not m:
-        return {}
-    try:
-        return yaml.safe_load(m.group(1)) or {}
-    except Exception:
-        return {}
-
-
-def read_agent(path: Path) -> dict:
-    """Lee un archivo de agente y retorna su metadata + contenido."""
-    content = path.read_text()
-    fm = parse_frontmatter(content)
-    return {
-        "path": path,
-        "name": path.stem,
-        "content": content,
-        "frontmatter": fm,
-        "lines": len(content.splitlines()),
-    }
-
-
-def get_forge_version(forge, name, profiles):
-    """
-    Busca la versión forge de un agente.
-    Prioridad: profiles (en orden) → core.
-    Retorna (path, source_label) o (None, "").
-    """
-    for profile in profiles:
-        p = forge / "profiles" / profile / "agents" / f"{name}.md"
-        if p.exists():
-            return p, f"profile:{profile}"
-    p = forge / "core" / "agents" / f"{name}.md"
-    if p.exists():
-        return p, "core"
-    return None, ""
-
-
-def similarity(a: str, b: str) -> float:
-    return SequenceMatcher(None, a, b).ratio()
-
-
-# ── Checks ────────────────────────────────────────────────────────────────────
-
-def check_frontmatter(agent):
-    issues = []
-    fm = agent["frontmatter"]
-
-    if not fm:
-        issues.append({"level": "error", "msg": "Sin bloque frontmatter (--- ... ---)"})
-        return issues
-
-    for field in REQUIRED_FRONTMATTER:
-        if field not in fm:
-            issues.append({"level": "error", "msg": f"Falta campo '{field}' en frontmatter"})
-
-    if "description" in fm:
-        desc = str(fm["description"])
-        if len(desc) > 120:
-            issues.append({"level": "warn", "msg": f"description muy larga ({len(desc)} chars) — debe caber en 1 línea clara"})
-        if "NO" not in desc.upper() and "no trabaja" not in desc.lower() and "scope" not in desc.lower():
-            issues.append({"level": "warn", "msg": "description no declara scope explícito (qué NO hace / en qué directorio trabaja)"})
-
-    if "model" in fm:
-        model = str(fm["model"])
-        if model not in VALID_MODELS:
-            issues.append({"level": "error", "msg": f"model '{model}' inválido — usar: opus | sonnet | haiku"})
-        name = agent["name"]
-        if name in OPUS_ROLES and model != "opus":
-            issues.append({"level": "warn", "msg": f"'{name}' debería usar model: opus (toma decisiones complejas)"})
-        if name not in OPUS_ROLES and model == "opus":
-            issues.append({"level": "warn", "msg": "model: opus en agente de implementación — sonnet es suficiente y más económico"})
-
-    if "last_verified" in fm:
-        try:
-            import datetime as _dt
-            lv = str(fm["last_verified"])  # formato "YYYY-MM"
-            year, month = int(lv[:4]), int(lv[5:7])
-            verified_date = _dt.date(year, month, 1)
-            months_old = (
-                (_dt.date.today().year - verified_date.year) * 12
-                + _dt.date.today().month - verified_date.month
-            )
-            if months_old >= 6:
-                issues.append({
-                    "level": "warn",
-                    "msg": f"last_verified hace {months_old} meses — verificar que las APIs de terceros siguen vigentes",
-                    "fix": f"Actualizar last_verified en frontmatter tras revisar la documentación del proveedor",
-                })
-        except Exception:
-            pass
-
-    if "standard_version" not in fm:
-        issues.append({
-            "field": "standard_version",
-            "level": "info",
-            "msg": "Campo 'standard_version' no presente — agente generado antes de standard v1.0",
-        })
-    elif fm.get("standard_version") != STANDARD_VERSION:
-        issues.append({
-            "field": "standard_version",
-            "level": "info",
-            "msg": f"standard_version '{fm['standard_version']}' difiere de la actual '{STANDARD_VERSION}'",
-        })
-
-    return issues
-
-
-def check_sections(agent):
-    issues = []
-    content = agent["content"]
-
-    for section in REQUIRED_SECTIONS:
-        if section not in content:
-            # Buscar variantes comunes
-            section_key = section.replace("## ", "").lower()
-            variants = [f"## anti-patterns", f"## no hacer", f"## restricciones"]
-            found_variant = any(v in content.lower() for v in variants)
-            if not found_variant:
-                issues.append({"level": "error", "msg": f"Falta sección '{section}' (requerida por estándar)"})
-
-    if agent["lines"] < 15:
-        issues.append({"level": "warn", "msg": f"Agente muy corto ({agent['lines']} líneas) — probablemente incompleto"})
-
-    return issues
-
-
-def check_vs_forge(agent, forge, profiles):
-    issues = []
-    tier = agent["frontmatter"].get("tier")
-
-    # Tier 3 (dominio): no existe en forge por diseño — correcto
-    if tier == 3:
-        issues.append({"level": "ok", "msg": "Tier 3 (dominio) — no se compara con forge"})
-        return issues
-
-    forge_path, source = get_forge_version(forge, agent["name"], profiles)
-
-    if forge_path is None:
-        if not tier:
-            # Sin tier: posiblemente Tier 3 no anotado, reportar como sugerencia
-            issues.append({"level": "info", "msg": "No encontrado en forge — si es Tier 3, agregar 'tier: 3' al frontmatter"})
-        elif tier in (1, 2):
-            issues.append({"level": "warn", "msg": f"Tier {tier} declarado pero no existe en forge — ¿falta crear el profile?"})
-        return issues
-
-    forge_content = forge_path.read_text()
-    ratio = similarity(agent["content"], forge_content)
-    forge_lines = len(forge_content.splitlines())
-    project_lines = agent["lines"]
-
-    extended = project_lines > forge_lines * 1.2   # proyecto tiene >20% más líneas
-    # Divergencia simétrica: mismo orden de magnitud, contenido diferente (especialización)
-    comparable = forge_lines * 0.7 <= project_lines <= forge_lines * 1.2
-
-    if ratio >= SIMILARITY_WARN:
-        issues.append({"level": "ok", "msg": f"Al día con forge ({source}) — similitud {ratio:.0%}"})
-    elif ratio >= SIMILARITY_OUTDATED:
-        if extended or comparable:
-            diff_lines = project_lines - forge_lines
-            sign = "+" if diff_lines >= 0 else ""
-            issues.append({
-                "level": "info",
-                "msg": f"Especialización intencional vs forge ({source}) — similitud {ratio:.0%}, {sign}{diff_lines} líneas respecto a forge",
-            })
-        else:
-            diff_lines = forge_lines - project_lines
-            issues.append({
-                "level": "warn",
-                "msg": f"Posibles mejoras disponibles en forge ({source}) — similitud {ratio:.0%}, forge tiene +{diff_lines} líneas (puede ser reescritura intencional — verificar manualmente)",
-                "may_be_intentional": True,
-                "fix": f"python3 .agentic/scripts/forge-init.py --tool claude-code --force --only={agent['name']}"
-            })
-    else:
-        if extended:
-            diff_lines = project_lines - forge_lines
-            issues.append({
-                "level": "info",
-                "msg": f"Muy extendido vs forge ({source}) — similitud {ratio:.0%}, proyecto tiene +{diff_lines} líneas (fork intencional)",
-            })
-        elif comparable:
-            issues.append({
-                "level": "warn",
-                "msg": f"Contenido muy diferente a forge ({source}) — similitud {ratio:.0%}. ¿Especialización intencional o desactualizado?",
-                "fix": f"Revisar manualmente vs python3 .agentic/scripts/forge-init.py --tool claude-code --force --only={agent['name']}"
-            })
-        else:
-            issues.append({
-                "level": "error",
-                "msg": f"Muy diferente a forge ({source}) — similitud {ratio:.0%}. Probablemente desactualizado (diferencia mayor al 50% — verificar si coincide con cambio de versión de forge)",
-                "fix": f"python3 .agentic/scripts/forge-init.py --tool claude-code --force --only={agent['name']}"
-            })
-
-    return issues
-
-
-# ── Relevancia de profiles por stack ─────────────────────────────────────────
-
-# Mapeo profile → condiciones que lo hacen relevante.
-# Una condición es un dict {campo: conjunto_de_valores_match}.
-# El profile es relevante si CUALQUIER condición se cumple.
-import textwrap as _textwrap
-
-# ── Catálogos de descripción para UI ─────────────────────────────────────────
-
-# (qué hace, qué ganás, trigger)
-_SKILL_INFO: dict[str, tuple[str, str, str]] = {
-    "security-audit": (
-        "Checklist de seguridad para endpoints, auth y datos sensibles.",
-        "Detecta vulnerabilidades antes de cada PR. Agnóstico al stack.",
-        "/security-audit",
-    ),
-    "db-migrate": (
-        "Flujo seguro de migraciones (Prisma, Drizzle, Rails, Alembic, Goose).",
-        "Evita pérdida de datos y conflictos al cambiar el schema.",
-        "/db-migrate",
-    ),
-    "local2prod": (
-        "Deploy completo a producción (Vercel, Railway, Fly.io, GitHub Actions).",
-        "Garantiza que el build y el runtime estén ok antes de cerrar la tarea.",
-        "/local2prod",
-    ),
-    "new-feature": (
-        "Orquesta planificación, implementación y deploy de una feature completa.",
-        "Mantiene el flujo consistente desde spec hasta producción.",
-        "/new-feature",
-    ),
-    "browser-test": (
-        "Automatización de navegador: screenshots y flujos visuales vía CDP.",
-        "Verifica el UI en el browser antes de dar cualquier tarea por terminada.",
-        "/browser-test",
-    ),
-    "wiki-ingest": (
-        "Ingesta documentos y fuentes en el wiki del proyecto.",
-        "Construye base de conocimiento persistente entre sesiones de trabajo.",
-        "/wiki-ingest",
-    ),
-    "wiki-query": (
-        "Responde preguntas usando el wiki como base de conocimiento.",
-        "El agente recuerda decisiones, convenciones y contexto del proyecto.",
-        "/wiki-query",
-    ),
-    "wiki-lint": (
-        "Verifica integridad del wiki: índice, links, páginas huérfanas.",
-        "Mantiene el wiki saludable y navegable con auto-reparación.",
-        "/wiki-lint",
-    ),
-}
-
-# (descripción, agentes que provee)
-_PROFILE_INFO: dict[str, tuple[str, str]] = {
-    "hono-drizzle":       ("API TypeScript con Hono + Drizzle ORM.", "api-engineer"),
-    "nextjs-admin":       ("Panel admin con Next.js + React.", "admin-engineer"),
-    "astro":              ("Sitios estáticos/híbridos con Astro.", "frontend-engineer"),
-    "vuenuxt":            ("Aplicaciones Vue 3 / Nuxt 3.", "frontend-engineer"),
-    "sveltekit":          ("Aplicaciones SvelteKit.", "frontend-engineer"),
-    "fastapi":            ("API Python con FastAPI + Pydantic.", "api-engineer"),
-    "django":             ("Full-stack Python con Django.", "api-engineer"),
-    "rails":              ("Full-stack Ruby on Rails.", "api-engineer"),
-    "express":            ("API Node.js con Express.", "api-engineer"),
-    "nestjs":             ("API Node.js modular con NestJS.", "api-engineer"),
-    "go-gin":             ("API Go de alta performance con Gin.", "api-engineer"),
-    "laravel":            (
-        "PHP con Laravel — API Sanctum, Blade+Livewire y migraciones L6→L13.",
-        "api-engineer · fullstack-engineer · migration-specialist",
-    ),
-    "wordpress":          (
-        "WordPress moderno: FSE, Gutenberg, Divi y Elementor.",
-        "wp-engineer · divi-engineer · elementor-engineer",
-    ),
-    "expo":               ("Apps móviles con Expo / React Native.", "mobile-engineer"),
-    "playwright-crawler": ("Web scraping y crawling con Playwright.", "scanner-engineer"),
-}
-
-_PROFILE_RELEVANCE: dict[str, list[dict]] = {
-    "hono-drizzle":       [{"backend": {"hono"}}, {"language": {"typescript"}}],
-    "nextjs-admin":       [{"frontend": {"nextjs"}}],
-    "astro":              [{"frontend": {"astro"}}],
-    "vuenuxt":            [{"frontend": {"nuxt"}}],
-    "sveltekit":          [{"frontend": {"sveltekit"}}],
-    "fastapi":            [{"backend": {"fastapi"}}, {"language": {"python"}}],
-    "django":             [{"backend": {"django"}}, {"language": {"python"}}],
-    "rails":              [{"backend": {"rails"}}, {"language": {"ruby"}}],
-    "express":            [{"backend": {"express"}}],
-    "nestjs":             [{"backend": {"nestjs"}}],
-    "go-gin":             [{"backend": {"gin"}}, {"language": {"go"}}],
-    "laravel":            [{"backend": {"laravel"}}, {"language": {"php"}}],
-    "wordpress":          [{"type": {"wordpress"}}, {"language": {"php"}}],
-    "expo":               [{"type": {"mobile"}}],
-    "playwright-crawler": [{"type": {"crawler"}}],
-}
-
-
-def _profile_is_relevant(profile_name: str, config: dict) -> bool:
-    """Retorna True si el profile coincide con el stack del proyecto."""
-    conditions = _PROFILE_RELEVANCE.get(profile_name)
-    if not conditions:
-        return True  # profile sin mapeo conocido → siempre mostrar
-
-    stack = config.get("stack", {}) or {}
-    project = config.get("project", {}) or {}
-    values = {
-        "backend":  str(stack.get("backend") or "").lower(),
-        "frontend": str(stack.get("frontend") or "").lower(),
-        "language": str(project.get("language") or "").lower(),
-        "type":     str(project.get("type") or "").lower(),
-    }
-
-    for cond in conditions:
-        if all(values.get(field, "") in allowed for field, allowed in cond.items()):
-            return True
-    return False
-
-
-# ── Oportunidades ─────────────────────────────────────────────────────────────
-
-def find_opportunities(forge, config, installed_names):
-    opps = []
-    agents_cfg = config.get("agents", {})
-    active_profiles = agents_cfg.get("profiles", [])
-    skills_cfg = config.get("skills", {})
-    active_skills = skills_cfg.get("active", [])
-    integrations = skills_cfg.get("integrations", [])
-
-    # Profiles disponibles en forge que el proyecto no usa Y son relevantes para su stack
-    profiles_dir = forge / "profiles"
-    has_stack_info = bool(
-        (config.get("stack", {}) or {}).get("backend") or
-        (config.get("stack", {}) or {}).get("frontend") or
-        (config.get("project", {}) or {}).get("language") or
-        (config.get("project", {}) or {}).get("type")
-    )
-
-    if profiles_dir.exists():
-        for profile_dir in sorted(profiles_dir.iterdir()):
-            if not profile_dir.is_dir():
-                continue
-            profile_name = profile_dir.name
-            if profile_name in active_profiles:
-                continue
-            # Filtrar por relevancia solo si el proyecto declara info de stack
-            if has_stack_info and not _profile_is_relevant(profile_name, config):
-                continue
-            agents_in_profile = list((profile_dir / "agents").glob("*.md"))
-            if agents_in_profile:
-                agent_names = [a.stem for a in agents_in_profile]
-                opps.append({
-                    "type": "profile",
-                    "slug": profile_name,
-                    "msg": f"Profile '{profile_name}' disponible en forge → provee: {', '.join(agent_names)}",
-                    "fix": f"Agregar '{profile_name}' a agents.profiles en project.yaml"
-                })
-
-    # Skills universales disponibles que no están activos
-    skills_dir = forge / "core" / "skills"
-    universal_skills = {
-        "security-audit", "db-migrate", "local2prod", "new-feature",
-        "browser-test", "wiki-ingest", "wiki-query", "wiki-lint",
-    }
-    for skill in sorted(universal_skills - set(active_skills)):
-        skill_path = skills_dir / skill / "SKILL.md"
-        if skill_path.exists():
-            opps.append({
-                "type": "skill",
-                "slug": skill,
-                "msg": f"Skill '{skill}' disponible pero no activo en project.yaml",
-                "fix": f"Agregar '{skill}' a skills.active en project.yaml"
-            })
-
-    # Wiki health — si los skills están activos, verificar que el wiki existe
-    wiki_skills_active = {"wiki-ingest", "wiki-query", "wiki-lint"}.intersection(active_skills)
-    if wiki_skills_active:
-        root = config.get("_root")
-        wiki_cfg = config.get("wiki", {})
-        wiki_path_str = wiki_cfg.get("path", "docs/wiki") if wiki_cfg else "docs/wiki"
-        if root:
-            wiki_path = Path(root) / wiki_path_str
-            if not wiki_path.exists():
-                opps.append({
-                    "type": "wiki",
-                    "msg": f"Skills de wiki activos pero {wiki_path_str}/ no existe",
-                    "fix": "python3 .agentic/scripts/forge-init.py --tool claude-code  (crea la estructura inicial)"
-                })
-            elif not (wiki_path / "index.md").exists():
-                opps.append({
-                    "type": "wiki",
-                    "msg": f"{wiki_path_str}/index.md falta — wiki incompleto",
-                    "fix": "python3 .agentic/scripts/forge-init.py --tool claude-code  (recrea el índice)"
-                })
-
-    # Integración obsidian disponible
-    if "obsidian-sync" not in integrations:
-        opps.append({
-            "type": "integration",
-            "msg": "Skill 'obsidian-sync' disponible (requiere Obsidian + Local REST API)",
-            "fix": "Agregar 'obsidian-sync' a skills.integrations si usás Obsidian"
-        })
-
-    # deploy.provider no configurado
-    deploy = config.get("deploy", {})
-    if not deploy.get("provider"):
-        opps.append({
-            "type": "config",
-            "msg": "deploy.provider no configurado — skill 'local2prod' no puede funcionar sin él",
-            "fix": "Configurar deploy.provider en project.yaml (vercel | railway | fly | github-actions | custom)"
-        })
-
-    return opps
-
-
-# ── Report ────────────────────────────────────────────────────────────────────
-
-def level_icon(level: str) -> str:
-    return {"ok": OK("✓"), "warn": WARN("⚠"), "error": ERR("✗"), "info": INFO("→")}.get(level, " ")
-
-
-_EMPTY_SUMMARY = {
-    "agents_total": 0, "agents_declared": 0,
-    "ok": 0, "info": 0, "warnings": 0, "errors": 0, "orphans": 0,
-}
-
-
-def run_audit(as_json: bool = False, forge_override=None, only=None):
-    try:
-        root = find_project_root()
-        if forge_override is not None:
-            forge = Path(forge_override)
-            if not forge.exists():
-                if as_json:
-                    print(json.dumps({"error": f"forge dir no existe: {forge_override}",
-                                      "error_code": "FORGE_NOT_FOUND",
-                                      "summary": {**_EMPTY_SUMMARY, "errors": 1}}))
-                    sys.exit(0)
-                print(ERR(f"ERROR: forge dir no existe: {forge}"), file=sys.stderr)
-                sys.exit(1)
-        else:
-            forge = find_forge_dir()
-        config = load_project(root)
-        config["_root"] = str(root)  # pass root for wiki path resolution
-    except FileNotFoundError as e:
-        if as_json:
-            code = "NO_PROJECT_YAML" if "project.yaml" in str(e) else "FORGE_NOT_FOUND"
-            print(json.dumps({
-                "error": str(e),
-                "error_code": code,
-                "hint": "Ejecuta el wizard: python3 .agentic/scripts/forge-wizard.py" if code == "NO_PROJECT_YAML" else "",
-                "summary": {**_EMPTY_SUMMARY, "errors": 1},
-            }))
-            sys.exit(0)
-        print(ERR(f"ERROR: {e}"), file=sys.stderr)
-        print(ERR("  → Primer uso: python3 .agentic/scripts/forge-wizard.py"), file=sys.stderr)
-        sys.exit(1)
-
-    agents_dir = root / ".claude" / "agents"
-    agents_cfg = config.get("agents", {})
-    active_profiles = agents_cfg.get("profiles", [])
-
-    declared = set(
-        agents_cfg.get("active", []) +
-        agents_cfg.get("compliance", []) +
-        agents_cfg.get("specialized", []) +
-        # agentes que los profiles proveerían
-        [p.stem
-         for profile in active_profiles
-         for p in (forge / "profiles" / profile / "agents").glob("*.md")
-         if (forge / "profiles" / profile / "agents").exists()]
-    )
-
-    # Leer todos los agentes instalados
-    installed = {}
-    if agents_dir.exists():
-        for f in sorted(agents_dir.glob("*.md")):
-            installed[f.stem] = read_agent(f)
-
-    # Filtrar por --only
-    if only:
-        if only not in installed:
-            print(ERR(f"ERROR: agente '{only}' no encontrado en .claude/agents/"), file=sys.stderr)
-            sys.exit(1)
-        installed = {only: installed[only]}
-
-    # ── Audit por agente ──────────────────────────────────────────────────────
-    agent_results = {}
-    for name, agent in installed.items():
-        checks = []
-        checks += check_frontmatter(agent)
-        checks += check_sections(agent)
-        checks += check_vs_forge(agent, forge, active_profiles)
-
-        tier = agent["frontmatter"].get("tier", "?")
-        in_declared = name in declared
-        if not in_declared:
-            checks.append({"level": "warn", "msg": "No declarado en project.yaml (active/compliance/profiles/specialized)"})
-
-        worst = "ok"
-        for c_ in checks:
-            if c_["level"] == "error":
-                worst = "error"
-                break
-            if c_["level"] == "warn" and worst != "error":
-                worst = "warn"
-            if c_["level"] == "info" and worst == "ok":
-                worst = "info"
-
-        agent_results[name] = {"tier": tier, "checks": checks, "status": worst}
-
-    # ── Oportunidades ─────────────────────────────────────────────────────────
-    opps = find_opportunities(forge, config, set(installed.keys()))
-
-    # ── Huérfanos ─────────────────────────────────────────────────────────────
-    orphans = [n for n in installed if n not in declared]
-
-    # ── Output ────────────────────────────────────────────────────────────────
-    proj_name = config.get("project", {}).get("name", "?")
-    n_ok   = sum(1 for r in agent_results.values() if r["status"] == "ok")
-    n_info = sum(1 for r in agent_results.values() if r["status"] == "info")
-    n_warn = sum(1 for r in agent_results.values() if r["status"] == "warn")
-    n_err  = sum(1 for r in agent_results.values() if r["status"] == "error")
-
-    if as_json:
-        print(json.dumps({
-            "project": config.get("project", {}).get("name"),
-            "summary": {
-                "agents_total": len(installed),
-                "agents_declared": len(declared),
-                "ok": n_ok,
-                "info": n_info,
-                "warnings": n_warn,
-                "errors": n_err,
-                "orphans": len(orphans),
-            },
-            "agents": {k: {**v, "path": str(v.get("path", ""))} for k, v in agent_results.items()},
-            "opportunities": opps,
-            "orphans": orphans,
-        }, indent=2, default=str))
-        return
-
-    print()
-    print(BOLD(f"forge audit — {proj_name}"))
-    print("═" * 60)
-
-    # Resumen
-    print(f"\n{BOLD('RESUMEN')}")
-    print(f"  {len(installed)} agentes en .claude/agents/")
-    print(f"  {len(declared)} declarados en project.yaml")
-    print(f"  {OK(str(n_ok))} conformes  {INFO(str(n_info))} sugerencias  {WARN(str(n_warn))} advertencias  {ERR(str(n_err))} gaps")
-    if orphans:
-        print(f"  {WARN(str(len(orphans)))} huérfanos (en .claude/ pero no en project.yaml)")
-
-    # Agentes por tier
-    by_tier: dict[str, list] = {}
-    for name, result in agent_results.items():
-        t = str(result["tier"])
-        by_tier.setdefault(t, []).append((name, result))
-
-    tier_labels = {"1": "Tier 1 — universal (core)", "2": "Tier 2 — profile (stack-specific)", "3": "Tier 3 — dominio (proyecto)", "?": "Sin tier declarado"}
-    print(f"\n{BOLD('SALUD POR AGENTE')}")
-    print("─" * 60)
-
-    for tier_key in sorted(by_tier.keys()):
-        print(f"\n  {DIM(tier_labels.get(tier_key, f'Tier {tier_key}'))}")
-        ok_names   = [n for n, r in sorted(by_tier[tier_key]) if r["status"] == "ok"]
-        prob_items = [(n, r) for n, r in sorted(by_tier[tier_key]) if r["status"] != "ok"]
-        if ok_names:
-            print(f"  {OK('✓')}  {DIM('  ·  '.join(ok_names))}")
-        for name, result in prob_items:
-            icon = level_icon(result["status"])
-            print(f"  {icon}  {BOLD(name)}")
-            for check in result["checks"]:
-                if check["level"] == "ok":
-                    continue
-                sub_icon = level_icon(check["level"])
-                print(f"       {sub_icon} {check['msg']}")
-                if "fix" in check:
-                    print(f"         {DIM('→ ' + check['fix'])}")
-
-    # Oportunidades
-    selectable     = [o for o in opps if o.get("type") in ("profile", "skill") and o.get("slug")]
-    non_selectable = [o for o in opps if o not in selectable]
-    items_indexed: list[dict] = []
-
-    if opps:
-        can_pick = bool(selectable) and sys.stdout.isatty() and not as_json and not only
-
-        if can_pick:
-            # Sugerencias no-seleccionables: mostrar antes del TUI
-            if non_selectable:
-                print(f"\n{BOLD('OPORTUNIDADES')} {DIM(f'({len(opps)} disponibles)')}")
-                print("─" * 60)
-                print(f"\n  {DIM('─── Otras sugerencias ───────────────────────────────────')}")
-                type_labels_ns = {"integration": "Integración", "config": "Config", "wiki": "Wiki"}
-                for opp in non_selectable:
-                    label = DIM(f"[{type_labels_ns.get(opp['type'], opp['type'])}]")
-                    print(f"  {INFO('→')}  {label} {opp['msg']}")
-                    if "fix" in opp:
-                        print(f"       {DIM('→ ' + opp['fix'])}")
-            items_indexed = selectable
-            _two_panel_opp_picker(items_indexed, root)
-        else:
-            # Modo estático — CI, JSON, --only, no-TTY
-            print(f"\n{BOLD('OPORTUNIDADES')} {DIM(f'({len(opps)} disponibles)')}")
-            print("─" * 60)
-
-            profile_opps = [o for o in selectable if o["type"] == "profile"]
-            skill_opps   = [o for o in selectable if o["type"] == "skill"]
-
-            def _wrap(text: str) -> str:
-                lines = _textwrap.wrap(text, width=66)
-                return ("\n" + " " * 7).join(lines)
-
-            if profile_opps:
-                print(f"\n  {DIM('─── Profiles de stack ───────────────────────────────────')}")
-                for o in profile_opps:
-                    idx = len(items_indexed) + 1
-                    items_indexed.append(o)
-                    slug = o["slug"]
-                    info = _PROFILE_INFO.get(slug)
-                    desc     = info[0] if info else ""
-                    agents_l = info[1] if info else (o.get("msg", "").split("→ provee:")[-1].strip())
-                    tag = DIM("[Profile]")
-                    print(f"\n  {BOLD(f'[{idx}]')} {BOLD(slug):<28} {tag}")
-                    if desc:
-                        print(f"       {_wrap(desc)}")
-                    if agents_l:
-                        print(f"       {DIM('Agentes: ' + agents_l)}")
-
-            if skill_opps:
-                print(f"\n  {DIM('─── Skills disponibles ──────────────────────────────────')}")
-                for o in skill_opps:
-                    idx = len(items_indexed) + 1
-                    items_indexed.append(o)
-                    slug = o["slug"]
-                    info = _SKILL_INFO.get(slug)
-                    what    = info[0] if info else o.get("msg", "")
-                    benefit = info[1] if info else ""
-                    trigger = info[2] if info else ""
-                    tag = DIM(f"[Skill  {trigger}]") if trigger else DIM("[Skill]")
-                    print(f"\n  {BOLD(f'[{idx}]')} {BOLD(slug):<28} {tag}")
-                    print(f"       {_wrap(what)}")
-                    if benefit:
-                        print(f"       {DIM(_wrap(benefit))}")
-
-            if non_selectable:
-                print(f"\n  {DIM('─── Otras sugerencias ───────────────────────────────────')}")
-                type_labels_ns = {"integration": "Integración", "config": "Config", "wiki": "Wiki"}
-                for opp in non_selectable:
-                    label = DIM(f"[{type_labels_ns.get(opp['type'], opp['type'])}]")
-                    print(f"  {INFO('→')}  {label} {opp['msg']}")
-                    if "fix" in opp:
-                        print(f"       {DIM('→ ' + opp['fix'])}")
-
-    # Huérfanos
-    if orphans:
-        print(f"\n{BOLD('HUÉRFANOS')} {DIM('(en .claude/ pero no en project.yaml)')}")
-        print("─" * 60)
-        for name in orphans:
-            print(f"  {WARN('⚠')}  {name}.md — agregar a agents.active, profiles o specialized")
-
-    # Gaps de project.yaml
-    missing_in_project = [n for n in declared if n not in installed]
-    if missing_in_project:
-        print(f"\n{BOLD('AGENTES DECLARADOS SIN ARCHIVO')}")
-        print("─" * 60)
-        for name in missing_in_project:
-            print(f"  {ERR('✗')}  {name}.md — declarado en project.yaml pero no existe en .claude/agents/")
-            forge_path, source = get_forge_version(forge, name, active_profiles)
-            if forge_path:
-                print(f"       {DIM(f'→ Disponible en forge ({source}): python3 .agentic/scripts/forge-init.py --tool claude-code')}")
-            else:
-                print(f"       {DIM('→ Crear manualmente en .claude/agents/')}")
-
-    print()
-    if n_err > 0:
-        print(ERR(f"  {n_err} gap(s) requieren atención antes de usar este proyecto con forge."))
-    elif n_warn > 0:
-        print(WARN(f"  {n_warn} advertencia(s). El proyecto funciona pero puede mejorar."))
-    else:
-        print(OK("  Todo conforme al estándar forge."))
-    print(DIM("  Nota: similitud < 0.80 puede indicar personalización intencional, no solo desactualización."))
-    print()
-
-
-
-def _simple_opp_picker(items_indexed: list, root: Path) -> None:
-    """Fallback picker lineal cuando no hay termios (Windows / no-TTY)."""
-    total = len(items_indexed)
-    hint  = f"1-{total}" if total > 1 else "1"
-    print(f"  {DIM(f'Seleccioná [{hint}], separados por coma  ·  a=todos  ·  Enter=saltear')}")
-    try:
-        sys.stdout.write("  > ")
-        sys.stdout.flush()
-        raw = input().strip()
-    except (EOFError, KeyboardInterrupt):
-        print()
-        return
-    if not raw or raw.lower() in ("n", ""):
-        return
-    if raw.lower() == "a":
-        selected = items_indexed
-    else:
-        selected = []
-        for part in raw.split(","):
-            part = part.strip()
-            if part.isdigit():
-                idx = int(part)
-                if 1 <= idx <= len(items_indexed):
-                    selected.append(items_indexed[idx - 1])
-    if not selected:
-        print(DIM("  Sin cambios."))
-        return
-    profiles_to_add = [o["slug"] for o in selected if o["type"] == "profile"]
-    skills_to_add   = [o["slug"] for o in selected if o["type"] == "skill"]
-    _apply_to_project_yaml(root, profiles_to_add, skills_to_add)
-
-
-def _two_panel_opp_picker(items_indexed: list, root: Path) -> None:
-    """Picker TUI de dos paneles: lista izquierda | detalle derecho."""
-    import shutil as _shutil
-
-    if not (sys.stdin.isatty() and sys.stdout.isatty()):
-        _simple_opp_picker(items_indexed, root)
-        return
-    try:
-        import termios as _termios
-        import tty as _tty
-    except ImportError:
-        _simple_opp_picker(items_indexed, root)
-        return
-
-    cols = _shutil.get_terminal_size(fallback=(80, 24)).columns
-    if cols < 60:
-        _simple_opp_picker(items_indexed, root)
-        return
-
-    # Dimensiones
-    left_inner  = min(36, max(28, (cols - 3) * 4 // 10))
-    right_inner = cols - left_inner - 5   # │ + sp + │ + sp + left border
-    panel_rows  = min(len(items_indexed) + 1, max(6, 14))
-
-    # Estado
-    selected: set[int] = set()
-    cursor = 0
-
-    _HIDE = "\033[?25l"
-    _SHOW = "\033[?25h"
-    _CY   = "\033[36m"
-    _BD   = "\033[1m"
-    _DM   = "\033[2m"
-    _GN   = "\033[32m"
-    _RST  = "\033[0m"
-
-    def _vlen(s: str) -> int:
-        return len(re.sub(r'\033\[[0-9;]*m', '', s))
-
-    def _pad(s: str, w: int) -> str:
-        v = _vlen(s)
-        if v > w:
-            plain = re.sub(r'\033\[[0-9;]*m', '', s)
-            return plain[:w - 1] + "…"
-        return s + " " * (w - v)
-
-    def _detail(item: dict) -> list:
-        lines: list[str] = []
-        itype = item.get("type", "")
-        slug  = item.get("slug", "")
-        w     = right_inner - 2
-        if itype == "skill":
-            info = _SKILL_INFO.get(slug)
-            if info:
-                what, benefit, trigger = info
-                lines.append(f"{_DM}Skill  {trigger}{_RST}")
-                lines.append("")
-                lines += [f"  {ln}" for ln in _textwrap.wrap(what, w - 2)]
-                lines.append("")
-                lines.append(f"{_DM}Qué ganás:{_RST}")
-                lines += [f"  {ln}" for ln in _textwrap.wrap(benefit, w - 2)]
-            else:
-                lines += _textwrap.wrap(item.get("msg", ""), w)
-        elif itype == "profile":
-            info = _PROFILE_INFO.get(slug)
-            if info:
-                desc, agents_l = info
-                lines.append(f"{_DM}Profile{_RST}")
-                lines.append("")
-                lines += _textwrap.wrap(desc, w)
-                lines.append("")
-                lines.append(f"{_DM}Agentes:{_RST}")
-                for a in agents_l.split(" · "):
-                    lines.append(f"  · {a.strip()}")
-            else:
-                lines += _textwrap.wrap(item.get("msg", ""), w)
-        return lines
-
-    def _draw() -> None:
-        sys.stdout.write("\033[2J\033[H")
-
-        n_sel     = len(selected)
-        n_prof    = sum(1 for o in items_indexed if o.get("type") == "profile")
-        n_skill   = sum(1 for o in items_indexed if o.get("type") == "skill")
-        hdr       = f"Oportunidades — {n_prof} profile(s)  ·  {n_skill} skill(s)"
-        sys.stdout.write(f"\n  {_BD}{hdr}{_RST}\n\n")
-
-        l_border = "─" * left_inner
-        r_border = "─" * right_inner
-        cur_item = items_indexed[cursor]
-        cur_slug = cur_item.get("slug", "?")
-        sys.stdout.write(f"  ╭{l_border}╮ ╭─ {_BD}{_pad(cur_slug, right_inner - 4)}{_RST} ─╮\n")
-
-        vis_start = max(0, cursor - panel_rows // 2)
-        vis_start = min(vis_start, max(0, len(items_indexed) - panel_rows))
-        detail    = (_detail(cur_item) + [""] * panel_rows)[:panel_rows]
-
-        for row in range(panel_rows):
-            item_idx = vis_start + row
-            if item_idx < len(items_indexed):
-                item  = items_indexed[item_idx]
-                slug  = item.get("slug", "")
-                itype = item.get("type", "")
-                tag   = "PRF" if itype == "profile" else "SKL"
-                chk   = f"{_GN}☑{_RST}" if item_idx in selected else "☐"
-                if item_idx == cursor:
-                    left_raw = f"{_CY}❯{_RST} {chk} {_DM}{tag}{_RST} {_BD}{slug}{_RST}"
-                else:
-                    left_raw = f"  {chk} {_DM}{tag}{_RST} {slug}"
-            else:
-                left_raw = ""
-
-            right_raw  = detail[row] if row < len(detail) else ""
-            sys.stdout.write(f"  │{_pad(left_raw, left_inner)}│ │{_pad(right_raw, right_inner)}│\n")
-
-        sys.stdout.write(f"  ╰{l_border}╯ ╰{r_border}╯\n")
-
-        sel_slugs   = [items_indexed[i].get("slug", "") for i in sorted(selected)]
-        sel_display = ", ".join(sel_slugs) if sel_slugs else "ninguno"
-        sel_label   = f"{n_sel} seleccionado(s)" if n_sel else "Ninguno seleccionado"
-        sys.stdout.write(f"\n  {_DM}{sel_label}:{_RST} {_DM}{sel_display}{_RST}\n")
-        sys.stdout.write(f"  {_DM}↑↓ navegar   Space seleccionar   a todos   Enter aplicar   q saltear{_RST}\n")
-        sys.stdout.flush()
-
-    def _getch() -> str:
-        fd  = sys.stdin.fileno()
-        old = _termios.tcgetattr(fd)
-        try:
-            _tty.setraw(fd)
-            ch = sys.stdin.read(1)
-            if ch == "\x1b":
-                ch2 = sys.stdin.read(1)
-                ch3 = sys.stdin.read(1)
-                return f"\x1b{ch2}{ch3}"
-            return ch
-        finally:
-            _termios.tcsetattr(fd, _termios.TCSADRAIN, old)
-
-    sys.stdout.write(_HIDE)
-    confirmed = False
-    try:
-        while True:
-            _draw()
-            ch = _getch()
-            if ch in ("\x03", "q"):
-                break
-            elif ch == "\x1b[A":
-                cursor = max(0, cursor - 1)
-            elif ch == "\x1b[B":
-                cursor = min(len(items_indexed) - 1, cursor + 1)
-            elif ch == " ":
-                if cursor in selected:
-                    selected.discard(cursor)
-                else:
-                    selected.add(cursor)
-            elif ch.lower() == "a":
-                if len(selected) == len(items_indexed):
-                    selected.clear()
-                else:
-                    selected = set(range(len(items_indexed)))
-            elif ch in ("\r", "\n"):
-                confirmed = True
-                break
-    finally:
-        sys.stdout.write(_SHOW)
-        sys.stdout.write("\033[2J\033[H")
-        sys.stdout.flush()
-
-    if confirmed and selected:
-        sel_items = [items_indexed[i] for i in sorted(selected)]
-        profiles_to_add = [o["slug"] for o in sel_items if o["type"] == "profile"]
-        skills_to_add   = [o["slug"] for o in sel_items if o["type"] == "skill"]
-        _apply_to_project_yaml(root, profiles_to_add, skills_to_add)
-    else:
-        print(DIM("  Sin cambios."))
-
-
-def _apply_to_project_yaml(root: Path, profiles: list[str], skills: list[str]) -> None:
-    """Agrega profiles y skills a project.yaml de forma segura."""
-    yaml_path = root / "project.yaml"
-    if not yaml_path.exists():
-        print(ERR("  ERROR: project.yaml no encontrado."))
-        return
-
-    try:
-        with open(yaml_path) as f:
-            content = yaml.safe_load(f)
-    except Exception as e:
-        print(ERR(f"  ERROR al leer project.yaml: {e}"))
-        return
-
-    changed = False
-
-    if profiles:
-        agents = content.setdefault("agents", {})
-        current_profiles = agents.get("profiles", []) or []
-        added = []
-        for p in profiles:
-            if p not in current_profiles:
-                current_profiles.append(p)
-                added.append(p)
-        agents["profiles"] = current_profiles
-        if added:
-            print(OK(f"  Profiles agregados: {', '.join(added)}"))
-            changed = True
-
-    if skills:
-        skill_cfg = content.setdefault("skills", {})
-        current_skills = skill_cfg.get("active", []) or []
-        added = []
-        for s in skills:
-            if s not in current_skills:
-                current_skills.append(s)
-                added.append(s)
-        skill_cfg["active"] = current_skills
-        if added:
-            print(OK(f"  Skills agregados: {', '.join(added)}"))
-            changed = True
-
-    if not changed:
-        print(DIM("  Sin cambios (ya estaban configurados)."))
-        return
-
-    try:
-        with open(yaml_path, "w") as f:
-            yaml.dump(content, f, allow_unicode=True, default_flow_style=False, sort_keys=False)
-        print(OK(f"  project.yaml actualizado."))
-    except Exception as e:
-        print(ERR(f"  ERROR al escribir project.yaml: {e}"))
-        return
-
-    print()
-    print(DIM("  Para instalar los agentes:"))
-    print(DIM("    python3 .agentic/scripts/forge-init.py --tool claude-code"))
-    print()
-
-
-def main():
-    as_json = "--json" in sys.argv
-    forge_override = None
-    only = None
-    args = sys.argv[1:]
-    i = 0
-    while i < len(args):
-        arg = args[i]
-        if arg.startswith("--forge="):
-            forge_override = arg[len("--forge="):]
-        elif arg == "--forge" and i + 1 < len(args):
-            i += 1
-            forge_override = args[i]
-        elif arg.startswith("--only="):
-            only = arg[len("--only="):]
-        i += 1
-    run_audit(as_json=as_json, forge_override=forge_override, only=only)
-
-
-if __name__ == "__main__":
-    main()