Deterministic Semantic AST Diff Router & Deterministic AST Partitioner with Decorator-Docstring and Frame-Reflection Guards for Multi-Agent Pull Requests.
Eliminates the 80% Agent Review Bottleneck • Two-Tier Semantic AST Partitioning • RFC 8785 Canonical Receipts • CVE-2026-85626 Safe Ref Firewall
Install via pip or run instantaneously with Astral uv:
# Run directly against your current Git branch vs. main
uv tool run git-antique --base main --head HEAD
# Or install in your development environment
pip install git-antique### git-antique Semantic Diff Receipt (`@antique_receipt:sha256:4f8e...`)
- **Gate Verdict**: **AUTO-APPROVABLE (ZERO LOGIC DIFF)**
- **Attention Compression**: **100.0%** (0 logic lines of 142 changed lines)
| File | Classification | Changed Lines | Human Attention Lines |
| :--- | :--- | ---: | ---: |
| `src/core/auth.py` | `TRIVIAL_COSMETIC` | 48 | 0 |
| `src/models/user.py` | `STRUCTURAL_ISOMORPHIC` | 94 | 0 |If an autonomous agent merely reformatted non-schema docstrings, sorted imports, and performed alpha-renaming on non-reflecting local variables, git-antique's deterministic AST partitioner with decorator-docstring and frame-reflection guards proves that zero semantic logic mutated. Your CI pipeline auto-approves the PR in sub-millisecond time.
Autonomous coding agents (Devin, SWE-bench bots, Claude Code, Cursor Composer) can generate hundreds of Pull Requests per day. However, human engineering attention does not scale linearly:
- The Review Deluge: A 500-line diff often contains 450 lines of cosmetic churn (formatting, type hints, docstrings, sorted imports, variable renames) and only 50 lines of actual semantic control-flow modifications.
- Reviewer Fatigue & Rubber-Stamping: Overwhelmed human reviewers either become a grinding pipeline bottleneck or begin rubber-stamping PRs, allowing subtle security bugs, logic regressions, and backdoors into production.
-
Fragile Text-Based Diffs: Standard
git diffoperates on textual lines. It cannot distinguish between an innocuous rename (temp_var$\to$ item) and a critical condition inversion (if not user.is_authenticated:$\to$ if user.is_authenticated:).
git-antique parses source code into Python Abstract Syntax Trees (AST) and routes code diffs through a deterministic two-tier semantic filter:
Incoming Git Diff
│
▼
┌───────────────────────────────────────┐
│ Lexical Normalizer │
│ • Strip whitespace & comments │
│ • Normalize contiguous sorted imports │
└──────────────────┬────────────────────┘
│
Tokens match? ─┼──► YES: Tier 0 (TRIVIAL_COSMETIC)
│ [0 Human Attention Lines]
▼
┌───────────────────────────────────────┐
│ Structural Normalizer │
│ • Strip static type annotations │
│ • Canonical De Bruijn local α-rename │
└──────────────────┬────────────────────┘
│
ASTs match? ──┼──► YES: Tier 1 (STRUCTURAL_ISOMORPHIC)
│ [0 Human Attention Lines]
▼
NO: Tier 2 (SEMANTIC_LOGIC_MUTATION)
• Branch mutations, call mutations, control flow
• Forces Human Four-Eyes Review
| Tier | Classification | Semantic Impact | Attention Tax | Action |
|---|---|---|---|---|
| Tier 0 | TRIVIAL_COSMETIC |
Docstrings, inline comments, whitespace, sorted contiguous imports. | 0 lines | Auto-Approvable |
| Tier 1 | STRUCTURAL_ISOMORPHIC |
Type annotation modifications, local variable alpha-renaming ( |
0 lines | Auto-Approvable |
| Tier 2 | SEMANTIC_LOGIC_MUTATION |
Changes to AST operators, function invocations, boolean conditions, or side effects. | Four-Eyes Review Required | |
| Fail-Closed | UNANALYZED_NON_PYTHON |
CI workflows (.github/), Dockerfiles, shell scripts, database migrations. |
Manual Review Required |
To prevent command-line flag injection when invoking Git subprocesses (git show, git diff), git-antique enforces strict Unicode NFC canonical validation on all ref arguments (verify_safe_git_ref):
- Rejects refs starting with leading dashes (e.g.
--upload-pack,--output). - Rejects null bytes (
\x00), carriage returns, and whitespace. - Rejects directory traversal paths (
..).
git-antique queries Git using git diff --name-only -z separated by bytes([0]), preventing filename corruption or newline injection on arbitrary filenames.
If a PR modifies non-Python files (e.g. modifying .github/workflows/ci.yml or adding an .exe), git-antique does not silently assume the diff is cosmetic. It classifies the file as UNANALYZED_NON_PYTHON and trips the gate to REVIEW REQUIRED, preventing backdoor injection through auxiliary assets.
Every evaluation produces a tamper-evident @antique_receipt:sha256:... generated via RFC 8785 deterministic JSON canonicalization.
Docstrings attached to schema-bound functions or classes (e.g. @mcp.tool, @click.command, @app.get, @router.post, @dataclass, @pydantic.*) define LLM runtime schemas and prompt injection vectors (ETUDE). git-antique pins schema docstrings and escalates any modification to SEMANTIC_LOGIC_MUTATION.
Functions executing runtime reflection calls (locals(), vars(), dir(), eval(), exec(), sys._getframe(), inspect.currentframe()) block local alpha-renaming and fail closed to SEMANTIC_LOGIC_MUTATION, preventing scope-leak regressions.
git-antique [OPTIONS]| Flag | Default | Description |
|---|---|---|
--repo PATH |
. |
Target Git repository root path. |
--base REF |
main |
Base Git revision (e.g., main, master, v0.1.0). |
--head REF |
HEAD |
Head Git revision to compare against base. |
--python-only |
False |
Filter inspection strictly to .py files. |
--format FORMAT |
markdown |
Output format: markdown (PR comment) or json (CI pipeline machine consumption). |
{
"receipt_id": "@antique_receipt:sha256:d8a1c9e8...",
"base_ref": "main",
"head_ref": "HEAD",
"total_changed_lines": 142,
"total_human_attention_lines": 0,
"attention_compression_ratio": 1.0,
"requires_human_logic_review": false,
"files": [
{
"filepath": "src/core/auth.py",
"classification": "TRIVIAL_COSMETIC",
"changed_lines": 48,
"human_attention_lines": 0
}
]
}Add git-antique to .github/workflows/antique-gate.yml to automatically verify agent PRs:
name: git-antique Semantic Gate
on:
pull_request:
branches: [main]
jobs:
semantic-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: astral-sh/setup-uv@v5
with:
enable-cache: true
- name: Run git-antique Review Gate
id: antique
run: |
uv tool run git-antique --base origin/main --head HEAD --format markdown > receipt.md
cat receipt.md
- name: Post PR Receipt Comment
if: github.event_name == 'pull_request'
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const receipt = fs.readFileSync('receipt.md', 'utf8');
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: receipt
});# Clone the repository
git clone https://github.com/invarcore/git-antique.git
cd git-antique
# Run complete test suite with 100% coverage check
uv run pytest -v --cov=git_antique --cov-fail-under=95Apache-2.0. Copyright © 2026 Invarcore Organization.