disensor 0.1.0__py3-none-any.whl

disensor/__init__.py

@@ -0,0 +1,2 @@
+"""disensor: declaracion de residuo de revision adversarial (desacuerdo controlado)."""
+__version__ = "0.1.0"

disensor/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

disensor/cli.py

@@ -0,0 +1,62 @@
+"""Interfaz de linea de comandos: disensor {nuevo, validar, gate}."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .gate import main_gate
+from .plantilla import main_nuevo
+from .reglas import cargar_schema, validar_artefacto
+
+
+def main_validar(args) -> int:
+    schema = cargar_schema()
+    fallo = False
+    for ruta in args.archivos:
+        with open(ruta, encoding="utf-8") as f:
+            artefacto = json.load(f)
+        errores = validar_artefacto(artefacto, schema)
+        print(f"{ruta}: {'VALIDO' if not errores else 'INVALIDO'}")
+        for msg in errores:
+            print(f"  {msg}")
+        fallo = fallo or bool(errores)
+    return 1 if fallo else 0
+
+
+def construir_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="disensor",
+        description="Declaracion de residuo de revision adversarial (desacuerdo controlado).",
+    )
+    sub = p.add_subparsers(dest="comando", required=True)
+
+    nuevo = sub.add_parser("nuevo", help="Crea una plantilla de artefacto para el evento en curso.")
+    nuevo.add_argument("--directorio", default=".residuo")
+    nuevo.add_argument("--compuerta", choices=["plan", "diff", "arquitectura"], default="diff")
+    nuevo.add_argument("--nivel", choices=["A", "B", "C"], default="B")
+    nuevo.add_argument("--perfil", choices=["completo", "minimizado"], default="completo")
+    nuevo.set_defaults(func=main_nuevo)
+
+    validar = sub.add_parser("validar", help="Valida artefactos contra el schema y las reglas R0 a R10.")
+    validar.add_argument("archivos", nargs="+")
+    validar.set_defaults(func=main_validar)
+
+    gate = sub.add_parser("gate", help="Gate de CI: valida el PR completo y aplica politica G1 a G5.")
+    gate.add_argument("--directorio", default=".residuo")
+    gate.add_argument("--config", default="disensor.config.json")
+    gate.add_argument("--base", default=None, help="SHA base del PR (por defecto, el evento de GitHub).")
+    gate.add_argument("--cabeza", default=None, help="SHA cabeza del PR (por defecto, el evento de GitHub).")
+    gate.add_argument("--sin-comentario", action="store_true", help="No publicar comentario en el PR.")
+    gate.set_defaults(func=main_gate)
+    return p
+
+
+def main() -> None:
+    args = construir_parser().parse_args()
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

disensor/gate.py

@@ -0,0 +1,245 @@
+"""Gate de CI: valida las declaraciones de residuo de un PR y aplica politica.
+
+Chequeos del gate (sobre los R0 a R10 por artefacto de reglas.py):
+  G1: al menos un artefacto valido en el rango del PR, salvo que la
+      configuracion declare el gate como no requerido (tipico en Nivel C).
+  G2: el nivel del artefacto coincide con el nivel declarado del repositorio
+      (seccion 12.2: nivel de criticidad declarado en un archivo del repo).
+  G3: Nivel A bloqueado mientras la gobernanza no este validada
+      (seccion 3.1: el Nivel A no arranca hasta que la seccion 10 este validada).
+  G4: politica de confinamiento por nivel (seccion 10: el revisor solo lee,
+      y eso se garantiza con permisos y no con la consigna).
+  G5: el commit revisado pertenece al rango del PR.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import urllib.request
+from pathlib import Path
+
+from .reglas import cargar_schema, validar_artefacto
+from .render import MARCADOR, render_comentario
+
+CONFIG_DEFECTO = {
+    "nivel_criticidad": "B",
+    "nivel_A_habilitado": False,
+    "gate": {
+        "requerido": True,
+        "confinamiento_aceptado_nivel_A": ["permisos", "sandbox"],
+        "advertir_confinamiento_no_verificado": True,
+    },
+}
+
+
+def cargar_config(ruta: Path) -> dict:
+    if not ruta.exists():
+        return dict(CONFIG_DEFECTO)
+    with ruta.open(encoding="utf-8") as f:
+        config = json.load(f)
+    combinada = dict(CONFIG_DEFECTO)
+    combinada.update({k: v for k, v in config.items() if k != "gate"})
+    gate = dict(CONFIG_DEFECTO["gate"])
+    gate.update(config.get("gate", {}))
+    combinada["gate"] = gate
+    return combinada
+
+
+def rango_del_pr(base: str | None, cabeza: str | None) -> tuple[str | None, str | None]:
+    """Base y cabeza del PR: flags primero, despues el evento de GitHub."""
+    if base and cabeza:
+        return base, cabeza
+    ruta_evento = os.environ.get("GITHUB_EVENT_PATH")
+    if ruta_evento and Path(ruta_evento).exists():
+        with open(ruta_evento, encoding="utf-8") as f:
+            evento = json.load(f)
+        pr = evento.get("pull_request") or {}
+        return (
+            base or (pr.get("base") or {}).get("sha"),
+            cabeza or (pr.get("head") or {}).get("sha"),
+        )
+    return base, cabeza
+
+
+def commits_del_rango(base: str, cabeza: str, cwd: Path) -> list[str] | None:
+    """Commits del rango base..cabeza, incluida la cabeza.
+
+    Devuelve None si git no puede resolver el rango (clon superficial, shas
+    desconocidos): eso es una advertencia. Una lista vacia es un resultado
+    valido y significa que el rango no contiene commits: G5 debe evaluarse
+    igual, porque un rango vacio no puede contener el commit revisado.
+    """
+    r = subprocess.run(
+        ["git", "rev-list", f"{base}..{cabeza}"],
+        capture_output=True, text=True, cwd=cwd, check=False,
+    )
+    if r.returncode != 0:
+        return None
+    return [linea.strip() for linea in r.stdout.splitlines() if linea.strip()]
+
+
+def numero_de_pr() -> int | None:
+    ruta_evento = os.environ.get("GITHUB_EVENT_PATH")
+    if ruta_evento and Path(ruta_evento).exists():
+        with open(ruta_evento, encoding="utf-8") as f:
+            evento = json.load(f)
+        pr = evento.get("pull_request") or {}
+        return pr.get("number")
+    return None
+
+
+def publicar_comentario(cuerpo: str) -> str:
+    """Crea o actualiza el comentario del gate en el PR. Devuelve un estado legible."""
+    token = os.environ.get("GITHUB_TOKEN")
+    repo = os.environ.get("GITHUB_REPOSITORY")
+    pr = numero_de_pr()
+    if not (token and repo and pr):
+        return "sin token, repositorio o numero de PR: comentario no publicado"
+    api = os.environ.get("GITHUB_API_URL", "https://api.github.com")
+    cabeceras = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "User-Agent": "disensor-gate",
+    }
+    try:
+        req = urllib.request.Request(
+            f"{api}/repos/{repo}/issues/{pr}/comments?per_page=100", headers=cabeceras
+        )
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            comentarios = json.load(resp)
+        existente = next((c for c in comentarios if MARCADOR in (c.get("body") or "")), None)
+        datos = json.dumps({"body": cuerpo}).encode("utf-8")
+        if existente:
+            req = urllib.request.Request(
+                f"{api}/repos/{repo}/issues/comments/{existente['id']}",
+                data=datos, headers=cabeceras, method="PATCH",
+            )
+        else:
+            req = urllib.request.Request(
+                f"{api}/repos/{repo}/issues/{pr}/comments",
+                data=datos, headers=cabeceras, method="POST",
+            )
+        with urllib.request.urlopen(req, timeout=30):
+            pass
+        return "comentario actualizado" if existente else "comentario publicado"
+    except Exception as exc:  # el gate no debe caerse por la red
+        return f"no se pudo publicar el comentario: {exc}"
+
+
+def escribir_resumen(cuerpo: str) -> None:
+    ruta = os.environ.get("GITHUB_STEP_SUMMARY")
+    if ruta:
+        with open(ruta, "a", encoding="utf-8") as f:
+            f.write(cuerpo + "\n")
+
+
+def correr_gate(directorio: Path, config_ruta: Path, base: str | None,
+                cabeza: str | None, repo_dir: Path, publicar: bool = True) -> int:
+    config = cargar_config(config_ruta)
+    schema = cargar_schema()
+    gate_cfg = config["gate"]
+
+    errores_gate: list[str] = []
+    advertencias: list[str] = []
+    errores_por_archivo: dict[str, list[str]] = {}
+    validos: list[dict] = []
+
+    base, cabeza = rango_del_pr(base, cabeza)
+    commits = commits_del_rango(base, cabeza, repo_dir) if (base and cabeza) else None
+    if commits is None and base and cabeza:
+        advertencias.append(
+            "no se pudo resolver el rango de commits (checkout con fetch-depth 0): G5 no se evalua"
+        )
+
+    archivos = sorted(p for p in directorio.glob("*.json")) if directorio.exists() else []
+    for ruta in archivos:
+        with ruta.open(encoding="utf-8") as f:
+            try:
+                artefacto = json.load(f)
+            except json.JSONDecodeError as exc:
+                errores_por_archivo[ruta.name] = [f"JSON invalido: {exc}"]
+                continue
+        errores = validar_artefacto(artefacto, schema)
+        if errores:
+            errores_por_archivo[ruta.name] = errores
+            continue
+
+        ev = artefacto["evento"]
+        propios: list[str] = []
+
+        # G2: nivel del artefacto contra nivel declarado del repositorio.
+        if ev["nivel_criticidad"] != config["nivel_criticidad"]:
+            propios.append(
+                f"[G2] nivel del artefacto ({ev['nivel_criticidad']}) distinto del declarado "
+                f"en el repositorio ({config['nivel_criticidad']})"
+            )
+
+        # G3: Nivel A bloqueado hasta validar la gobernanza (seccion 3.1).
+        if ev["nivel_criticidad"] == "A" and not config.get("nivel_A_habilitado", False):
+            propios.append(
+                "[G3] Nivel A bloqueado: la gobernanza de datos (seccion 10) no esta validada "
+                "en este repositorio (nivel_A_habilitado=false). Aplicar el protocolo en Nivel A "
+                "en esta situacion no es cumplirlo a medias: es violarlo."
+            )
+
+        # G4: politica de confinamiento por nivel.
+        for r in artefacto["actores"]["revisores"]:
+            conf = r["confinamiento"]
+            if ev["nivel_criticidad"] == "A" and conf["modo"] not in gate_cfg["confinamiento_aceptado_nivel_A"]:
+                propios.append(
+                    f"[G4] revisor {r['id_revisor']}: confinamiento '{conf['modo']}' no admitido en Nivel A "
+                    f"(el revisor solo lee, y eso se garantiza con permisos y no con la consigna)"
+                )
+            if not conf["verificado"] and gate_cfg.get("advertir_confinamiento_no_verificado", True):
+                advertencias.append(
+                    f"{ruta.name}: confinamiento del revisor {r['id_revisor']} sin verificacion posterior"
+                )
+
+        # G5: el commit revisado pertenece al rango del PR.
+        if commits is not None:
+            cc = ev["commit_cabeza"]
+            if not any(c.startswith(cc) or cc.startswith(c) for c in commits):
+                propios.append(
+                    f"[G5] commit revisado {cc} fuera del rango del PR ({base[:7]}..{cabeza[:7]})"
+                )
+
+        if propios:
+            errores_por_archivo[ruta.name] = propios
+        else:
+            validos.append(artefacto)
+
+    # G1: al menos un artefacto valido, salvo gate no requerido.
+    if gate_cfg.get("requerido", True) and not validos:
+        errores_gate.append(
+            "[G1] ningun artefacto de residuo valido para este PR "
+            f"(directorio '{directorio}'). La declaracion lista residuo concreto o dice "
+            "explicitamente que no hubo ninguno; un campo vacio no es una declaracion."
+        )
+
+    cuerpo = render_comentario(validos, errores_por_archivo, errores_gate)
+    if advertencias:
+        cuerpo += "\n\nAdvertencias:\n" + "\n".join(f"- {a}" for a in advertencias)
+
+    escribir_resumen(cuerpo)
+    if publicar:
+        estado = publicar_comentario(cuerpo)
+        print(f"[gate] {estado}")
+
+    fallo = bool(errores_gate or errores_por_archivo)
+    print(cuerpo)
+    print(f"\n[gate] {'FALLO' if fallo else 'OK'}: {len(validos)} artefacto(s) valido(s), "
+          f"{len(errores_por_archivo)} con errores, {len(errores_gate)} error(es) globales")
+    return 1 if fallo else 0
+
+
+def main_gate(args) -> int:
+    return correr_gate(
+        directorio=Path(args.directorio),
+        config_ruta=Path(args.config),
+        base=args.base,
+        cabeza=args.cabeza,
+        repo_dir=Path.cwd(),
+        publicar=not args.sin_comentario,
+    )

