CI & Pre-Push Gates
Publishing a change passes through gates that protect the shared branch: an ordered pre-push checklist a human runs before sending work, and continuous integration that runs automatically once the work arrives. This chapter defines those gates, the order in which the local checks run, and the requirement that documentation and its index stay consistent.
Continuous Integration on Push
Section titled “Continuous Integration on Push”Once a change reaches the remote, automated verification runs without further prompting. CI is the backstop that confirms the published state actually builds and passes.
| Rule | Level |
|---|---|
| Tests MUST run automatically on every push | MUST |
| Test coverage MUST be measured and uploaded as part of the run | MUST |
| A failing CI run SHOULD be treated as a blocking signal for the affected branch | SHOULD |
This chapter describes the gates and their guarantees, not the pipeline configuration: how the automation is wired is an implementation detail and is intentionally out of scope.
The Pre-Push Checklist
Section titled “The Pre-Push Checklist”Before a human chooses to push, an ordered checklist runs locally. The order is deliberate — cheaper, broader checks come first so that a problem is caught before more expensive verification runs.
| Step | Gate | Purpose |
|---|---|---|
| 1 | Docs | Documentation and its index are current and consistent |
| 2 | Security | No secrets, credentials, or sensitive data are about to be published |
| 3 | Tests | The test suite passes locally |
| Rule | Level |
|---|---|
| The pre-push checklist MUST run in the order docs, then security, then tests | MUST |
| A failed gate MUST stop the checklist before the push | MUST |
| The push MUST remain an explicit human decision after the checklist passes | MUST |
The checklist does not replace the human decision to publish; it qualifies the state as push-ready and leaves the choice to a person.
Documentation & Index Synchrony
Section titled “Documentation & Index Synchrony”Documentation and its index MUST stay bidirectionally in sync. Every page is reachable from the index, and every index entry points to a page that exists. Drift in either direction is a defect.
| Defect | Description | Level |
|---|---|---|
| Orphan page | A page exists but is not reachable from the index | MUST NOT |
| Dead reference | An index entry or link points to a page that does not exist | MUST NOT |
| Stale duplicate | An outdated copy of a page lingers alongside its replacement | MUST NOT |
| Rule | Level |
|---|---|
| The documentation set and its index MUST remain bidirectionally consistent | MUST |
| The docs gate SHOULD detect orphans, dead references, and stale duplicates before a push | SHOULD |