Grug

Grug see bug. Grug crush bug. Grug guard code.
One grumpy caveman. Whole software lifecycle.

---

What Grug do

Grug is a modular GitHub bot with focused personas across the SDLC. Four are enabled by default:

• Chief (Grug - Chief) - plan readiness before the hunt leaves the cave
• Elder (Grug - Elder) - durable Cave review with Markings, Lore, Omen
• Guard (Grug - Guard) - cave-mouth security (SAST, secrets, SCA, IaC + Seer)
• Teller (Grug - Teller) - tale of the hunt (walkthrough + mermaid map)

Smasher, Warder, and Pulse are wired as opt-in tracers. Omen runtime signal already augments Elder where a repository-to-service mapping exists. Check titles use caveman names (Grug - <Persona>); legacy aliases dual-post during cutover so old required-status rulesets keep working.

Grug live in GitHub. Grug post Check Runs. Grug never spam comments. You ship. Grug guard.

Install

Hosted SaaS — recommended

1. Sign in at grug.lol with GitHub
2. Install the Grug Boss GitHub App on the repos you want gated
3. Toggle personas per-repo in the dashboard

That's it. Webhook is wired, check-runs post on every PR.

Note: the hosted instance is allowlist-gated — request access from @evan if you're new. Self-host (below) is the open path.

Self-host (run Grug in your own cave)

Grug is AGPL-3.0. Deploy your own instance against your own AWS account + Cloudflare account. Step-by-step in docs/SELF_HOST.md.

# roughly
aws ssm put-parameter ...   # pre-load App secrets
pulumi up                   # provision AWS infra (SSM refs, SQS, KMS, DD monitors)
# provision Postgres (grug_kv on CNPG) + stand up a Cloudflare tunnel
# push to main → deploy.k8s.yml builds the images + applies k8s/ to your cluster
# point GitHub App webhook → webhook.<your-domain>/webhook/github
# done. Grug guard now.

What Chief checks (Hunt Plan)

Before the tribe leave the cave, Chief reads the Hunt Plan on the PR body — 4 blocking plan checks, 1 advisory:

	Plan check	Pass when	Blocks?
yes	why	Has ## Why (or ## Summary) section, enough words to name the hunt	yes
yes	acceptance	Has ## Acceptance criteria (or ## Test plan) with enough bullets	yes
yes	estimate	Body or label includes Size: XS/S/M/L (XL must be split)	yes
yes	scope-fence	Has ## Out of scope section	yes
soft	issue-link	Body links an issue via closes #N	advisory

What Elder and Guard check

Elder: deep code review (Apex)

Every PR snapshot, after its base, head, and real author intent stay stable for the adaptive quiet window:

• Swift Hunt settle - tiny PRs skip the quiet wait; medium PRs settle a few seconds; large multi-file storms keep the full window. Elder posts an in_progress Grug - Elder check the moment the durable job is queued, so required-status rulesets show pending instead of "check missing".
• Tiered Cave review (ADR-0019 / #645) - default is a single coder arm for ordinary PRs; the reasoner arm escalates only on large diffs, high-risk paths, explicit deep-review, or a calibration sample. Dual-arm GRUG_REVIEW_DEPTH=deep remains the max-recall rollback. Covers 25+ named correctness, error-handling, concurrency, and security-shape rules. Whole-file + 1-hop cross-file context + PR intent ride every pass. SaaS overload fallback stays last-resort (ADR-0005).
• Markings Board - structured inline findings: severity, effort, What Elder sees, Fix (one-click when safe), Lore citations from prior tribe history, and a copy-paste agent repair prompt. Check-run summary is a full findings table.
• Lore + Omen - accepted/rejected ledger history becomes measured confidence and few-shot practices; Datadog runtime signal (Omen) fuses when a service map exists - a moat that comes from owning the stack end-to-end.
• Stable snapshot identity - bot HTML footers no longer thrash mid-flight reviews; only base/head or real human intent changes re-queue Elder.
• Feedback learning - judge labels and write-authorized maintainer reactions retain per-model provenance. Confirmed findings refresh positive practices and few-shot examples; false positives become bounded AVOID guidance for later reviews.

Guard: deterministic security review

• SAST — Semgrep OSS over vendored offline rules + a zero-dep builtin detector (sql/command/template injection, path traversal, SSRF, unsafe deserialization, weak crypto, cleartext secret logging).
• SCA — dependency-CVE scan of manifest/lockfile changes via the OSV API.
• Secret scanning — provider-token patterns + entropy-gated generic rule on added lines of ANY file type; values are masked, never echoed.
• IaC scanning — Terraform / Kubernetes YAML / Dockerfile misconfigs (open 0.0.0.0/0, privileged pods, public ACLs, root containers).
• Exploitability judge — an LLM precision layer that grades every security candidate real-vs-noise before it reaches your PR; recall + precision are tracked against a committed benchmark corpus.

Advisory-first: Elder and Guard findings post as neutral until their separate per-repo blocking flags are enabled.

Roadmap (epic #464)

• expand Smasher beyond its mutation-testing tracer
• add deploy gating to Warder's changelog and semver analysis
• deepen Pulse's scheduled project-health sweep
• add title/body scope review to Chief

Architecture

┌──────────────────────────────────────────────────────┐
│                    grug.lol                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐      │
│  │  web/    │  │ webhook/ │  │     api/         │      │
│  │ React+   │  │ FastAPI  │  │  FastAPI         │      │
│  │ Vite SPA │  │ pod      │  │  (OAuth, /me,    │      │
│  │ CF Pages │  │ (HMAC →  │  │  /installations) │      │
│  │          │  │ persona  │  │   pod            │      │
│  │          │  │ dispatch)│  │                  │      │
│  └──────────┘  └──────────┘  └──────────────────┘      │
│       webhook + api on Kubernetes (OKE),               │
│       behind a Cloudflare tunnel; + grug-consumer       │
│       (SQS) and grug-poller job    │
│                                                        │
│  ┌──────────────────────────────────────────────┐     │
│  │ infra/pulumi/  +  k8s/                        │     │
│  │ Postgres (CNPG) + SQS + KMS + SSM + CF + DD   │     │
│  └──────────────────────────────────────────────┘     │
└──────────────────────────────────────────────────────┘

PRD #21 + slice issues #22-#34 track v1.

Contributing

Issues + PRs welcome. Use the Hunt Plan template — Grug will gate your own PR. Fair is fair.

PR body must have ## Why, ## Acceptance criteria, ## Out of scope, Size:, and closes #N.

Related docs

Doc	What inside
docs/RUNBOOK.md	Operations (first deploy, secret rotation, tear-down + rebuild)
docs/SELF_HOST.md	Step-by-step self-host setup
docs/HITL_PREREQUISITES.md	One-time GitHub App registration walkthrough
docs/NETWORK-TOPOLOGY.md	k8s/tunnel/CNPG/SQS topology, request flows, trust boundaries
CONTEXT.md	Domain glossary (every term you'll see in the code)
docs/adr/	Architecture decision records

License

AGPL-3.0 — see docs/SELF_HOST.md for network-service compliance notes if you self-host.

_{Grug not lawyer. Grug just guard.}