grok-reviewer-andresmgsl
8d6f902209
- Add scripts/lib/common.sh (ORG/BOT/FORGE_BACKEND, logging, process_running) - discover.sh: dedupe review-requested+assignee PRs; JSON+summary formats - discover.sh: FORGE_BACKEND=forgejo via Forgejo API + stoke token - Fix poll-loop process detection (basename, not install path) - health-check: jq-safe JSON; backend-aware auth (gh or stoke) - install-live: require rsync/jq/tmux; soft-warn missing gh/stoke - self-test.sh offline smoke; restore/poll-once use shared config - Docs: Forgejo table, watcher.env, OPERATIONS troubleshooting
86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
# Architecture
|
||
|
||
## What this is
|
||
|
||
A **durable, org-wide GitHub review agent** for [heavy-duty](https://github.com/heavy-duty).
|
||
|
||
It polls GitHub for Issues/PRs where bot **`grok-bot-andresmgsl`** is:
|
||
|
||
- requested as **reviewer**, or
|
||
- **assignee**
|
||
|
||
…across **every repository** in the organization. It reads full thread history, reviews diffs, and posts structured feedback until it can **Approve**.
|
||
|
||
## Components
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Grok durable scheduler (15m) ──► poll cycle (interactive) │
|
||
│ Grok durable scheduler (1h) ──► health watchdog │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ tmux session: heavy-duty-watcher │
|
||
│ ├─ poll-loop (scripts/poll-loop.sh → poll-once.sh) │
|
||
│ ├─ health-loop (scripts/health-loop.sh → health-check.sh) │
|
||
│ ├─ tools (manual gh / logs) │
|
||
│ └─ grok (optional interactive resume) │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
GitHub org:heavy-duty
|
||
or Forgejo org (FORGE_BACKEND=forgejo)
|
||
state.json + logs/
|
||
```
|
||
|
||
### Forge backends
|
||
|
||
| `FORGE_BACKEND` | Auth | Discovery | Review CLI |
|
||
|-----------------|------|-----------|------------|
|
||
| `github` (default) | `gh` | `gh search` | `gh pr review` |
|
||
| `forgejo` | `stoke auth` | Forgejo API via stoke token | `stoke pr review` |
|
||
|
||
### Why two poll paths?
|
||
|
||
| Path | Survives |
|
||
|------|----------|
|
||
| Grok durable scheduler | New Grok sessions (durable flag); may need re-arm after ~7 days |
|
||
| Local `poll-loop.sh` in tmux | Box uptime; independent of Grok UI |
|
||
|
||
After reboot: run `scripts/restore.sh`.
|
||
|
||
## State model
|
||
|
||
`state.json` is the single source of truth for de-duplication:
|
||
|
||
```json
|
||
{
|
||
"scope": "org:heavy-duty",
|
||
"items": {
|
||
"heavy-duty/box#pr:79": {
|
||
"last_head_sha": "abc…",
|
||
"last_action": "reviewed",
|
||
"review_event": "REQUEST_CHANGES"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
Keys are always `owner/repo#pr:N` or `owner/repo#issue:N` so multiple repos never collide.
|
||
|
||
## Review policy (summary)
|
||
|
||
Full rules live in [`../POLL_INSTRUCTIONS.md`](../POLL_INSTRUCTIONS.md).
|
||
|
||
- Act only when assignee or review-requested
|
||
- Read **all** comments before speaking
|
||
- Clear **Verdict** / **Status** line first
|
||
- **Request changes** until agreement; **Approve** when fully satisfied
|
||
- Silent when nothing material changed
|
||
|
||
## Security / safety
|
||
|
||
- No merge / close / force-push / reassignment unless operator asks
|
||
- Uses the bot’s GitHub token via `gh` / MCP
|
||
- Does not store secrets in the repo (state is operational metadata only)
|