disensor 0.6.2__tar.gz → 0.6.4__tar.gz

disensor-0.6.4/PKG-INFO

@@ -0,0 +1,382 @@
+Metadata-Version: 2.4
+Name: disensor
+Version: 0.6.4
+Summary: Adversarial plan & code review with a declared residue. Emits, validates and CI-enforces residue declarations (residue/v0.3 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.
+
+*Este documento también está [en español](https://github.com/NicolasRocchia/disensor/blob/main/README.es.md).*
+
+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](https://doi.org/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:
+
+```bash
+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.
+
+```bash
+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:
+
+```json
+{
+  "criticality_level": "B",
+  "level_A_enabled": false
+}
+```
+
+And the workflow (see `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.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.
+
+```json
+{
+  "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:
+
+| Schema/CLI (EN) | Paper (ES) |
+|---|---|
+| residue | residuo |
+| finding | hallazgo |
+| gate (plan, diff, architecture) | compuerta (plan, diff, arquitectura) |
+| criticality_level | nivel de criticidad |
+| profile full / minimized | perfil completo / minimizado |
+| actors: generator, reviewers, human_arbiter | actores: generador, revisores, árbitro humano |
+| family | familia (de modelo) |
+| confinement (permissions, sandbox, read_only_by_instruction, no_confinement) | confinamiento (permisos, sandbox, solo lectura por instrucción, sin confinamiento) |
+| prompt_hash | consigna (hash de la consigna adversarial) |
+| final_state: incorporated, debt_recorded, owner_decision, refuted_verifiable, refuted_interpretive, escalated_open | estado final: incorporado, deuda registrada, decisión del dueño, refutado verificable, refutado interpretativo, escalado abierto |
+| residue classes: escalation_without_decision, principal_refutation, execution_gap | clases de residuo: escalado sin decisión, refutación del principal, gap de ejecución |
+| abbreviated_path / protected_cases_touched | ruta abreviada / casos protegidos |
+| fix_verification | verificación de la corrección |
+| lead_acceptance | aceptación de referente |
+| declared_absence / declaration | ausencia declarada / declaración |
+| metrics: counts, valid, false_positives | métricas: conteos, válidos, falsos positivos |
+
+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:
+
+| Used to be valid | Now rejected | Why |
+|---|---|---|
+| `refuted_verifiable` with `evidence: {}` | The evidence object has to carry `text`, `link` or `hash` | v0.2 required the object to be present, not its content: a finding could be closed without touching the code by declaring empty evidence ([#5](https://github.com/NicolasRocchia/disensor/issues/5)) |
+| `refuted_verifiable` with `verification.against: "none"` | `against` has to be `repository`, `execution` or `external_source` | Refuting without having verified anything is a contradiction, not a refutation ([#5](https://github.com/NicolasRocchia/disensor/issues/5)) |
+| `minimized` profile with free text in `extensions` | Every value under `extensions` has to be opaque: `sha256:` hash, number, boolean, `null`, or containers of those | The extension space is not interpreted by the rules, so text parked there left the environment while the profile claimed nothing left ([#8](https://github.com/NicolasRocchia/disensor/issues/8)) |
+| `refuted_verifiable` with evidence present but blank (`link: ""`, `text` of pure whitespace) | `text` and `link` have to carry at least one non-blank character | Presence without content reopened the [#5](https://github.com/NicolasRocchia/disensor/issues/5) hole through the weakest leg of the `anyOf`; v0.3's own adversarial round caught it |
+| `minimized` profile with free text in the **keys** of `extensions` | Every key under an opaque object has the shape of an identifier (`[A-Za-z0-9._:-]`, at most 128) | An opaque value is not enough if the message travels in the name: [#8](https://github.com/NicolasRocchia/disensor/issues/8) closed the values and left the keys |
+
+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](https://github.com/NicolasRocchia/disensor/issues/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:**
+
+| Used to pass | Now fails | What to do |
+|---|---|---|
+| Checkout without `fetch-depth: 0` (the gate warned and approved anyway) | The gate cannot resolve the PR range and **fails closed** | Add `fetch-depth: 0` to the checkout. A control that cannot decide does not approve. |
+| A `diff` gate declaration without `base_commit` | Rejected | Fill it in. A diff review identifies the pair (reviewed base, reviewed head), not a loose head. |
+| An artifact with any file name | Rejected | The file is called `<event_id>.json` and the `event_id` has to be a canonical UUID. `disensor new` already generates them that way. |
+| A config with unknown keys or of the wrong type | Rejected | The configuration is validated against a closed schema. `level_A_enabled: "false"` in quotes no longer enables Level A by being a non-empty string. |
+| A declaration from an earlier PR was enough to approve the current one | Rejected | Each PR declares its own. The gate only evaluates what the PR adds. |
+| Declaring `plan` to approve a code change | Rejected | The scope policy says which gate each path accepts, and by default everything requires `diff`. |
+| Reviewing a commit and then continuing to add code | Rejected | The declaration has to cover every path in the state it will be merged in. |
+
+**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](https://github.com/NicolasRocchia/disensor/issues/5),
+[#7](https://github.com/NicolasRocchia/disensor/issues/7) and
+[#8](https://github.com/NicolasRocchia/disensor/issues/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.