disinto/review/AGENTS.md

<!-- last-reviewed: ebadff09a1ce3c0140e4975985d383136a9a5504 -->
# Review Agent

**Role**: AI-powered PR review — post structured findings and formal
approve/request-changes verdicts to forge.

**Trigger**: `review-poll.sh` runs every 10 min via cron. It scans open PRs
whose CI has passed and that lack a review for the current HEAD SHA, then
spawns `review-pr.sh <pr-number>`.

**Key files**:
- `review/review-poll.sh` — Cron scheduler: finds unreviewed PRs with passing CI. Sources `lib/guard.sh` and calls `check_active reviewer` — skips if `$FACTORY_ROOT/state/.reviewer-active` is absent. **Circuit breaker**: counts existing `<!-- review-error: <sha> -->` comments; skips a PR if ≥3 consecutive errors for the same HEAD SHA (prevents flooding on repeated review failures).
- `review/review-pr.sh` — Creates/reuses a tmux session (`review-{project}-{pr}`), injects PR diff, waits for Claude to write structured JSON output, posts markdown review + formal forge review, auto-creates follow-up issues for pre-existing tech debt. **cd at startup**: changes to `$PROJECT_REPO_ROOT` early in the script — before any git commands — because the factory root is not a git repo after image rebuild (#408). Calls `resolve_forge_remote()` at startup to determine the correct git remote name (avoids hardcoded 'origin'). Before starting the session, runs `lib/build-graph.py --changed-files <PR files>` and appends the JSON structural analysis (affected objectives, orphaned prerequisites, thin evidence) to the review prompt. Graph failures are non-fatal — review proceeds without it.

**Environment variables consumed**:
- `FORGE_TOKEN` — Dev-agent token (must not be the same account as FORGE_REVIEW_TOKEN)
- `FORGE_REVIEW_TOKEN` — Review-agent token for approvals (use human/admin account; branch protection: in approvals whitelist)
- `FORGE_REPO`, `FORGE_API`, `PROJECT_NAME`, `PROJECT_REPO_ROOT`
- `PRIMARY_BRANCH`, `WOODPECKER_REPO_ID`
chore: gardener housekeeping 2026-04-08 2026-04-08 18:02:36 +00:00			`<!-- last-reviewed: ebadff09a1ce3c0140e4975985d383136a9a5504 -->`
chore: gardener housekeeping 2026-03-21 Progressive disclosure split of AGENTS.md (487→152 lines): - Extracted per-directory AGENTS.md files for all 8 agents + lib/ - Root AGENTS.md now serves as a table of contents with summary table - All watermarks updated to 16e430e Grooming results: - Promoted #469 (WATCH flow missing curl) and #436 (idle_pane_count bug) to backlog - 12 dust items classified, no groups ripe for bundling yet - No blocked issues, no AD violations 2026-03-21 12:44:23 +00:00			`# Review Agent`

			`Role: AI-powered PR review — post structured findings and formal`
fix: Replace Codeberg dependency with local Forgejo instance (#611) - Add setup_forge() to bin/disinto: provisions Forgejo via Docker, creates admin + bot users (dev-bot, review-bot), generates API tokens, creates repo, and pushes code — all automated - Rename env vars: CODEBERG_TOKEN→FORGE_TOKEN, REVIEW_BOT_TOKEN→ FORGE_REVIEW_TOKEN, CODEBERG_REPO→FORGE_REPO, CODEBERG_API→ FORGE_API, CODEBERG_WEB→FORGE_WEB, CODEBERG_BOT_USERNAMES→ FORGE_BOT_USERNAMES (with backwards-compat fallbacks) - Rename API helpers: codeberg_api()→forge_api(), codeberg_api_all() →forge_api_all() (with compat aliases) - Add forge_url field to project TOML; load-project.sh derives FORGE_API/FORGE_WEB from forge_url + repo - Update parse_repo_slug() to accept any host URL, not just codeberg - Forgejo data stored under ~/.disinto/forgejo/ (not in factory repo) - Update all 58 files: agent scripts, formulas, docs, site HTML Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> 2026-03-23 16:57:12 +00:00			`approve/request-changes verdicts to forge.`
chore: gardener housekeeping 2026-03-21 Progressive disclosure split of AGENTS.md (487→152 lines): - Extracted per-directory AGENTS.md files for all 8 agents + lib/ - Root AGENTS.md now serves as a table of contents with summary table - All watermarks updated to 16e430e Grooming results: - Promoted #469 (WATCH flow missing curl) and #436 (idle_pane_count bug) to backlog - 12 dust items classified, no groups ripe for bundling yet - No blocked issues, no AD violations 2026-03-21 12:44:23 +00:00
			Trigger: `review-poll.sh` runs every 10 min via cron. It scans open PRs
			`whose CI has passed and that lack a review for the current HEAD SHA, then`
			spawns `review-pr.sh <pr-number>`.

			`Key files:`
chore: gardener housekeeping 2026-04-05 2026-04-05 13:40:45 +00:00			- `review/review-poll.sh` — Cron scheduler: finds unreviewed PRs with passing CI. Sources `lib/guard.sh` and calls `check_active reviewer` — skips if `$FACTORY_ROOT/state/.reviewer-active` is absent. Circuit breaker: counts existing `<!-- review-error: <sha> -->` comments; skips a PR if ≥3 consecutive errors for the same HEAD SHA (prevents flooding on repeated review failures).
chore: gardener housekeeping 2026-04-08 2026-04-08 12:10:41 +00:00			- `review/review-pr.sh` — Creates/reuses a tmux session (`review-{project}-{pr}`), injects PR diff, waits for Claude to write structured JSON output, posts markdown review + formal forge review, auto-creates follow-up issues for pre-existing tech debt. cd at startup: changes to `$PROJECT_REPO_ROOT` early in the script — before any git commands — because the factory root is not a git repo after image rebuild (#408). Calls `resolve_forge_remote()` at startup to determine the correct git remote name (avoids hardcoded 'origin'). Before starting the session, runs `lib/build-graph.py --changed-files <PR files>` and appends the JSON structural analysis (affected objectives, orphaned prerequisites, thin evidence) to the review prompt. Graph failures are non-fatal — review proceeds without it.
chore: gardener housekeeping 2026-03-21 Progressive disclosure split of AGENTS.md (487→152 lines): - Extracted per-directory AGENTS.md files for all 8 agents + lib/ - Root AGENTS.md now serves as a table of contents with summary table - All watermarks updated to 16e430e Grooming results: - Promoted #469 (WATCH flow missing curl) and #436 (idle_pane_count bug) to backlog - 12 dust items classified, no groups ripe for bundling yet - No blocked issues, no AD violations 2026-03-21 12:44:23 +00:00
			`Environment variables consumed:`
fix: Replace Codeberg dependency with local Forgejo instance (#611) - Add setup_forge() to bin/disinto: provisions Forgejo via Docker, creates admin + bot users (dev-bot, review-bot), generates API tokens, creates repo, and pushes code — all automated - Rename env vars: CODEBERG_TOKEN→FORGE_TOKEN, REVIEW_BOT_TOKEN→ FORGE_REVIEW_TOKEN, CODEBERG_REPO→FORGE_REPO, CODEBERG_API→ FORGE_API, CODEBERG_WEB→FORGE_WEB, CODEBERG_BOT_USERNAMES→ FORGE_BOT_USERNAMES (with backwards-compat fallbacks) - Rename API helpers: codeberg_api()→forge_api(), codeberg_api_all() →forge_api_all() (with compat aliases) - Add forge_url field to project TOML; load-project.sh derives FORGE_API/FORGE_WEB from forge_url + repo - Update parse_repo_slug() to accept any host URL, not just codeberg - Forgejo data stored under ~/.disinto/forgejo/ (not in factory repo) - Update all 58 files: agent scripts, formulas, docs, site HTML Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> 2026-03-23 16:57:12 +00:00			- `FORGE_TOKEN` — Dev-agent token (must not be the same account as FORGE_REVIEW_TOKEN)
			- `FORGE_REVIEW_TOKEN` — Review-agent token for approvals (use human/admin account; branch protection: in approvals whitelist)
			- `FORGE_REPO`, `FORGE_API`, `PROJECT_NAME`, `PROJECT_REPO_ROOT`
chore: gardener housekeeping 2026-03-21 Progressive disclosure split of AGENTS.md (487→152 lines): - Extracted per-directory AGENTS.md files for all 8 agents + lib/ - Root AGENTS.md now serves as a table of contents with summary table - All watermarks updated to 16e430e Grooming results: - Promoted #469 (WATCH flow missing curl) and #436 (idle_pane_count bug) to backlog - 12 dust items classified, no groups ripe for bundling yet - No blocked issues, no AD violations 2026-03-21 12:44:23 +00:00			- `PRIMARY_BRANCH`, `WOODPECKER_REPO_ID`