ci-verify-before-merge

---
name: ci-verify-before-merge
description: "Verify CI status BEFORE bypass-merging a PR. Use when about to call POST .../pulls/{N}/merge OR PATCH branch_protections, OR when user says 'merge le PR'. Prevents shipping broken code to trunk."
mode: [engineering, ops, coding]
effort: low
version: 1.0.0
tier: [admin, dev]
---

# ci-verify-before-merge

**CRITICAL DEFENSIVE SKILL** — verify CI green before any bypass-merge action.

## When to invoke

Whenever the agent is about to:
- Call `POST /repos/{owner}/{repo}/pulls/{N}/merge` (Forgejo merge API)
- PATCH `branch_protections` to lower `required_approvals` (bypass pattern)
- Run `gh pr merge` (GitHub CLI)
- Run `git push --no-verify`
- Manually merge with `git merge --no-ff` followed by push to trunk
- Receive user instruction "merge le PR" / "bypass merge" / "ship now"

## What it does

1. Extract PR/commit identifier from intent
2. Query Forgejo API: `GET /repos/{owner}/{repo}/commits/{sha}/status`
3. If `state == "success"` → merge allowed (audit logged)
4. Otherwise → BLOCK with explanation + 3 mitigation paths

## Why (the 2026-05-02 incident)

`atlas-plugin#68` and `synapse#453` were bypass-merged via `PATCH branch_protections required_approvals 1→0→1` without waiting for CI. Both shipped with red CI:

- **atlas-plugin v7.4.0**: auto-release tagged on top of `l1-structural` + `skill-lint-scan` failures → marketplace got broken plugin
- **synapse#453**: `deploy-dev` failed after 22s → broken state on dev branch

Root cause: agent prioritized claimed velocity over verification. Eight `LAW-WORKFLOW-001` advisories were dismissed during the session.

## How to invoke

The hook `pre-merge-ci-check` runs automatically on every Bash tool call. The skill is the LLM-side companion that documents the doctrine + provides a Python helper for explicit verification:

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/ci-verify-before-merge/cli/check_ci_status.py \
    --repo axoiq/synapse --pr 453
# Output: green | red | pending | unknown + exit code 0/1/2/3
```

## Override mechanism (audit-trail-required)

For legitimate cases where CI is independently verified (e.g., manual smoke test, CI broken due to infra issue not code issue):

```bash
CI_VERIFY_BYPASS=1 <merge-command>     # one-shot bypass, audited
export CI_VERIFY_DISABLE=1             # session-wide (NOT recommended)
```

Both write to `~/.claude/ci-audit.jsonl` for post-incident review.

## Iron Law

`LAW-CI-VERIFY-001`: Never bypass branch protection or call merge API without verified CI green status. Override requires explicit user permission AND audit log entry.

## Related

- Plan parent: incident response 2026-05-02 atlas-plugin v7.4.1
- Companion rule: `.claude/rules/ci-verify-before-merge.md` (in synapse + project copies)
- Companion memory: `feedback_ci_verify_before_merge_mandatory.md`
- Sibling skill: `ci-feedback-loop` (post-push CI monitoring) — invoke this BEFORE merge
- Pattern reference: `audit-enforcement-protocol.md` 8-layer defense (this is L4 + L5 + L7)