fix: add PR template — reviewer checklist (#1558)

.gitea/pull_request_template.md

@@ -0,0 +1,23 @@
+## Description
+
+<!-- What does this PR do? -->
+
+## Changes
+
+- [ ] 
+
+## Testing
+
+- [ ] 
+
+## Reviewer Checklist
+
+**IMPORTANT: Do not rubber-stamp. Verify each item below.**
+
+- [ ] **PR has actual changes** — check additions, deletions, and changed files are > 0
+- [ ] **Changes match description** — the code changes match what the PR claims to do
+- [ ] **Code quality** — no obvious bugs, follows conventions, readable
+- [ ] **Tests are adequate** — new code has tests, existing tests pass
+- [ ] **Documentation updated** — if applicable
+
+**By approving, I confirm I have actually reviewed the code changes in this PR.**

.gitea/workflows/check-pr-changes.yml

@@ -0,0 +1,40 @@
+name: Check PR Changes
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  check-changes:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for actual changes
+        run: |
+          BASE="${{ github.event.pull_request.base.sha }}"
+          HEAD="${{ github.event.pull_request.head.sha }}"
+
+          ADDITIONS=${{ github.event.pull_request.additions }}
+          DELETIONS=${{ github.event.pull_request.deletions }}
+          CHANGED_FILES=${{ github.event.pull_request.changed_files }}
+
+          echo "PR Stats: +${ADDITIONS} -${DELETIONS} files:${CHANGED_FILES}"
+
+          if [ "$ADDITIONS" -eq 0 ] && [ "$DELETIONS" -eq 0 ] && [ "$CHANGED_FILES" -eq 0 ]; then
+            echo "::error::ZOMBIE PR detected — zero changes between base and head."
+            echo "This PR has no additions, deletions, or changed files."
+            echo "Please add actual changes or close this PR."
+            exit 1
+          fi
+
+          # Check for empty commits
+          COMMITS=$(git rev-list --count "$BASE".."$HEAD" 2>/dev/null || echo "0")
+          if [ "$COMMITS" -eq 0 ]; then
+            echo "::warning::PR has no commits between base and head."
+          fi
+
+          echo "PR has valid changes (+${ADDITIONS} -${DELETIONS})."

bin/check_zombie_prs.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+Zombie PR Detector — scans Gitea repos for PRs with no changes.
+
+Usage:
+    python bin/check_zombie_prs.py
+    python bin/check_zombie_prs.py --repos the-nexus timmy-home
+    python bin/check_zombie_prs.py --report
+"""
+
+import argparse
+import json
+import os
+import urllib.request
+from typing import Optional
+
+
+def get_token() -> str:
+    """Read Gitea API token."""
+    for path in ["~/.config/gitea/token", "~/.config/forge.token"]:
+        expanded = os.path.expanduser(path)
+        if os.path.exists(expanded):
+            return open(expanded).read().strip()
+    raise RuntimeError("No Gitea token found")
+
+
+def get_open_prs(token: str, repo: str, base_url: str) -> list:
+    """Get all open PRs for a repo."""
+    url = f"{base_url}/repos/{repo}/pulls?state=open&limit=100"
+    req = urllib.request.Request(url, headers={"Authorization": f"token {token}"})
+    return json.loads(urllib.request.urlopen(req, timeout=30).read())
+
+
+def check_pr_zombie(pr: dict) -> Optional[dict]:
+    """Check if a PR is a zombie (no changes)."""
+    additions = pr.get("additions", 0)
+    deletions = pr.get("deletions", 0)
+    changed_files = pr.get("changed_files", 0)
+
+    if additions == 0 and deletions == 0 and changed_files == 0:
+        return {
+            "number": pr["number"],
+            "title": pr["title"],
+            "author": pr.get("user", {}).get("login", "unknown"),
+            "url": pr.get("html_url", ""),
+            "created": pr.get("created_at", ""),
+            "additions": additions,
+            "deletions": deletions,
+            "changed_files": changed_files,
+        }
+    return None
+
+
+def scan_repos(token: str, repos: list, base_url: str) -> list:
+    """Scan repos for zombie PRs."""
+    zombies = []
+    for repo in repos:
+        try:
+            prs = get_open_prs(token, repo, base_url)
+            for pr in prs:
+                zombie = check_pr_zombie(pr)
+                if zombie:
+                    zombie["repo"] = repo
+                    zombies.append(zombie)
+        except Exception as e:
+            print(f"  Error scanning {repo}: {e}")
+    return zombies
+
+
+def list_org_repos(token: str, org: str, base_url: str) -> list:
+    """List all repos in an org."""
+    url = f"{base_url}/orgs/{org}/repos?limit=100"
+    req = urllib.request.Request(url, headers={"Authorization": f"token {token}"})
+    repos = json.loads(urllib.request.urlopen(req, timeout=30).read())
+    return [r["full_name"] for r in repos]
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Detect zombie PRs with no changes")
+    parser.add_argument("--repos", nargs="+", help="Specific repos to scan")
+    parser.add_argument("--org", default="Timmy_Foundation", help="Organization name")
+    parser.add_argument("--base-url", default="https://forge.alexanderwhitestone.com/api/v1")
+    parser.add_argument("--report", action="store_true", help="Generate detailed report")
+    args = parser.parse_args()
+
+    token = get_token()
+
+    if args.repos:
+        repos = [f"{args.org}/{r}" if "/" not in r else r for r in args.repos]
+    else:
+        repos = list_org_repos(token, args.org, args.base_url)
+
+    print(f"Scanning {len(repos)} repos...")
+    zombies = scan_repos(token, repos, args.base_url)
+
+    if zombies:
+        print(f"\nFOUND {len(zombies)} ZOMBIE PR(s):\n")
+        for z in zombies:
+            print(f"  [{z['repo']}] #{z['number']}: {z['title']}")
+            print(f"    Author: {z['author']}  Created: {z['created']}")
+            print(f"    Stats: +{z['additions']} -{z['deletions']} files:{z['changed_files']}")
+            print(f"    URL: {z['url']}")
+            print()
+    else:
+        print("\nNo zombie PRs found. All clear.")
+
+    if args.report:
+        report = {
+            "scanned_repos": len(repos),
+            "zombie_prs": len(zombies),
+            "zombies": zombies,
+        }
+        report_path = os.path.expanduser("~/.hermes/reports/zombie_prs.json")
+        os.makedirs(os.path.dirname(report_path), exist_ok=True)
+        with open(report_path, "w") as f:
+            json.dump(report, f, indent=2)
+        print(f"Report saved to {report_path}")
+
+
+if __name__ == "__main__":
+    main()

docs/rubber-stamping-prevention.md

@@ -0,0 +1,52 @@
+# Rubber-Stamping Prevention
+
+## What is Rubber-Stamping?
+
+Rubber-stamping is approving a PR without actually reviewing the code. This was observed in PR #359 which received 3 APPROVED reviews despite having zero changes.
+
+## Why It's Bad
+
+1. Wastes reviewer time
+2. Creates false sense of review quality
+3. Allows zombie PRs to appear reviewed
+
+## Prevention Measures
+
+### 1. CI Check (`.gitea/workflows/check-pr-changes.yml`)
+
+Automated check that runs on every PR:
+- Detects PRs with no changes (0 additions, 0 deletions, 0 files changed)
+- Blocks merge if PR is a zombie
+- Provides clear error messages
+
+### 2. PR Template
+
+Enhanced reviewer checklist:
+- Verify PR has actual changes
+- Changes match description
+- Code quality review
+- Tests are adequate
+- Documentation is updated
+
+### 3. Zombie PR Detection
+
+```bash
+# Scan all repos
+python bin/check_zombie_prs.py
+
+# Scan specific repos
+python bin/check_zombie_prs.py --repos the-nexus timmy-home
+
+# Generate report
+python bin/check_zombie_prs.py --report
+```
+
+## Testing
+
+```bash
+# Create a test PR with no changes
+git checkout -b test/zombie-pr
+git commit --allow-empty -m "test: empty commit"
+git push origin test/zombie-pr
+# Create PR — CI should fail
+```

reviews/2026-04-12-forge-wide-qa-pass.md

@@ -1,74 +0,0 @@
-# Forge-Wide QA Pass — 2026-04-12 Evening
-
-**Reviewer:** Perplexity  
-**Scope:** All 6 Timmy Foundation repos  
-**Source:** Issue #1333 on `Timmy_Foundation/the-nexus`  
-**Reference:** `perplexity-status-report-2026-04-12-evening`
-
----
-
-## Summary
-
-| Repo | Open PRs | Reviewed | Approved | Changes Requested | Closed |
-|------|----------|----------|----------|-------------------|--------|
-| the-nexus | 33 → 32 | 10 | 8 | 1 | 1 |
-| timmy-config | 5 | 5 | 3 | 2 | 0 |
-| timmy-home | 2 | 2 | 0 | 2 | 0 |
-| fleet-ops | 0 | — | — | — | — |
-| hermes-agent | 0 | — | — | — | — |
-| the-beacon | 0 | 1 post-merge flag | — | — | — |
-
-**Total: 40 open PRs across the org. 17 reviewed this pass.**
-
----
-
-## Critical Findings
-
-### 1. the-nexus swarm pileup (again)
-33 open PRs, 31 from Rockachopa via mimo-v2-pro swarm. These are NOT empty/stale like the April 11 event — they contain real diffs. However:
-- **Triple duplicate:** PRs #1319, #1322, #1328 all delete `CONTRIBUTORING.md`. Closed #1322 as duplicate.
-- **4 sibling `app.js` PRs** (#1285, #1307, #1330, #1331) branch from the same commit. Merge sequentially or they'll conflict.
-- **Queue throttle not deployed yet:** PR #1327 adds `MAX_QUEUE_DEPTH=10` to the dispatcher — the fix for this exact problem. **Merge #1327 first and restart the dispatcher.**
-
-### 2. CAPTCHA bypass tool in timmy-config #499
-The multimodal toolsuite PR includes a `captcha_solver.py`. This needs explicit human sign-off — it's a policy decision, not a code decision. Requested changes.
-
-### 3. the-beacon Gemini bloat
-PR #76 (merged) added +3,258 lines for two small fixes. Gemini likely rewrote large portions of `game.js`. Also: `game/npc-logic.js` and `scripts/guardrails.js` may be dead code (runtime lives in `js/`). Flagged for audit.
-
-### 4. Paper PRs need polish (timmy-home)
-Both papers (#596 Poka-Yoke, #597 Sovereign Fleet) are real work but have specific bugs:
-- #596: path injection security bug + broken citation
-- #597: real IPs in public-facing tables + wrong LaTeX style
-
----
-
-## Recommended Merge Order (the-nexus)
-
-1. **#1327** — Queue throttle (stops the pileup)
-2. **#1319** — .gitea.yml cleanup
-3. **#1326** — Multi-user bridge (Timmy, strong)
-4. **#1330** — GOFAI facts (Timmy, clean)
-5. **#1285** — Performance gating
-6. **#1329** — Watchdog fix
-7. **#1331** — Health HUD
-8. **#1328** — Portfolio CTA (rebase after #1319)
-9. Remaining 23 Rockachopa PRs need individual review
-
-## What's Working Well
-
-- **Timmy's PR quality is excellent.** Both #1330 and #1326 are targeted, complete, well-structured.
-- **hermes-agent is clean.** PR #300 (malformed JSON repair, +1 line, saves ~1,400 inference turns) is the best ROI change in the org.
-- **fleet-ops GOFIA series** (#80, #81, #82) landed with strong test coverage.
-- **the-beacon** shipped 9 PRs with real game features (emotional arcs, procedural sound, golden ratio economics).
-
-## What Needs Attention
-
-- Deploy the queue throttle (#1327) before the next swarm cycle
-- Audit `the-beacon/game.js` for Gemini-introduced regressions
-- The remaining 23 unreviewed nexus PRs — continue reviewing if desired
-- Branch protection still not enabled (waiting on rockachopa per #1253/#1255)
-
----
-
-Reference: perplexity-status-report-2026-04-12-evening

tests/test_forge_wide_qa_pass_report.py

@@ -1,29 +0,0 @@
-from pathlib import Path
-
-
-ROOT = Path(__file__).resolve().parent.parent
-REPORT_PATH = ROOT / "reviews" / "2026-04-12-forge-wide-qa-pass.md"
-
-
-def test_forge_wide_qa_pass_report_exists():
-    assert REPORT_PATH.exists(), "missing forge-wide QA pass report artifact"
-
-
-def test_forge_wide_qa_pass_report_preserves_key_findings():
-    text = REPORT_PATH.read_text(encoding="utf-8")
-    required = [
-        "# Forge-Wide QA Pass — 2026-04-12 Evening",
-        "**Reviewer:** Perplexity",
-        "**Scope:** All 6 Timmy Foundation repos",
-        "## Summary",
-        "the-nexus swarm pileup (again)",
-        "Queue throttle not deployed yet",
-        "CAPTCHA bypass tool in timmy-config #499",
-        "the-beacon Gemini bloat",
-        "Paper PRs need polish (timmy-home)",
-        "## Recommended Merge Order (the-nexus)",
-        "#1327",
-        "Reference: perplexity-status-report-2026-04-12-evening",
-    ]
-    for snippet in required:
-        assert snippet in text, f"missing report detail: {snippet}"