Merge pull request 'architect: gatekeeper agent — external signal verification' (#31) from architect/gatekeeper-agent into main

sprints/gatekeeper-agent.md

@@ -0,0 +1,58 @@
+# Sprint: gatekeeper agent
+
+## Vision issues
+- #485 — gatekeeper agent: verify external signals before they enter the factory
+
+## What this enables
+
+The factory gains a trust boundary between external mirrors (Codeberg, GitHub) and the internal Forgejo issue tracker. Today, external bug reports and feature requests must be manually copied into internal Forgejo — there is no automated inbound path from mirrors. The gatekeeper closes this gap by:
+
+1. Polling external mirrors for new issues
+2. Verifying claims against internal ground truth (git history, agent logs, system state)
+3. Creating sanitized internal issues only when claims are confirmed
+4. Defending against prompt injection via issue body rewriting (evidence-based, never verbatim copy)
+
+This directly supports the Growth goals: "attract developers", "contributors", "lower the barrier to entry" — external contributors can file issues on public mirrors and the factory processes them safely.
+
+## What exists today
+
+- **Mirror push** (lib/mirrors.sh): outbound only — pushes primary branch + tags to configured mirrors after each merge. No inbound path.
+- **Bug-report pipeline** (docker/edge/dispatcher.sh): reproduce -> triage -> verify agents handle internal bug reports. The gatekeeper slots upstream of this pipeline.
+- **Secret scanning** (lib/secret-scan.sh): detects and redacts secrets in issue bodies before posting. Reusable for gatekeeper sanitization.
+- **Issue lifecycle** (lib/issue-lifecycle.sh): claim model, dependency checking, label filtering. Gatekeeper follows the same patterns.
+- **Per-agent identities** (lib/hire-agent.sh): Forgejo bot accounts with dedicated tokens. Gatekeeper gets its own identity.
+- **Agent run pattern**: all slow agents follow the same *-run.sh + formula pattern (gardener-run.sh, planner-run.sh, etc.). Gatekeeper follows this exactly.
+- **Vault dispatch** for external actions: PR-based approval workflow. External API tokens (GITHUB_TOKEN, CODEBERG_TOKEN) are vault-only per AD-006.
+
+## Complexity
+
+- **New files (~5):** gatekeeper/gatekeeper-run.sh, gatekeeper/AGENTS.md, formulas/run-gatekeeper.toml, state marker
+- **Modified files (~3):** docker/agents/entrypoint.sh (polling registration), AGENTS.md (agent table), docker-compose env vars
+- **Gluecode vs greenfield:** ~70% gluecode (agent scaffolding, polling, issue creation reuse existing patterns), ~30% greenfield (external API polling, claim verification logic, prompt injection defense)
+- **Estimated sub-issues:** 5-7
+
+## Risks
+
+1. **Prompt injection via crafted issue bodies** — primary risk. External issue bodies are untrusted input that could manipulate agents if copied verbatim. Mitigation: gatekeeper rewrites issues based on verified evidence, never copies external content. The internal issue body is authored by the gatekeeper, not the reporter.
+
+2. **AD-006 tension** — the gatekeeper needs READ access to external APIs (GitHub Issues API, Codeberg Issues API), which requires GITHUB_TOKEN and CODEBERG_TOKEN. These are vault-only tokens per AD-006. The token access pattern is a design fork (see below).
+
+3. **False positives/negatives** — gatekeeper may reject legitimate reports (false positive) or admit crafted ones (false negative). Mitigated by the existing reproduce/triage pipeline downstream — the gatekeeper is a first filter, not the only filter.
+
+4. **Rate limiting** — GitHub API has 5000 req/hour (authenticated). Codeberg (Gitea) is typically more permissive. Hourly polling with pagination is well within limits.
+
+5. **Scope creep** — the gatekeeper could expand into a full external community management tool. Sprint should be scoped to: poll -> verify -> create internal issue. No auto-responses to external reporters in v1.
+
+## Cost — new infra to maintain
+
+- **1 new agent** in the polling loop (gatekeeper-run.sh, ~6h interval like gardener/architect)
+- **1 new Forgejo bot account** (gatekeeper-bot)
+- **1 new formula** (run-gatekeeper.toml)
+- **External API dependency** — relies on GitHub/Codeberg APIs being available. Failure is graceful (skip poll, retry next interval).
+- **No new services, no new containers** — runs in the existing agents container.
+
+## Recommendation
+
+**Worth it.** This is the missing inbound path for the mirror infrastructure that already exists. The outbound side (mirror push) has been working since early in the project. The gatekeeper completes the loop: code goes out via mirrors, feedback comes back via gatekeeper. The implementation is mostly gluecode following established patterns, with the greenfield work concentrated in the verification logic and prompt injection defense — both well-scoped problems.
+
+The main decision point is how to handle AD-006 (external token access). This is a design fork that needs human input before sub-issues can be filed.