disensor/plantilla.py

@@ -0,0 +1,86 @@
+"""Scaffolding de un artefacto nuevo: `disensor nuevo`.
+
+Genera una plantilla prellenada con lo que git ya sabe (repositorio, commits,
+timestamp) y marcadores que no pasan la validacion hasta completarse. Una
+plantilla que valida vacia seria cumplimiento cosmetico de fabrica.
+"""
+from __future__ import annotations
+
+import datetime
+import json
+import subprocess
+import uuid
+from pathlib import Path
+
+
+def _git(args: list[str], cwd: Path) -> str:
+    r = subprocess.run(["git", *args], capture_output=True, text=True, cwd=cwd, check=False)
+    return r.stdout.strip() if r.returncode == 0 else ""
+
+
+def plantilla(compuerta: str, nivel: str, perfil: str, cwd: Path) -> dict:
+    ahora = datetime.datetime.now().astimezone().isoformat(timespec="seconds")
+    remoto = _git(["config", "--get", "remote.origin.url"], cwd) or "COMPLETAR_repositorio"
+    cabeza = _git(["rev-parse", "HEAD"], cwd) or "COMPLETAR"
+    base = _git(["merge-base", "HEAD", "origin/main"], cwd) or _git(
+        ["merge-base", "HEAD", "origin/master"], cwd
+    )
+    a: dict = {
+        "esquema": "residuo/v0.1",
+        "perfil": perfil,
+        "evento": {
+            "id_evento": str(uuid.uuid4()),
+            "creado_en": ahora,
+            "repositorio": remoto,
+            "commit_cabeza": cabeza,
+            "compuerta": compuerta,
+            "nivel_criticidad": nivel,
+            "ruta_abreviada": {"usada": False},
+        },
+        "actores": {
+            "generador": {"familia": "anthropic", "modelo": "claude-code"},
+            "revisores": [
+                {
+                    "id_revisor": "r1",
+                    "familia": "openai",
+                    "modelo": "COMPLETAR_modelo_del_revisor",
+                    "confinamiento": {
+                        "modo": "solo_lectura_por_instruccion",
+                        "verificado": False,
+                        "metodo_verificacion": "git_status_limpio",
+                    },
+                }
+            ],
+            "arbitro_humano": {"presente": True},
+        },
+        "hallazgos": [],
+        "residuo": {
+            "ausencia_declarada": True,
+            "declaracion": "COMPLETAR: declaracion expresa de ausencia, o reemplazar este objeto por items",
+        },
+        "metricas": {
+            "conteos": {
+                "total_hallazgos": 0,
+                "validos": {"incorporado": 0, "deuda_registrada": 0, "decision_del_dueno": 0},
+                "falsos_positivos": {"refutado_verificable": 0, "refutado_interpretativo": 0},
+                "escalados_abiertos": 0,
+            }
+        },
+    }
+    if base:
+        a["evento"]["commit_base"] = base
+    return a
+
+
+def main_nuevo(args) -> int:
+    directorio = Path(args.directorio)
+    directorio.mkdir(parents=True, exist_ok=True)
+    a = plantilla(args.compuerta, args.nivel, args.perfil, Path.cwd())
+    ruta = directorio / f"{a['evento']['id_evento']}.json"
+    with ruta.open("w", encoding="utf-8") as f:
+        json.dump(a, f, ensure_ascii=False, indent=2)
+        f.write("\n")
+    print(f"Plantilla creada: {ruta}")
+    print("Completar los campos COMPLETAR_ y los hallazgos del evento; despues: disensor validar", ruta)
+    print("Nota: la plantilla no valida hasta completarse. Es intencional.")
+    return 0

