disensor

Adversarial plan & code review with a declared residue.

Este documento también está en español.

Residue declaration of adversarial review, with validation and a CI gate. Reference implementation of the artifact defined by the controlled disagreement method: one model generates, a model from another family attacks, the generator verifies every finding, and the cycle ends when each finding has been resolved, refuted with evidence, or escalated to a human.

The artifact this repo defines and enforces records how each review event ended: the findings with their terminal state, and the residue: what the cycle could not close by itself and rests on someone's judgement. The declaration lists residue, not coverage: it aims the human reviewer's scrutiny instead of reading as a seal of quality.

Method paper: 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. The paper is in Spanish; the glossary at the end maps its terminology to the schema.

What is here

• spec/residue.schema.json: the artifact schema (JSON Schema 2020-12), version residue/v0.3.
• spec/examples/: three example artifacts, including a real anonymised event and the minimized profile with no free text.
• src/disensor/: Python package with the validator (rules R0 to R10), the CI gate (checks G1 to G9), the PR comment rendering, artifact and repository scaffolding (init), and the packaged filling guide (GUIDE.md).
• action.yml: composite GitHub Action, ready to use.
• docs/integracion-claude-code.md (Spanish only): how the real flow (Claude Code plus a reviewer from another family) emits the artifact at the close of each event.
• docs/antecedentes.md (Spanish only): where the method sits relative to the literature (residual doubt and defeaters, design rationale and its capture bottleneck, multi-agent adversarial review, governance runtimes, supply chain provenance), with the verification status of each reference.

Quick start

The package is installed once (globally); each repository is initialised once:

pip install disensor        # or pipx install disensor, recommended for CLIs

disensor init               # at the repo root: config, CLAUDE.md, filling skill and CI workflow

disensor prompt --gate diff            # the adversarial brief, to hand to a reviewer from another family
disensor new --gate diff --level B     # template prefilled in .residue/
disensor validate .residue/<id>.json   # schema + rules R0 to R10
disensor gate --no-comment             # what CI will run, locally

disensor guide                         # the filling guide, for any agent or human
disensor guide --lang es               # the same guide in Spanish
disensor prompt --gate diff --hash     # the sha256: of the packaged brief, which is what prompt_hash wants
disensor hash consigna.md              # or the hash of yours, if you wrote it

The brief ships inside the package, so its hash is reproducible: anyone can recompute it from the same version and see what the reviewer was actually asked. If you edit it, the hash changes and the artifact declares that a different brief was used, which is exactly what the field is for.

Trying it without touching your CI

There are two modes and it pays not to mix them. To try it, you need no workflow, no required checks and no organisation permissions: the gate runs the same on your machine and says exactly what it would say in CI.

disensor init --no-workflow          # config, CLAUDE.md and skill; without touching .github/
disensor prompt --gate diff          # the brief, to the reviewer from another family
disensor new --gate diff --level B   # and you fill the declaration with what happened
disensor validate .residue/<id>.json
disensor gate --no-comment --base <base-sha> --head HEAD

Only when you want it to enforce do you run the full disensor init (which writes the workflow) and apply the deployment requirements below. Before that it is a tool that tells you how you would do; after that it is a control that blocks.

The Spanish v0.1 subcommands and flags (nuevo, validar, --compuerta, --nivel, --directorio, --sin-comentario) still work as aliases.

disensor init writes, idempotently, the disensor.config.json (the level travels with the code, in a versioned file), the event-close section in CLAUDE.md, the Claude Code skill with the full filling guide (.claude/skills/disensor/SKILL.md, loaded on demand at the close of each round) and the gate workflow; whatever already exists is respected and reported. The principle is that after pip install disensor and disensor init the user touches nothing by hand: Claude knows when (CLAUDE.md) and how (the skill), any other agent gets the same with disensor guide, and CI enforces the result. Resulting config:

{
  "criticality_level": "B",
  "level_A_enabled": false
}

And the workflow (see docs/ejemplo-workflow.yml):

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.6.4

The gate validates the declarations the PR adds, applies the policy and posts the result as a comment (updated in place on every push). Everything it decides comes from git objects in the merge-base..head range, never from the working tree: on a pull_request event the checkout leaves the synthetic merge commit while head.sha points at the real head, so reading from disk would classify one tree and validate another.

What the gate enforces

Per artifact (rules R0 to R10): coherence between findings and residue, counts that add up, family decorrelation between generator and reviewer, mandatory material evidence in verifiable refutations (text, link or hash) against a verifiable target (verification.against other than none), mandatory human attention in interpretive refutations, a fix verified before closing a finding in a diff gate, rejection of generic markers (in English and in Spanish), and a minimized profile with the free text R9 covers stripped.

