# Gatekeeper Service — PR Review, Quality Gates & Merge Authority

> **Status:** Stub — deferred. Referenced from `2026-03-15-agent-platform-architecture.md` (Phase 7 Workspaces).
> Implement after Workspaces (P8-015) is complete and the workspace/git infrastructure is operational.

**Date:** 2026-03-15
**Packages:** `apps/gateway`, `packages/types`, `packages/agent`

---

## Problem Statement

Project agents create PRs but cannot review or merge their own work. A separate, isolated agent service with read-only code access and quality gate enforcement is needed to act as the authoritative merge authority.

The Gatekeeper existed in the old Mosaic codebase and must be ported/redesigned for mosaic-mono-v1.

---

## Key Design Constraints

- **Isolated trust boundary** — project agents cannot invoke Gatekeeper directly; it listens for PR events from the git provider
- **`isSystem: true`** — system agent, not editable by users
- **Read-only code access** — reads diffs and runs checks; cannot commit or push
- **Quality gates required before merge** — lint, typecheck, test results must pass
- **Cannot self-approve** — the agent that authored the PR cannot be the Gatekeeper for that PR

---

## Scope (To Be Designed)

- [ ] Gatekeeper agent bootstrap — system agent config, tool set, prompt engineering
- [ ] PR event listener — Gitea/GitHub webhook integration (PR opened/updated/ready)
- [ ] Quality gate runner — trigger CI checks, poll for results, enforce pass criteria
- [ ] Review generation — LLM-driven code review comment generation
- [ ] Merge execution — approve + merge when gates pass; reject with comments when they fail
- [ ] Configurable strictness — per-project required checks, review depth
- [ ] Trust boundary enforcement — gateway rejects Gatekeeper tool calls that exceed read-only scope
- [ ] Audit trail — OTEL spans for all Gatekeeper decisions (approve/reject/merge)

---

## Dependencies

- Workspaces (P8-015) — Gatekeeper needs project workspace layout to locate code
- Git provider API tools — PR creation/review/merge API (Gitea/GitHub/GitLab)
- CI/CD tool integration — Woodpecker pipeline status polling

---

## References

- Original design context: `docs/plans/2026-03-15-agent-platform-architecture.md` → "Gatekeeper Service" section
- Workspace RBAC and agent trust model: same document → "RBAC & Filesystem Security"