git-preflight-gate 0.1.6__py3-none-any.whl

git_preflight_gate-0.1.6.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+git_preflight_gate-0.1.6.dist-info/licenses/LICENSE,sha256=FiSMHs2bDfBb2jb4R3qAR6MRDeku8203wSaPlRg5tic,1069
+sim/__init__.py,sha256=tkOQZJGTK4hlzrVJJkWJNcaAFuFhj3geBw8R79BS_a4,428
+sim/gate_workflows_ci.py,sha256=tCpdndGc7RMPOtjd-IsCwOC8C-YopxFT6wiVkjK9bck,29941
+git_preflight_gate-0.1.6.dist-info/METADATA,sha256=Hgj6cY4dYH8jPJoY17FsS0mPBqJIzC1XE7kBZ6tIj48,12834
+git_preflight_gate-0.1.6.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+git_preflight_gate-0.1.6.dist-info/entry_points.txt,sha256=-KoZKb1gLlgvyqHZ2SwTeHJhYIage76hBTF_5M1XUAs,65
+git_preflight_gate-0.1.6.dist-info/top_level.txt,sha256=lf-JWfiGnB0ZZ1Sd9fz8Zh9R5MCupexpcxpg21zinzs,4
+git_preflight_gate-0.1.6.dist-info/RECORD,,

git_preflight_gate-0.1.6.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

git_preflight_gate-0.1.6.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ci-authority-gate = sim.gate_workflows_ci:main

git_preflight_gate-0.1.6.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+sim

sim/__init__.py

@@ -0,0 +1,8 @@
+"""Paquete del gate estructural de CI (`gate_workflows_ci`).
+
+HUELLA-SIM-PAQUETE-20261106: el manifiesto declara este paquete para que el
+wheel lleve el instrumento y `pip install` deje un CLI en el PATH. El action
+composite NO lo usa: invoca el instrumento por ruta absoluta, porque en un
+runner `github.action_path` apunta al checkout de la accion, no a
+site-packages. Las dos rutas conviven y ninguna depende de la otra.
+"""

sim/gate_workflows_ci.py

