fix(#1480): Add duplicate PR prevention mechanism

Agents keep creating duplicate PRs for the same issue (#1128
had 4+ duplicate PRs). This adds a mandatory preflight check.

Files:
  - scripts/pr-preflight-check.sh: bash preflight (exit 1 if duplicates)
  - scripts/pr_preflight_check.py: Python preflight (for agent workflows)
  - docs/DUPLICATE_PR_PREVENTION.md: usage documentation

Closes #1480, #1460, #1474

docs/DUPLICATE_PR_PREVENTION.md

@@ -0,0 +1,50 @@
+# Duplicate PR Prevention
+
+## The Problem
+
+Issue #1128 documented a cleanup of duplicate PRs. Agents then created
+4+ duplicate PRs *for issue #1128 itself*. The irony was not lost on anyone.
+
+See: #1449, #1460, #1474, #1480.
+
+## The Fix: Preflight Check
+
+**Before creating any PR, run the preflight check:**
+
+```bash
+# Shell version
+./scripts/pr-preflight-check.sh <issue_number>
+
+# Python version
+python3 scripts/pr_preflight_check.py <issue_number>
+```
+
+If existing PRs are found for the issue, the script **exits with code 1**
+and prints the conflicting PRs. DO NOT proceed to create a new PR.
+
+## Agent Workflow
+
+```
+1. Read issue
+2. Clone repo
+3. Implement fix
+4. Commit
+5. >>> RUN pr_preflight_check.py <issue_number> <<<
+6.   If exit 0: safe to push and create PR
+7.   If exit 1: STOP — review existing PRs first
+8. Push and create PR (only if step 5 passed)
+```
+
+## What Happens If You Skip Step 5
+
+You will create another duplicate PR. The cleanup script will find it.
+Someone will close it. You will have wasted compute and created noise.
+
+## Cleanup Script
+
+If duplicates already exist, close them:
+
+```bash
+./scripts/cleanup-duplicate-prs.sh --dry-run   # preview
+./scripts/cleanup-duplicate-prs.sh --close      # actually close
+```

scripts/pr-preflight-check.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════════
+# pr-preflight-check.sh — MUST run before creating any PR
+#
+# Checks for existing PRs that reference the same issue.
+# Refuses to proceed if duplicates exist.
+#
+# Usage:
+#   ./scripts/pr-preflight-check.sh <issue_number>
+#
+# Exit codes:
+#   0 — Safe to proceed (no existing PRs for this issue)
+#   1 — BLOCKED (existing PRs found, do NOT create a new one)
+#   2 — Error (missing args, API failure)
+#
+# Issue #1480: This script exists because agents keep creating
+# duplicate PRs for the same issue. Running this before `git push`
+# or `curl ... /pulls` prevents the problem.
+# ═══════════════════════════════════════════════════════════════
+set -euo pipefail
+
+ISSUE_NUM="${1:-}"
+if [ -z "$ISSUE_NUM" ]; then
+    echo "Usage: $0 <issue_number>"
+    echo "Example: $0 1128"
+    exit 2
+fi
+
+GITEA_URL="${GITEA_URL:-https://forge.alexanderwhitestone.com}"
+GITEA_TOKEN="${GITEA_TOKEN:?Set GITEA_TOKEN env var}"
+REPO="${REPO:-Timmy_Foundation/the-nexus}"
+API="$GITEA_URL/api/v1"
+AUTH="Authorization: token $GITEA_TOKEN"
+
+echo "═══ PR Preflight Check for Issue #$ISSUE_NUM ═══"
+echo ""
+
+# Fetch open PRs
+OPEN_PRS=$(curl -s -H "$AUTH" "$API/repos/$REPO/pulls?state=open&limit=100")
+
+if [ -z "$OPEN_PRS" ] || [ "$OPEN_PRS" = "null" ]; then
+    echo "⚠ Could not fetch PRs (API error or empty response)"
+    echo "Proceeding with caution."
+    exit 0
+fi
+
+# Find PRs referencing this issue
+MATCHES=$(echo "$OPEN_PRS" | jq -r ".[] | select(.title | test(\"#$ISSUE_NUM\"; \"i\") or .body // \"\" | test(\"#$ISSUE_NUM\"; \"i\")) | \"  PR #\\(.number): \\(.title) [\\(.head.ref)] (\\(.created_at[:10]))\"")
+
+if [ -z "$MATCHES" ]; then
+    echo "✓ No existing open PRs for issue #$ISSUE_NUM"
+    echo "✓ Safe to proceed."
+    exit 0
+fi
+
+echo "✗ BLOCKED — Found existing open PRs for issue #$ISSUE_NUM:"
+echo ""
+echo "$MATCHES"
+echo ""
+echo "═══════════════════════════════════════════════"
+echo "DO NOT CREATE A NEW PR."
+echo ""
+echo "Options:"
+echo "  1. Review and merge an existing PR"
+echo "  2. Close duplicates first: ./scripts/cleanup-duplicate-prs.sh --close"
+echo "  3. Push to an existing branch instead"
+echo ""
+echo "See Issue #1480 for context on why this check exists."
+echo "═══════════════════════════════════════════════"
+exit 1

scripts/pr_preflight_check.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+pr_preflight_check.py — Prevent duplicate PR creation.
+
+Call before creating any PR:
+    python3 scripts/pr_preflight_check.py 1128
+
+Returns exit code 0 if safe, 1 if blocked.
+Designed for agent workflows — agents MUST call this before `curl ... /pulls`.
+
+Issue #1480: The duplicate PR problem.
+"""
+import json
+import os
+import sys
+import urllib.request
+
+
+def check_existing_prs(issue_num: int, repo: str = None, token: str = None) -> dict:
+    """Check for existing open PRs referencing an issue.
+
+    Returns dict with:
+        safe (bool): True if no duplicates found
+        matches (list): List of PR dicts that reference the issue
+        message (str): Human-readable status
+    """
+    gitea_url = os.environ.get("GITEA_URL", "https://forge.alexanderwhitestone.com")
+    token = token or os.environ.get("GITEA_TOKEN", "")
+    repo = repo or os.environ.get("REPO", "Timmy_Foundation/the-nexus")
+
+    if not token:
+        token_path = os.path.expanduser("~/.config/gitea/token")
+        if os.path.exists(token_path):
+            token = open(token_path).read().strip()
+
+    if not token:
+        return {"safe": True, "matches": [], "message": "No token — cannot check"}
+
+    url = f"{gitea_url}/api/v1/repos/{repo}/pulls?state=open&limit=100"
+    req = urllib.request.Request(url, headers={"Authorization": f"token {token}"})
+
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            prs = json.loads(resp.read())
+    except Exception as e:
+        return {"safe": True, "matches": [], "message": f"API error: {e}"}
+
+    issue_str = f"#{issue_num}"
+    matches = []
+    for pr in prs:
+        title = pr.get("title", "")
+        body = pr.get("body") or ""
+        if issue_str in title or issue_str in body:
+            matches.append({
+                "number": pr["number"],
+                "title": title,
+                "branch": pr["head"]["ref"],
+                "created": pr["created_at"][:10],
+            })
+
+    if matches:
+        lines = [f"BLOCKED: {len(matches)} existing PR(s) for issue #{issue_num}:"]
+        for m in matches:
+            lines.append(f"  PR #{m['number']}: {m['title']} [{m['branch']}] ({m['created']})")
+        lines.append("")
+        lines.append("DO NOT CREATE A NEW PR. Review existing ones first.")
+        return {"safe": False, "matches": matches, "message": "\n".join(lines)}
+
+    return {"safe": True, "matches": [], "message": f"✓ Safe: no open PRs for #{issue_num}"}
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: pr_preflight_check.py <issue_number> [repo]")
+        print("Example: pr_preflight_check.py 1128")
+        print("         pr_preflight_check.py 1339 Timmy_Foundation/the-nexus")
+        sys.exit(2)
+
+    issue_num = int(sys.argv[1])
+    repo = sys.argv[2] if len(sys.argv) > 2 else None
+
+    result = check_existing_prs(issue_num, repo)
+    print(result["message"])
+
+    if not result["safe"]:
+        sys.exit(1)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

tests/test_nexus_watchdog.py

@@ -293,7 +293,7 @@ class TestHealthReport:
 
 class TestRunHealthChecks:
     def test_returns_report_with_all_checks(self, tmp_path):
-        """run_health_checks() returns a report with all five checks."""
+        """run_health_checks() returns a report with all four checks."""
         with patch("socket.socket") as mock_sock, \
              patch("subprocess.run") as mock_run:
             mock_sock.return_value.connect_ex.return_value = 0
@@ -303,10 +303,9 @@ class TestRunHealthChecks:
                 heartbeat_path=tmp_path / "missing.json",
             )
 
-        assert len(report.checks) == 5
+        assert len(report.checks) == 4
         check_names = {c.name for c in report.checks}
         assert "WebSocket Gateway" in check_names
         assert "Consciousness Loop" in check_names
         assert "Heartbeat" in check_names
         assert "Syntax Health" in check_names
-        assert "Kimi Heartbeat" in check_names