Git & Version Control Guardrails
Relevant source files
The following files were used as context for generating this wiki page:
Git & Version Control Guardrails in the IDAHO-VAULT project comprise a specialized set of automated policies, scripts, and workflows designed to maintain the integrity of a personal knowledge vault. These guardrails ensure that the vault remains a "single authoritative, tamper-resistant, multi-agent-writable" system where multiple AI agents can contribute without causing data corruption, secret leakage, or cross-platform compatibility issues. Sources: Sieve.md:28-32, RECOVERED-BOOK-GEMINIAEUS-PR214-2026-08-14/original-tree/!/MIND/BOOK-OF-GEMINIAEUS/Sheet2.md:214-219
The system employs a layered defense strategy, utilizing GitHub Actions, local pre-commit checks, and specialized risk-classification logic to govern how changes are merged into the main branch. This is particularly critical given the "Swarm" of AI agents—including Claude, Codex, and Gemini—that actively participate in the repository's lifecycle. Sources: Sieve.md:12-26, PROPOSAL-CLAUDE-CODEX-SECURITY-COLLAB-2026-05-25.md:12-19
Core Security and Policy Enforcements
The guardrails implement several non-negotiable rules to protect the repository from common version control risks. These are primarily executed via Python scripts located in .github/scripts/. Sources: Sieve.md:37-37
Secret Pattern Policy
A critical perimeter guard, check_secret_patterns.py, runs on every Pull Request (PR) and push to main. It utilizes regex patterns to detect accidental commits of sensitive data, such as GitHub tokens (ghp_), OpenAI keys (sk-), and private key PEM blocks. To prevent subversion, the validator runs from a pinned copy of the main branch. Sources: Sieve.md:39-44
Path Portability (NETWEB Standard)
To ensure the vault works across Windows (NTFS), macOS (APFS), and Linux, the project enforces a "Portable Path Standard." This blocks filenames that are illegal on Windows (e.g., CON.md, AUX.md), prevents case-insensitive collisions (e.g., Act.md vs ACT.md), and limits path lengths to 218 characters to stay within NTFS MAX_PATH limits. Sources: RECOVERED-BOOK-GEMINIAEUS-PR214-2026-08-14/original-tree/!/MIND/BOOK-OF-GEMINIAEUS/Sheet2.md:214-245
Content Validation
The validate_content.py script ensures that periodic notes and task lists do not contain unrendered template placeholders (e.g., <% ... %> or {{ ... }}). This prevents failed template expansions from propagating through the "Daily Rollover" cycle. Sources: Sieve.md:46-52
Multi-Agent PR Pipeline
The repository utilizes an automated pipeline to manage contributions from various AI agents. Each agent operates in its own branch prefix (e.g., claude/, codex/), and their PRs are routed through a risk-classification system. Sources: Sieve.md:12-26, audit-results.txt:1-12
Risk Routing Logic
The classify_paths.py script implements a two-axis risk-tiering scheme to label PRs:
| Axis | Classification | Criteria |
|---|---|---|
| Filetype | Clear / Low / Med | Prose (Clear) vs. Code (Med) |
| Depth | High / Nope | Files inside the !/ Swarmic Nest or core governance files |
Sources: Sieve.md:65-71
CI/CD Workflow Interaction
The following diagram illustrates the flow of a PR through the guardrail system:
The diagram shows the progression of an agent-initiated PR from creation to final human approval. Sources: Sieve.md:12-26, PROPOSAL-CLAUDE-CODEX-SECURITY-COLLAB-2026-05-25.md:83-91
Branch Protection and Governance
Following a "softlock" incident where agents added conflicting required checks, branch protection rules were restructured to be reliable and minimal. Sources: PROPOSAL-CLAUDE-CODEX-SECURITY-COLLAB-2026-05-25.md:22-26
Proposed Required Checks
For stability, the project identifies specific "Strong Candidate" checks that must pass before a merge:
- Secret Pattern Policy:
secret-pattern-policy - Large File Policy:
large-file-policy - Path Portability:
check-portable-paths
Sources: PROPOSAL-CLAUDE-CODEX-SECURITY-COLLAB-2026-05-25.md:55-63
Repository Infrastructure Summary
The following table summarizes the key scripts involved in version control governance:
| Script | Purpose | Status |
|---|---|---|
daily_rollover.py | Moves incomplete tasks to new daily notes. | Active |
update_manifest.py | Manages file-write locking via UUIDs. | Active |
check_secret_patterns.py | Scans for credentials and keys. | Critical |
check_portable_paths.py | Enforces cross-platform compatibility. | Critical |
classify_paths.py | Routes PRs by risk tier. | Active |
Sources: Sieve.md:12-26, LEVELSET-v2.md:38-48
Operational Protocols
The guardrails are supported by the LEVELSET and ORIENTATE protocols, which ensure agents have the correct context before attempting version control actions. Sources: LEVELSET-v2.md:10-15
LEVELSET Synthesis
LEVELSET is a permanent, auditable checkpoint protocol. It inventories the repository state, active feature branches, and infrastructure built, ensuring a "single-source-of-truth" across all Claude sessions. Sources: LEVELSET-v2.md:10-25
Swarm Handoff Logic
When agents transition work, they use a structured handoff to ensure subsequent agents do not violate version control policies. This includes noting active branches, pending merge decisions, and technical debt. Sources: RECOVERED-BOOK-GEMINIAEUS-PR214-2026-08-14/original-tree/!/MIND/BOOK-OF-GEMINIAEUS/Sheet2.md:118-125
This sequence highlights the "Human-in-the-Loop" requirement for all architectural and state-changing merges. Sources: RECOVERED-BOOK-GEMINIAEUS-PR214-2026-08-14/original-tree/!/MIND/BOOK-OF-GEMINIAEUS/Sheet2.md:22-26, PROPOSAL-CLAUDE-CODEX-SECURITY-COLLAB-2026-05-25.md:92-98
The Git & Version Control Guardrails serve as the "connective tissue" of the vault's execution layer, providing the necessary boundaries for safe, automated, and cross-platform knowledge management. Sources: RECOVERED-BOOK-GEMINIAEUS-PR214-2026-08-14/original-tree/!/MIND/BOOK-OF-GEMINIAEUS/Sheet2.md:29-30, Sieve.md:28-32