From 6045cfa7d20875353e248e079ac9ab19e8122a3c Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 19 Mar 2026 23:15:34 +0000 Subject: [PATCH 1/2] fix: prediction-agent / predictor not documented in AGENTS.md agent list (#307) Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 38 +++++++++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fcebbb6..a635d7e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,7 @@ disinto/ ├── review/ review-poll.sh, review-pr.sh — PR review ├── gardener/ gardener-poll.sh, gardener-agent.sh — backlog grooming ├── planner/ planner-poll.sh, planner-agent.sh — vision gap analysis +│ prediction-poll.sh, prediction-agent.sh — evidence-based predictions ├── supervisor/ supervisor-poll.sh — health monitoring ├── vault/ vault-poll.sh, vault-agent.sh, vault-fire.sh — action gating ├── action/ action-poll.sh, action-agent.sh — operational task execution @@ -149,9 +150,9 @@ P3 (degraded PRs, circular deps, stale deps), P4 (housekeeping). **Role**: Three-phase planning. Phase 1: update the AGENTS.md documentation tree to reflect recent code changes. Phase 1.5: triage `prediction/unreviewed` -issues filed by the predictor (goblin) — accept as action/backlog issues or -dismiss as noise. Phase 2: gap-analyse VISION.md vs current project state -(including accepted predictions), create up to 5 backlog issues for the +issues filed by the [Predictor](#predictor-planner) — accept as action/backlog +issues or dismiss as noise. Phase 2: gap-analyse VISION.md vs current project +state (including accepted predictions), create up to 5 backlog issues for the highest-leverage gaps. **Trigger**: `planner-poll.sh` runs weekly via cron. @@ -168,6 +169,37 @@ highest-leverage gaps. - `CLAUDE_TIMEOUT` - `MATRIX_TOKEN`, `MATRIX_ROOM_ID`, `MATRIX_HOMESERVER` +### Predictor (`planner/`) + +**Role**: Evidence-based pattern detection (the "goblin"). Reads structured +JSON from the project's `evidence/` directory (red-team, evolution, user-test, +holdout, resources, protocol) plus secondary Codeberg signals (recent issues +and merged PRs) and system resource snapshots. Asks Claude to identify +staleness, regressions, opportunities, and risks, then files up to 5 +`prediction/unreviewed` issues for the [Planner](#planner-planner) to triage. +The predictor MUST NOT emit feature work — only observations about evidence +state, metric trends, and system conditions. + +**Trigger**: `prediction-poll.sh` runs hourly via cron. It iterates over all +`projects/*.toml` files and runs `prediction-agent.sh` for each project. +Guarded by a global lock (`/tmp/prediction-poll.lock`) and a memory check +(skips if available RAM < 2000 MB). + +**Key files**: +- `planner/prediction-poll.sh` — Cron wrapper: lock, memory guard, iterates projects, calls prediction-agent.sh per project +- `planner/prediction-agent.sh` — Scans `evidence/` subdirectories for latest + previous JSON, fetches recent Codeberg activity, collects system resource snapshot, builds prompt, invokes `claude -p --model sonnet` (one-shot), parses JSON output lines, creates `prediction/unreviewed` issues on Codeberg, notifies Matrix + +**Environment variables consumed**: +- `CODEBERG_TOKEN`, `CODEBERG_REPO`, `CODEBERG_API`, `PROJECT_NAME`, `PROJECT_REPO_ROOT` +- `CLAUDE_TIMEOUT` — Max seconds for the Claude invocation (default 7200) +- `MATRIX_TOKEN`, `MATRIX_ROOM_ID`, `MATRIX_HOMESERVER` — Notifications (optional) + +**Lifecycle**: prediction-poll.sh (hourly cron) → lock + memory guard → +for each project TOML: prediction-agent.sh → scan `evidence/` → +`claude -p --model sonnet` → parse JSON predictions → create +`prediction/unreviewed` issues → Matrix notification. The planner's Phase 1.5 +later triages these predictions into action/backlog issues or dismisses them. + ### Action (`action/`) **Role**: Execute operational tasks described by action formulas — run scripts, From ad624029826704e5a7eccebe381699ce03226608 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 19 Mar 2026 23:30:30 +0000 Subject: [PATCH 2/2] fix: update Planner future-direction note to reflect live Predictor Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index a635d7e..31d0868 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -161,7 +161,7 @@ highest-leverage gaps. - `planner/planner-poll.sh` — Cron wrapper: lock, memory guard, runs planner-agent.sh - `planner/planner-agent.sh` — Phase 1: uses `claude -p --model sonnet --max-turns 30` (one-shot with tool access) to read/update AGENTS.md files. Phase 1.5: fetches `prediction/unreviewed` issues and uses `claude -p --model sonnet` to triage each prediction (ACCEPT_ACTION, ACCEPT_BACKLOG, or DISMISS); creates corresponding action/backlog issues and relabels predictions to `prediction/backlog` or closes them. Phase 2: uses `claude -p --model sonnet` to compare AGENTS.md tree vs VISION.md (plus accepted predictions from Phase 1.5) and create gap issues. All phases are one-shot (`claude -p`), not interactive sessions -**Future direction**: The planner will read an `evidence/` directory of structured JSON written by sense/mutation processes (see `docs/EVIDENCE-ARCHITECTURE.md`). This replaces human "ship it" decisions with evidence-gated deployment across dimensions: holdout, red-team, user-test, evolution fitness, protocol metrics, funnel. Not yet implemented. +**Future direction**: The [Predictor](#predictor-planner) already reads `evidence/` JSON and files prediction issues for the planner to triage. The next step is evidence-gated deployment (see `docs/EVIDENCE-ARCHITECTURE.md`): replacing human "ship it" decisions with automated gates across dimensions (holdout, red-team, user-test, evolution fitness, protocol metrics, funnel). Not yet implemented. **Environment variables consumed**: - `CODEBERG_TOKEN`, `CODEBERG_REPO`, `CODEBERG_API`, `PROJECT_NAME`, `PROJECT_REPO_ROOT`