disensor 0.1.0__tar.gz → 0.2.0__tar.gz

disensor-0.2.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: disensor
+Version: 0.2.0
+Summary: Adversarial plan & code review with a declared residue. Emits, validates and CI-enforces residue declarations (residue/v0.2 schema).
+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.
+
+**English**: disensor emits, validates and CI-enforces *residue declarations*: a JSON artifact that records how each adversarial review event ended (one model generates, a model from another family attacks, every finding reaches a terminal state) and, above all, what the cycle could NOT close by itself. Install with `pip install disensor`, scaffold a repo with `disensor init`. As of v0.2 the whole contract (schema keys, enums, CLI) is English; the docs below are in Spanish, and the ES-EN glossary at the end maps the paper's terminology to the schema.
+
+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/residue.schema.json`: el esquema del artefacto (JSON Schema 2020-12), versión residue/v0.2.
+- `spec/examples/`: 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, el scaffolding de artefactos y el de repositorios (`init`).
+- `action.yml`: GitHub Action compuesta, lista para usar.
+- `docs/integracion-claude-code.md`: cómo el flujo real (Claude Code más un revisor de otra familia) emite el artefacto al cierre de cada evento.
+
+## Uso rápido
+
+El paquete se instala una vez (global); cada repositorio se inicializa una vez:
+
+```bash
+pip install disensor        # o pipx install disensor, recomendado para CLIs
+
+disensor init               # en la raíz del repo: config, sección de CLAUDE.md y workflow de CI
+disensor new --gate diff --level B     # plantilla prellenada en .residue/
+disensor validate .residue/<id>.json   # schema + reglas R0 a R10
+disensor gate --no-comment             # lo que va a correr CI, en local
+```
+
+Los subcomandos y flags de la v0.1 en español (`nuevo`, `validar`, `--compuerta`, `--nivel`, `--directorio`, `--sin-comentario`) siguen funcionando como alias.
+
+`disensor init` escribe, en forma idempotente, el `disensor.config.json` (el nivel viaja con el código, en un archivo versionado), la sección de cierre de evento en `CLAUDE.md` y el workflow del gate; lo que ya existe se respeta y se informa. Config resultante:
+
+```json
+{
+  "criticality_level": "B",
+  "level_A_enabled": 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.2.0
+```
+
+El gate valida todos los artefactos de `.residue/` 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 (en inglés y en español), 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 `minimized` del artefacto permite ambientes donde ni siquiera el texto de los hallazgos puede salir del entorno.
+
+## Conformidad entre implementaciones
+
+`spec/vectors/` contiene los vectores de conformidad: 22 artefactos con su veredicto esperado (válido o no, y las etiquetas de regla que deben dispararse). Toda implementación del validador tiene que pasarlos idénticos: la referencia en Python los corre en la suite (`tests/test_vectors.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.vectors spec/vectors`.
+
+`plano-evidencia/` contiene el Worker de ingesta (Cloudflare Workers más D1) con el port TypeScript del validador y el recibo de integridad de solo agregado. Ver su README para el estado de verificación y el despliegue.
+
+## Glosario ES-EN
+
+La terminología del paper es en español; el contrato (claves y enums del esquema, CLI) es en inglés desde v0.2. Equivalencias principales:
+
+| Paper (ES) | Esquema/CLI (EN) |
+|---|---|
+| residuo | residue |
+| hallazgo | finding |
+| compuerta (plan, diff, arquitectura) | gate (plan, diff, architecture) |
+| nivel de criticidad | criticality_level |
+| perfil completo / minimizado | profile full / minimized |
+| actores: generador, revisores, árbitro humano | actors: generator, reviewers, human_arbiter |
+| familia (de modelo) | family |
+| confinamiento (permisos, sandbox, solo lectura por instrucción) | confinement (permissions, sandbox, read_only_by_instruction) |
+| consigna (hash de la consigna adversarial) | prompt_hash |
+| estado final: incorporado, deuda registrada, decisión del dueño, refutado verificable, refutado interpretativo, escalado abierto | final_state: incorporated, debt_recorded, owner_decision, refuted_verifiable, refuted_interpretive, escalated_open |
+| clases de residuo: escalado sin decisión, refutación del principal, gap de ejecución | residue classes: escalation_without_decision, principal_refutation, execution_gap |
+| ruta abreviada / casos protegidos | abbreviated_path / protected_cases_touched |
+| verificación de la corrección | fix_verification |
+| aceptación de referente | lead_acceptance |
+| ausencia declarada / declaración | declared_absence / declaration |
+| métricas: conteos, válidos, falsos positivos | metrics: counts, valid, false_positives |
+
+Migración desde v0.1: renombrar `.residuo/` a `.residue/`, las claves del config (`nivel_criticidad` a `criticality_level`, `nivel_A_habilitado` a `level_A_enabled`) y las claves de los artefactos según el glosario. El validador reconoce artefactos v0.1 y lo dice explícitamente; el gate rechaza en voz alta un config con claves viejas en lugar de aplicar defaults en silencio.
+
+## Estado
+
+v0.2, borrador en uso. Decisión cerrada en v0.2: claves del esquema y CLI en inglés (el español queda como alias en la CLI y como idioma de la documentación). El esquema puede cambiar hasta v1.0; los cambios se declaran en el propio esquema. Decisión abierta antes de v1.0: 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.2.0/README.md

@@ -0,0 +1,113 @@
+# disensor
+
+Adversarial plan & code review with a declared residue.
+
+**English**: disensor emits, validates and CI-enforces *residue declarations*: a JSON artifact that records how each adversarial review event ended (one model generates, a model from another family attacks, every finding reaches a terminal state) and, above all, what the cycle could NOT close by itself. Install with `pip install disensor`, scaffold a repo with `disensor init`. As of v0.2 the whole contract (schema keys, enums, CLI) is English; the docs below are in Spanish, and the ES-EN glossary at the end maps the paper's terminology to the schema.
+
+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/residue.schema.json`: el esquema del artefacto (JSON Schema 2020-12), versión residue/v0.2.
+- `spec/examples/`: 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, el scaffolding de artefactos y el de repositorios (`init`).
+- `action.yml`: GitHub Action compuesta, lista para usar.
+- `docs/integracion-claude-code.md`: cómo el flujo real (Claude Code más un revisor de otra familia) emite el artefacto al cierre de cada evento.
+
+## Uso rápido
+
+El paquete se instala una vez (global); cada repositorio se inicializa una vez:
+
+```bash
+pip install disensor        # o pipx install disensor, recomendado para CLIs
+
+disensor init               # en la raíz del repo: config, sección de CLAUDE.md y workflow de CI
+disensor new --gate diff --level B     # plantilla prellenada en .residue/
+disensor validate .residue/<id>.json   # schema + reglas R0 a R10
+disensor gate --no-comment             # lo que va a correr CI, en local
+```
+
+Los subcomandos y flags de la v0.1 en español (`nuevo`, `validar`, `--compuerta`, `--nivel`, `--directorio`, `--sin-comentario`) siguen funcionando como alias.
+
+`disensor init` escribe, en forma idempotente, el `disensor.config.json` (el nivel viaja con el código, en un archivo versionado), la sección de cierre de evento en `CLAUDE.md` y el workflow del gate; lo que ya existe se respeta y se informa. Config resultante:
+
+```json
+{
+  "criticality_level": "B",
+  "level_A_enabled": 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.2.0
+```
+
+El gate valida todos los artefactos de `.residue/` 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 (en inglés y en español), 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 `minimized` del artefacto permite ambientes donde ni siquiera el texto de los hallazgos puede salir del entorno.
+
+## Conformidad entre implementaciones
+
+`spec/vectors/` contiene los vectores de conformidad: 22 artefactos con su veredicto esperado (válido o no, y las etiquetas de regla que deben dispararse). Toda implementación del validador tiene que pasarlos idénticos: la referencia en Python los corre en la suite (`tests/test_vectors.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.vectors spec/vectors`.
+
+`plano-evidencia/` contiene el Worker de ingesta (Cloudflare Workers más D1) con el port TypeScript del validador y el recibo de integridad de solo agregado. Ver su README para el estado de verificación y el despliegue.
+
+## Glosario ES-EN
+
+La terminología del paper es en español; el contrato (claves y enums del esquema, CLI) es en inglés desde v0.2. Equivalencias principales:
+
+| Paper (ES) | Esquema/CLI (EN) |
+|---|---|
+| residuo | residue |
+| hallazgo | finding |
+| compuerta (plan, diff, arquitectura) | gate (plan, diff, architecture) |
+| nivel de criticidad | criticality_level |
+| perfil completo / minimizado | profile full / minimized |
+| actores: generador, revisores, árbitro humano | actors: generator, reviewers, human_arbiter |
+| familia (de modelo) | family |
+| confinamiento (permisos, sandbox, solo lectura por instrucción) | confinement (permissions, sandbox, read_only_by_instruction) |
+| consigna (hash de la consigna adversarial) | prompt_hash |
+| estado final: incorporado, deuda registrada, decisión del dueño, refutado verificable, refutado interpretativo, escalado abierto | final_state: incorporated, debt_recorded, owner_decision, refuted_verifiable, refuted_interpretive, escalated_open |
+| clases de residuo: escalado sin decisión, refutación del principal, gap de ejecución | residue classes: escalation_without_decision, principal_refutation, execution_gap |
+| ruta abreviada / casos protegidos | abbreviated_path / protected_cases_touched |
+| verificación de la corrección | fix_verification |
+| aceptación de referente | lead_acceptance |
+| ausencia declarada / declaración | declared_absence / declaration |
+| métricas: conteos, válidos, falsos positivos | metrics: counts, valid, false_positives |
+
+Migración desde v0.1: renombrar `.residuo/` a `.residue/`, las claves del config (`nivel_criticidad` a `criticality_level`, `nivel_A_habilitado` a `level_A_enabled`) y las claves de los artefactos según el glosario. El validador reconoce artefactos v0.1 y lo dice explícitamente; el gate rechaza en voz alta un config con claves viejas en lugar de aplicar defaults en silencio.
+
+## Estado
+
+v0.2, borrador en uso. Decisión cerrada en v0.2: claves del esquema y CLI en inglés (el español queda como alias en la CLI y como idioma de la documentación). El esquema puede cambiar hasta v1.0; los cambios se declaran en el propio esquema. Decisión abierta antes de v1.0: 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 → disensor-0.2.0}/pyproject.toml

@@ -4,8 +4,8 @@ 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)."
+version = "0.2.0"
+description = "Adversarial plan & code review with a declared residue. Emits, validates and CI-enforces residue declarations (residue/v0.2 schema)."
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }
@@ -22,4 +22,4 @@ disensor = "disensor.cli:main"
 where = ["src"]
 
 [tool.setuptools.package-data]