Per artifact, against the PR: level equal to the repository's declared one (G2), Level A blocked while governance is not validated (G3), reviewer confinement policy per level (G4), and membership of the reviewed commit in the PR (G5), which for the diff gate also requires base_commit, because a diff review identifies the pair (reviewed base, reviewed head) and not a loose head.

Per PR:

• G1: if the PR touches paths that require review, it adds at least one valid declaration.
• G6, coverage: every changed path is covered by a declaration whose gate the scope policy accepts for that path, and which qualifies for it, meaning the path did not change between the reviewed commit and the head. A stale declaration covers nothing.
• G7, integration witness: some declaration saw the complete final tree. Path-by-path coverage is not enough: two side branches reviewed separately and later merged cover every path between them while nobody reviewed the integration.
• G8, evidence is append-only: a PR cannot modify, delete or rename declarations that were already there, nor reuse an existing event_id.
• G9, new declarations state the current version: a declaration the PR adds has to declare residue/v0.3. Superseded versions are still read so that history is not rewritten; that readability is not a permit to keep emitting under the weaker rules. The evidence plane applies the same criterion at ingestion.

The gate fails closed: if it cannot resolve the PR range, it does not go green. A compliance control that cannot decide does not approve.

Honest limit, inherited from the protocol: the machine detects the empty field and the generic marker, not the false declaration. Human sampling of merged PRs remains the only real defence against cosmetic compliance.

Scope policy

Which gate is accepted for each path is declared in the config, and is always read from the current tip of the target branch, never from the PR checkout. From the target and not from the merge-base, which is a different question: the merge-base is as old as the branch, so a branch created before the repository hardened its policy would drag the old one along. The PR scope is measured against the merge-base; the policy that governs is the one the target has today. That is why a PR that changes the policy is judged by the previous policy, which is correct and also avoids the mutual deadlock of the naive design, where the PR that loosens the configuration is rejected by the very rule it wants to change and no transition is possible.

{
  "criticality_level": "B",
  "level_A_enabled": false,
  "gate": {
    "required": true,
    "scope": [
      { "paths": ["docs/adr/**"], "accepts": ["architecture", "diff"] },
      { "paths": ["CHANGELOG.md"], "accepts": [] },
      { "paths": ["**"], "accepts": ["diff"] }
    ]
  }
}

The first matching entry wins. accepts: [] is an explicit exemption, which is the governed way out for changelogs or automated PRs. Patterns are anchored at the root, * does not cross /, ** matches zero or more complete segments, and matching is case sensitive byte by byte so that the same policy means the same thing on any runner. A path that matches nothing requires diff: the absence of policy is not a permit.

Non-relaxable floor: the effective configuration path, .github/workflows/** and the evidence directory always require diff, whatever scope says. Without that floor, an innocent-looking policy such as **/*.yml with architecture would downgrade the workflows, which are the source of the control itself.

Deployment requirements

This is a requirement, not a suggestion. The gate runs inside the workflow it audits, so there is a boundary no code of its own can cross and the platform has to resolve:

• Strict required check (or merge queue) on pull_request, so that the check has to correspond to the latest head.
• CODEOWNERS over the effective configuration path (it may not be called disensor.config.json if --config is used) and over .github/workflows/.
• Organisation ruleset or required workflow, defined outside the audited repository.
• Pin the Action by SHA, not by tag: a tag is movable and is not a root of trust. disensor init writes the tag of the installed version for convenience, and the generated workflow itself warns that it has to be replaced by the SHA that tag points at. This repository's documentation also uses the tag, because it documents which version corresponds; the SHA is put there by whoever deploys.
• Bootstrap: the first PR that adds the config and the workflow cannot make itself the root of trust. Initial activation is an administrative step, prior to the gate meaning anything.

Explicit limit: reading the policy from the base turns a one-step bypass into a two-step one, it does not eliminate it. Whoever can merge a relaxation uses it on the next PR. And none of this protects against a workflow that was modified, skipped or replaced. Only the platform resolves that.

What it does not do

It runs no models, asks for no API keys in CI, and no code travels to any service: it validates a JSON that is already versioned in the repo. Orchestrating the loop lives where the team already works; the artifact's minimized profile is meant for environments where the text of the findings cannot leave.

In the minimized profile, R9 strips the finding fields the protocol defines, text and link from every piece of evidence, the residue item description, and a repository that starts with http. The schema also requires every value under extensions to be opaque (a sha256: hash, a number, a boolean, null, or containers of those) and every key to have the shape of an identifier: a name, not a message.

