From 3c6723bd8fb85e61e26d5acae5d2915766655cd5 Mon Sep 17 00:00:00 2001 From: openhands Date: Sat, 21 Mar 2026 11:55:15 +0000 Subject: [PATCH] fix: feat: architecture decisions section in AGENTS.md + gardener alignment checks (#479) Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 19 +++++++++++++++++++ formulas/run-gardener.toml | 29 +++++++++++++++++++++++++++-- 2 files changed, 46 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a0df5aa..54a457e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -408,6 +408,25 @@ prevents merge conflicts between concurrent changes. --- +## Architecture Decisions + +Humans write these. Agents read and enforce them. + +| ID | Decision | Rationale | +|---|---|---| +| AD-001 | Nervous system runs from cron, not action issues. | Planner, predictor, gardener, supervisor run directly via `*-run.sh`. They create work, they don't become work. (See PR #474 revert.) | +| AD-002 | Single-threaded pipeline per project. | One dev issue at a time. No new work while a PR awaits CI or review. Prevents merge conflicts and keeps context clear. | +| AD-003 | The runtime creates and destroys, the formula preserves. | Runtime manages worktrees/sessions/temp. Formulas commit knowledge to git before signaling done. | +| AD-004 | Event-driven > polling > fixed delays. | Never `waitForTimeout` or hardcoded sleep. Use phase files, webhooks, or poll loops with backoff. | +| AD-005 | Secrets via env var indirection, never in issue bodies. | Issue bodies become code. Secrets go in `.env` or TOML project files, referenced as `$VAR_NAME`. | + +**Who enforces what:** +- **Gardener** checks open backlog issues against ADs during grooming; closes violations with a comment referencing the AD number. +- **Planner** plans within the architecture; does not create issues that violate ADs. +- **Dev-agent** reads AGENTS.md before implementing; refuses work that violates ADs. + +--- + ## Phase-Signaling Protocol (for persistent tmux sessions) When running as a **persistent tmux session** (issue #80+), Claude must signal diff --git a/formulas/run-gardener.toml b/formulas/run-gardener.toml index 9513527..4fa067c 100644 --- a/formulas/run-gardener.toml +++ b/formulas/run-gardener.toml @@ -101,10 +101,35 @@ Sibling dependency rule (CRITICAL): NEVER add bidirectional ## Dependencies between siblings (creates deadlocks). Use ## Related for cross-references: "## Related\n- #NNN (sibling)" +7. Architecture decision alignment check (AD check): + For each open issue labeled 'backlog', check whether the issue + contradicts any architecture decision listed in the + ## Architecture Decisions section of AGENTS.md. + Read AGENTS.md and extract the AD table. For each backlog issue, + compare the issue title and body against each AD. If an issue + clearly violates an AD: + a. Post a comment explaining the violation: + curl -sf -X POST -H "Authorization: token $CODEBERG_TOKEN" \ + -H "Content-Type: application/json" \ + "$CODEBERG_API/issues//comments" \ + -d '{"body":"Closing: violates AD-NNN (). See AGENTS.md § Architecture Decisions."}' + b. Close the issue: + curl -sf -X PATCH -H "Authorization: token $CODEBERG_TOKEN" \ + -H "Content-Type: application/json" \ + "$CODEBERG_API/issues/" \ + -d '{"state":"closed"}' + c. Log to the result file: + echo "ACTION: closed #NNN — violates AD-NNN" >> "$RESULT_FILE" + + Only close for clear, unambiguous violations. If the issue is + borderline or could be interpreted as compatible, leave it open + and ESCALATE instead. + Processing order: 1. Handle PRIORITY_blockers_starving_factory first — promote or resolve - 2. Process tech-debt issues by score (impact/effort) - 3. Classify remaining items as dust or escalate + 2. AD alignment check — close backlog issues that violate architecture decisions + 3. Process tech-debt issues by score (impact/effort) + 4. Classify remaining items as dust or escalate Do NOT bundle dust yourself — the dust-bundling step handles accumulation, dedup, TTL expiry, and bundling into backlog issues.