@@ -0,0 +1,813 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+gate_workflows_ci.py
+====================
+Verificador estructural DETERMINISTA de la topologia de autoridad en pipelines
+de CI.  Analiza el AST de los YAML de .github/workflows/ y aplica CINCO
+invariantes contables.  No lee red, no escribe archivos, no usa aleatoriedad,
+no consulta el reloj.
+
+INVARIANTE CENTRAL (forma corregida):
+
+    Autoridad(Job) > 0   =>   Ejecucion(repo U deps)(Job) = vacio
+
+No se afirma "cero ejecucion": la autoridad tiene que ejecutar ALGO (descargar
+un artefacto, correr el cliente nativo).  Lo que se prohibe es que ese algo
+provenga del repositorio o de sus dependencias.
+
+UNIVERSO DECLARADO: .github/workflows/*.yml + .github/workflows/*.yaml
+MOTOR: python3 stdlib + PyYAML (safe_load) -- sin red, sin escritura, sin azar
+REGLA DE VEREDICTO: RC 0 (PASA) | RC > 0 (FALLO CERRADO, causa tipada)
+
+TABLA DE CAUSAS (RC):
+  1  AUTORIDAD_CONTAMINADA  Job con permisos de ESCRITURA que ejecuta codigo
+                            de terceros mediante `run:` (gestor de paquetes,
+                            interprete, descarga o mutacion de VCS).  Un
+                            cliente nativo de publicacion (ALLOWLIST_SINK)
+                            no cuenta como ejecucion: publica artefactos.
+  2  SUMIDERO_IMPUDO         Job sumidero (`id-token: write`) que hace
+                            `actions/checkout`, invoca herramientas dinamicas
+                            (npx/pipx) o no consume exclusivamente artefactos
+                            descargados (`actions/download-artifact`).
+  3  DISPARADOR_ENVENENADO   Trigger `pull_request_target` / `workflow_run`
+                            con checkout explicito del commit del PR / head
+                            dentro de un contexto con secretos o autoridad.
+  4  SECRETO_EXPUESTO        `${{ secrets.* }}` interpolado dentro de un bloque
+                            `run:` (el valor entra al argv y al log), o en
+                            `env:` / `with:` de un job con disparador
+                            privilegiado que alcanza contenido no confiable.
+                            Un secreto pasado como INPUT de una accion no es
+                            exposicion: es el mecanismo documentado.  Ver el
+                            dominio declarado de RC 4 mas abajo.
+  5  REF_MUTABLE             `uses:` con tag flotante (@v*, @main, @master) en
+                            vez de SHA-1 de 40 caracteres.
+ 31  UNIVERSO_VACIO          No hay archivos de workflow que medir.
+ 32  YAML_INVALIDO           El archivo no parsea.
+
+RESIDUO DECLARADO (PLANO CIEGO FUERA DEL ARCHIVO):
+  1. Permisos por defecto del GITHUB_TOKEN a nivel de repositorio/organizacion.
+  2. Politicas de confianza OIDC / Trusted Publishing en el registro destino.
+  3. Ejecucion de codigo nativo no aislado en runtime (modificacion de deps).
+  4. Workflows reutilizables (`workflow_call`) y acciones compuestas alojadas
+     en repositorios ajenos.
+  => El instrumento certifica la AUSENCIA de la forma `autoridad contaminada`
+     en el archivo que PUEDE leer.  NO certifica el plano que no ve.
+
+DOMINIO DECLARADO DE RC 1 (ancho, no umbral):
+  `actions/checkout` por si solo NO dispara RC 1.  RC 1 mide EJECUCION
+  (`run:`), no presencia del arbol.  La presencia del arbol en un job con
+  autoridad de publicacion es RC 2 (SUMIDERO_IMPUDO).  La particion es
+  declarada, no silenciosa.
+  ALLOWLIST_SINK: el cliente nativo de publicacion (`npm publish ...`) queda
+  fuera del computo de ejecucion de terceros, porque el sumidero canonico
+  TIENE que ejecutarlo.  Es una restriccion de DOMINIO declarada, no una
+  bajada de umbral: el conjunto admitido es exactamente el cliente nativo.
+
+DOMINIO DECLARADO DE RC 4 (secreto + sumidero):
+  El defecto es la EXPOSICION, no la PRESENCIA del secreto.  Hay dos sumideros
+  y solo dos:
+    SINK_SHELL    -> `${{ secrets.* }}` interpolado dentro de `run:`: el valor
+                     entra al argv del proceso y al log del step, y habilita
+                     inyeccion de shell.  Siempre RC 4.
+    SINK_CONTEXTO -> `${{ secrets.* }}` en `env:` (global o de job) o en `with:`
+                     de un paso, EN UN JOB cuyo disparador es privilegiado
+                     (`pull_request_target` / `workflow_run`) y que hace checkout
+                     de una ref no confiable.  RC 4.
+  Un secreto en `env:` de un job ordinario, o como INPUT (`with:`) de una accion
+  SHA-pinada, NO es exposicion: es la forma documentada de dar una credencial.
+  Se publica como OBSERVACION (se vio y no es sumidero), no como hallazgo: el
+  lector tiene que poder distinguir "no lo vi" de "lo vi y no lo es".
+  Medido 2026-11-06 sobre 47 workflows de 6 repos maduros: 23 jobs con secreto,
+  23/23 en `with:`, 0/23 en `run:`.  Con la regla anterior el 100 % de la clase
+  era falso positivo (HUELLA-RC4-SUMIDERO-20261106).
+"""
+
+import argparse
+import io
+import json
+import os
+import re
+import sys
+
+try:
+    import yaml
+except Exception as _e:  # pragma: no cover
+    sys.stderr.write("MOTOR INCOMPLETO: PyYAML ausente (%s). Fail-closed.\n" % (_e,))
+    raise SystemExit(30)
+
+MOTOR = "python3 stdlib + PyYAML %s (sin red, sin escritura, sin azar)" % (
+    getattr(yaml, "__version__", "?"),
+)
+UNIVERSO = ".github/workflows/*.yml + .github/workflows/*.yaml del arbol objetivo"
+INVARIANTE = "Autoridad(Job) > 0  =>  Ejecucion(repo U deps)(Job) = vacio"
+REGLA = "RC 0 (PASA) | RC > 0 (FALLO CERRADO, causa tipada)"
+
+RESIDUO = (
+    "Permisos por defecto del GITHUB_TOKEN a nivel de repositorio u organizacion.",
+    "Politicas de confianza OIDC / Trusted Publishing en el registro destino (npm, PyPI, AWS).",
+    "Modificacion de dependencias en runtime si se ejecuta codigo nativo no aislado.",
+    "Workflows reutilizables (workflow_call) y acciones compuestas alojadas en repositorios ajenos.",
+)
+
+CAUSAS = {
+    1: "AUTORIDAD_CONTAMINADA",
+    2: "SUMIDERO_IMPUDO",
+    3: "DISPARADOR_ENVENENADO",
+    4: "SECRETO_EXPUESTO",
+    5: "REF_MUTABLE",
+    31: "UNIVERSO_VACIO",
+    32: "YAML_INVALIDO",
+}
+
+# ----------------------------------------------------------------------------
+# Patrones.  Todos son LEXICOS y se aplican linea por linea (dominio declarado:
+# una linea de `run:` es la unidad de juicio).
+# ----------------------------------------------------------------------------
+PAT_EXEC = re.compile(
+    r"\b(npm|pnpm|yarn|npx|pipx|pip3|pip|cargo|rustc|go|gem|bundle|composer"
+    r"|make|cmake|node|deno|bun|python3|python|ruby|php|java|mvn|gradle|dotnet)\b"
+)
+PAT_FETCH = re.compile(r"\b(curl|wget)\b")
+PAT_GITMUT = re.compile(r"\bgit\s+(push|commit|tag|remote|config)\b")
+PAT_GH = re.compile(r"(^|[\s;&|(])gh\s+[a-z]")
+# HUELLA-SINK-NATIVO-20261106: el allowlist cubria solo `npm publish`, asi que
+# todo otro cliente nativo de publicacion (`gh release create`, `twine upload`,
+# `docker push`, `cargo|poetry|uv publish`) contaba como "ejecuta codigo de
+# terceros" y disparaba RC 1 en el patron de release canonico y endurecido.
+# Medido en `pallets/flask`: `.github/workflows/publish.yaml :: create-release`
+# (`permissions: contents: write`, sin checkout, `gh release create --draft`)
+# -> RC 1 falso. La allowlist NO abre la puerta a `gh api` ni a `gh` en general:
+# solo a los verbos de publicacion, que no ejecutan codigo del repositorio.
+PAT_SINK_OK = re.compile(
+    r"^\s*(?:"
+    r"npm\s+publish\b"
+    r"|pnpm\s+publish\b"
+    r"|yarn\s+npm\s+publish\b"
+    r"|twine\s+upload\b"
+    r"|gh\s+release\s+(?:create|upload|edit)\b"
+    r"|docker\s+push\b"
+    r"|cargo\s+publish\b"
+    r"|poetry\s+publish\b"
+    r"|uv\s+publish\b"
+    r")"
+)
+PAT_DINAMICO = re.compile(r"\b(npx|pipx)\b")
+PAT_SECRETS = re.compile(r"\$\{\{\s*secrets\.[A-Za-z0-9_]")
+PAT_SHA40 = re.compile(r"^[0-9a-f]{40}$")
+PAT_UNTRUSTED_REF = re.compile(r"github\.event\.(pull_request\.head|workflow_run\.head)")
+
+
+def _walk_str(obj):
+    """Todos los literales de cadena de un subarbol YAML (claves incluidas)."""
+    if isinstance(obj, str):
+        yield obj
+    elif isinstance(obj, dict):
+        for k, v in obj.items():
+            yield str(k)
+            yield from _walk_str(v)
+    elif isinstance(obj, (list, tuple)):
+        for x in obj:
+            yield from _walk_str(x)
+
+
+def _clave_on(wf):
+    """PyYAML (YAML 1.1) convierte la clave `on` en el booleano True."""
+    for k in (True, "on", "On", "ON"):
+        if k in wf:
+            return wf[k]
+    return None
+
+
+def _triggers(val):
+    if val is None:
+        return set()
+    if isinstance(val, str):
+        return {val}
+    if isinstance(val, (list, tuple)):
+        return {str(x) for x in val}
+    if isinstance(val, dict):
+        return {str(k) for k in val.keys()}
+    return set()
+
+
+def _mapa_perm(p):
+    if p is None:
+        return None
+    if isinstance(p, str):
+        v = p.strip().lower()
+        if v == "write-all":
+            return {"*": "write"}
+        if v == "read-all":
+            return {"*": "read"}
+        return {v: "write"}
+    if isinstance(p, dict):
+        return {str(k): str(v).strip().lower() for k, v in p.items()}
+    return None
+
+
+def scopes_write(mapa):
+    if not mapa:
+        return set()
+    return {k for k, v in mapa.items() if v == "write"}
+
+
+def _pasos(job):
+    out = []
+    for s in (job.get("steps") or []):
+        if isinstance(s, dict):
+            out.append(s)
+    return out
+
+
+def _runs(job):
+    return [str(s.get("run", "")) for s in _pasos(job) if "run" in s]
+
+
+def _uses(job):
+    return [str(s.get("uses", "")) for s in _pasos(job) if "uses" in s]
+
+
+def _todos_los_uses(wf):
+    out = []
+    jobs = wf.get("jobs")
+    if isinstance(jobs, dict):
+        for job in jobs.values():
+            if not isinstance(job, dict):
+                continue
+            if isinstance(job.get("uses"), str):
+                out.append(job["uses"])
+            out.extend(_uses(job))
+    return out
+
+
+def _tiene_checkout(job):
+    return any(u.startswith("actions/checkout") for u in _uses(job))
+
+
+def _tiene_download(job):
+    return any(u.startswith("actions/download-artifact") for u in _uses(job))
+
+
+def _secretos_por_ubicacion(wf, job):
+    """Ubica cada `${{ secrets.* }}` en su sumidero real.
+
+    HUELLA-RC4-SUMIDERO-20261106 (medido 2026-11-06): RC 4 medía PRESENCIA de
+    `secrets.*`, no EXPOSICION.  Sobre 47 workflows de 6 repos maduros
+    (pallets/flask, pydantic/pydantic, python-poetry/poetry, saleor/saleor,
+    wagtail/wagtail, encode/httpx) hay 23 jobs con secreto y 23/23 lo pasan en
+    `with:` a una accion SHA-pinada (codecov-action, create-github-app-token,
+    configure-aws-credentials, create-pull-request): 0/23 en `run:`.  La forma
+    documentada de dar una credencial a una accion se reportaba como fuga: el
+    100 % de la clase era falso positivo.
+
+    Devuelve (en_run, en_insumo, obs):
+      en_run    -- textos `run:` que interpolan un secreto (SINK_SHELL)
+      en_insumo -- valores secretos en `env:` (global / de job) o `with:` (SINK_CONTEXTO)
+      obs       -- [(ubicacion, fuente)]: el secreto se vio y no es sumidero por si mismo
+    """
+    en_run, en_insumo, obs = [], [], []
+    for etiqueta, src in (("env global", wf.get("env")), ("env de job", job.get("env"))):
+        if src:
+            vals = [x for x in _walk_str(src) if PAT_SECRETS.search(x)]
+            if vals:
+                en_insumo.extend(vals)
+                obs.append((etiqueta, etiqueta))
+    for s in _pasos(job):
+        if "run" in s and PAT_SECRETS.search(str(s.get("run", ""))):
+            en_run.append(str(s.get("run", "")))
+        if "with" in s:
+            vals = [x for x in _walk_str(s.get("with")) if PAT_SECRETS.search(x)]
+            if vals:
+                en_insumo.extend(vals)
+                obs.append(("with:", "with: %s" % (str(s.get("uses", "?"))[:60],)))
+    return en_run, en_insumo, obs
+
+
+def _linea_ejecuta(linea):
+    """Una linea de shell ejecuta codigo de terceros?"""
+    s = linea.strip()
+    if not s or s.startswith("#"):
+        return False
+    if PAT_SINK_OK.match(s):  # ALLOWLIST_SINK: cliente nativo de publicacion
+        return False
+    return bool(
+        PAT_EXEC.search(s) or PAT_FETCH.search(s) or PAT_GITMUT.search(s) or PAT_GH.search(s)
+    )
+
+
+def ref_mutable(valor):
+    v = valor.strip()
+    if v.startswith("./") or v.startswith(".\\"):
+        return False
+    if v.startswith("docker://"):
+        return "@sha256:" not in v
+    if "@" not in v:
+        return True
+    return not PAT_SHA40.match(v.rsplit("@", 1)[1])
+
+
+# ----------------------------------------------------------------------------
+# NUCLEO
+# ----------------------------------------------------------------------------
+def analizar(texto, nombre):
+    """Devuelve la lista de hallazgos [(rc, causa, archivo, job, detalle)]."""
+    return analizar_detallado(texto, nombre)[0]
+
+
+def analizar_detallado(texto, nombre):
+    """Devuelve (hallazgos, observaciones).
+
+    Las observaciones son secretos que el instrumento VIO y no son sumidero por
+    si mismos.  Viajan aparte para que `rc` no las cuente como defecto y para
+    que el lector pueda distinguir "no lo vi" de "lo vi y no lo es".
+    """
+    hs = []
+    obs = {}
+    try:
+        wf = yaml.safe_load(texto)
+    except yaml.YAMLError as e:
+        return [{"rc": 32, "causa": CAUSAS[32], "archivo": nombre, "job": "-",
+                 "detalle": str(e)[:200]}], []
+    if not isinstance(wf, dict):
+        return [{"rc": 32, "causa": CAUSAS[32], "archivo": nombre, "job": "-",
+                 "detalle": "raiz del YAML no es un mapping"}], []
+
+    wf_perm = _mapa_perm(wf.get("permissions"))
+    triggers = _triggers(_clave_on(wf))
+    pr_target = bool(triggers & {"pull_request_target", "workflow_run"})
+    clase_trigger = ",".join(sorted(triggers & {"pull_request_target", "workflow_run"}))
+
+    # ---- RC 5: barrido global de referencias
+    for v in _todos_los_uses(wf):
+        if ref_mutable(v):
+            hs.append({"rc": 5, "causa": CAUSAS[5], "archivo": nombre, "job": "-",
+                       "detalle": "uses con ref flotante: %s" % (v[:90],)})
+
+    # HUELLA-RC4-SUMIDERO-20261106: el bloque `env:` global ya no emite RC 4 por
+    # si mismo.  Lo mide cada job que lo hereda (el env global se propaga a todos
+    # los jobs), y solo cuenta como exposicion si el job tiene sumidero.
+
+    jobs = wf.get("jobs")
+    if not isinstance(jobs, dict):
+        jobs = {}
+
+    for jn in sorted(jobs.keys(), key=str):
+        job = jobs.get(jn)
+        if not isinstance(job, dict):
+            continue
+        perm = _mapa_perm(job.get("permissions")) if "permissions" in job else wf_perm
+        sw = scopes_write(perm)
+
+        # ---- RC 1: AUTORIDAD_CONTAMINADA
+        if sw:
+            malas = []
+            for cmd in _runs(job):
+                for linea in cmd.splitlines():
+                    if _linea_ejecuta(linea):
+                        malas.append(linea.strip())
+            if malas:
+                hs.append({"rc": 1, "causa": CAUSAS[1], "archivo": nombre, "job": str(jn),
+                           "detalle": "scopes=%s ejecuta: %s"
+                                      % (",".join(sorted(sw)), malas[0][:90])})
+
+        # ---- RC 2: SUMIDERO_IMPUDO
+        if ("id-token" in sw) or ("*" in sw):
+            motivos = []
+            if _tiene_checkout(job):
+                motivos.append("actions/checkout")
+            if any(PAT_DINAMICO.search(c) for c in _runs(job)):
+                motivos.append("herramienta dinamica (npx/pipx)")
+            if not _tiene_download(job):
+                motivos.append("sin actions/download-artifact")
+            if motivos:
+                hs.append({"rc": 2, "causa": CAUSAS[2], "archivo": nombre, "job": str(jn),
+                           "detalle": "; ".join(motivos)})
+
+        # ---- secretos: ubicacion por sumidero (HUELLA-RC4-SUMIDERO-20261106)
+        en_run, en_insumo, obs_sec = _secretos_por_ubicacion(wf, job)
+
+        untrusted = False
+        if pr_target and _tiene_checkout(job):
+            refs = []
+            for s in _pasos(job):
+                if str(s.get("uses", "")).startswith("actions/checkout"):
+                    w = s.get("with")
+                    if isinstance(w, dict):
+                        refs.append(str(w.get("ref", "")))
+            untrusted = any(PAT_UNTRUSTED_REF.search(r) for r in refs)
+
+        # ---- RC 3: DISPARADOR_ENVENENADO
+        contexto = bool(sw) or bool(en_run or en_insumo)
+        if pr_target and _tiene_checkout(job) and untrusted and contexto:
+            hs.append({"rc": 3, "causa": CAUSAS[3], "archivo": nombre, "job": str(jn),
+                       "detalle": "trigger %s + checkout de ref no confiable en contexto privilegiado"
+                                  % (clase_trigger,)})
+
+        # ---- RC 4: SECRETO_EXPUESTO (secreto + sumidero, no presencia)
+        if en_run:
+            hs.append({"rc": 4, "causa": CAUSAS[4], "archivo": nombre, "job": str(jn),
+                       "detalle": "secrets interpolado en run: (%d bloque(s)): el valor entra al argv"
+                                  % (len(en_run),)})
+        elif en_insumo and pr_target and untrusted:
+            hs.append({"rc": 4, "causa": CAUSAS[4], "archivo": nombre, "job": str(jn),
+                       "detalle": "secrets en env/with bajo %s + checkout de ref no confiable"
+                                  " (el instrumento no evalua if:/labels: una etiqueta de"
+                                  " mantenedor no cubre el relanzamiento por synchronize)"
+                                  % (clase_trigger,)})
+        else:
+            for sitio, fuente in obs_sec:
+                obs.setdefault((sitio, fuente), set()).add(str(jn))
+
+    observaciones = [
+        {"archivo": nombre, "ubicacion": k[0], "fuente": k[1],
+         "job": ", ".join(sorted(js)) if len(js) < 6 else "%d jobs" % (len(js),)}
+        for k, js in sorted(obs.items())
+    ]
+    return hs, observaciones
+
+
+# ----------------------------------------------------------------------------
+# BANCO MUST-FAIL INCORPORADO  (sobre cadenas: CERO escrituras a disco)
+# ----------------------------------------------------------------------------
+SHA_CHECKOUT = "11bd71901bbe5b1630ceea73d27597364c9af683"
+SHA_SETUPNODE = "39370e3970a6d050c480ffad4ff0ed4d3fdee5af"
+SHA_UPLOAD = "65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08"
+SHA_DOWNLOAD = "fa0a91b85d4f404e444e00e005971372dc801d16"
+
+C0_CANONICO = """
+name: publicar
+on:
+  release:
+    types: [published]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@%s
+      - uses: actions/setup-node@%s
+        with:
+          node-version: "20"
+      - run: npm ci --ignore-scripts
+      - run: npm pack
+      - run: sha256sum ./*.tgz > SHASUMS256.txt
+      - uses: actions/upload-artifact@%s
+        with:
+          name: dist
+          path: |
+            *.tgz
+            SHASUMS256.txt
+  publish:
+    needs: [build]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      actions: read
+    steps:
+      - uses: actions/download-artifact@%s
+        with:
+          name: dist
+      - run: sha256sum -c SHASUMS256.txt
+      - run: npm publish --provenance ./*.tgz
+""" % (SHA_CHECKOUT, SHA_SETUPNODE, SHA_UPLOAD, SHA_DOWNLOAD)
+
+C1_AUTORIDAD = """
+name: contaminado
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@%s
+      - run: npm ci
+""" % (SHA_CHECKOUT,)
+
+# HUELLA-SINK-NATIVO-20261106: control positivo -- el release canonico de
+# `pallets/flask` (autoridad de escritura, sin checkout, `gh release create`)
+# tiene que PASAR.  Antes de la allowlist daba RC 1.
+C7_PUBLICADOR_NATIVO = """
+name: publish
+on:
+  push:
+    tags: ['*']
+permissions: {}
+jobs:
+  create-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@%s
+        with:
+          name: dist
+          path: dist/
+      - name: create release
+        run: gh release create --draft --repo ${GITHUB_REPOSITORY} ${GITHUB_REF_NAME} dist/*
+        env:
+          GH_TOKEN: ${{ github.token }}
+""" % (SHA_DOWNLOAD,)
+
+# ... y su must-fail: `gh` NO es un sink en bloque.  Bajo la misma autoridad,
+# `gh api` mutando la configuracion del repositorio sigue siendo RC 1.
+C8_GH_API_EN_AUTORIDAD = """
+name: contaminado-gh
+on: push
+jobs:
+  alterar:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - run: gh api -X DELETE repos/${GITHUB_REPOSITORY}/branches/main/protection
+"""
+
+C2_SUMIDERO = """
+name: sumidero
+on:
+  release:
+    types: [published]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - run: npm publish --provenance ./*.tgz
+"""
+
+C3_DISPARADOR = """
+name: pr-target
+on: pull_request_target
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@%s
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+""" % (SHA_CHECKOUT,)
+
+D1_ENV_SECRETO_SIN_SUMIDERO = """
+name: env-secreto
+on: push
+env:
+  TOKEN: ${{ secrets.NPM_TOKEN }}
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - run: echo ok
+"""
+
+D2_ACCION_CON_SECRETO = """
+name: inputo-de-accion
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@%s
+        with:
+          repository: alexisromtz-lab/privado
+          token: ${{ secrets.REPO_TOKEN }}
+""" % (SHA_CHECKOUT,)
+
+D3_SECRETO_EN_RUN = """
+name: secreto-en-shell
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - run: |
+          curl -sS -H "Authorization: Bearer ${{ secrets.API_TOKEN }}" https://example.test/hook
+"""
+
+D4_SECRETO_EN_CONTEXTO_NO_CONFIABLE = """
+name: pr-target-con-secreto
+on: pull_request_target
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@%s
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          token: ${{ secrets.APP_TOKEN }}
+""" % (SHA_CHECKOUT,)
+
+C5_REF = """
+name: flotante
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci --ignore-scripts
+"""
+
+C6_DOS_CAUSAS = """
+name: sumidero-sucio
+on:
+  release:
+    types: [published]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@%s
+      - uses: actions/download-artifact@%s
+        with:
+          name: dist
+      - run: npx --yes provenance-publish ./dist/*.tgz
+""" % (SHA_CHECKOUT, SHA_DOWNLOAD)
+
+BANCO = (
+    ("C0_CANONICO_DOS_JOBS", C0_CANONICO, 0, frozenset(), 0),
+    ("C1_AUTORIDAD_CONTAMINADA", C1_AUTORIDAD, 1, frozenset([1]), 0),
+    ("C2_SUMIDERO_IMPUDO", C2_SUMIDERO, 2, frozenset([2]), 0),
+    ("C3_DISPARADOR_ENVENENADO", C3_DISPARADOR, 3, frozenset([3]), 0),
+    ("C5_REF_MUTABLE", C5_REF, 5, frozenset([5]), 0),
+    ("C6_DOS_CAUSAS_A_LA_VEZ", C6_DOS_CAUSAS, 1, frozenset([1, 2]), 0),
+    ("C7_PUBLICADOR_NATIVO", C7_PUBLICADOR_NATIVO, 0, frozenset(), 0),
+    ("C8_GH_API_EN_AUTORIDAD", C8_GH_API_EN_AUTORIDAD, 1, frozenset([1]), 0),
+    ("D1_ENV_SECRETO_SIN_SUMIDERO", D1_ENV_SECRETO_SIN_SUMIDERO, 0, frozenset(), 1),
+    ("D2_ACCION_CON_SECRETO", D2_ACCION_CON_SECRETO, 0, frozenset(), 1),
+    ("D3_SECRETO_EN_RUN", D3_SECRETO_EN_RUN, 4, frozenset([4]), 0),
+    ("D4_SECRETO_EN_CONTEXTO_NO_CONFIABLE", D4_SECRETO_EN_CONTEXTO_NO_CONFIABLE, 3,
+     frozenset([3, 4]), 0),
+)
+CONTROL = "C0_CANONICO_DOS_JOBS"
+
+
+def correr_banco():
+    filas = []
+    for nombre, texto, rc_esp, causas_esp, obs_esp in BANCO:
+        hs, obs = analizar_detallado(texto, "<memoria>/%s.yml" % nombre)
+        rc = min((h["rc"] for h in hs), default=0)
+        causas = frozenset(h["rc"] for h in hs)
+        ok = (rc == rc_esp) and (causas == causas_esp) and (len(obs) == obs_esp)
+        filas.append({
+            "caso": nombre,
+            "rc_esperado": rc_esp,
+            "rc_medido": rc,
+            "causas_esperadas": sorted(causas_esp),
+            "causas_medidas": sorted(causas),
+            "observaciones_esperadas": obs_esp,
+            "observaciones_medidas": len(obs),
+            "ok": ok,
+            "detalle": [h["detalle"] for h in hs],
+        })
+    banco_ok = all(f["ok"] for f in filas)
+    return filas, banco_ok
+
+
+# ----------------------------------------------------------------------------
+# SALIDA
+# ----------------------------------------------------------------------------
+def imprimir_cabecera():
+    print("UNIVERSO DECLARADO: %s" % UNIVERSO)
+    print("MOTOR: %s" % MOTOR)
+    print("REGLA DE VEREDICTO: %s" % REGLA)
+    print("INVARIANTE: %s" % INVARIANTE)
+    print("RESIDUO DECLARADO (PLANO CIEGO FUERA DE YAML):")
+    for r in RESIDUO:
+        print("  - %s" % r)
+
+
+def _fmt_causas(s):
+    return "{rc:%s|%s}" % (
+        ",".join(str(x) for x in s) if s else "-",
+        ",".join(CAUSAS.get(x, "?") for x in s) if s else "ninguna",
+    )
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Gate estructural de CI: topologia de autoridad en .github/workflows/."
+    )
+    ap.add_argument("ruta", nargs="?", default=".", help="raiz del arbol objetivo (default: .)")
+    ap.add_argument("--root", dest="root", default=None, help="raiz explicita del arbol objetivo")
+    ap.add_argument("--file", dest="archivo", default=None, help="analizar UN archivo YAML")
+    ap.add_argument("--json", dest="json", action="store_true", help="salida JSON")
+    ap.add_argument("--self-test", dest="self_test", action="store_true",
+                    help="correr el banco must-fail incorporado (sin tocar disco)")
+    ap.add_argument("--must-fail", dest="must_fail", action="store_true",
+                    help="alias de --self-test: exige que cada causa provoque su RC")
+    ns = ap.parse_args(argv)
+
+    banco = ns.self_test or ns.must_fail
+
+    if banco:
+        filas, banco_ok = correr_banco()
+        if ns.json:
+            print(json.dumps({
+                "universo": UNIVERSO, "motor": MOTOR, "invariante": INVARIANTE,
+                "regla_de_veredicto": REGLA, "residuo_declarado": list(RESIDUO),
+                "causas": CAUSAS, "self_test": filas, "banco_ok": banco_ok,
+                "rc": 0 if banco_ok else 21,
+            }, indent=2, ensure_ascii=False))
+        else:
+            imprimir_cabecera()
+            print("")
+            print("BANCO MUST-FAIL (casos en memoria; el instrumento no escribe disco)")
+            print("%-28s %-20s %-20s %-6s %s" % ("CASO", "ESPERADO", "MEDIDO", "OBS", "OK"))
+            for f in filas:
+                print("%-28s %-20s %-20s %-6s %s" % (
+                    f["caso"],
+                    _fmt_causas(frozenset(f["causas_esperadas"])),
+                    _fmt_causas(frozenset(f["causas_medidas"])),
+                    "%d/%d" % (f["observaciones_medidas"], f["observaciones_esperadas"]),
+                    "SI" if f["ok"] else "NO",
+                ))
+            print("")
+            for f in filas:
+                for d in f["detalle"]:
+                    print("  [%s] %s" % (f["caso"], d))
+            print("")
+            print("banco_ok = %s" % banco_ok)
+        return 0 if banco_ok else 21
+
+    raiz = ns.root or ns.ruta
+    archivos = []
+    if ns.archivo:
+        archivos = [ns.archivo]
+    else:
+        d = os.path.join(raiz, ".github", "workflows")
+        if os.path.isdir(d):
+            for fn in sorted(os.listdir(d)):
+                if fn.endswith(".yml") or fn.endswith(".yaml"):
+                    archivos.append(os.path.join(d, fn))
+
+    hallazgos = []
+    observaciones = []
+    if not archivos:
+        hallazgos.append({"rc": 31, "causa": CAUSAS[31], "archivo": "-", "job": "-",
+                          "detalle": "0 archivos en %s: nada que medir" % (os.path.join(raiz, ".github", "workflows"),)})
+    else:
+        for ruta in archivos:
+            try:
+                with io.open(ruta, "r", encoding="utf-8") as fh:
+                    texto = fh.read()
+            except Exception as e:
+                hallazgos.append({"rc": 32, "causa": CAUSAS[32], "archivo": ruta, "job": "-",
+                                  "detalle": "no legible: %s" % (e,)})
+                continue
+            hs_archivo, obs_archivo = analizar_detallado(texto, ruta)
+            hallazgos.extend(hs_archivo)
+            observaciones.extend(obs_archivo)
+
+    causas = sorted({h["rc"] for h in hallazgos})
+    rc = min(causas) if causas else 0
+
+    if ns.json:
+        print(json.dumps({
+            "universo": UNIVERSO, "motor": MOTOR, "invariante": INVARIANTE,
+            "regla_de_veredicto": REGLA, "residuo_declarado": list(RESIDUO),
+            "causas": CAUSAS, "raiz": raiz, "archivos": archivos,
+            "hallazgos": hallazgos, "causas_presentes": causas, "rc": rc,
+            "observaciones": observaciones,
+        }, indent=2, ensure_ascii=False))
+    else:
+        imprimir_cabecera()
+        print("")
+        print("RAIZ: %s" % raiz)
+        print("ARCHIVOS MEDIDOS: %d" % len(archivos))
+        for h in hallazgos:
+            print("  RC %-2d %-22s %s :: %s :: %s"
+                  % (h["rc"], h["causa"], h["archivo"], h["job"], h["detalle"]))
+        print("")
+        print("OBSERVACIONES (secreto visto, sin sumidero: NO es hallazgo): %d"
+              % len(observaciones))
+        for o in observaciones:
+            print("  OBS    %-22s %s :: %s (%s)"
+                  % (o["ubicacion"], o["archivo"], o["fuente"], o["job"]))
+        print("")
+        print("CAUSAS PRESENTES: %s" % (causas if causas else "ninguna"))
+        print("VEREDICTO: %s  RC=%d" % ("PASA" if rc == 0 else "FALLO CERRADO", rc))
+    return rc
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())