claude-lead-andresmgsl/heavy-duty-watcher
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Org-wide review agent for heavy-duty — GitHub + Forgejo backends, durable polls, reboot-safe tmux restore
3 commits 1 branch 0 tags 63 KiB
Shell 100%
Find a file
grok-reviewer-andresmgsl 8d6f902209 Harden watcher: shared config, dual forge backends, safer discovery 
- 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
2026-07-22 23:23:33 +00:00
config Harden watcher: shared config, dual forge backends, safer discovery 2026-07-22 23:23:33 +00:00
docs Harden watcher: shared config, dual forge backends, safer discovery 2026-07-22 23:23:33 +00:00
scripts Harden watcher: shared config, dual forge backends, safer discovery 2026-07-22 23:23:33 +00:00
.gitignore Initial release: org-wide heavy-duty GitHub review watcher 2026-07-18 17:40:05 +00:00
LICENSE Initial release: org-wide heavy-duty GitHub review watcher 2026-07-18 17:40:05 +00:00
POLL_INSTRUCTIONS.md Harden watcher: shared config, dual forge backends, safer discovery 2026-07-22 23:23:33 +00:00
README.md Harden watcher: shared config, dual forge backends, safer discovery 2026-07-22 23:23:33 +00:00

README.md

heavy-duty-watcher

Org-wide review agent for the heavy-duty organization (GitHub by default; optional Forgejo backend via stoke).

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
  • Dual forge backends — FORGE_BACKEND=github (default) or forgejo
  • 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)
  • Deduped discovery — PRs that are both review-requested and assigned appear once
  • 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, auth, freshness; self-heals
  • Offline self-test — scripts/self-test.sh (bash -n + structure checks)

Quick start

git clone https://github.com/grok-bot-andresmgsl/heavy-duty-watcher.git
# or from Forgejo: https://forgejo.heavyduty.builders/grok-reviewer-andresmgsl/heavy-duty-watcher.git
cd heavy-duty-watcher
gh auth status          # bot account with org access (GitHub backend)
./scripts/self-test.sh  # optional offline smoke
./scripts/install-live.sh
./scripts/restore.sh    # after reboot: always this

Forgejo backend

cp config/watcher.env.example config/watcher.env
# set FORGE_BACKEND=forgejo  and  BOT_LOGIN=<forgejo-bot>
stoke auth login
FORGE_BACKEND=forgejo ./scripts/discover.sh

Arm durable schedulers from a live Grok session using prompts in docs/SCHEDULER_PROMPTS.md.

Repository layout

heavy-duty-watcher/
├── README.md
├── POLL_INSTRUCTIONS.md      ← authoritative review rules (read every cycle)
├── config/
│   ├── state.template.json
│   └── watcher.env.example
├── scripts/
│   ├── lib/common.sh         ← shared env + helpers
│   ├── discover.sh           ← org-wide actionable list (github|forgejo)
│   ├── 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
│   └── self-test.sh          ← offline smoke
├── docs/
│   ├── ARCHITECTURE.md
│   ├── OPERATIONS.md
│   ├── ORG_SCOPE.md
│   ├── SCHEDULER_PROMPTS.md
│   └── REVIEW_PLAYBOOK.md
└── logs/                     ← runtime (gitignored)

How a poll works

discover (org search / forgejo API)
   → 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.

Configuration

Copy config/watcher.env.example → config/watcher.env (gitignored):

Variable Default Meaning
ORG heavy-duty GitHub/Forgejo org
BOT_LOGIN grok-bot-andresmgsl Bot account login
FORGE_BACKEND github github or forgejo
FORGEJO_URL https://forgejo.heavyduty.builders Forge base URL
POLL_INTERVAL_SEC 900 tmux poll-loop sleep
HEALTH_INTERVAL_SEC 3600 health-loop sleep
STALE_POLL_MINUTES 45 health WARN threshold

Day-to-day commands

./scripts/discover.sh                 # JSON (default)
FORMAT=summary ./scripts/discover.sh  # human table
./scripts/health-check.sh
./scripts/self-test.sh
tail -f logs/poll.log logs/health.log
tmux attach -t heavy-duty-watcher

Documentation map

Doc Audience
POLL_INSTRUCTIONS.md Agent — must follow every cycle
docs/ARCHITECTURE.md Design / durability model
docs/OPERATIONS.md Humans operating the watcher
docs/SCHEDULER_PROMPTS.md Copy-paste durable task prompts
docs/REVIEW_PLAYBOOK.md Review style examples
docs/ORG_SCOPE.md Org repo notes

After reboot

~/heavy-duty-watcher/scripts/restore.sh
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 / stoke auth login on the host

License

MIT — see LICENSE.