docrot-gate

Docs don't die at once. They rot one stale command at a time.
_{one file · zero dependencies · stdlib only}

---

The failure this catches

• The README command worked three years ago; a new hire runs it and gets an error.
• Docs reference files that were renamed; the links 404 and nobody goes back to fix them.
• The version is hardcoded in three places and the real version is a fourth.

One command, on a file you already have:

python gate.py examples/docs

Real output — produced by the bundled examples/, not a mock-up

docrot-gate: root=examples/docs
docs: 2, refs checked: 4, broken: 2, external skipped: 0
BROKEN README.md:3 [code-path] ./scripts/old_deploy.sh
BROKEN README.md:5 [link] missing.md

What it does

• Checks relative links, referenced make targets, and version strings against the repo.
• JSON output for dashboards, plain text for humans.
• Runs in a second on a normal docs tree — make it a pre-commit hook.

What it does not do

• It does not execute commands in docs. It checks that targets exist.
• It cannot detect prose that is logically wrong but syntactically fine.
• External URL liveness is out of scope (network flakiness is not a finding).

Being explicit here is cheaper than a wrong expectation later.

Exit codes

0 = no stale reference. 1 = broken reference found. 2 = bad input.

Install

git clone https://github.com/chenhz01/docrot-gate
cd docrot-gate
python gate.py --help

Python 3.9+. Nothing to pip install — stdlib only.

Use it in CI

- name: docrot-gate
  run: python gate.py examples/docs

Use it as a GitHub Action

action.yml is included, so you can call this repo directly as a composite action.

# .github/workflows/gates.yml
- uses: actions/checkout@v4

- uses: chenhz01/[email protected]
  with:
    # IMPORTANT: this path is inside YOUR repository.
    # The examples/ in this repo are NOT in your workspace — pass your own files.
    args: "path/to/docs"

Pin the tag (@v0.1.3) rather than @main — main moves. Check Releases for the newest tag; v0.1.0 predates the fix that makes a mistyped path fail instead of silently passing.

If you omit args, the action only prints help and exits 0. It raises a warning annotation — quoting this gate's own correct usage — so a green check is never mistaken for "it inspected my files".

中文速览

文档腐烂门 — 文档不是一次性死掉的，它一个命令一个命令地烂掉。

• README 里那条命令三年前能用，新人照着敲，报错。
• 文档引用的文件早就改名了，链接 404，没人回头修。
• 版本号写死在三个地方，实际版本是第四个。

一行命令：python gate.py examples/docs

边界：It does not execute commands in docs. It checks that targets exist.

互推：只装一个的话，装哪个

十五个链接是迷宫，一个症状是门。按上表挑一个，其余九个在下面 The gates。 每个仓都能单独活：复制 gate.py，一条命令跑完，不共享运行时、不装包、不加配置。 有星就给这一个，没有也不影响任何仓的可用性——没有任何门是「先给星才能用」。

热门前置：保证结构，不保证排名

本页承诺的是 15 项可机器复核的结构特征，当前 15/15（2026-10-20 复核）。 GitHub 从未公开 Trending 的排序算法，所以任何「保证上热门」的说法都在描述一件它不可能知道的事； 本仓不这么说。跑 python tools/hotness.py 可自行复算每一条。

Start here (if you install only one)

Fifteen links is a maze; one symptom is a door. Find your symptom, install that gate, ignore the rest until it hurts.

what you are seeing	install this
the bill is 10x normal and the trace is a wall of the same step	loop-gate
the agent can delete prod and nobody signed off on that	permission-gate
answers get worse after truncation and nobody knows what got dropped	context-gate
two rules in the prompt contradict each other; the model obeys neither	instruction-gate
AI text ships with fabricated links and empty phrases	output-gate
half the repo might be dead and nobody can prove which half	deadcode-gate

A gate you did not need is a gate you uninstall, so nothing here says "install all fifteen". Each repo stands alone: copy gate.py, run one command, no shared runtime, no package manager, no config file to grow.

On stars. If this one saved you an incident, star it — that is the only signal I get about which gate to build next. There is no exchange: starring one repo does not owe me a star on another, and no gate here is unlocked by a star. Star trading breaks GitHub's rules and would poison the single honest metric this project has.

Hot-ready guarantee

What is guaranteed is structure, not ranking. Fifteen properties, each one machine-checked against this repo — current score 15/15 (2026-10-20).

Plain version: instead of asking you to trust a badge, I list what I actually checked, name the script that checks it, and let you re-run it. If one of these lines is false, that is a bug in my repo, not a matter of taste.

• Falsifiable side: python tools/hotness.py re-runs every check and prints the evidence line for each one. You do not have to trust this paragraph.
• Non-falsifiable side: GitHub has never published how Trending sorts repositories, so any repo promising you a guaranteed spot is telling you something it cannot know. This one does not make that promise.
• If a claim on this page stops being true, that is a bug: open an issue and it gets fixed in the same week, not in the next launch.

What actually carries this repo:

• the command in this README is byte-for-byte the command CI runs _{(21-char argv, exact match)}
• the output block is a real run of examples/, not a mock-up _{(Real output section)}
• CI asserts the exit code, so the badge can turn red — and it has _{(asserts exit=1)}
• every fixture is committed, so a fresh clone reproduces the output _{(2 files under examples/ tracked in git)}
• * -text in .gitattributes: same bytes on Windows and Linux _{(.gitattributes * -text)}

The gates

#	gate	what it stops
02	loop-gate	Find where your agent looped, before it burns another run
03	permission-gate	Score how much more your agent can do than it should
04	context-gate	Measure what truncation deletes, before the model starts guessing
05	instruction-gate	Two of your instructions contradict each other. This finds them
06	output-gate	Before AI-written text ships, run the four checks it always fails
07	memory-expiry-gate	Give every memory a TTL, then prove the expiry semantics actually hold
08	drift-gate	When embeddings drift, retrieval quietly rots. Fingerprint it
09	price-gate	Your cost model is only as good as the price table under it
10	complexity-ceiling	Per-file complexity budgets that fail the build instead of the reviewer
11	deadcode-gate	Quantify how much of the repo is dead, instead of guessing
12	docrot-gate ← you are here	Docs don't die at once. They rot one stale command at a time
13	leak-gate	Scan for internal detail before the doc leaves the building
14	backup-gate	A backup you have never verified is a rumor
15	trail-gate	Hash-chained agent audit trail — and it verifies its own chain

License

• Code: Apache-2.0 — see LICENSE
• Docs and example data: CC BY 4.0 — see LICENSE-SPEC

Attribution required when you redistribute the documentation; code can be used commercially without a separate agreement. See NOTICE.