docs: agent platform architecture plan — augmentation + task breakdown (#173)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

docs/plans/gatekeeper-service.md

@@ -0,0 +1,53 @@
+# 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"