git-preflight-gate 0.1.6__tar.gz

git_preflight_gate-0.1.6/LICENSE

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

git_preflight_gate-0.1.6/MANIFEST.in

@@ -0,0 +1,17 @@
+# HUELLA-MANIFEST-SDIST-20261106
+# El sdist es el archivo que viaja; el wheel lleva el paquete `sim`.
+# Medido antes de escribir (2026-11-06, tag v0.1.3): el sdist pesaba 8 920 B y
+# NO contenia preflight-gate.sh, action.yml, sim/ ni templates/ — 0 de 4 piezas
+# del producto. Un sdist que omite el producto no es un paquete pequeno: es un
+# paquete que nombra otra cosa.
+include LICENSE
+include README.md
+include README.es.md
+include action.yml
+include preflight-gate.sh
+include pyproject.toml
+recursive-include sim *.py
+recursive-include templates *.yml
+recursive-include tests *
+# El aparato de CI no viaja: es del repositorio, no del paquete.
+prune .github

git_preflight_gate-0.1.6/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: git-preflight-gate
+Version: 0.1.6
+Summary: Pre-write preflight gate (bash) and CI authority gate (Python composite action): fail-closed, standard library only except PyYAML for the CI extra.
+Author: alexisromtz-lab
+License: MIT
+Project-URL: Homepage, https://github.com/alexisromtz-lab/git-preflight-gate
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: ci-authority-gate
+Requires-Dist: PyYAML==6.0.3; extra == "ci-authority-gate"
+Dynamic: license-file
+
+<!-- HUELLA-README-EN-20261105 -->
+**Language:** English · [Español](README.es.md)
+
+# CI Authority Gate
+
+**Repository:** [`git-preflight-gate`](https://github.com/alexisromtz-lab/git-preflight-gate) · **Marketplace:** [Install the action](https://github.com/marketplace/actions/ci-authority-gate)
+
+**An integrity gate for autonomous AI agents: so that a bot does not dirty the tree
+and does not commit concurrency collisions either.**
+
+Before an agent writes a line, the gate demands a destination tuple —
+`TARGET` (absolute) · `BLOB_PRE` · `HUELLA` · `LINEAS_PRE` — and returns a code that
+**authorizes or blocks** the write. Without a prior run ending in `RC 0`, nothing is written.
+
+## Install
+
+```bash
+pip install git-preflight-gate        # Python CI gate (PyYAML comes with it)
+ci-authority-gate /path/to/your/repo  # RC 0 = pass · RC > 0 = fail-closed, cause printed
+```
+
+Two doors, measured separately — do not confuse them:
+
+| door | command | what it needs |
+|---|---|---|
+| **CI authority gate** | `pip install git-preflight-gate` | Python ≥ 3.9 + PyYAML (pip resolves it) |
+| **pre-write gate (bash)** | `curl -fsSL https://raw.githubusercontent.com/alexisromtz-lab/git-preflight-gate/main/preflight-gate.sh -o preflight-gate.sh` | bash + git, **zero dependencies** |
+
+The wheel ships the Python gate (`sim/`); the bash gate ships in the source distribution and in the repository, and is deliberately dependency-free so it can run on a machine with nothing installed. Neither is a wrapper around the other.
+
+### The pre-write gate, at the shell
+
+```bash
+bash preflight-gate.sh /absolute/path/file.py <blob_pre> <exclusive_marker> <lineas_pre>
+```
+
+## The codes (fail-closed)
+
+| RC | meaning |
+|---:|---|
+| `0` | PRE-FLIGHT OK — the target accepts an edit on `BLOB_PRE` |
+| `10` | the object does not exist (creation) |
+| `11` | **the marker already lives in the target** ⇒ collision: the row is already written |
+| `12` | measured blob ≠ contract ⇒ the tree moved |
+| `13` | dirty git state ⇒ unadjudicated modifications |
+| `14` | the target is not inside a git tree ⇒ the gate cannot verify identity |
+| `15` | line count differs from the contract |
+| `20` | misuse (incomplete tuple, or `TARGET` not absolute) |
+
+Every code comes out **with its cause printed**. A correct `RC` for the wrong reason is not a gate: it is a coincidence.
+
+## Why `RC 11` is the case that matters
+
+The most expensive defect of an agent is not picking the wrong path: it is **writing again something another hand already wrote**, and reporting success. The marker is an exclusive literal fragment of the text to be inserted; if it is already in the target, the write is rejected before the file is touched. The gate does not guess intent: it denies the collision.
+
+## Why `TARGET` must be absolute
+
+The gate rebases with `git -C <directory>` to measure the blob and the state. A relative path would be counted from **two different bases** (`cwd` and the object's directory) and could hash *another* file that does exist. Fail-closed: relative path ⇒ `RC 20`.
+
+## Why `RC 14` exists
+
+Without a git tree, `git status` returns 128 with empty output. A naive gate reads that empty output as "clean" and goes green. Here the impossibility is declared: without a tree there is no blob identity worth anything.
+
+## Case bank
+
+```bash
+bash tests/must_fail.sh
+```
+
+9 cases, **9/9**, each verifying the code **and** the cause: `20` (incomplete tuple), `20` (relative path), `10`, `11`, `12`, `15`, `13`, `14`, and the positive control `0`. A bank without a positive control only proves the instrument knows how to say no.
+
+## Out-of-band telemetry
+
+Each run records 7 fields (`hora_utc target blob_pre blob_medido rc hash_arbol_ini hash_arbol_fin`) in `${GATE_TELEMETRIA_LOG:-$HOME/preflight-telemetria.log}`. Telemetry **cannot move the RC**, **cannot abort** and **cannot refresh the index** (`--no-optional-locks`). The path is never relative: a log inside the tree becomes an untracked file, and then the gate ends up measuring its own telemetry — the instrument counting itself.
+
+## Declared limits
+
+- On a nonexistent `TARGET` the gate stops at `RC 10` **before** comparing blob and lines: in the creation branch, the tuple is a **contract**, not a measurement. It is declared, not repaired (fail-closed is correct).
+- It does not judge content: it certifies identity and collision, not correctness.
+
+## The root Action: CI Authority Gate
+
+The `action.yml` at this repository's root is a **composite action** running a second instrument, `sim/gate_workflows_ci.py`: a structural verifier of the authority topology in `.github/workflows/`. Five counting invariants, seven typed causes, `RC = min(causes)`, `UNIVERSO_VACIO` = cause `31` (zero files is failure, not approval).
+
+Measured identity of the instrument copied into this tree:
+
+| property | value |
+|---|---|
+| lines / bytes | 615 / 21470 |
+| git blob | `ff9c69a944e7965b3fda0901f7745d80a9e85c7c` |
+| sha256-16 | `073954a84f3c84fd` |
+
+Using it as a consumer:
+
+```yaml
+- uses: alexisromtz-lab/git-preflight-gate@v0.1.4
+  with:
+    workflows-dir: .github/workflows
+    fail-on-red: "true"
+```
+
+<!-- HUELLA-RELEASE-V013-20261031 -->
+`v0.1.3`, `v0.1.2` and `v0.1.1` run the same `action.yml` (`9ef420ec`) and the same `sim/gate_workflows_ci.py` (`ff9c69a9`): the gate's code did not change across the three. What changes is the adoption wrapper — `v0.1.2` added `templates/platino-gate.yml` and `v0.1.3` added `action-selftest.yml`, the manifest alignment and this documentation. If you pin by SHA, use the commit — not the tag.
+
+The four inputs (`workflows-dir`, `root`, `python-bin`, `fail-on-red`) and the two
+outputs (`rc`, `veredicto`) preserve the contract of the `action.yml` that this
+repository **replaces**: any CI that pointed at the root action of a working repository
+migrates by changing only the repository name in `uses:`; the rest of the `with:` block
+does not change.
+
+The action does not guess the domain: the instrument resolves a single point, `<root>/.github/workflows`. That is why `workflows-dir` routes to `--file` when the path exists and to `--root` when it does not. A `--root` that accepted any directory with YAML files would be editing the ruler so the demo fits.
+
+Single dependency: `PyYAML==6.0.3`, declared as an optional extra (`pip install ".[ci-authority-gate]"`). The rest is stdlib. The instrument does not read the network, does not write files, does not use randomness and does not consult the clock.
+
+Installable without cloning the repository, from the release wheel. The
+`ci-authority-gate` extra is mandatory for the CLI: without PyYAML the instrument does
+not measure and exits `RC=30` (fail-closed), not green.
+
+```bash
+pip install "git-preflight-gate[ci-authority-gate] @ https://github.com/alexisromtz-lab/git-preflight-gate/releases/download/v0.1.4/git_preflight_gate-0.1.4-py3-none-any.whl"
+ci-authority-gate --self-test   # built-in must-fail bank; touches no disk
+ci-authority-gate --root .      # measures <root>/.github/workflows and returns its RC
+```
+
+<!-- HUELLA-README-V014-20261106 -->
+`v0.1.4` does not change the gate: `action.yml` (`9ef420ec`) and
+`sim/gate_workflows_ci.py` (`ff9c69a9`) are the same blobs as in `v0.1.3`. What changes
+is the package: `MANIFEST.in` makes the sdist carry the product, and the manifest
+declares the `sim` package and the `ci-authority-gate` script. Before this change the
+wheel was 6 768 B of `dist-info` only and no CLI existed. It is not on PyPI yet: the
+only `pip` path today is the release URL.
+
+Measured positive control: workflow with `permissions: contents: read` and `uses` pinned by full SHA ⇒ `CAUSAS PRESENTES: ninguna`, `VEREDICTO: PASA`, `RC=0`. Negative control: `pull_request_target` + `permissions: write-all` + `curl | bash` + `actions/checkout@v4` ⇒ `CAUSAS PRESENTES: [1, 2, 5]`, `RC=1`. Empty universe ⇒ `CAUSAS PRESENTES: [31]`, `RC=31`.
+
+## The two instruments are not to be confused
+
+| instrument | question | form |
+|---|---|---|
+| `preflight-gate.sh` | may this agent write *this file* now? | bash CLI, target tuple |
+| `sim/gate_workflows_ci.py` | does this CI topology concentrate authority without control? | composite action + Python CLI |
+
+The first protects a write; the second audits a workflow tree. They share the doctrine (fail-closed, printed cause, zero files = declared impossibility), not the code.
+
+## Install it in your repository in 1 minute
+
+<!-- HUELLA-BADGE-PLATINO-README-20261031 -->
+
+```bash
+mkdir -p .github/workflows
+curl -fsSL https://raw.githubusercontent.com/alexisromtz-lab/git-preflight-gate/main/templates/platino-gate.yml \
+  -o .github/workflows/platino-gate.yml
+git add .github/workflows/platino-gate.yml
+git commit -m "ci: platino preflight gate"
+git push
+```
+
+That is all: the workflow fires on the next `push` or PR.
+
+### The file must be named `platino-gate.yml` (this is a contract, not advice)
+
+If you rename it — `ci.yml`, `gate.yml`, `platino-gate.yaml` — the first job fails closed with `RC 20` and tells you why. The reason is measured, not aesthetic: the status badge resolves **by file name** (`.../workflow/status/YOUR-REPO/YOUR-REPO/platino-gate.yml`). With another name, the badge would read *your* CI workflow, not this gate, and would publish a green that measures nothing. The contract lives inside the workflow, not on this page.
+
+Falsified by `tests/test_platino_gate_template.py`: 5 name cases and 5 structural cases, `RC 0` only if all 10 agree; a template mutated to accept any `.yml` returns `RC 1` naming the offending row.
+
+## The badge
+
+When the run finishes, the **Summary** tab publishes the badge already filled in with your `owner/repo`. There are two, and they are not the same:
+
+| badge | what it claims | permissions it asks for |
+|---|---|---|
+| **status** (dynamic) | the real result of the most recent run of `platino-gate.yml` | `contents: read` |
+| **seal** (static) | "this repository passed the gate" | `contents: read` |
+
+```markdown
+[![Platino Preflight Gate](https://img.shields.io/github/actions/workflow/status/OWNER/REPO/platino-gate.yml?label=preflight%20gate&branch=main)](https://github.com/alexisromtz-lab/la-auditora)
+
+[![Audited by Platino Labs](https://img.shields.io/badge/audited_by-Platino_Labs-6f42c1)](https://github.com/alexisromtz-lab/la-auditora)
+```
+
+The status one cannot lie: GitHub draws it from the run. **The seal can**: it is a literal anyone can paste in green without having run anything. Use it only when the run is green — the gate cannot verify that for you.
+
+**Zero write permissions, in both cases.** The workflow does not touch your README, does not ask for `contents: write` and needs no service of ours: the badge is a `shields.io` URL that reads the public status of your own workflow. There is no endpoint to host, no token to expire.
+
+### What it measures and what it does not
+
+| measures | does not measure |
+|---|---|
+| authority topology in `.github/workflows/`: `permissions`, triggers, `uses` pinned by SHA, execution sinks | whether your code does what it says |
+| seven typed causes, `RC = min(causes)`, `UNIVERSO_VACIO` = cause `31` | default `GITHUB_TOKEN` permissions at organization level |
+| the tree you have, at the commit that runs | OIDC / Trusted Publishing trust in the destination registry |
+
+The second block is printed on every run, under `RESIDUO DECLARADO`. A gate that does not declare its limits is not a gate: it is a promise.
+
+### How the wrapper tests itself
+
+<!-- HUELLA-BADGE-SELFTEST-DOC-20261031 -->
+`action.yml` is not tested by reading its YAML: it is executed. On every push to `main`, the workflow [`action-selftest.yml`](.github/workflows/action-selftest.yml) runs the action twice with `uses: ./` — once on this repository itself, where it demands `rc=0` / `PASA`, and once on a poisoned fixture in `tests/fixtures/sumidero`, where it demands `rc=2` / `SUMIDERO_IMPUDO`. If the extra's installation (`pip install "<action_dir>[ci-authority-gate]"`) or the input routing breaks, it goes red here before going red on your runner.
+
+A self-test that only knows how to be green discriminates nothing: that is why the second case demands the action **fail** with the correct cause.
+
+## License
+
+MIT. See `LICENSE`.

git_preflight_gate-0.1.6/README.es.md

@@ -0,0 +1,258 @@
+<!-- HUELLA-README-ES-20261105 -->
+**Idioma:** Español · [English](README.md)
+
+# CI Authority Gate
+
+**Repository:** [`git-preflight-gate`](https://github.com/alexisromtz-lab/git-preflight-gate) · **Marketplace:** [Install the action](https://github.com/marketplace/actions/ci-authority-gate)
+
+**Un gate de integridad para agentes de IA autónomos: que un bot no ensucie el árbol
+ni cometa colisiones de concurrencia.**
+
+Antes de que un agente escriba una línea, el gate exige una tupla de destino —
+`TARGET` (absoluto) · `BLOB_PRE` · `HUELLA` · `LINEAS_PRE` — y devuelve un código que
+**autoriza o bloquea** la escritura. Sin corrida previa con `RC 0`, no se escribe.
+
+## Instalación
+
+```bash
+pip install git-preflight-gate        # gate de CI en Python (PyYAML viaja con él)
+ci-authority-gate /ruta/a/tu/repo     # RC 0 = pasa · RC > 0 = fallo cerrado con causa
+```
+
+Dos puertas, medidas por separado — no se confunden:
+
+| puerta | comando | qué necesita |
+|---|---|---|
+| **gate de CI** | `pip install git-preflight-gate` | Python ≥ 3.9 + PyYAML (lo resuelve pip) |
+| **pre-write gate (bash)** | `curl -fsSL https://raw.githubusercontent.com/alexisromtz-lab/git-preflight-gate/main/preflight-gate.sh -o preflight-gate.sh` | bash + git, **cero dependencias** |
+
+El wheel trae el gate de Python (`sim/`); el gate de bash viaja en el sdist y en el repositorio, y es deliberadamente sin dependencias para correr en una máquina sin nada instalado. Ninguno envuelve al otro.
+
+### El pre-write gate, en la terminal
+
+```bash
+bash preflight-gate.sh /ruta/absoluta/archivo.py <blob_pre> <huella_exclusiva> <lineas_pre>
+```
+
+## Los códigos (fail-closed)
+
+| RC | significado |
+|---:|---|
+| `0` | PRE-VUELO OK — el destino acepta la edición sobre `BLOB_PRE` |
+| `10` | el objeto no existe (creación) |
+| `11` | **la huella ya habita en el destino** ⇒ colisión: la fila ya está escrita |
+| `12` | blob medido ≠ contrato ⇒ el árbol se movió |
+| `13` | estado sucio en git ⇒ modificaciones no adjudicadas |
+| `14` | el destino no vive en un árbol git ⇒ el gate no puede validar identidad |
+| `15` | líneas distintas al contrato |
+| `20` | uso incorrecto (tupla incompleta, o `TARGET` no absoluto) |
+
+Cada código sale **con su causa impresa**. Un `RC` correcto por el motivo equivocado
+no es un gate: es una coincidencia.
+
+## Por qué `RC 11` es el caso que importa
+
+El defecto más caro de un agente no es equivocarse de ruta: es **volver a escribir algo
+que otra mano ya escribió**, y reportar éxito. La huella es un fragmento literal
+exclusivo del texto a insertar; si ya está en el destino, la escritura se rechaza antes
+de tocar el archivo. El gate no adivina intenciones: niega la colisión.
+
+## Por qué `TARGET` debe ser absoluto
+
+El gate re-basa con `git -C <directorio>` para medir el blob y el estado. Una ruta
+relativa se contaría desde **dos bases distintas** (`cwd` y el directorio del objeto) y
+podría hashear *otro* archivo que sí existe. Fail-closed: ruta relativa ⇒ `RC 20`.
+
+## Por qué `RC 14` existe
+
+Sin árbol git, `git status` devuelve 128 con salida vacía. Un gate ingenuo lee esa
+salida vacía como «limpio» y da verde. Aquí se declara la imposibilidad: sin árbol no
+hay identidad de blob que valga.
+
+## Banco de casos
+
+```bash
+bash tests/must_fail.sh
+```
+
+9 casos, **9/9**, cada uno verificando código **y** causa: `20` (tupla incompleta),
+`20` (ruta relativa), `10`, `11`, `12`, `15`, `13`, `14` y el control positivo `0`.
+Un banco sin control positivo sólo demuestra que el instrumento sabe decir que no.
+
+## Telemetría fuera de banda
+
+Cada corrida anota 7 campos (`hora_utc target blob_pre blob_medido rc hash_arbol_ini
+hash_arbol_fin`) en `${GATE_TELEMETRIA_LOG:-$HOME/preflight-telemetria.log}`. La
+telemetría **no puede mover el RC**, **no puede abortar** y **no puede refrescar el
+índice** (`--no-optional-locks`). La ruta nunca es relativa: un log dentro del árbol se
+vuelve un archivo no rastreado, y entonces el gate termina midiendo su propia
+telemetría — el instrumento que se cuenta a sí mismo.
+
+## Límites declarados
+
+- Sobre un `TARGET` inexistente el gate corta en `RC 10` **antes** de comparar blob y
+  líneas: en la rama de creación, la tupla es **contrato**, no medición. Se declara; no
+  se repara (fail-closed es correcto).
+- No juzga el contenido: certifica identidad y colisión, no corrección.
+
+## La Action de la raíz: CI Authority Gate
+
+El `action.yml` de este repositorio es una **action composite** que ejecuta un segundo
+instrumento, `sim/gate_workflows_ci.py`: un verificador estructural de la topología de
+autoridad en `.github/workflows/`. Cinco invariantes contables, siete causas tipadas,
+`RC = min(causas)`, `UNIVERSO_VACIO` = causa `31` (cero archivos es fracaso, no
+aprobación).
+
+Identidad medida del instrumento copiado a este árbol:
+
+| propiedad | valor |
+|---|---|
+| líneas / bytes | 615 / 21470 |
+| git blob | `ff9c69a944e7965b3fda0901f7745d80a9e85c7c` |
+| sha256-16 | `073954a84f3c84fd` |
+
+Uso como consumidor:
+
+```yaml
+- uses: alexisromtz-lab/git-preflight-gate@v0.1.4
+  with:
+    workflows-dir: .github/workflows
+    fail-on-red: "true"
+```
+
+<!-- HUELLA-RELEASE-V013-20261031 -->
+`v0.1.3`, `v0.1.2` y `v0.1.1` ejecutan el mismo `action.yml` (`9ef420ec`) y el mismo
+`sim/gate_workflows_ci.py` (`ff9c69a9`): el código del gate no cambió entre los tres.
+Lo que cambia es el envoltorio de adopción —`v0.1.2` añadió `templates/platino-gate.yml`
+y `v0.1.3` añadió `action-selftest.yml`, la alineación del manifiesto y esta
+documentación—. Si fijas por SHA, usa el commit —no el tag—.
+
+Los cuatro inputs (`workflows-dir`, `root`, `python-bin`, `fail-on-red`) y los dos
+outputs (`rc`, `veredicto`) conservan el contrato del `action.yml` que este repositorio
+**reemplaza**: cualquier CI que apuntaba a la action de la raíz de un repositorio de
+trabajo migra cambiando sólo el nombre del repositorio en `uses:`; el resto del bloque
+`with:` no cambia.
+
+La acción no adivina el dominio: el instrumento resuelve un único punto,
+`<raiz>/.github/workflows`. Por eso `workflows-dir` se enruta a `--file` cuando el path
+existe y a `--root` cuando no. Un `--root` que aceptara cualquier directorio con YAMLs
+sería editar el metro para que quepa la demo.
+
+Dependencia única: `PyYAML==6.0.3`, declarada como extra opcional
+(`pip install ".[ci-authority-gate]"`). El resto es stdlib. El instrumento no lee red,
+no escribe archivos, no usa aleatoriedad y no consulta el reloj.
+
+Instalable sin clonar el repositorio, desde el wheel de la release. El extra
+`ci-authority-gate` es obligatorio para el CLI: sin PyYAML el instrumento no mide y
+sale con `RC=30` (fail-closed), no con verde.
+
+```bash
+pip install "git-preflight-gate[ci-authority-gate] @ https://github.com/alexisromtz-lab/git-preflight-gate/releases/download/v0.1.4/git_preflight_gate-0.1.4-py3-none-any.whl"
+ci-authority-gate --self-test   # banco must-fail incorporado; no toca disco
+ci-authority-gate --root .      # mide <raiz>/.github/workflows y devuelve su RC
+```
+
+<!-- HUELLA-README-V014-20261106 -->
+`v0.1.4` no cambia el gate: `action.yml` (`9ef420ec`) y `sim/gate_workflows_ci.py`
+(`ff9c69a9`) son los mismos blobs que en `v0.1.3`. Lo que cambia es el paquete:
+`MANIFEST.in` hace que el sdist lleve el producto, y el manifiesto declara el paquete
+`sim` y el script `ci-authority-gate`. Antes de este cambio el wheel eran 6 768 B de
+solo `dist-info` y no existía ningún CLI. En PyPI todavía no está publicado: la única
+vía de `pip` hoy es la URL de la release.
+
+Control positivo medido: workflow con `permissions: contents: read` y `uses` fijado por
+SHA completo ⇒ `CAUSAS PRESENTES: ninguna`, `VEREDICTO: PASA`, `RC=0`. Control negativo:
+`pull_request_target` + `permissions: write-all` + `curl | bash` + `actions/checkout@v4`
+⇒ `CAUSAS PRESENTES: [1, 2, 5]`, `RC=1`. Universo vacío ⇒ `CAUSAS PRESENTES: [31]`,
+`RC=31`.
+
+## Los dos instrumentos no se confunden
+
+| instrumento | pregunta | forma |
+|---|---|---|
+| `preflight-gate.sh` | ¿este agente puede escribir *este archivo* ahora? | CLI bash, tupla de destino |
+| `sim/gate_workflows_ci.py` | ¿esta topología de CI concentra autoridad sin control? | action composite + CLI Python |
+
+El primero protege una escritura; el segundo audita un árbol de workflows. Comparten la
+doctrina (fail-closed, causa impresa, cero archivos = imposibilidad declarada), no el
+código.
+
+## Instalarlo en tu repositorio en 1 minuto
+
+<!-- HUELLA-BADGE-PLATINO-README-20261031 -->
+
+```bash
+mkdir -p .github/workflows
+curl -fsSL https://raw.githubusercontent.com/alexisromtz-lab/git-preflight-gate/main/templates/platino-gate.yml \
+  -o .github/workflows/platino-gate.yml
+git add .github/workflows/platino-gate.yml
+git commit -m "ci: platino preflight gate"
+git push
+```
+
+Eso es todo: el workflow se dispara en el siguiente `push` o PR.
+
+### El archivo debe llamarse `platino-gate.yml` (esto es un contrato, no un consejo)
+
+Si lo renombras —`ci.yml`, `gate.yml`, `platino-gate.yaml`— el primer job falla
+cerrado con `RC 20` y te dice por qué. La razón es medida, no estética: el badge
+de estado se resuelve **por nombre de archivo** (`.../workflow/status/TU-REPO/TU-REPO/platino-gate.yml`).
+Con otro nombre, el badge leería *tu* workflow de CI, no este gate, y publicaría un
+verde que no mide nada. El contrato está dentro del workflow, no en esta página.
+
+Falsado por `tests/test_platino_gate_template.py`: 5 casos de nombre y 5
+estructurales, `RC 0` solo si los 10 concuerdan; un template mutado para aceptar
+cualquier `.yml` devuelve `RC 1` nombrando la fila culpable.
+
+## El badge
+
+Al terminar el run, la pestaña **Summary** publica el badge ya rellenado con tu
+`owner/repo`. Hay dos, y no son lo mismo:
+
+| badge | qué afirma | permisos que pide |
+|---|---|---|
+| de **estado** (dinámico) | el resultado real del run más reciente de `platino-gate.yml` | `contents: read` |
+| **sello** (estático) | «este repositorio pasó el gate» | `contents: read` |
+
+```markdown
+[![Platino Preflight Gate](https://img.shields.io/github/actions/workflow/status/OWNER/REPO/platino-gate.yml?label=preflight%20gate&branch=main)](https://github.com/alexisromtz-lab/la-auditora)
+
+[![Audited by Platino Labs](https://img.shields.io/badge/audited_by-Platino_Labs-6f42c1)](https://github.com/alexisromtz-lab/la-auditora)
+```
+
+El de estado no puede mentir: lo dibuja GitHub desde el run. **El sello, sí**: es un
+literal que cualquiera puede pegar en verde sin haber corrido nada. Ponlo solo cuando
+el run esté en verde — el gate no lo puede verificar por ti.
+
+**Cero permisos de escritura, en los dos casos.** El workflow no toca tu README, no
+pide `contents: write` y no necesita ningún servicio nuestro: el badge es una URL de
+`shields.io` que lee el estado público de tu propio workflow. No hay endpoint que
+hospedar, ni token que caducar.
+
+### Qué mide y qué no
+
+| mide | no mide |
+|---|---|
+| topología de autoridad en `.github/workflows/`: `permissions`, disparadores, `uses` por SHA, sumideros de ejecución | si tu código hace lo que dice |
+| siete causas tipadas, `RC = min(causas)`, `UNIVERSO_VACIO` = causa `31` | los permisos por defecto del `GITHUB_TOKEN` a nivel de organización |
+| el árbol que tienes, en el commit que corre | confianza OIDC / Trusted Publishing en el registro destino |
+
+El segundo bloque está impreso en cada run, bajo `RESIDUO DECLARADO`. Un gate que no
+declara sus límites no es un gate: es una promesa.
+
+### Cómo se prueba el propio envoltorio
+
+<!-- HUELLA-BADGE-SELFTEST-DOC-20261031 -->
+El `action.yml` no se prueba leyendo su YAML: se ejecuta. En cada push a `main`, el
+workflow [`action-selftest.yml`](.github/workflows/action-selftest.yml) corre la acción
+dos veces con `uses: ./` —sobre este mismo repositorio, donde exige `rc=0` / `PASA`, y
+sobre una fixture envenenada en `tests/fixtures/sumidero`, donde exige `rc=2` /
+`SUMIDERO_IMPUDO`—. Si la instalación del extra (`pip install "<action_dir>[ci-authority-gate]"`)
+o el enrutado de inputs se rompen, enrojece aquí antes de enrojecer en tu runner.
+
+Un self-test que sólo sabe estar verde no discrimina nada: por eso el segundo caso exige
+que la acción **falle** con la causa correcta.
+
+## Licencia
+
+MIT. Ver `LICENSE`.