1d00544e86
Polls all heavy-duty/* repos every 15m for assignee/review-requested work, reviews with clear Verdicts until agreement, and includes tmux restore + hourly health self-heal. Fully documented.
78 lines
3 KiB
Markdown
78 lines
3 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
|
||
state.json + logs/
|
||
```
|
||
|
||
### 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)
|