disensor/reglas.py

@@ -0,0 +1,197 @@
+"""Reglas de validacion del artefacto de residuo (esquema v0.1).
+
+Dos capas, en el espiritu de la seccion 12.2 del protocolo:
+  1. JSON Schema: forma y campos condicionales.
+  2. Reglas estructurales R0 a R10: coherencia que un schema no expresa.
+
+Limite honesto, declarado en el protocolo: la maquina detecta el campo vacio
+y el marcador generico, no la declaracion falsa. El muestreo humano sigue
+siendo la unica defensa real contra el cumplimiento cosmetico.
+"""
+from __future__ import annotations
+
+import json
+from importlib import resources
+
+from jsonschema import Draft202012Validator
+
+MARCADORES_GENERICOS = {
+    "n/a", "na", "ninguno", "ninguna", "todo resuelto", "aplicado",
+    "ok", "sin residuo", "-", "no aplica",
+}
+
+ESTADOS_A_RESIDUO = {"escalado_abierto", "refutado_verificable", "refutado_interpretativo"}
+
+CLASE_ESPERADA = {
+    "escalado_abierto": "escalado_sin_decision",
+    "refutado_verificable": "refutacion_del_principal",
+    "refutado_interpretativo": "refutacion_del_principal",
+}
+
+CAMPOS_TEXTO_PROHIBIDOS_MINIMIZADO = {"titulo", "descripcion", "ubicacion"}
+
+
+def cargar_schema() -> dict:
+    """Carga el schema empaquetado con la distribucion."""
+    with resources.files("disensor").joinpath("residuo.schema.json").open(encoding="utf-8") as f:
+        return json.load(f)
+
+
+def errores_schema(artefacto: dict, schema: dict) -> list[str]:
+    validador = Draft202012Validator(schema)
+    return [
+        f"[schema] {'/'.join(str(p) for p in err.path) or '(raiz)'}: {err.message}"
+        for err in sorted(validador.iter_errors(artefacto), key=lambda x: list(x.path))
+    ]
+
+
+def errores_reglas(a: dict) -> list[str]:
+    """Reglas estructurales sobre un artefacto ya valido contra el schema."""
+    e: list[str] = []
+
+    def error(regla: str, msg: str) -> None:
+        e.append(f"[{regla}] {msg}")
+
+    perfil = a["perfil"]
+    hallazgos = a.get("hallazgos", [])
+    residuo = a["residuo"]
+    items = residuo.get("items", [])
+    por_id = {h["id"]: h for h in hallazgos}
+    compuerta = a["evento"]["compuerta"]
+    nivel = a["evento"]["nivel_criticidad"]
+
+    # R0: sin arbitro humano el evento no cumple el protocolo (seccion 6).
+    if not a["actores"]["arbitro_humano"]["presente"]:
+        error("R0", "evento sin arbitro humano presente")
+
+    # R10: en perfil completo, la lista de hallazgos es obligatoria.
+    if perfil == "completo" and not hallazgos:
+        error("R10", "perfil completo sin lista de hallazgos")
+
+    # R1: todo hallazgo cuyo estado integra el residuo tiene su item, y todo
+    # item con referencia apunta a un hallazgo existente del estado correcto.
+    if hallazgos:
+        refs = {i.get("ref_hallazgo") for i in items if i.get("ref_hallazgo")}
+        for h in hallazgos:
+            if h["estado_final"] in ESTADOS_A_RESIDUO and h["id"] not in refs:
+                error("R1", f"hallazgo {h['id']} ({h['estado_final']}) sin item de residuo")
+        for i in items:
+            ref = i.get("ref_hallazgo")
+            if ref:
+                if ref not in por_id:
+                    error("R1", f"item {i['id']} referencia hallazgo inexistente {ref}")
+                else:
+                    est = por_id[ref]["estado_final"]
+                    if est in CLASE_ESPERADA and i["clase"] != CLASE_ESPERADA[est]:
+                        error("R1", f"item {i['id']} clase {i['clase']} no corresponde al estado {est} de {ref}")
+
+    # R2: sin marcadores genericos en las declaraciones de texto.
+    textos = []
+    if residuo.get("ausencia_declarada"):
+        textos.append(("residuo.declaracion", residuo.get("declaracion", "")))
+    for i in items:
+        if "descripcion" in i:
+            textos.append((f"residuo.items[{i['id']}].descripcion", i["descripcion"]))
+    for donde, t in textos:
+        if t.strip().lower() in MARCADORES_GENERICOS:
+            error("R2", f"marcador generico en {donde}: '{t}'")
+
+    # R2 bis: marcadores de plantilla sin completar, en cualquier campo.
+    # Sin esto, una plantilla de perfil minimizado validaria de fabrica.
+    def buscar_plantilla(valor, ruta: str) -> None:
+        if isinstance(valor, str) and valor.startswith("COMPLETAR"):
+            error("R2", f"marcador de plantilla sin completar en {ruta}")
+        elif isinstance(valor, dict):
+            for k, v in valor.items():
+                buscar_plantilla(v, f"{ruta}.{k}")
+        elif isinstance(valor, list):
+            for n, v in enumerate(valor):
+                buscar_plantilla(v, f"{ruta}[{n}]")
+
+    buscar_plantilla(a, "artefacto")
+
+    # R3: ruta abreviada incompatible con los cinco casos protegidos (3.2).
+    ra = a["evento"]["ruta_abreviada"]
+    if ra.get("usada") and ra.get("casos_protegidos_tocados"):
+        error("R3", "ruta abreviada usada sobre un cambio que toca casos protegidos de 3.2")
+
+    # R4: decorrelacion: ningun revisor modelo comparte familia con el generador.
+    fam_gen = a["actores"]["generador"]["familia"]
+    for r in a["actores"]["revisores"]:
+        if r["familia"] == fam_gen:
+            error("R4", f"revisor {r['id_revisor']} comparte familia ({fam_gen}) con el generador: sin decorrelacion")
+
+    # R5: Nivel A + gap de ejecucion exige aceptacion escrita de un referente (seccion 7).
+    if nivel == "A":
+        for i in items:
+            if i["clase"] == "gap_de_ejecucion" and "aceptacion_referente" not in i:
+                error("R5", f"item {i['id']}: gap de ejecucion en Nivel A sin aceptacion de referente (bloquea el merge)")
+
+    # R6: conteos coherentes con la lista de hallazgos (si esta presente).
+    if hallazgos:
+        c = a["metricas"]["conteos"]
+
+        def conteo(est: str) -> int:
+            return sum(1 for h in hallazgos if h["estado_final"] == est)
+
+        esperado = {
+            ("validos", "incorporado"): conteo("incorporado"),
+            ("validos", "deuda_registrada"): conteo("deuda_registrada"),
+            ("validos", "decision_del_dueno"): conteo("decision_del_dueno"),
+            ("falsos_positivos", "refutado_verificable"): conteo("refutado_verificable"),
+            ("falsos_positivos", "refutado_interpretativo"): conteo("refutado_interpretativo"),
+        }
+        for (grupo, campo), v in esperado.items():
+            if c[grupo][campo] != v:
+                error("R6", f"conteo {grupo}.{campo}={c[grupo][campo]} pero la lista tiene {v}")
+        if c["escalados_abiertos"] != conteo("escalado_abierto"):
+            error("R6", f"escalados_abiertos={c['escalados_abiertos']} pero la lista tiene {conteo('escalado_abierto')}")
+        if c["total_hallazgos"] != len(hallazgos):
+            error("R6", f"total_hallazgos={c['total_hallazgos']} pero la lista tiene {len(hallazgos)}")
+
+    # R7: en compuerta diff, todo incorporado cierra con la correccion verificada.
+    if compuerta == "diff":
+        for h in hallazgos:
+            if h["estado_final"] == "incorporado":
+                v = h.get("verificacion_de_la_correccion")
+                if not v:
+                    error("R7", f"hallazgo {h['id']} incorporado en compuerta diff sin verificacion de la correccion")
+                elif v["tipo"] == "pendiente_en_compuerta_diff":
+                    error("R7", f"hallazgo {h['id']}: la verificacion de la correccion no puede quedar pendiente en la propia compuerta diff")
+
+    # R8: refutacion interpretativa siempre pide atencion humana (seccion 6).
+    for i in items:
+        if i.get("tipo_refutacion") == "interpretativa" and not i.get("requiere_atencion_humana"):
+            error("R8", f"item {i['id']}: refutacion interpretativa con requiere_atencion_humana=false")
+
+    # R9: perfil minimizado no admite texto libre.
+    if perfil == "minimizado":
+        for h in hallazgos:
+            for campo in CAMPOS_TEXTO_PROHIBIDOS_MINIMIZADO & h.keys():
+                error("R9", f"hallazgo {h['id']}: campo '{campo}' prohibido en perfil minimizado")
+            ev = h.get("evidencia", {})
+            if "texto" in ev or "enlace" in ev:
+                error("R9", f"hallazgo {h['id']}: evidencia con texto o enlace en perfil minimizado (solo hash)")
+        for i in items:
+            if "descripcion" in i:
+                error("R9", f"item {i['id']}: descripcion prohibida en perfil minimizado")
+            ev = i.get("evidencia", {})
+            if "texto" in ev or "enlace" in ev:
+                error("R9", f"item {i['id']}: evidencia con texto o enlace en perfil minimizado (solo hash)")
+        if a["evento"]["repositorio"].startswith("http"):
+            error("R9", "perfil minimizado con URL de repositorio en claro (usar hash o identificador opaco)")
+
+    return e
+
+
+def validar_artefacto(artefacto: dict, schema: dict | None = None) -> list[str]:
+    """Valida un artefacto completo. Devuelve la lista de errores (vacia si es valido).
+
+    Si el schema falla, las reglas estructurales no se evaluan: operarian
+    sobre una forma que no esta garantizada.
+    """
+    schema = schema or cargar_schema()
+    errores = errores_schema(artefacto, schema)
+    if errores:
+        return errores
+    return errores_reglas(artefacto)