disensor 0.2.0__tar.gz → 0.3.0__tar.gz

{disensor-0.2.0/src/disensor.egg-info → disensor-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: disensor
-Version: 0.2.0
+Version: 0.3.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
@@ -28,7 +28,7 @@ Paper del método: Rocchia, N. (2026), *Desacuerdo controlado: revisión adversa
 
 - `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`).
+- `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`), y la guía de llenado empaquetada (`GUIDE.md`).
 - `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.
 
@@ -39,15 +39,18 @@ 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 init               # en la raíz del repo: config, CLAUDE.md, skill de llenado 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
+
+disensor guide                         # la guía de llenado, para cualquier agente o humano
+disensor hash consigna.md              # el sha256: que pide prompt_hash, sin calcularlo a mano
 ```
 
 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:
+`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`, la skill de Claude Code con la guía completa de llenado (`.claude/skills/disensor/SKILL.md`, cargada a demanda al cerrar cada ronda) y el workflow del gate; lo que ya existe se respeta y se informa. El principio es que después de `pip install disensor` y `disensor init` el usuario no toque nada a mano: Claude sabe cuándo (CLAUDE.md) y cómo (la skill), cualquier otro agente recibe lo mismo con `disensor guide`, y el CI hace cumplir el resultado. Config resultante:
 
 ```json
 {
@@ -120,7 +123,7 @@ Migración desde v0.1: renombrar `.residuo/` a `.residue/`, las claves del confi
 
 ## 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).
+v0.3, borrador en uso. El esquema sigue en residue/v0.2 (v0.3 no lo toca: agrega la skill de llenado, `disensor guide` y `disensor hash`). 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
 

{disensor-0.2.0 → disensor-0.3.0}/README.md

@@ -14,7 +14,7 @@ Paper del método: Rocchia, N. (2026), *Desacuerdo controlado: revisión adversa
 
 - `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`).
+- `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`), y la guía de llenado empaquetada (`GUIDE.md`).
 - `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.
 
