context-gate

Measure what truncation deletes, before the model starts guessing.
_{one file · zero dependencies · stdlib only}

---

The failure this catches

• Head truncation cut off the final error message, so the model invented a different one.
• Same input, different truncation strategy, answers differ by 2x — nobody knows why.
• 'Just truncate when it overflows' is in the design doc; where it truncates is whoever coded last.

One command, on a file you already have:

python gate.py bench --input examples/units.json --budget 600

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

units=40 total_tokens=2000 budget=600
strategy            score   weighted   critical   tokens
head               0.2133     0.3000     0.0833      600
tail               0.4133     0.3000     0.5833      600
middle             0.2467     0.3000     0.1667      600
head_tail          0.3467     0.3000     0.4167      600
top_importance     0.5800     0.3000     1.0000      600
hybrid             0.3500     0.2500     0.5000      500
winner: top_importance

What it does

• Benchmarks head / tail / middle / hybrid against a token budget you set.
• Reports critical-unit survival, not just bytes kept — the number that matters.
• Ships a synthetic generator, so you can get a baseline before you have logs.

What it does not do

• It does not call a model — quality here is measured by unit survival, not answer accuracy.
• You must mark critical units yourself; it cannot infer importance from text.
• It does not implement truncation for you, it tells you which one to implement.

Being explicit here is cheaper than a wrong expectation later.

Exit codes

0 = the benchmark ran. 2 = bad input. This is a measurement, not a gate: exceeding --budget is reported, not enforced. Compare the strategies, then set your own ceiling.

Install

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

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

Use it in CI

- name: context-gate
  run: python gate.py bench --input examples/units.json --budget 600

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/context-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: "bench --input path/to/units.json --budget 600"

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

中文速览

上下文门 — 在模型开始瞎编之前，先量化截断到底删掉了什么。

• head 截断把最后那段报错切掉了，模型于是开始编一个不存在的错。
• 同一份输入，换个截断策略，答案质量差一倍，但没人知道差在哪。
• 「上下文不够就截断」写在架构文档里，具体截哪里，全凭当时的实现者。

一行命令：python gate.py bench --input examples/units.json --budget 600

边界：It does not call a model — quality here is measured by unit survival, not answer accuracy.

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

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