disensor 0.1.0__tar.gz

disensor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolas Rocchia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

disensor-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: disensor
+Version: 0.1.0
+Summary: disensor: adversarial plan & code review with a declared residue. Emite, valida y hace cumplir en CI declaraciones de residuo (esquema residuo/v0.1).
+Author-email: Nicolas Rocchia <nicolasrocchia@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema>=4.18
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# disensor
+
+Adversarial plan & code review with a declared residue.
+
+Declaración de residuo de revisión adversarial, con validación y gate de CI. Implementación de referencia del artefacto definido a partir del método de **desacuerdo controlado**: un modelo genera, un modelo de otra familia ataca, el generador verifica cada hallazgo, y el ciclo termina cuando todo hallazgo quedó resuelto, refutado con evidencia o escalado a un humano.
+
+El artefacto que este repo define y hace cumplir registra cómo terminó cada evento de revisión: los hallazgos con su estado terminal, y el **residuo**: lo que el ciclo no pudo cerrar por sí mismo y descansa sobre el juicio de alguien. La declaración lista residuo, no cobertura: dirige el escrutinio del revisor humano en lugar de leerse como sello de calidad.
+
+Paper del método: Rocchia, N. (2026), *Desacuerdo controlado: revisión adversarial automatizada con un segundo asistente de código en el desarrollo de software*, DOI [10.5281/zenodo.21633495](https://doi.org/10.5281/zenodo.21633495).
+
+## Qué hay acá
+
+- `spec/residuo.schema.json`: el esquema del artefacto (JSON Schema 2020-12), versión v0.1.
+- `spec/ejemplos/`: tres artefactos de ejemplo, incluido un evento real anonimizado y el perfil minimizado sin texto libre.
+- `src/disensor/`: paquete Python con el validador (reglas R0 a R10), el gate de CI (chequeos G1 a G5), el render del comentario de PR y el scaffolding de artefactos.
+- `action.yml`: GitHub Action compuesta, lista para usar.
+- `docs/integracion-claude-code.md`: cómo el flujo real (Claude Code + Codex) emite el artefacto al cierre de cada evento.
+
+## Uso rápido
+
+```bash
+pip install disensor     # para desarrollo, desde el repo clonado: pip install -e .
+
+disensor nuevo --compuerta diff --nivel B    # plantilla prellenada en .residuo/
+disensor validar .residuo/<id>.json          # schema + reglas R0 a R10
+disensor gate --sin-comentario               # lo que va a correr CI, en local
+```
+
+En el repositorio consumidor, `disensor.config.json` en la raíz declara el nivel de criticidad (el nivel viaja con el código, en un archivo versionado):
+
+```json
+{
+  "nivel_criticidad": "B",
+  "nivel_A_habilitado": false
+}
+```
+
+Y el workflow (ver `docs/ejemplo-workflow.yml`):
+
+```yaml
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: NicolasRocchia/disensor@v0.1.0
+```
+
+El gate valida todos los artefactos de `.residuo/` del PR, aplica la política y publica la declaración como comentario (se actualiza en el lugar en cada push).
+
+## Qué hace cumplir el gate
+
+Por artefacto (reglas R0 a R10): coherencia entre hallazgos y residuo, conteos que cierran, decorrelación de familias entre generador y revisor, evidencia obligatoria en refutaciones verificables, atención humana obligatoria en refutaciones interpretativas, corrección verificada antes de cerrar un hallazgo en compuerta de diff, rechazo de marcadores genéricos, y perfil minimizado sin fugas de texto.
+
+Por PR (chequeos G1 a G5): al menos una declaración válida en el rango, nivel del artefacto igual al declarado del repositorio, Nivel A bloqueado mientras la gobernanza no esté validada, política de confinamiento del revisor por nivel, y commit revisado dentro del rango del PR.
+
+Límite honesto, heredado del protocolo: la máquina detecta el campo vacío y el marcador genérico, no la declaración falsa. El muestreo humano de PR cerrados sigue siendo la única defensa real contra el cumplimiento cosmético.
+
+## Qué no hace
+
+No corre modelos, no pide claves de API en CI, y ningún código viaja a ningún servicio: valida un JSON que ya está versionado en el repo. La orquestación del loop vive donde el equipo ya trabaja; el perfil `minimizado` del artefacto permite ambientes donde ni siquiera el texto de los hallazgos puede salir del entorno.
+
+## Conformidad entre implementaciones
+
+`spec/vectores/` contiene los vectores de conformidad: 22 artefactos con su veredicto esperado (valido o no, y las etiquetas de regla que deben dispararse). Toda implementacion del validador tiene que pasarlos identicos: la referencia en Python los corre en la suite (`tests/test_vectores.py`) y el port TypeScript del plano de evidencia los corre con `npm run conformidad`. Se comparan etiquetas, no mensajes. Los vectores se regeneran con `python -m disensor.vectores spec/vectores`.
+
+`plano-evidencia/` contiene el Worker de ingesta (Cloudflare Workers mas D1) con el port TypeScript del validador y el recibo de integridad de solo agregado. Ver su README para el estado de verificacion y el despliegue.
+
+## Estado
+
+v0.1, borrador en uso. El esquema puede cambiar hasta v1.0; los cambios se declaran en el propio esquema. Dos decisiones abiertas antes de v0.2: claves del esquema en español o inglés, y licencia definitiva (hoy MIT; Apache-2.0 está en consideración por la concesión de patentes antes del release público).
+
+## Licencia
+
+MIT.

disensor-0.1.0/README.md

@@ -0,0 +1,81 @@
+# disensor
+
+Adversarial plan & code review with a declared residue.
+
+Declaración de residuo de revisión adversarial, con validación y gate de CI. Implementación de referencia del artefacto definido a partir del método de **desacuerdo controlado**: un modelo genera, un modelo de otra familia ataca, el generador verifica cada hallazgo, y el ciclo termina cuando todo hallazgo quedó resuelto, refutado con evidencia o escalado a un humano.
+
+El artefacto que este repo define y hace cumplir registra cómo terminó cada evento de revisión: los hallazgos con su estado terminal, y el **residuo**: lo que el ciclo no pudo cerrar por sí mismo y descansa sobre el juicio de alguien. La declaración lista residuo, no cobertura: dirige el escrutinio del revisor humano en lugar de leerse como sello de calidad.
+
+Paper del método: Rocchia, N. (2026), *Desacuerdo controlado: revisión adversarial automatizada con un segundo asistente de código en el desarrollo de software*, DOI [10.5281/zenodo.21633495](https://doi.org/10.5281/zenodo.21633495).
+
+## Qué hay acá
+
+- `spec/residuo.schema.json`: el esquema del artefacto (JSON Schema 2020-12), versión v0.1.
+- `spec/ejemplos/`: tres artefactos de ejemplo, incluido un evento real anonimizado y el perfil minimizado sin texto libre.
+- `src/disensor/`: paquete Python con el validador (reglas R0 a R10), el gate de CI (chequeos G1 a G5), el render del comentario de PR y el scaffolding de artefactos.
+- `action.yml`: GitHub Action compuesta, lista para usar.
+- `docs/integracion-claude-code.md`: cómo el flujo real (Claude Code + Codex) emite el artefacto al cierre de cada evento.
+
+## Uso rápido
+
+```bash
+pip install disensor     # para desarrollo, desde el repo clonado: pip install -e .
+
+disensor nuevo --compuerta diff --nivel B    # plantilla prellenada en .residuo/
+disensor validar .residuo/<id>.json          # schema + reglas R0 a R10
+disensor gate --sin-comentario               # lo que va a correr CI, en local
+```
+
+En el repositorio consumidor, `disensor.config.json` en la raíz declara el nivel de criticidad (el nivel viaja con el código, en un archivo versionado):
+
+```json
+{
+  "nivel_criticidad": "B",
+  "nivel_A_habilitado": false
+}
+```
+
+Y el workflow (ver `docs/ejemplo-workflow.yml`):
+
+```yaml
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: NicolasRocchia/disensor@v0.1.0
+```
+
+El gate valida todos los artefactos de `.residuo/` del PR, aplica la política y publica la declaración como comentario (se actualiza en el lugar en cada push).
+
+## Qué hace cumplir el gate
+
+Por artefacto (reglas R0 a R10): coherencia entre hallazgos y residuo, conteos que cierran, decorrelación de familias entre generador y revisor, evidencia obligatoria en refutaciones verificables, atención humana obligatoria en refutaciones interpretativas, corrección verificada antes de cerrar un hallazgo en compuerta de diff, rechazo de marcadores genéricos, y perfil minimizado sin fugas de texto.
+
+Por PR (chequeos G1 a G5): al menos una declaración válida en el rango, nivel del artefacto igual al declarado del repositorio, Nivel A bloqueado mientras la gobernanza no esté validada, política de confinamiento del revisor por nivel, y commit revisado dentro del rango del PR.
+
+Límite honesto, heredado del protocolo: la máquina detecta el campo vacío y el marcador genérico, no la declaración falsa. El muestreo humano de PR cerrados sigue siendo la única defensa real contra el cumplimiento cosmético.
+
+## Qué no hace
+
+No corre modelos, no pide claves de API en CI, y ningún código viaja a ningún servicio: valida un JSON que ya está versionado en el repo. La orquestación del loop vive donde el equipo ya trabaja; el perfil `minimizado` del artefacto permite ambientes donde ni siquiera el texto de los hallazgos puede salir del entorno.
+
+## Conformidad entre implementaciones
+
+`spec/vectores/` contiene los vectores de conformidad: 22 artefactos con su veredicto esperado (valido o no, y las etiquetas de regla que deben dispararse). Toda implementacion del validador tiene que pasarlos identicos: la referencia en Python los corre en la suite (`tests/test_vectores.py`) y el port TypeScript del plano de evidencia los corre con `npm run conformidad`. Se comparan etiquetas, no mensajes. Los vectores se regeneran con `python -m disensor.vectores spec/vectores`.
+
+`plano-evidencia/` contiene el Worker de ingesta (Cloudflare Workers mas D1) con el port TypeScript del validador y el recibo de integridad de solo agregado. Ver su README para el estado de verificacion y el despliegue.
+
+## Estado
+
+v0.1, borrador en uso. El esquema puede cambiar hasta v1.0; los cambios se declaran en el propio esquema. Dos decisiones abiertas antes de v0.2: claves del esquema en español o inglés, y licencia definitiva (hoy MIT; Apache-2.0 está en consideración por la concesión de patentes antes del release público).
+
+## Licencia
+
+MIT.

disensor-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "disensor"
+version = "0.1.0"
+description = "disensor: adversarial plan & code review with a declared residue. Emite, valida y hace cumplir en CI declaraciones de residuo (esquema residuo/v0.1)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Nicolas Rocchia", email = "nicolasrocchia@gmail.com" }]
+dependencies = ["jsonschema>=4.18"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.scripts]
+disensor = "disensor.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+disensor = ["residuo.schema.json"]

disensor-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

disensor-0.1.0/src/disensor/__init__.py

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

disensor-0.1.0/src/disensor/__main__.py

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

disensor-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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