0002 — CI Safety Mechanisms and Direct Push Guard¶
Date: 2026-03-06 Status: Accepted
Context¶
The repository started with direct pushes to main. As it grows into a
curated knowledgebase of AI tooling patterns, unreviewed changes create risk:
inconsistent quality, undocumented structural decisions, and no checkpoint
before content becomes canonical.
The goal is a lightweight flow with enough friction to encourage discipline: feature branch → PR → automated checks → merge.
GitHub branch protection (which would enforce this as a hard gate) requires GitHub Pro or Team for private repositories. This repo is private and will remain so. Paying for branch protection on a personal knowledgebase is not worth the cost.
Decision¶
Adopt a two-layer model: noise-based deterrence (not hard blocking) plus local quality gates.
Layer 1: GitHub Actions (CI — runs on every PR and push)¶
adr-check: When a PR touches any tool directory
(claude/, cursor/, windsurf/, gemini/), it must include a new
decisions/NNNN-*.md file. Soft gate — bypassable with skip-adr label for
minor, non-structural changes.
markdown-lint: All *.md files must pass markdownlint-cli2 with the
shared .markdownlint.yml config. Runs on PRs and on all branch pushes.
direct-push-guard: Fires on every push to main. Queries the GitHub API
to check whether the pushed commit is associated with a merged PR. If not —
opens a GitHub Issue assigned to the pusher with a loud title and instructions.
This is not a block; it is a visible, persistent, assigned paper trail that
demands acknowledgement (close with a note, or revert and redo via PR).
Layer 2: pre-commit (local quality gate)¶
.pre-commit-config.yaml runs locally before every commit:
trailing-whitespaceend-of-file-fixercheck-merge-conflictmarkdownlint(same config as CI — catches failures before push)
Bot Identity¶
PRs opened by Claude (via MCP or GitHub Actions workflows) use the
phazeight-ai-agent GitHub App. PRs show as opened by
phazeight-ai-agent[bot]; Luke approves as the human in the loop.
Setup guide: claude/patterns/github-app-bot-setup.md
Consequences¶
Positive:
- ADRs are required for structural changes, creating a self-documenting change history
- Pre-commit catches formatting issues locally before they hit CI
- Direct pushes to
mainare immediately surfaced as assigned GitHub Issues — hard to ignore, requires deliberate acknowledgement - Zero ongoing cost
Negative / trade-offs:
- Direct pushes are not technically blocked — the guard is friction, not a wall
skip-adrand closing the issue both require discipline not to overuse- The direct-push-guard produces a false alarm on PR merges if the GitHub API returns no associated PR (rare edge case — close the issue and move on)
Alternatives Considered¶
- GitHub Pro branch protection ($4/month): Hard block on direct pushes, required status checks. Rejected — not worth the cost for a personal repo.
- Make repo public (free branch protection): Rejected — repo will contain private patterns and sensitive configuration over time.
- Honor system only, no guard workflow: Rejected — no feedback loop when the flow is bypassed; the issue + email notification provides the necessary friction.
- Hard ADR enforcement (no bypass): Rejected — too rigid for trivial content changes.