The profile narrows the leak channel; it does not close it. R9 does not reach every string in the artifact. residue.declaration, event.pr, verification.detail, human_arbiter.id and lead_acceptance are some of the fields that still admit free prose, and the list is not meant to be exhaustive: read the schema for the current surface. Note that a hashed repository does not help if event.pr carries the URL. The schema says as much about the extension space: an identifier-shaped key can still carry a message. Treat minimized as a reduction of surface, not as a guarantee that nothing leaves.

Conformance between implementations

spec/vectors/ holds the conformance vectors: 31 artifacts with their expected verdict (valid or not, and the rule labels that must fire). Every validator implementation has to pass them identically: the Python reference runs them in its suite (tests/test_vectors.py) and the TypeScript port of the evidence plane runs them with npm run conformidad. Labels are compared, not messages. The vectors are regenerated with python -m disensor.vectors spec/vectors.

plano-evidencia/ holds the ingestion Worker (Cloudflare Workers plus D1) with the TypeScript port of the validator and the append-only integrity receipt. See its README for verification status and deployment.

Glossary EN-ES

The contract (schema keys and enums, CLI) has been English since v0.2. The method paper is in Spanish, so this maps the contract you read here to the terminology you will find there:

Migrating from v0.1: rename .residuo/ to .residue/, the config keys (nivel_criticidad to criticality_level, nivel_A_habilitado to level_A_enabled) and the artifact keys according to the glossary. The validator recognises v0.1 artifacts and says so explicitly; the gate loudly rejects a config with old keys instead of applying defaults in silence.

Schema migration: residue/v0.2 to residue/v0.3

Mind the ambiguity: this section is about the version of the schema; the next one is about versions of the package. They are two different numberings.

v0.3 renames no keys and adds none. It hardens the points where the declared guarantee was stronger than the implemented one (three found before the round and two that v0.3's own adversarial round added), and adds one value to an enum:

And verification.against now accepts external_source: literature, third-party specifications, advisories or external documentation. In v0.2 a verification against an external source had no truthful category available and had to be declared as repository (#7).

How to migrate: set the schema field to residue/v0.3 (the key stays; its value changes). If the artifact already satisfies the invariants in the table, there is nothing else to do: no fixture of this repository that was valid under v0.2 needed correcting. The conformance vectors do include artifacts that violate them, on purpose, as negative cases. The validator recognises a v0.2 artifact and explains what v0.3 hardened instead of merely saying the const failed.

Why the identifier was raised instead of hardening v0.2 in place: not for compatibility, of which there was none to protect. It was because the whole product rests on a schema identifier meaning one thing; if v0.2 meant something different depending on when it was read, the tool would contradict itself in its own repository.

The original v0.2 contract stays frozen, byte for byte as published, in spec/residue.schema.v0.2.json: the current schema still reads v0.2, but the document that identifier points at no longer depends on a reconstruction.

Migrating from v0.3 to v0.4 (package versions)

The artifact schema does not change and already-versioned declarations remain valid: what changes is which PRs the gate approves. Updating without reading this leaves CI red with messages that do explain the cause, but it is worth knowing beforehand.

What starts failing and why:

What fixes itself, with nothing to do: the gate stopped working from the second PR onwards, because it also evaluated artifacts from earlier PRs and their reviewed commit fell outside the new range. If you were living with that, it goes away.

Before updating, if the repository already has .residue/ with history, it is worth running disensor gate --no-comment locally on an open PR to see what it says.

Status

v0.6.4, on residue/v0.3. The long-form documentation is bilingual since v0.6.3: README.md is the English one that PyPI renders, README.es.md is the Spanish, and the filling guide ships in both languages. This version makes the packaged Spanish guide reachable with disensor guide --lang es. Releases are published to PyPI via Trusted Publishing (OIDC, release.yml): no tokens on any machine. v0.4 rewrote the gate so that it derives the PR scope from git (see "What the gate enforces") and v0.5 ships the packaged adversarial brief with a reproducible hash; the move to residue/v0.3 hardens three points of the artifact, closing issues #5, #7 and #8. See "Schema migration: residue/v0.2 to residue/v0.3". Decision closed in v0.2: schema keys and CLI in English (Spanish remains as CLI aliases). The schema may change up to v1.0; changes are declared in the schema itself. Decision open before v1.0: the definitive licence (MIT today; Apache-2.0 under consideration for its patent grant).

Licence

MIT.