An open-source verification harness and hierarchical context scaffolding designed to enforce deterministic boundaries and multi-tier quality gates for autonomous AI coding agents.
Disclaimer: Checkrail is an independent open-source engineering project. It is not affiliated with, endorsed by, or associated with any other project, commercial platform, or trademark holder.
Experimental (pre-1.0). Checkrail is under active development. Gate specifications, file formats, and runtime interfaces may evolve across releases. Use in production environments at your own discretion. No benchmark results have been published yet for token optimization claims.
As Large Language Models (LLMs) and autonomous agent frameworks (Kilo, Claude Code, OpenCode, Cursor, Devin) transition from exploratory code-completion to fully autonomous codebase refactoring and CI/CD operations, they introduce critical failure modes:
- Context Bloat & Token Degradation (Attention Bleed): Recursive file-tree scanning and unfiltered context dumps exhaust attention mechanisms, increasing operational latency, API costs, and hallucination rates.
- Guardrail & Security Erosion: Unconstrained agents inadvertently modify security manifests, weaken CI checks, or bypass permission boundaries.
- Secret Ingestion & Exfiltration: Accidental ingestion and staging of
.envfiles, SSH credentials, and private keys. - Repository Documentation Drift: Autonomous changes break manual architectural maps, invalidating agent grounding on subsequent turns.
- Session Amnesia & State Loss: Fragmented state transitions between multi-turn or multi-agent worktree handovers.
Checkrail introduces a multi-tiered, deterministic verification and context-management harness that enforces formal safety boundaries and is architecturally designed to mitigate context degradation and enforce policy and quality gate compliance before code reaches review.
┌─────────────────────────────────────────────────────────────────────────────┐
│ Layer 0: AGENTS.md (Root Invariants) │
│ Deterministic trigger routing • Lean L0 context routing │
└──────────────────────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────┴──────────────────────┐
▼ ▼
┌───────────────────────────────┐ ┌───────────────────────────────┐
│ Layer 1: Architecture Core │ │ Layer 2: Protocol Engine │
│ (docs/agent/SUMMARY.md) │ │ (docs/agent/protocol.md) │
│ Domain context, Stack & Flow │ │ Deep workflows & fallback │
└───────────────────────────────┘ └───────────────────────────────┘
│ │
└──────────────────────┬──────────────────────┘
│
┌──────────────────────────────────────┴──────────────────────────────────────┐
│ Automated Governance & Verification Harness │
│ ├── 9-Tier Quality Verification (scripts/quality-gates.sh) │
│ ├── Zero-Drift Compact Indexing (scripts/sync-docs.sh) │
│ ├── Sandboxed Permission Rules (kilo.jsonc) │
│ ├── Formal Empirical Audit Matrix (docs/agent/bootstrap-audit.md) │
│ └── Deterministic State Handover (docs/agent/HANDOVER.md) │
└─────────────────────────────────────────────────────────────────────────────┘
Checkrail discards monolithic prompts in favor of an indexed 3-layer architecture:
- Layer 0 (
AGENTS.md): Always-on routing table. Directs agents to exact files without recursive exploration. - Layer 1 (
docs/agent/SUMMARY.md): High-level domain, stack specifications, and pipeline models. - Layer 2 (
docs/agent/protocol.md): Deep execution workflows, loaded strictly when blocking ambiguities arise.
Every agent and developer change is passed through a deterministic nine-tier verification pipeline (Gate 0 – Gate 8):
- Gate 0: Tooling Prerequisite Check — Verifies major/minor version compliance (
.tool-versions). - Gate 1: Base Branch & Differential Scoping — Isolates target diffs and prevents unanchored commits.
- Gate 2: Clean Tree & Working-Copy Integrity — Validates staging consistency and rejects untracked drift.
- Gate 3: Protected Guardrail Defense — Blocks agent mutations to security, CI, and policy files unless explicitly authorized with
--allow-guardrail. - Gate 4: Shell Syntax & POSIX/LF Compliance — Strict
bash -nvalidation and line-ending verification. - Gate 5: Static Analysis & Code Quality — Python static typing, linting (
ruff), and QA harnesses. - Gate 6: Infrastructure & Configuration Verification — Validates Terraform and cloud orchestration manifests.
- Gate 7: Deterministic Documentation Verification — Fails if documentation index (
docs/file-index.md) drifts from disk state. - Gate 8: Anti-Leak Cryptographic & Secret Scan — Integrated Gitleaks analysis and fallback heuristic scanning.
- Generates a compact, deterministic inventory in
docs/file-index.mdfromscripts/file-descriptions.txt. - Provides structural grounding to agents within a bounded token budget (≤ 20 KB, enforced by
sync-docs.sh).
- Strict deny/ask rules for destructive actions (
rm -rf, raw.envreading, unconstrained shell execution).
- Bounded 40-line invariant state schema (
[TASK],[DIFF_SUMMARY],[GATES_STATUS],[NEXT],[BLOCKERS]) providing continuous context across distributed worktrees and agent sessions.
Checkrail documents a failure-mode analysis and remediation record in docs/agent/bootstrap-audit.md, covering 24 hardened-bootstrap findings and their verified fixes, including:
- Subshell variable-inheritance failures in child processes.
- Cross-platform Bash compatibility, including macOS's default Bash 3.2.
- Path-traversal and symlink-overwrite defenses.
- TOCTOU (Time-of-Check to Time-of-Use) atomic file operations.
- Windows execution alias stub handling in CI environments.
- Not a Formal Proof: Checkrail enforces deterministic static checks, shell validation, and git boundaries. It does not mathematically prove the runtime semantic correctness of generated application code.
- Token Metrics Are Architectural: Token efficiency gains stem from structured context separation (L0/L1/L2) avoiding full-tree reads. Empirical benchmark quantification is ongoing and not yet published.
- POSIX / Linux Centric: Checkrail is built primarily for Bash-compatible environments (Linux, macOS, WSL2). Native Windows environments without a POSIX layer are not supported.
- No Semantic Logic Guarantee: The gates verify syntax, diff scope, secret absence, and structure—not whether the business logic meets user intent.
git clone https://github.com/miladjln/checkrail.git
cd checkrail
# Run full diagnostic verification
bash scripts/doctor.sh# Register quality gates into local git hooks
pre-commit installWhenever repository files or modules change:
# Update descriptions in scripts/file-descriptions.txt, then:
bash scripts/sync-docs.sh
# Stage the regenerated index
git add docs/file-index.md# Fast-tier gate for staged changes (Pre-Commit)
bash scripts/quality-gates.sh --staged-only --fast
# Complete 9-tier verification suite (CI Equivalent)
bash scripts/quality-gates.sh| Script | Function | Key Flags |
|---|---|---|
scripts/doctor.sh |
Health check for environment, dependencies, CRLF, and pack integrity. | None |
scripts/quality-gates.sh |
Comprehensive 9-tier automated quality and security gates. | --staged-only, --fast, --allow-guardrail, --ack-new-guardrail, --quiet, --strict-versions |
scripts/sync-docs.sh |
Deterministic documentation indexer and drift detector. | --check, --compact, --full |
checkrail/
├── .github/
│ ├── workflows/
│ │ └── quality-gates.yml # Production CI Verification Pipeline
│ ├── ISSUE_TEMPLATE/ # Standardized Bug & Feature Blueprints
│ ├── PULL_REQUEST_TEMPLATE.md # Gate-Enforced Pull Request Checklist
│ ├── dependabot.yml # Automated Dependency & Action Updates
│ └── CODEOWNERS # Access & Ownership Matrix
├── .kilo/ # Autonomous Agent Workspace & Subagent Runtime
├── docs/
│ ├── agent/
│ │ ├── SUMMARY.md # Layer 1 Architectural Context
│ │ ├── protocol.md # Layer 2 Execution Protocol
│ │ ├── HANDOVER.md # Standardized State Handover File
│ │ └── bootstrap-audit.md # Formal Security & Regression Audit Log
│ └── file-index.md # Auto-Generated Compact File Inventory
├── scripts/
│ ├── doctor.sh # Environment Diagnostic & Health Script
│ ├── file-descriptions.txt # Canonical File Description Register
│ ├── quality-gates.sh # 9-Tier Security & Quality Gate Harness
│ └── sync-docs.sh # Zero-Drift Documentation Synchronizer
├── .gitattributes # LF Enforcement & Normalization Policy
├── .gitignore # Comprehensive VCS Ignore Register
├── .kilocodeignore # LLM Context Exclusion Filter
├── .pre-commit-config.yaml # Pre-commit Hook Hookpack Configuration
├── .tool-versions # Pinned Tool Runtime Versions
├── AGENTS.md # Layer 0 Root Agent Rulebook & Invariants
├── CITATION.cff # Formal Academic Citation Metadata
├── CONTRIBUTING.md # Engineering & Contribution Guidelines
├── kilo.jsonc # Engine Security Sandbox & Permissions
├── LICENSE # MIT Open-Source License
├── README.md # Comprehensive Technical Specification
└── SECURITY.md # Security Vulnerability & Disclosure Policy
If you incorporate Checkrail in academic papers, research benchmarks, or industrial autonomous frameworks, please cite:
@software{jalilian2026checkrail,
author = {Jalilian, Seyed Milad},
title = {Checkrail: Deterministic Quality Gates and Hierarchical Context Scaffolding for AI Coding Agents},
year = {2026},
url = {https://github.com/miladjln/checkrail},
version = {0.1.0}
}We welcome contributions from engineers and researchers. Please review CONTRIBUTING.md for workflow protocols and gate standards.
For vulnerability disclosures and security policies, refer to SECURITY.md.
This project is licensed under the MIT License — see the LICENSE file.
Copyright (c) 2026 Seyed Milad Jalilian