79 lines
3 KiB
Markdown
79 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)
|