PR Process & CI Guardrails
Relevant source files
The following files were used as context for generating this wiki page:
The Pull Request (PR) process and Continuous Integration (CI) guardrails in this repository establish a strict framework for code and documentation changes. The system is designed to ensure that all modifications—whether performed by human contributors or AI agents—adhere to established design invariants, governance policies, and technical standards.
These guardrails enforce a "one task, one PR" model, requiring explicit linkage between work and source issues, and utilize automated verification scripts to prevent structural drift. This is particularly critical for maintaining the "LGFC V6" production design standards, which serve as the primary product requirement.
Sources: README.md:32-34, Agent.md:40-45, governance/ai/AGENT-GOVERNANCE.md:14-16
PR Workflow & Issue Accounting
The repository utilizes an automated parser to ensure every PR is correctly accounted for and linked to a valid GitHub issue. This process prevents "mixed-intent" PRs and ensures that every change is traceable to a specific requirement.
Issue Linkage Requirements
A PR must be linked to exactly one primary source issue. The system recognizes links in the PR body or through branch naming conventions. Failure to provide a valid issue mapping results in a CI failure.
Sources: scripts/ci/pr-issue-accounting-parser.js:93-125, tests/fixtures/reviewer-gate/cases.json:34-45
| Linkage Type | Pattern / Format | Priority |
|---|---|---|
| Semantic Line | - **Issue:** #123 | Highest |
| Closing Keyword | Closes #123, Fixes #123 | Medium |
| Branch Name | issue-123-feature or 123-feature | Fallback |
Agent-Specific Execution Model
For AI agents (Codex), the PR process follows a strict "Executor" model where the PR represents a singular task. Agents are forbidden from creating new PRs if one already exists for a task and must modify only allowlisted files.
Sources: PROMPTS/Codex-Rules.md:4-15, governance/ai/AGENT-GOVERNANCE.md:27-30
The diagram shows the required sequence for AI agents to successfully complete a task within the existing PR structure.
Sources: PROMPTS/Codex-Rules.md:4-28
CI Guardrails & Security Gates
The CI pipeline enforces several "gates" that evaluate the safety and compliance of a PR based on labels, changed files, and the presence of reviews.
Reviewer Gate Logic
The reviewer gate determines if a PR is "merge-safe" based on the scope of changes. Specific directories are considered "protected scopes" that require active head-linked reviews.
Sources: tests/fixtures/reviewer-gate/cases.json:14-32
- Protected Scopes: Modifications to
.github/workflows/orscripts/ci/triggers higher scrutiny. - Infrastructure Changes: PRs labeled
infraoften require current-head reviews unless they are part of a remediation effort. - Advisory Findings: Minor violations (e.g., in
docs-onlyorwebsite-onlyPRs) may be downgraded to "advisory" status, allowing the PR to proceed if criteria are met.
Sources: tests/fixtures/reviewer-gate/cases.json:1-12, tests/fixtures/reviewer-gate/cases.json:76-98
Documentation Header Enforcement
All active documentation files must contain a YAML-like header for DIATAXIS routing and authority tracking. A CI script (docs_check_headers.sh) validates these headers against a required key list.
Sources: scripts/ci/docs_check_headers.sh:11-35
This sequence illustrates how the CI pipeline validates that every documentation file includes necessary governance metadata.
Sources: scripts/ci/docs_check_headers.sh:42-90
V6 Lock & Structural Integrity
A critical part of the CI process is the "V6 Lock" verification. This ensures that the production website does not drift from the approved legacy V6 design.
Verification Targets
The verify_v6_lock.sh script (located in both audits/ and tools/) performs deep checks on CSS tokens and component structures:
- Global CSS: Ensures
--lgfc-blue(#0033cc) and.section-gaputility classes are intact. - Structural Anchors: Verifies existence of
docs/lgfc-homepage-legacy-v6.html. - Component Integrity: Checks that the Header remains non-sticky and that the Join banner contains exact, approved marketing copy.
Sources: audits/verify_v6_lock.sh:14-50, tools/verify_v6_lock.sh:91-135
Implementation Table: V6 Invariants
| Component | Requirement | Check Method |
|---|---|---|
| Header | Non-sticky positioning | Grep for position: sticky (Fail if found) |
| Join Banner | Exact copy: "Become a member. Get access..." | Exact string matching in JoinCTA.tsx |
| Spacing | .section-gap applied to ≥5 homepage sections | Count of class occurrences in page.tsx |
| Social Wall | Presence of elfsight-app- UUID | Regex check in SocialWall.tsx |
| Sources: audits/verify_v6_lock.sh:52-85, tools/verify_v6_lock.sh:145-200 |
Conclusion
The PR process and CI guardrails serve as the enforcement mechanism for the repository's authority hierarchy. By combining automated issue accounting, strict AI operating rules, and structural verification scripts like the V6 Lock, the project maintains high standards of traceability and design consistency. Contributors must ensure all PRs are narrow in scope and verified against these automated gates before merging.
Sources: Agent.md:30-40, governance/ai/AGENT-GOVERNANCE.md:1-12