@@ -25,15 +25,18 @@ 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 init               # en la raíz del repo: config, CLAUDE.md, skill de llenado 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
+
+disensor guide                         # la guía de llenado, para cualquier agente o humano
+disensor hash consigna.md              # el sha256: que pide prompt_hash, sin calcularlo a mano
 ```
 
 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:
+`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`, la skill de Claude Code con la guía completa de llenado (`.claude/skills/disensor/SKILL.md`, cargada a demanda al cerrar cada ronda) y el workflow del gate; lo que ya existe se respeta y se informa. El principio es que después de `pip install disensor` y `disensor init` el usuario no toque nada a mano: Claude sabe cuándo (CLAUDE.md) y cómo (la skill), cualquier otro agente recibe lo mismo con `disensor guide`, y el CI hace cumplir el resultado. Config resultante:
 
 ```json
 {
@@ -106,7 +109,7 @@ Migración desde v0.1: renombrar `.residuo/` a `.residue/`, las claves del confi
 
 ## 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).
+v0.3, borrador en uso. El esquema sigue en residue/v0.2 (v0.3 no lo toca: agrega la skill de llenado, `disensor guide` y `disensor hash`). 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
 

{disensor-0.2.0 → disensor-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "disensor"
-version = "0.2.0"
+version = "0.3.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"
@@ -22,4 +22,4 @@ disensor = "disensor.cli:main"
 where = ["src"]
 
 [tool.setuptools.package-data]
-disensor = ["residue.schema.json"]
+disensor = ["residue.schema.json", "GUIDE.md"]

disensor-0.3.0/src/disensor/GUIDE.md

@@ -0,0 +1,108 @@
+# How to fill a residue declaration (residue/v0.2)
+
+This guide is the single source of truth for filling the artifact that
+`disensor new` creates under `.residue/`. It ships inside the package:
+`disensor guide` prints it for any coding agent, and `disensor init` installs
+it as a Claude Code skill. The validator (`disensor validate`) and the CI gate
+enforce everything described here; filling the artifact correctly the first
+time is cheaper than iterating against their errors.
+
+## The flow at the close of a review round
+
+1. `disensor new --gate <plan|diff> --level <A|B|C>` creates the template,
+   prefilled with what git knows (repository, commits, timestamp, uuid).
+2. Fill in every `FILL_IN` marker and the findings of the round. The template
+   does not validate while markers remain: that is intentional.
+3. `disensor validate .residue/<id>.json`. Fix until it prints VALID.
+4. Commit the artifact alone: `docs(residue): declare event <short-id>`.
+   Never mixed with code changes.
+
+Declare what happened, not what should have happened. An event without
+findings and with an express declaration of absence is valid data, not a
+failure.
+
+## Actors
+
+- `generator`: the assistant that produced the plan or diff. `family` is its
+  model family (anthropic, openai, google, meta, mistral, other).
+- `reviewers[]`: the attacking assistants. Each needs `reviewer_id` (r1,
+  r2...), `family`, `model`, and `confinement`. Rule R4 rejects any reviewer
+  whose family equals the generator's: decorrelation is the point of the
+  method, not an option.
+- `reviewers[].prompt_hash`: hash of the adversarial brief given to the
+  reviewer. Compute it with `disensor hash <brief-file>`; paste the full
+  `sha256:...` output.
+- `confinement.mode`: how it was guaranteed that the reviewer only reads
+  (permissions, sandbox, read_only_by_instruction, no_confinement). Declare
+  the real mode; the gate makes gaps visible instead of hiding them.
+- `confinement.verified`: true ONLY if you ran `git status` after the
+  reviewer's run and the tree was clean. Otherwise leave false.
+- `human_arbiter.present`: must be true; an event without a human arbiter
+  does not comply with the protocol (R0).
+
+## Findings
+
+One entry per point the reviewer raised. Fields: `id` (h1, h2...), `origin`
+(the reviewer_id that produced it), `severity` (critical, major, minor,
+info), `title`, `description`, `location` (full profile only), and:
+
+- `verification.against`: what the generator checked the finding against
+  before accepting or refuting it: `repository` (code, config, contracts),
+  `execution` (running tests or the program), or `none`. Do not take the
+  reviewer's word: verify, then decide.
+- `final_state`, the terminal outcome. Decision table:
+  - `incorporated`: the finding changed the plan or the code. In the diff
+    gate you MUST add `fix_verification` with type `diff_gate` or
+    `specific_test` (R7); `pending_in_diff_gate` is only legal in the plan
+    gate. If the reviewer's remedy was wrong and you fixed it, record
+    `remedy_adjustment`.
+  - `debt_recorded`: valid, deferred; requires `debt_id` (schema).
+  - `owner_decision`: valid, the owner changed scope, behavior or accepted
+    risk; requires `risk_record` (schema).
+  - `refuted_verifiable`: false positive with proof; requires `evidence`
+    (text quote, link, or hash).
+  - `refuted_interpretive`: false positive by judgment; it MUST also appear
+    as a residue item (R1) with `requires_human_attention: true` (R8).
+  - `escalated_open`: no decision yet; it MUST also appear as a residue
+    item (R1).
+
+## Residue
+
+The heart of the declaration: what the cycle could not close by itself.
+Either `items` or the express absence, never an empty field.
+
+- `items[]`: `id` (r1, r2...), `class`, `finding_ref` when it comes from a
+  finding, `requires_human_attention`.
+  - `escalation_without_decision`: from every `escalated_open` finding.
+  - `principal_refutation`: from every refuted finding; add
+    `refutation_type` (`verifiable` or `interpretive`; interpretive forces
+    `requires_human_attention: true`).
+  - `execution_gap`: behavior execution could not arbitrate; add
+    `gap_reason`. In Level A an execution gap blocks the merge until a
+    technical lead accepts it in writing (`lead_acceptance`, R5).
+- Absence: `"declared_absence": true` plus `declaration`, minimum 30
+  characters of concrete text. Generic markers (none, n/a, all resolved,
+  ninguno, todo resuelto...) are rejected by R2 in any language.
+
+## Metrics
+
+`counts` must add up exactly against the findings list (R6): each
+`valid.*` and `false_positives.*` bucket equals the number of findings in
+that state, `escalated_open` likewise, `total_findings` equals the list
+length. Count, do not estimate.
+
+## Minimized profile
+
+No free text anywhere (R9): no titles, descriptions or locations in
+findings; no descriptions in items; evidence only as `hash`; `repository`
+as a hash or opaque identifier, never a URL.
+
+## Quick map of validator labels
+
+R0 human arbiter absent; R1 residue/finding coherence; R2 generic or
+template markers; R3 abbreviated path over protected cases; R4 reviewer
+shares the generator's family; R5 Level A execution gap without lead
+acceptance; R6 counts that do not add up; R7 incorporated without verified
+fix in the diff gate; R8 interpretive refutation without human attention;
+R9 text leaks in the minimized profile; R10 full profile without findings;
+`schema` shape errors (missing required fields, wrong enums, bad patterns).

{disensor-0.2.0 → disensor-0.3.0}/src/disensor/__init__.py

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

{disensor-0.2.0 → disensor-0.3.0}/src/disensor/cli.py

@@ -12,6 +12,7 @@ import sys
 from pathlib import Path
 
 from .gate import main_gate
+from .guide import main_guide, main_hash
 from .init import main_init
 from .rules import load_schema, validate_artifact
 from .template import main_new
@@ -38,11 +39,12 @@ def build_parser() -> argparse.ArgumentParser:
     )
     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 = sub.add_parser("init", help="Scaffold a repository: config, CLAUDE.md section, filling skill 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("--no-claude", action="store_true", help="Do not touch CLAUDE.md nor the skill.")
+    init.add_argument("--no-skill", action="store_true", help="Write the CLAUDE.md section but not the skill.")
     init.add_argument("--claude-global", action="store_true",
-                      help="Write the Claude Code section to ~/.claude/CLAUDE.md instead of the repo.")
+                      help="Write the Claude Code section and skill to ~/.claude 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)
 
@@ -67,6 +69,15 @@ def build_parser() -> argparse.ArgumentParser:
     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)
+
+    guide = sub.add_parser("guide", help="Print the artifact filling guide (for any coding agent or human).")
+    guide.set_defaults(func=main_guide)
+
+    hash_ = sub.add_parser("hash", help="Compute the sha256:<hex> value for prompt_hash from a file or text.")
+    src = hash_.add_mutually_exclusive_group(required=True)
+    src.add_argument("file", nargs="?", help="File to hash (e.g. the adversarial brief).")
+    src.add_argument("--text", help="Hash this literal text instead of a file.")
+    hash_.set_defaults(func=main_hash)
     return p
 
 

disensor-0.3.0/src/disensor/guide.py

@@ -0,0 +1,32 @@
+"""Packaged filling guide and hash helper: `disensor guide` and `disensor hash`.
+
+The guide (GUIDE.md, shipped inside the package) is the single source of
+truth on how to fill a residue declaration. `disensor init` installs it as a
+Claude Code skill; `disensor guide` prints it for any other coding agent or
+for a human. `disensor hash` computes the `sha256:...` value the schema
+expects in `prompt_hash`, so nobody hashes the adversarial brief by hand.
+"""
+from __future__ import annotations
+
+import hashlib
+from importlib import resources
+from pathlib import Path
+
+
+def guide_text() -> str:
+    """The packaged guide, verbatim."""
+    return resources.files("disensor").joinpath("GUIDE.md").read_text(encoding="utf-8")
+
+
+def main_guide(args) -> int:
+    print(guide_text(), end="")
+    return 0
+
+
+def main_hash(args) -> int:
+    if args.text is not None:
+        data = args.text.encode("utf-8")
+    else:
+        data = Path(args.file).read_bytes()
+    print("sha256:" + hashlib.sha256(data).hexdigest())
+    return 0

{disensor-0.2.0 → disensor-0.3.0}/src/disensor/init.py

@@ -5,10 +5,16 @@ initialized once with this command. Idempotent by design: running it again
 respects what already exists and reports what it did, so nothing is ever
 silently overwritten.
 
-It writes three pieces, each optional by flag:
+It writes four pieces, each optional by flag:
   1. disensor.config.json: the criticality level, versioned with the code.
-  2. A CLAUDE.md section: the event-close instructions for Claude Code.
-  3. .github/workflows/disensor.yml: the CI gate, pinned to this version.
+  2. A CLAUDE.md section: the event-close trigger for Claude Code.
+  3. A Claude Code skill with the full filling guide, loaded on demand
+     (the same text `disensor guide` prints for any other agent).
+  4. .github/workflows/disensor.yml: the CI gate, pinned to this version.
+
+After `pip install disensor` and `disensor init`, the user should not have
+to touch anything by hand: Claude knows when (CLAUDE.md) and how (skill),
+and CI enforces the result.
 """
 from __future__ import annotations
 
@@ -17,6 +23,7 @@ import subprocess
 from pathlib import Path
 
 from . import __version__
+from .guide import guide_text
 
 CLAUDE_HEADING = "## disensor: residue declaration at event close"
 
@@ -25,29 +32,16 @@ CLAUDE_SECTION = f"""{CLAUDE_HEADING}
 At the end of each adversarial review round (plan or diff), BEFORE closing
 the event:
 
-1. Run `disensor new --gate <plan|diff> --level <A|B|C>` and fill in the
-   template it creates under `.residue/` with what happened in the round:
-   - One finding per point raised by the reviewer (an assistant of another
-     model family), with its terminal state: incorporated (with
-     `remedy_adjustment` if you fixed the proposed remedy), debt_recorded
-     (with id), owner_decision (with the risk record), refuted_verifiable
-     (with evidence), refuted_interpretive, or escalated_open.
-   - The verification of each finding (`against`: repository or execution).
-   - In the diff gate, the fix verification of each incorporated finding
-     (diff_gate or specific_test). Never "pending".
-   - The residue: escalations without a decision, refutations of the
-     principal, and execution gaps. If nothing remained, the express
-     declaration of absence (concrete text, not "no residue").
-   - The sha256 hash of the adversarial brief used, in `prompt_hash`.
-   - `confinement.verified: true` ONLY if you ran `git status` after the
-     round and it was clean.
-2. Run `disensor validate` on the file. If it fails, fix it: the CI gate
+1. `disensor new --gate <plan|diff> --level <A|B|C>` creates the template
+   under `.residue/`.
+2. Fill it following the disensor skill (`.claude/skills/disensor/SKILL.md`;
+   the same guide is available as `disensor guide`). Do not invent findings
+   or states: the artifact declares what happened, not what should have
+   happened.
+3. Run `disensor validate` on the file until it prints VALID; the CI gate
    rejects exactly the same.
-3. The artifact goes in its own commit (`docs(residue): declare event
-   <short-id>`). Never mixed with code.
-4. Do not invent findings or states: the artifact declares what happened,
-   not what should have happened. An event without findings and with an
-   express declaration of absence is valid pilot data, not a failure.
+4. The artifact goes in its own commit (`docs(residue): declare event
+   <short-id>`), never mixed with code.
 """
 
 GLOBAL_GUARD = (
@@ -55,6 +49,13 @@ GLOBAL_GUARD = (
     "`disensor.config.json`:\n\n"
 )
 
+SKILL_FRONTMATTER = """---
+name: disensor
+description: Fill and validate a disensor residue declaration (.residue/*.json) at the close of an adversarial review round. Use when closing a review event, filling the template created by `disensor new`, or fixing errors reported by `disensor validate`.
+---
+
+"""
+
 WORKFLOW = f"""# Generated by disensor init. The gate validates the .residue/ artifacts of each PR.
 name: disensor
 on:
@@ -119,6 +120,16 @@ def _write_claude(path: Path, section: str, label: str, report: list[str]) -> No
     report.append(f"created {label}")
 
 
+def _write_skill(base: Path, label: str, report: list[str]) -> None:
+    path = base / ".claude" / "skills" / "disensor" / "SKILL.md"
+    if path.exists():
+        report.append(f"kept    {label} (already exists)")
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(SKILL_FRONTMATTER + guide_text(), encoding="utf-8")
+    report.append(f"created {label}")
+
+
 def _write_workflow(root: Path, report: list[str]) -> None:
     path = root / ".github" / "workflows" / "disensor.yml"
     if path.exists():
@@ -139,16 +150,21 @@ def main_init(args) -> int:
     _write_config(root, args.level, report)
 
     if args.claude_global:
+        home = Path.home()
         _write_claude(
-            Path.home() / ".claude" / "CLAUDE.md",
+            home / ".claude" / "CLAUDE.md",
             GLOBAL_GUARD + CLAUDE_SECTION,
             "~/.claude/CLAUDE.md (global)",
             report,
         )
+        if not args.no_skill:
+            _write_skill(home, "~/.claude/skills/disensor/SKILL.md (global)", report)
     elif not args.no_claude:
         _write_claude(root / "CLAUDE.md", CLAUDE_SECTION, "CLAUDE.md", report)
+        if not args.no_skill:
+            _write_skill(root, ".claude/skills/disensor/SKILL.md", report)
     else:
-        report.append("skipped CLAUDE.md (--no-claude)")
+        report.append("skipped CLAUDE.md and skill (--no-claude)")
 
     if args.no_workflow:
         report.append("skipped .github/workflows/disensor.yml (--no-workflow)")
@@ -160,6 +176,8 @@ def main_init(args) -> int:
     print(
         "\nNext: the adversarial loop needs a reviewer from another model family "
         "(rule R4). Close each review round with `disensor new`, fill in the "
-        "artifact, and `disensor validate` it before committing."
+        "artifact (the skill or `disensor guide` explains every field, and "
+        "`disensor hash` computes prompt_hash), and `disensor validate` it "
+        "before committing."
     )
     return 0

{disensor-0.2.0 → disensor-0.3.0/src/disensor.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: disensor
-Version: 0.2.0
+Version: 0.3.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
@@ -28,7 +28,7 @@ Paper del método: Rocchia, N. (2026), *Desacuerdo controlado: revisión adversa
 
 - `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`).
+- `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`), y la guía de llenado empaquetada (`GUIDE.md`).
 - `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.
 
@@ -39,15 +39,18 @@ 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 init               # en la raíz del repo: config, CLAUDE.md, skill de llenado 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
+
+disensor guide                         # la guía de llenado, para cualquier agente o humano
+disensor hash consigna.md              # el sha256: que pide prompt_hash, sin calcularlo a mano
 ```
 
 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:
+`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`, la skill de Claude Code con la guía completa de llenado (`.claude/skills/disensor/SKILL.md`, cargada a demanda al cerrar cada ronda) y el workflow del gate; lo que ya existe se respeta y se informa. El principio es que después de `pip install disensor` y `disensor init` el usuario no toque nada a mano: Claude sabe cuándo (CLAUDE.md) y cómo (la skill), cualquier otro agente recibe lo mismo con `disensor guide`, y el CI hace cumplir el resultado. Config resultante:
 
 ```json
 {
@@ -120,7 +123,7 @@ Migración desde v0.1: renombrar `.residuo/` a `.residue/`, las claves del confi
 
 ## 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).
+v0.3, borrador en uso. El esquema sigue en residue/v0.2 (v0.3 no lo toca: agrega la skill de llenado, `disensor guide` y `disensor hash`). 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
 

{disensor-0.2.0 → disensor-0.3.0}/src/disensor.egg-info/SOURCES.txt

@@ -1,10 +1,12 @@
 LICENSE
 README.md
 pyproject.toml
+src/disensor/GUIDE.md
 src/disensor/__init__.py
 src/disensor/__main__.py
 src/disensor/cli.py
 src/disensor/gate.py
+src/disensor/guide.py
 src/disensor/init.py
 src/disensor/render.py
 src/disensor/residue.schema.json
@@ -17,6 +19,7 @@ src/disensor.egg-info/dependency_links.txt
 src/disensor.egg-info/entry_points.txt
 src/disensor.egg-info/requires.txt
 src/disensor.egg-info/top_level.txt
+tests/test_guide.py
 tests/test_init.py
 tests/test_rules.py
 tests/test_vectors.py

disensor-0.3.0/tests/test_guide.py

@@ -0,0 +1,36 @@
+"""Tests of `disensor guide` and `disensor hash`: the no-hands helpers."""
+from __future__ import annotations
+
+import hashlib
+import re
+
+from disensor.cli import build_parser
+from disensor.guide import guide_text
+
+PROMPT_HASH_PATTERN = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+def run(capsys, *argv: str) -> str:
+    args = build_parser().parse_args(list(argv))
+    assert args.func(args) == 0
+    return capsys.readouterr().out
+
+
+def test_guide_prints_packaged_text(capsys):
+    out = run(capsys, "guide")
+    assert out == guide_text()
+    assert "residue/v0.2" in out and "R4" in out and "disensor hash" in out
+
+
+def test_hash_of_file_matches_hashlib_and_schema_pattern(tmp_path, capsys):
+    f = tmp_path / "consigna.md"
+    f.write_bytes(b'{"prueba":"recibo"}')
+    out = run(capsys, "hash", str(f)).strip()
+    assert out == "sha256:" + hashlib.sha256(b'{"prueba":"recibo"}').hexdigest()
+    assert PROMPT_HASH_PATTERN.match(out)
+
+
+def test_hash_of_text(capsys):
+    out = run(capsys, "hash", "--text", "consigna adversarial v3").strip()
+    expected = hashlib.sha256("consigna adversarial v3".encode("utf-8")).hexdigest()
+    assert out == f"sha256:{expected}"

{disensor-0.2.0 → disensor-0.3.0}/tests/test_init.py

@@ -30,24 +30,25 @@ def test_init_scaffolds_everything(repo, monkeypatch):
     assert config == {"criticality_level": "B", "level_A_enabled": False}
     claude = (repo / "CLAUDE.md").read_text(encoding="utf-8")
     assert CLAUDE_HEADING in claude and "disensor validate" in claude
+    skill = (repo / ".claude" / "skills" / "disensor" / "SKILL.md").read_text(encoding="utf-8")
+    assert skill.startswith("---\nname: disensor\n")
+    assert "final_state" in skill and "R4" in skill  # the full guide travels in the skill
     workflow = (repo / ".github" / "workflows" / "disensor.yml").read_text(encoding="utf-8")
     assert f"NicolasRocchia/disensor@v{__version__}" in workflow
     assert "fetch-depth: 0" in workflow
 
 
 def test_init_is_idempotent(repo, monkeypatch):
+    pieces = [
+        repo / "disensor.config.json",
+        repo / "CLAUDE.md",
+        repo / ".claude" / "skills" / "disensor" / "SKILL.md",
+        repo / ".github" / "workflows" / "disensor.yml",
+    ]
     run_init(repo, monkeypatch)
-    before = {
-        p.name: p.read_text(encoding="utf-8")
-        for p in [repo / "disensor.config.json", repo / "CLAUDE.md",
-                  repo / ".github" / "workflows" / "disensor.yml"]
-    }
+    before = {str(p): p.read_text(encoding="utf-8") for p in pieces}
     run_init(repo, monkeypatch)
-    after = {
-        p.name: p.read_text(encoding="utf-8")
-        for p in [repo / "disensor.config.json", repo / "CLAUDE.md",
-                  repo / ".github" / "workflows" / "disensor.yml"]
-    }
+    after = {str(p): p.read_text(encoding="utf-8") for p in pieces}
     assert before == after
 
 
@@ -69,9 +70,16 @@ def test_init_flags_skip_pieces(repo, monkeypatch):
     assert json.loads((repo / "disensor.config.json").read_text(encoding="utf-8"))[
         "criticality_level"] == "C"
     assert not (repo / "CLAUDE.md").exists()
+    assert not (repo / ".claude").exists()  # --no-claude also skips the skill
     assert not (repo / ".github").exists()
 
 
+def test_init_no_skill_keeps_claude_section(repo, monkeypatch):
+    run_init(repo, monkeypatch, "--no-skill")
+    assert CLAUDE_HEADING in (repo / "CLAUDE.md").read_text(encoding="utf-8")
+    assert not (repo / ".claude").exists()
+
+
 def test_init_claude_global_is_guarded(repo, monkeypatch, tmp_path_factory):
     home = tmp_path_factory.mktemp("home")
     monkeypatch.setenv("HOME", str(home))
@@ -81,7 +89,9 @@ def test_init_claude_global_is_guarded(repo, monkeypatch, tmp_path_factory):
     content = global_md.read_text(encoding="utf-8")
     assert "disensor.config.json" in content.splitlines()[0] or "ONLY inside repositories" in content
     assert CLAUDE_HEADING in content
+    assert (home / ".claude" / "skills" / "disensor" / "SKILL.md").exists()
     assert not (repo / "CLAUDE.md").exists()
+    assert not (repo / ".claude").exists()
 
 
 def test_init_warns_on_v01_config(repo, monkeypatch, capsys):