Governance & PR Guardrails
Relevant source files
The following files were used as context for generating this wiki page:
Governance and Pull Request (PR) guardrails define the foundational engineering standards and automated workflows required for all repository contributors. These rules ensure architectural consistency, resource safety, and strict scope management for both human and AI-assisted changes. The system enforces a "Single Invariant Principle" where each PR represents one logical slice of the system to prevent architectural drift.
Sources: GEMINI.md:3-6, GEMINI.md:46-48, docs/PR_SCOPE_GUARDRAILS.md:14-16
PR Lifecycle and Automation Policy
The repository maintains a strict boundary for automated changes and AI coding agents. Automation tools must not redefine project scope or broaden technical boundaries beyond the immediate task.
Automation Scope Boundaries
The project categorizes architecture into production and non-production boundaries. All automated changes must respect these labels:
- Production Architecture: Includes the FastAPI backend and Next.js frontend stack.
- Non-Production: Includes Gradio-based tools, which are restricted to internal testing and demos.
Sources: .github/AUTOMATION_SCOPE_POLICY.md:14-23, AUDIT_REPORT.md:147-152
PR Triage and Review Flow
All PRs must progress through specific lifecycle stages. If a PR stalls for more than 48 hours, the system flags it for an immediate architectural sync. Contributors use specialized tags like [manual-stop] or [star] to pause automated pipelines for manual sign-off in preview environments.
The diagram shows the logic flow for PR processing, including mandatory triage checks and stall triggers.
Sources: GEMINI.md:9-15, GEMINI.md:17-21
Mandatory PR Description Standards
Every PR description must include specific triage data to assess impacts and failure modes. Vague descriptions result in immediate closure of the PR.
Canonical Description Fields
Automated and agent-authored PRs must complete six mandatory fields:
| Field | Description |
|---|---|
| Primary Objective | The high-level purpose and business value of the change. |
| In Scope | Exact list of features or fixes implemented. |
| Out of Scope | Explicit list of related items not addressed to prevent scope creep. |
| Files Expected to Change | A list of modified files with a rationale for their grouping. |
| Validation Commands | The exact shell commands run locally to verify the change. |
| Merge Criteria | Specific conditions (tests, coverage, docs) that must be met for merging. |
Sources: docs/PR_SCOPE_GUARDRAILS.md:55-75, GEMINI.md:9-15
Dependency Governance
Dependency management follows a strict hierarchy where requirements.txt serves as the authoritative source of truth for runtime and deployment environments.
Order of Operations for Dependency Changes
Contributors must follow a specific sequence when modifying dependencies:
- Update
requirements.txt: Define the runtime source of truth. - Align
pyproject.toml: Match the runtime policy for package metadata. - Adjust
requirements-dev.txt: Update only if development or testing tools are affected. - Update Infrastructure: Align validators, workflows, and documentation.
- Run Validation: Execute mandatory local checks.
Sources: docs/DEPENDENCY_POLICY.md:32-37, CONTRIBUTING.md:209-215
Mandatory Validation Commands
Before submission, you must run the following validation suite to ensure environment integrity:
# 1. Runtime validation
pip install -r requirements.txt
pip check
# 2. Editable install validation
pip install -e .
pip check
# 3. Full development tooling validation
pip install -r requirements.txt -r requirements-dev.txt
pytest --version
flake8 --version
pylint --version
Sources: docs/DEPENDENCY_POLICY.md:65-80
Architectural Constraints
The repository enforces hard invariants to ensure resource safety and system stability.
Concurrency and Resource Safety
- Lock TTLs: Lock context managers must have a maximum bound of 300 seconds.
- Deterministic Back-off: Lock acquisition must not exceed 30 seconds before throwing a
LockAcquisitionTimeout. - Context Management: All connection pools, file handles, and sessions must use context managers to ensure absolute disposal.
- Idempotency: All operations must be safe against partial failures (e.g., network drops or process termination).
Sources: GEMINI.md:24-34
Scope Compliance Classes
PRs are categorized into specific classes to manage risk and review effort:
| Class | Type | Description |
|---|---|---|
| 1 | Dependency Alignment | Updates to pins or security overrides without logic changes. |
| 2 | Validator/Workflow | Follow-up work for CI/CD or documentation updates. |
| 3 | Framework/Security | Major version upgrades or critical security patches. |
| 4 | Cleanup-only | Refactoring or dead code removal with no behavioral change. |
Sources: docs/PR_SCOPE_GUARDRAILS.md:20-30
Summary
The Governance & PR Guardrails system acts as a gatekeeper for the repository, ensuring that every change is bounded, documented, and architecturally sound. By enforcing the Single Invariant Principle and maintaining strict dependency hierarchies, the project preserves long-term maintainability and enterprise readiness. High-risk changes are managed through mandatory validation commands and specific scope compliance checklists.