Merge pull request 'fix: feat: architecture decisions section in AGENTS.md + gardener alignment checks (#479)' (#484) from fix/issue-479 into main

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

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/<number>/comments" \
+          -d '{"body":"Closing: violates AD-NNN (<decision summary>). 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/<number>" \
+          -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)
+  2. AD alignment check — close backlog issues that violate architecture decisions
-  3. Classify remaining items as dust or escalate
+  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.