trail-gate

Hash-chained agent audit trail — and it verifies its own chain.
_{two files · zero dependencies · stdlib only}

---

The failure this catches

• The postmortem log was missing the one step that mattered, and nobody could prove it was not edited.
• Four agents each wrote their own log, and the timelines do not line up.
• 'Rolled back' is the entire record of what the rollback actually undid.

One command, on a file you already have:

python gate.py verify examples/trail.jsonl

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

valid: True | events: 2 | errors: 0

Try it on your own input (optional)

The one-liner above reads the bundled examples/ as shipped, so it works on a fresh clone. To watch the gate act on something you wrote yourself, drive a scratch copy — cp resets it at the start of every run, so the result is the same each time and the bundled sample is never modified:

cp examples/trail.jsonl demo-trail.jsonl
python gate.py append demo-trail.jsonl --type decision --payload {"action":"deploy"}
python gate.py append demo-trail.jsonl --type tool_call --payload {"tool":"run_tests"}
python gate.py verify demo-trail.jsonl

What it does

• Append-only JSONL where each event hashes the previous one.
• verify detects tamper, gaps, reordering, bad types, and broken rollback references.
• Rollback is a first-class event with a ref to the seq it undoes.

What it does not do

• Local integrity only — it does not stop someone rewriting the whole file.
• No server, no signatures, no timestamp authority. Ship it to a WORM store if you need that.
• It records what you tell it; it does not observe your agent.

Being explicit here is cheaper than a wrong expectation later.

Exit codes

0 = chain intact. 1 = tamper, gap, reorder, bad type, or broken rollback. 2 = bad input. The bundled example is a valid chain — it exits 0 on purpose.

Install

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

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

Use it in CI

- name: trail-gate
  run: python gate.py verify examples/trail.jsonl

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/trail-gate@v0.1.3
  with:
    # IMPORTANT: this path is inside YOUR repository.
    # The examples/ in this repo are NOT in your workspace — pass your own files.
    args: "verify path/to/trail.jsonl"

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".

中文速览

轨迹门 — 哈希链式 Agent 审计轨迹——而且它会验证自己的链。

• 出事要复盘，发现日志缺了最关键那一步，而且没人能证明它没被改过。
• 四个 Agent 各自写日志，时间线对不上。
• 回滚到底回滚了什么，只有一句「已回滚」。

一行命令：python gate.py verify examples/trail.jsonl

边界：Local integrity only — it does not stop someone rewriting the whole file.

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

十五个链接是迷宫，一个症状是门。按上表挑一个，其余九个在下面 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 _{(35-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=0)}
• 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	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 ← you are here	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.