PR Review & Auto-Merge Engine
Relevant source files
The following files were used as context for generating this wiki page:
The PR Review & Auto-Merge Engine is a specialized governance layer within the IDAHO-VAULT project designed to manage a swarm of AI agents contributing to the repository. Its primary purpose is to ensure that all AI-authored changes are classified by risk, scanned for security vulnerabilities, and validated against content safety protocols before being held in a staged state for final human approval.
Sources: Tappet.md, AGENTIC-GITHUB-REVIEW-BEST-PRACTICES-2026-06-15.md
Architecture and Core Systems
The engine operates as a structured pipeline that treats AI-generated content with the same Continuous Integration (CI) discipline as production code. It utilizes a multi-agent coordination model where specialized agents perform distinct cognitive tasks—such as security analysis, performance optimization, and architectural review—coordinated by an orchestrator layer.
Sources: Tappet.md, AGENTIC-GITHUB-REVIEW-BEST-PRACTICES-2026-06-15.md
Governance Layers
The engine is ranked across several core systems that enforce vault integrity:
- Agent Swarm Governance: A registry coordinated via
agents.jsonandswarm.jsonthat defines tiered capabilities (Direct Write, Advisory, or Read-only) for each agent. - Risk-Classification Engine: Utilizes
classify_paths.pyto apply a two-axis tier scheme (filetype and Nest-depth) to every Pull Request (PR), labeling them asrisk/loworrisk/high. - Automated PR Pipeline: Automatically creates PRs for agent-prefixed branches (e.g.,
claude/*,codex/*), tags them for their lifecycle stage (e.g.,staged), and manages them through a merge queue.
Sources: Tappet.md, PROPOSAL-CLAUDE-CODEX-SECURITY-COLLAB-2026-05-25.md
Data Flow Diagram
The following diagram illustrates the flow of an AI-authored change from branch creation to final merge.
Review Discipline and Security Invariants
The engine enforces strict security invariants to prevent "personality fractures" and unreliable contributions from AI agents.
Mandatory Enforcement Rules
| Rule | Description | Implementation |
|---|---|---|
| Secret Exclusion | Scans for credentials, GitHub tokens, and private keys. | check_secret_patterns.py |
| Manifest Locking | Requires registration in manifest.json under a soft-lock before commit. | update_manifest.py |
| Path Portability | Blocks cross-platform path violations (e.g., illegal characters). | check-portable-paths.yml |
| Content Validation | Prevents deletion of protected files like CONSTITUTION.md. | validate_content.py |
Sources: Tappet.md
Human-in-the-Loop Governance
A critical design principle is that the agent can never bless its own work. The main branch is protected such that Logan (the human owner) remains the sole merge authority. Even in automated rhythms, high-risk or doctrinal PRs (those affecting !/ or .claude/) are flagged for "Aquinas-time"—a human-reserved judgment period.
Sources: AGENTIC-GITHUB-REVIEW-BEST-PRACTICES-2026-06-15.md:214-230, !/ARBORSCAPE-PR-EXPANSION-2026-05-22.md
Operational Rhythms
The engine employs "rhythms"—scheduled cadences for routine maintenance. These rhythms handle repetitive gardening tasks such as branch cleanup and stale PR sweeps, allowing the human owner to focus on architectural decisions.
PR Triage Sequence
When evaluating a PR, the engine performs a per-utterance verification against the GitHub API state to detect divergence between agent claims and reality.
Chronic Failure Monitoring
The engine periodically performs CI failure sweeps to identify chronic issues. For example, specific matrix jobs like Cross-Platform Smoke or security scans like Codacy are monitored for auto-superseding pushes or environmental Shadowing (e.g., importlib.py shadowing stdlib).
Sources: !/AUDIT-CI-FAILURE-SWEEP-2026-07-31.md, audit-results.txt
PR State and Risk Classification
The classify_paths.py utility computes binary tiers based on the "maze" (filetype) and "labyrinth" (depth) of the changes.
- Low-Risk: Typically includes natural language files or machine documentation. These may receive
review/pendingtags for auto-merge eligibility. - High-Risk: Includes computer code or changes to core governance roots (e.g.,
!/Swarmic Nest). These always require explicit human intervention.
Sources: Tappet.md, !/ARBORSCAPE-PR-EXPANSION-2026-05-22.md
The PR Review & Auto-Merge Engine successfully bridges the gap between high-volume AI contributions and the requirement for absolute human governance. By codifying institutional memory and security checks into the CI pipeline, the vault maintains a self-policing environment where AI agents are treated as productive but potentially unreliable infrastructure.