-disensor = ["residuo.schema.json"]
+disensor = ["residue.schema.json"]

disensor-0.2.0/src/disensor/__init__.py

@@ -0,0 +1,2 @@
+"""disensor: residue declaration of adversarial review (controlled disagreement)."""
+__version__ = "0.2.0"

disensor-0.2.0/src/disensor/cli.py

@@ -0,0 +1,79 @@
+"""Command line interface: disensor {init, new, validate, gate}.
+
+v0.1 was published with Spanish subcommands and flags; they remain as
+aliases (nuevo, validar, and the Spanish long flags) so existing scripts
+and muscle memory keep working.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .gate import main_gate
+from .init import main_init
+from .rules import load_schema, validate_artifact
+from .template import main_new
+
+
+def main_validate(args) -> int:
+    schema = load_schema()
+    failed = False
+    for path in args.files:
+        with open(path, encoding="utf-8") as f:
+            artifact = json.load(f)
+        errors = validate_artifact(artifact, schema)
+        print(f"{path}: {'VALID' if not errors else 'INVALID'}")
+        for msg in errors:
+            print(f"  {msg}")
+        failed = failed or bool(errors)
+    return 1 if failed else 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="disensor",
+        description="Residue declaration of adversarial review (controlled disagreement).",
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser("init", help="Scaffold a repository: config, CLAUDE.md section and CI workflow.")
+    init.add_argument("--level", "--nivel", choices=["A", "B", "C"], default="B")
+    init.add_argument("--no-claude", action="store_true", help="Do not touch CLAUDE.md.")
+    init.add_argument("--claude-global", action="store_true",
+                      help="Write the Claude Code section to ~/.claude/CLAUDE.md instead of the repo.")
+    init.add_argument("--no-workflow", action="store_true", help="Do not write the CI workflow.")
+    init.set_defaults(func=main_init)
+
+    new = sub.add_parser("new", aliases=["nuevo"],
+                         help="Create an artifact template for the current event.")
+    new.add_argument("--directory", "--directorio", default=".residue")
+    new.add_argument("--gate", "--compuerta", choices=["plan", "diff", "architecture"], default="diff")
+    new.add_argument("--level", "--nivel", choices=["A", "B", "C"], default="B")
+    new.add_argument("--profile", "--perfil", choices=["full", "minimized"], default="full")
+    new.set_defaults(func=main_new)
+
+    validate = sub.add_parser("validate", aliases=["validar"],
+                              help="Validate artifacts against the schema and rules R0 to R10.")
+    validate.add_argument("files", nargs="+")
+    validate.set_defaults(func=main_validate)
+
+    gate = sub.add_parser("gate", help="CI gate: validates the whole PR and applies policy G1 to G5.")
+    gate.add_argument("--directory", "--directorio", default=".residue")
+    gate.add_argument("--config", default="disensor.config.json")
+    gate.add_argument("--base", default=None, help="Base SHA of the PR (defaults to the GitHub event).")
+    gate.add_argument("--head", "--cabeza", default=None, help="Head SHA of the PR (defaults to the GitHub event).")
+    gate.add_argument("--no-comment", "--sin-comentario", action="store_true",
+                      help="Do not post a comment on the PR.")
+    gate.set_defaults(func=main_gate)
+    return p
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

disensor-0.2.0/src/disensor/gate.py

@@ -0,0 +1,257 @@
+"""CI gate: validates the residue declarations of a PR and applies policy.
+
+Gate checks (on top of the per-artifact R0 to R10 of rules.py):
+  G1: at least one valid artifact in the PR range, unless the configuration
+      declares the gate as not required (typical in Level C).
+  G2: the artifact level matches the declared level of the repository
+      (section 12.2: criticality level declared in a repo file).
+  G3: Level A blocked while governance is not validated
+      (section 3.1: Level A does not start until section 10 is validated).
+  G4: confinement policy per level (section 10: the reviewer only reads,
+      and that is guaranteed with permissions, not with the brief).
+  G5: the reviewed commit belongs to the PR range.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import urllib.request
+from pathlib import Path
+
+from .render import MARKER, render_comment
+from .rules import load_schema, validate_artifact
+
+DEFAULT_CONFIG = {
+    "criticality_level": "B",
+    "level_A_enabled": False,
+    "gate": {
+        "required": True,
+        "level_A_accepted_confinement": ["permissions", "sandbox"],
+        "warn_unverified_confinement": True,
+    },
+}
+
+V01_CONFIG_KEYS = {"nivel_criticidad", "nivel_A_habilitado"}
+
+
+def load_config(path: Path) -> dict:
+    if not path.exists():
+        return dict(DEFAULT_CONFIG)
+    with path.open(encoding="utf-8") as f:
+        config = json.load(f)
+    old_keys = V01_CONFIG_KEYS & set(config)
+    if old_keys:
+        raise SystemExit(
+            f"{path}: v0.1 Spanish keys found ({', '.join(sorted(old_keys))}). "
+            "disensor 0.2 renamed the configuration to English: nivel_criticidad -> "
+            "criticality_level, nivel_A_habilitado -> level_A_enabled, gate.requerido -> "
+            "gate.required, gate.confinamiento_aceptado_nivel_A -> gate.level_A_accepted_confinement, "
+            "gate.advertir_confinamiento_no_verificado -> gate.warn_unverified_confinement. "
+            "Failing loudly instead of silently applying defaults."
+        )
+    combined = dict(DEFAULT_CONFIG)
+    combined.update({k: v for k, v in config.items() if k != "gate"})
+    gate = dict(DEFAULT_CONFIG["gate"])
+    gate.update(config.get("gate", {}))
+    combined["gate"] = gate
+    return combined
+
+
+def pr_range(base: str | None, head: str | None) -> tuple[str | None, str | None]:
+    """Base and head of the PR: flags first, then the GitHub event."""
+    if base and head:
+        return base, head
+    event_path = os.environ.get("GITHUB_EVENT_PATH")
+    if event_path and Path(event_path).exists():
+        with open(event_path, encoding="utf-8") as f:
+            event = json.load(f)
+        pr = event.get("pull_request") or {}
+        return (
+            base or (pr.get("base") or {}).get("sha"),
+            head or (pr.get("head") or {}).get("sha"),
+        )
+    return base, head
+
+
+def range_commits(base: str, head: str, cwd: Path) -> list[str] | None:
+    """Commits of the base..head range, head included.
+
+    Returns None if git cannot resolve the range (shallow clone, unknown
+    shas): that is a warning. An empty list is a valid result and means the
+    range contains no commits: G5 must still be evaluated, because an empty
+    range cannot contain the reviewed commit.
+    """
+    r = subprocess.run(
+        ["git", "rev-list", f"{base}..{head}"],
+        capture_output=True, text=True, cwd=cwd, check=False,
+    )
+    if r.returncode != 0:
+        return None
+    return [line.strip() for line in r.stdout.splitlines() if line.strip()]
+
+
+def pr_number() -> int | None:
+    event_path = os.environ.get("GITHUB_EVENT_PATH")
+    if event_path and Path(event_path).exists():
+        with open(event_path, encoding="utf-8") as f:
+            event = json.load(f)
+        pr = event.get("pull_request") or {}
+        return pr.get("number")
+    return None
+
+
+def post_comment(body: str) -> str:
+    """Creates or updates the gate comment on the PR. Returns a readable status."""
+    token = os.environ.get("GITHUB_TOKEN")
+    repo = os.environ.get("GITHUB_REPOSITORY")
+    pr = pr_number()
+    if not (token and repo and pr):
+        return "no token, repository or PR number: comment not posted"
+    api = os.environ.get("GITHUB_API_URL", "https://api.github.com")
+    headers = {
+        "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=headers
+        )
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            comments = json.load(resp)
+        existing = next((c for c in comments if MARKER in (c.get("body") or "")), None)
+        data = json.dumps({"body": body}).encode("utf-8")
+        if existing:
+            req = urllib.request.Request(
+                f"{api}/repos/{repo}/issues/comments/{existing['id']}",
+                data=data, headers=headers, method="PATCH",
+            )
+        else:
+            req = urllib.request.Request(
+                f"{api}/repos/{repo}/issues/{pr}/comments",
+                data=data, headers=headers, method="POST",
+            )
+        with urllib.request.urlopen(req, timeout=30):
+            pass
+        return "comment updated" if existing else "comment posted"
+    except Exception as exc:  # the gate must not crash on network issues
+        return f"could not post the comment: {exc}"
+
+
+def write_summary(body: str) -> None:
+    path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if path:
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(body + "\n")
+
+
+def run_gate(directory: Path, config_path: Path, base: str | None,
+             head: str | None, repo_dir: Path, post: bool = True) -> int:
+    config = load_config(config_path)
+    schema = load_schema()
+    gate_cfg = config["gate"]
+
+    gate_errors: list[str] = []
+    warnings: list[str] = []
+    errors_by_file: dict[str, list[str]] = {}
+    valid: list[dict] = []
+
+    base, head = pr_range(base, head)
+    commits = range_commits(base, head, repo_dir) if (base and head) else None
+    if commits is None and base and head:
+        warnings.append(
+            "could not resolve the commit range (checkout with fetch-depth 0): G5 not evaluated"
+        )
+
+    files = sorted(p for p in directory.glob("*.json")) if directory.exists() else []
+    for path in files:
+        with path.open(encoding="utf-8") as f:
+            try:
+                artifact = json.load(f)
+            except json.JSONDecodeError as exc:
+                errors_by_file[path.name] = [f"invalid JSON: {exc}"]
+                continue
+        errors = validate_artifact(artifact, schema)
+        if errors:
+            errors_by_file[path.name] = errors
+            continue
+
+        ev = artifact["event"]
+        own: list[str] = []
+
+        # G2: artifact level against the declared level of the repository.
+        if ev["criticality_level"] != config["criticality_level"]:
+            own.append(
+                f"[G2] artifact level ({ev['criticality_level']}) differs from the one declared "
+                f"in the repository ({config['criticality_level']})"
+            )
+
+        # G3: Level A blocked until governance is validated (section 3.1).
+        if ev["criticality_level"] == "A" and not config.get("level_A_enabled", False):
+            own.append(
+                "[G3] Level A blocked: data governance (section 10) is not validated "
+                "in this repository (level_A_enabled=false). Applying the protocol at Level A "
+                "in this situation is not half-compliance: it is a violation."
+            )
+
+        # G4: confinement policy per level.
+        for r in artifact["actors"]["reviewers"]:
+            conf = r["confinement"]
+            if ev["criticality_level"] == "A" and conf["mode"] not in gate_cfg["level_A_accepted_confinement"]:
+                own.append(
+                    f"[G4] reviewer {r['reviewer_id']}: confinement '{conf['mode']}' not admitted in Level A "
+                    f"(the reviewer only reads, and that is guaranteed with permissions, not with the brief)"
+                )
+            if not conf["verified"] and gate_cfg.get("warn_unverified_confinement", True):
+                warnings.append(
+                    f"{path.name}: confinement of reviewer {r['reviewer_id']} without post-run verification"
+                )
+
+        # G5: the reviewed commit belongs to the PR range.
+        if commits is not None:
+            hc = ev["head_commit"]
+            if not any(c.startswith(hc) or hc.startswith(c) for c in commits):
+                own.append(
+                    f"[G5] reviewed commit {hc} outside the PR range ({base[:7]}..{head[:7]})"
+                )
+
+        if own:
+            errors_by_file[path.name] = own
+        else:
+            valid.append(artifact)
+
+    # G1: at least one valid artifact, unless the gate is not required.
+    if gate_cfg.get("required", True) and not valid:
+        gate_errors.append(
+            "[G1] no valid residue artifact for this PR "
+            f"(directory '{directory}'). The declaration lists concrete residue or says "
+            "explicitly that there was none; an empty field is not a declaration."
+        )
+
+    body = render_comment(valid, errors_by_file, gate_errors)
+    if warnings:
+        body += "\n\nWarnings:\n" + "\n".join(f"- {w}" for w in warnings)
+
+    write_summary(body)
+    if post:
+        status = post_comment(body)
+        print(f"[gate] {status}")
+
+    failed = bool(gate_errors or errors_by_file)
+    print(body)
+    print(f"\n[gate] {'FAILED' if failed else 'OK'}: {len(valid)} valid artifact(s), "
+          f"{len(errors_by_file)} with errors, {len(gate_errors)} global error(s)")
+    return 1 if failed else 0
+
+
+def main_gate(args) -> int:
+    return run_gate(
+        directory=Path(args.directory),
+        config_path=Path(args.config),
+        base=args.base,
+        head=args.head,
+        repo_dir=Path.cwd(),
+        post=not args.no_comment,
+    )