121 lines
3.8 KiB
Markdown
121 lines
3.8 KiB
Markdown
|
# heavy-duty-watcher
|
||
|
|
|
||
|
|
**Org-wide GitHub review agent** for the [heavy-duty](https://github.com/heavy-duty) organization.
|
||
|
|
|
||
|
|
Runs as bot **`grok-bot-andresmgsl`**. Every 15 minutes it discovers open Issues/PRs where this bot is **assignee** or **requested reviewer** across **all** `heavy-duty/*` repos, reads the full discussion, and posts structured reviews until it **agrees** (Approve) or still has blockers (Request changes).
|
||
|
|
|
||
|
|
> Not a drive-by bot. No unsolicited comments. No merge/close/reassign unless an operator asks.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Features
|
||
|
|
|
||
|
|
- **Org-wide scope** — one watcher for every repo under `heavy-duty`
|
||
|
|
- **Strict collaboration rules** — clear Verdict/Status, specific, non-redundant, blockers vs nits
|
||
|
|
- **Stateful de-dupe** — tracks per-item head SHA and last action (`owner/repo#pr:N`)
|
||
|
|
- **Dual durability** — Grok durable schedulers **and** local tmux loops
|
||
|
|
- **Reboot recovery** — `scripts/restore.sh` rebuilds tmux + resumes the agent
|
||
|
|
- **Hourly health watchdog** — verifies poll loop, gh auth, freshness; self-heals
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Quick start
|
||
|
|
|
||
|
|
```bash
|
||
|
|
git clone https://github.com/grok-bot-andresmgsl/heavy-duty-watcher.git
|
||
|
|
cd heavy-duty-watcher
|
||
|
|
gh auth status # bot account with org access
|
||
|
|
./scripts/install-live.sh
|
||
|
|
./scripts/restore.sh # after reboot: always this
|
||
|
|
```
|
||
|
|
|
||
|
|
Arm durable schedulers from a live Grok session using prompts in [`docs/SCHEDULER_PROMPTS.md`](docs/SCHEDULER_PROMPTS.md).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Repository layout
|
||
|
|
|
||
|
|
```text
|
||
|
|
heavy-duty-watcher/
|
||
|
|
├── README.md ← you are here
|
||
|
|
├── POLL_INSTRUCTIONS.md ← authoritative review rules (read every cycle)
|
||
|
|
├── config/
|
||
|
|
│ ├── state.template.json
|
||
|
|
│ └── watcher.env.example
|
||
|
|
├── scripts/
|
||
|
|
│ ├── discover.sh ← org-wide actionable list
|
||
|
|
│ ├── poll-once.sh ← one headless poll (Grok)
|
||
|
|
│ ├── poll-loop.sh ← every 15m
|
||
|
|
│ ├── health-check.sh
|
||
|
|
│ ├── health-loop.sh ← every 1h + self-heal
|
||
|
|
│ ├── restore.sh ← reboot recovery (tmux)
|
||
|
|
│ └── install-live.sh ← deploy under ~/heavy-duty-watcher
|
||
|
|
├── docs/
|
||
|
|
│ ├── ARCHITECTURE.md
|
||
|
|
│ ├── OPERATIONS.md
|
||
|
|
│ ├── SCHEDULER_PROMPTS.md
|
||
|
|
│ └── REVIEW_PLAYBOOK.md
|
||
|
|
└── logs/ ← runtime (gitignored)
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## How a poll works
|
||
|
|
|
||
|
|
```text
|
||
|
|
discover (org search)
|
||
|
|
→ for each match
|
||
|
|
read ALL comments + reviews + diff + checks
|
||
|
|
compare head SHA / prior bot comments (state.json)
|
||
|
|
if material change:
|
||
|
|
post Verdict: Request changes | Comment | Approve
|
||
|
|
else:
|
||
|
|
silent
|
||
|
|
→ update state.json + logs/poll.log
|
||
|
|
```
|
||
|
|
|
||
|
|
Full rules: [`POLL_INSTRUCTIONS.md`](POLL_INSTRUCTIONS.md).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Documentation map
|
||
|
|
|
||
|
|
| Doc | Audience |
|
||
|
|
|-----|----------|
|
||
|
|
| [POLL_INSTRUCTIONS.md](POLL_INSTRUCTIONS.md) | Agent — must follow every cycle |
|
||
|
|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design / durability model |
|
||
|
|
| [docs/OPERATIONS.md](docs/OPERATIONS.md) | Humans operating the watcher |
|
||
|
|
| [docs/SCHEDULER_PROMPTS.md](docs/SCHEDULER_PROMPTS.md) | Copy-paste durable task prompts |
|
||
|
|
| [docs/REVIEW_PLAYBOOK.md](docs/REVIEW_PLAYBOOK.md) | Review style examples |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## After reboot
|
||
|
|
|
||
|
|
```bash
|
||
|
|
~/heavy-duty-watcher/scripts/restore.sh
|
||
|
|
```
|
||
|
|
|
||
|
|
Creates/attaches tmux session `heavy-duty-watcher` with:
|
||
|
|
|
||
|
|
| Window | Role |
|
||
|
|
|--------|------|
|
||
|
|
| `grok` | Interactive agent (resume session when possible) |
|
||
|
|
| `poll-loop` | Headless 15m polls |
|
||
|
|
| `health-loop` | Hourly health + self-heal |
|
||
|
|
| `tools` | Manual shell |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Safety
|
||
|
|
|
||
|
|
- Only comments when **assigned** or **review-requested**
|
||
|
|
- Never merges, closes, force-pushes, or reassigns by default
|
||
|
|
- Secrets are **not** stored in this repo — use `gh auth` on the host
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
MIT — see [LICENSE](LICENSE).
|