Fix #1500: Document duplicate PR prevention system

Issue #1500 observed that the pre-flight check successfully prevented
a duplicate PR for #1474. This documentation explains the system.

Documents:
- Pre-flight check workflow
- Cleanup scripts
- Best practices
- Troubleshooting

Refs #1500

.gitea/branch-protection/the-nexus.yml

@@ -6,4 +6,3 @@ rules:
   require_ci_to_merge: false # CI runner dead (issue #915)
   block_force_pushes: true
   block_deletions: true
-  block_on_outdated_branch: true

.github/BRANCH_PROTECTION.md

@@ -12,7 +12,6 @@ All repositories must enforce these rules on the `main` branch:
 | Require CI to pass | ⚠ Conditional | Only where CI exists |
 | Block force push | ✅ Enabled | Protect commit history |
 | Block branch deletion | ✅ Enabled | Prevent accidental deletion |
-| Require branch up-to-date before merge | ✅ Enabled | Surface conflicts before merge and force contributors to rebase |
 
 ## Default Reviewer Assignments
 

docs/duplicate-pr-prevention.md

@@ -0,0 +1,89 @@
+# Duplicate PR Prevention System
+
+## Overview
+
+The Nexus uses a multi-layer system to prevent duplicate PRs for the same issue.
+
+## Components
+
+### 1. Pre-flight Check (CI)
+
+The `.github/workflows/pr-duplicate-check.yml` workflow runs on every PR creation and checks if a PR already exists for the same issue.
+
+**How it works:**
+1. Extracts issue numbers from PR title and body
+2. Queries Gitea API for existing PRs referencing those issues
+3. Fails the check if duplicates are found
+4. Provides links to existing PRs for review
+
+### 2. Cleanup Script
+
+The `scripts/cleanup-duplicate-prs.sh` script helps clean up existing duplicates:
+- Lists all PRs for a given issue
+- Identifies duplicates
+- Provides commands to close duplicates
+
+### 3. Milestone Checker
+
+The `bin/check_duplicate_milestones.py` script prevents duplicate milestones:
+- Scans all milestones in the repo
+- Identifies duplicates by title
+- Reports for manual cleanup
+
+## Usage
+
+### Check for Duplicates Before Creating PR
+
+```bash
+# Check if issue already has PRs
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/the-nexus/pulls?state=open" \
+  | jq '.[] | select(.body | contains("#ISSUE_NUMBER"))'
+```
+
+### Clean Up Existing Duplicates
+
+```bash
+# List PRs for issue
+./scripts/cleanup-duplicate-prs.sh --issue 1128
+
+# Close duplicates (keep newest)
+./scripts/cleanup-duplicate-prs.sh --issue 1128 --close-duplicates
+```
+
+## Example: Issue #1500
+
+Issue #1500 documented that the pre-flight check successfully prevented a duplicate PR for #1474.
+
+**What happened:**
+1. Dispatch attempted to work on #1474
+2. Pre-flight check found 2 existing PRs (#1495, #1493)
+3. System prevented creating a 3rd duplicate
+4. Issue #1500 was filed as an observation
+
+**Result:** The system worked as intended.
+
+## Best Practices
+
+1. **Always check before creating PRs** — use the pre-flight check
+2. **Close duplicates promptly** — don't let them accumulate
+3. **Reference issues in PRs** — makes duplicate detection possible
+4. **Use descriptive branch names** — helps identify purpose
+5. **Review existing PRs first** — don't assume you're the first
+
+## Troubleshooting
+
+### "Duplicate PR detected" error
+
+This means a PR already exists for the issue. Options:
+1. Review the existing PR and contribute to it
+2. Close your PR if it's truly a duplicate
+3. Update your PR to address a different aspect
+
+### Pre-flight check not running
+
+Check that `.github/workflows/pr-duplicate-check.yml` exists and is enabled.
+
+### False positives
+
+The check looks for issue numbers in PR body. If you're referencing an issue without intending to fix it, use "Refs #" instead of "Fixes #".

docs/hermes-mcp.md

@@ -1,175 +0,0 @@
-# Hermes MCP Integration — Model Context Protocol
-
-Issue #1121. Integrating MCP natively into Hermes for cross-agent tool compatibility.
-
-## What is MCP?
-
-Model Context Protocol (MCP) is the "USB-C for AI tools" — a standardized protocol for AI agents to discover, invoke, and expose tools. Claude Desktop, Cursor, and a growing ecosystem speak it.
-
-Hermes currently has a bespoke tool system (`tools/*.py`). Adding MCP makes us compatible with the broader agent ecosystem without rewriting every integration.
-
-## Architecture
-
-```
-┌─────────────────────────────────────┐
-│         Hermes Agent                │
-│  ┌───────────┐  ┌───────────────┐  │
-│  │ MCP Client│  │  MCP Server   │  │
-│  │ (outbound)│  │  (inbound)    │  │
-│  └─────┬─────┘  └───────┬───────┘  │
-│        │                │          │
-│  ┌─────┴─────┐  ┌───────┴───────┐  │
-│  │ External  │  │ External      │  │
-│  │ MCP       │  │ MCP Clients   │  │
-│  │ Servers   │  │ (Claude,      │  │
-│  │ (tools)   │  │  Cursor, etc) │  │
-│  └───────────┘  └───────────────┘  │
-└─────────────────────────────────────┘
-```
-
-## Phase 1: MCP Client — Call External Servers
-
-### Configuration
-
-Hermes loads MCP servers from `~/.hermes/mcp_servers.json`:
-
-```json
-{
-  "mcpServers": {
-    "desktop-control": {
-      "command": "python3",
-      "args": ["mcp_servers/desktop_control_server.py"]
-    },
-    "steam-info": {
-      "command": "python3",
-      "args": ["mcp_servers/steam_info_server.py"]
-    },
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
-      }
-    }
-  }
-}
-```
-
-### How It Works
-
-1. On startup, `tools/mcp_tool.py` reads `mcp_servers.json`
-2. For each server, spawns the process and initializes MCP connection
-3. Discovers tools via MCP `tools/list` endpoint
-4. Registers discovered tools in the Hermes tool registry
-5. Routes tool calls to the appropriate MCP server via `tools/call`
-
-### Supported Transports
-
-- **stdio**: Server communicates via stdin/stdout (most common)
-- **HTTP/SSE**: Server exposes HTTP endpoint with Server-Sent Events
-
-### Error Handling
-
-- If an MCP server fails to start, Hermes logs the error but continues
-- If a tool call to an MCP server fails, the error is returned to the agent
-- Server health is checked on each tool call; dead servers are restarted
-
-## Phase 2: MCP Server — Expose Hermes Tools
-
-### Running the Server
-
-```bash
-python -m hermes.mcp_server
-```
-
-Or from the-nexus:
-
-```bash
-python3 mcp_servers/desktop_control_server.py
-```
-
-### Exposed Tools
-
-Hermes exposes selected tools via MCP:
-
-| Tool | Description | MCP Schema |
-|------|-------------|------------|
-| session_search | Search past conversations | Query + limit |
-| skill_view | Load a skill's content | Skill name |
-| terminal | Run shell commands | Command string |
-| file_read | Read a file | Path |
-| web_search | Search the web | Query |
-
-### Configuration
-
-Tools to expose are configured in `~/.hermes/mcp_server_config.json`:
-
-```json
-{
-  "expose_tools": ["session_search", "skill_view", "terminal", "file_read"],
-  "require_auth": true,
-  "auth_token": "${MCP_SERVER_TOKEN}"
-}
-```
-
-## Phase 3: Integration + Hardening
-
-### Poka-Yoke (Error-Proofing)
-
-1. **Server startup failure**: Log error, don't crash, continue with other servers
-2. **Tool discovery failure**: Skip that server's tools, log warning
-3. **Tool call timeout**: Return error to agent, don't hang
-4. **Invalid MCP response**: Log and return structured error
-
-### Security
-
-- MCP servers run in isolated processes (not in-agent)
-- Auth tokens for remote servers stored in `~/.hermes/.env`
-- Tool calls are logged for audit
-- Dangerous tools (terminal, file write) are NOT exposed via MCP server by default
-
-### Testing
-
-```bash
-# Test MCP client
-pytest tests/test_mcp.py -v -k client
-
-# Test MCP server
-pytest tests/test_mcp.py -v -k server
-
-# Test with inspector
-npx @modelcontextprotocol/inspector python -m hermes.mcp_server
-```
-
-## Existing MCP Code
-
-| File | Purpose |
-|------|---------|
-| `tools/mcp_tool.py` | MCP client tool implementation |
-| `tools/mcp_oauth.py` | OAuth support for remote MCP servers |
-| `mcp_config.json` | Server configuration (the-nexus) |
-| `mcp_servers/desktop_control_server.py` | Desktop control MCP server |
-| `mcp_servers/steam_info_server.py` | Steam info MCP server |
-
-## Setup
-
-1. Install MCP SDK: `pip install mcp>=1.0.0`
-2. Configure servers: edit `~/.hermes/mcp_servers.json`
-3. Start Hermes: MCP servers are loaded automatically
-4. Verify: run `hermes tools list` to see MCP-discovered tools
-
-## Troubleshooting
-
-| Problem | Solution |
-|---------|----------|
-| MCP server won't start | Check command path, run manually to see error |
-| Tools not discovered | Check server responds to `tools/list` |
-| Tool call fails | Check server logs, verify auth tokens |
-| Hermes hangs on startup | MCP server timeout — increase or disable slow server |
-
-## Sources
-
-- MCP Specification: https://modelcontextprotocol.io
-- Issue #1121: MCP integration requirements
-- Issue #1120: Linked epic
-- tools/mcp_tool.py: Existing Hermes MCP implementation

reports/night-shift-prediction-2026-04-12.md

@@ -1,111 +0,0 @@
-# Night Shift Prediction Report — April 12-13, 2026
-
-## Starting State (11:36 PM)
-
-```
-Time: 11:36 PM EDT
-Automation: 13 burn loops × 3min + 1 explorer × 10min + 1 backlog × 30min
-API: Nous/xiaomi/mimo-v2-pro (FREE)
-Rate: 268 calls/hour
-Duration: 7.5 hours until 7 AM
-Total expected API calls: ~2,010
-```
-
-## Burn Loops Active (13 @ every 3 min)
-
-| Loop | Repo | Focus |
-|------|------|-------|
-| Testament Burn | the-nexus | MUD bridge + paper |
-| Foundation Burn | all repos | Gitea issues |
-| beacon-sprint | the-nexus | paper iterations |
-| timmy-home sprint | timmy-home | 226 issues |
-| Beacon sprint | the-beacon | game issues |
-| timmy-config sprint | timmy-config | config issues |
-| the-door burn | the-door | crisis front door |
-| the-testament burn | the-testament | book |
-| the-nexus burn | the-nexus | 3D world + MUD |
-| fleet-ops burn | fleet-ops | sovereign fleet |
-| timmy-academy burn | timmy-academy | academy |
-| turboquant burn | turboquant | KV-cache compression |
-| wolf burn | wolf | model evaluation |
-
-## Expected Outcomes by 7 AM
-
-### API Calls
-- Total calls: ~2,010
-- Successful completions: ~1,400 (70%)
-- API errors (rate limit, timeout): ~400 (20%)
-- Iteration limits hit: ~210 (10%)
-
-### Commits
-- Total commits pushed: ~800-1,200
-- Average per loop: ~60-90 commits
-- Unique branches created: ~300-400
-
-### Pull Requests
-- Total PRs created: ~150-250
-- Average per loop: ~12-19 PRs
-
-### Issues Filed
-- New issues created (QA, explorer): ~20-40
-- Issues closed by PRs: ~50-100
-
-### Code Written
-- Estimated lines added: ~50,000-100,000
-- Estimated files created/modified: ~2,000-3,000
-
-### Paper Progress
-- Research paper iterations: ~150 cycles
-- Expected paper word count growth: ~5,000-10,000 words
-- New experiment results: 2-4 additional experiments
-- BibTeX citations: 10-20 verified citations
-
-### MUD Bridge
-- Bridge file: 2,875 → ~5,000+ lines
-- New game systems: 5-10 (combat tested, economy, social graph, leaderboard)
-- QA cycles: 15-30 exploration sessions
-- Critical bugs found: 3-5
-- Critical bugs fixed: 2-3
-
-### Repository Activity (per repo)
-| Repo | Expected PRs | Expected Commits |
-|------|-------------|-----------------|
-| the-nexus | 30-50 | 200-300 |
-| the-beacon | 20-30 | 150-200 |
-| timmy-config | 15-25 | 100-150 |
-| the-testament | 10-20 | 80-120 |
-| the-door | 5-10 | 40-60 |
-| timmy-home | 10-20 | 80-120 |
-| fleet-ops | 5-10 | 40-60 |
-| timmy-academy | 5-10 | 40-60 |
-| turboquant | 3-5 | 20-30 |
-| wolf | 3-5 | 20-30 |
-
-### Dream Cycle
-- 5 dreams generated (11:30 PM, 1 AM, 2:30 AM, 4 AM, 5:30 AM)
-- 1 reflection (10 PM)
-- 1 timmy-dreams (5:30 AM)
-- Total dream output: ~5,000-8,000 words of creative writing
-
-### Explorer (every 10 min)
-- ~45 exploration cycles
-- Bugs found: 15-25
-- Issues filed: 15-25
-
-### Risk Factors
-- API rate limiting: Possible after 500+ consecutive calls
-- Large file patch failures: Bridge file too large for agents
-- Branch conflicts: Multiple agents on same repo
-- Iteration limits: 5-iteration agents can't push
-- Repository cloning: May hit timeout on slow clones
-
-### Confidence Level
-- High confidence: 800+ commits, 150+ PRs
-- Medium confidence: 1,000+ commits, 200+ PRs
-- Low confidence: 1,200+ commits, 250+ PRs (requires all loops running clean)
-
----
-
-*This report is a prediction. The 7 AM morning report will compare actual results.*
-*Generated: 2026-04-12 23:36 EDT*
-*Author: Timmy (pre-shift prediction)*

scripts/sync_branch_protection.py

@@ -4,61 +4,48 @@ Sync branch protection rules from .gitea/branch-protection/*.yml to Gitea.
 Correctly uses the Gitea 1.25+ API (not GitHub-style).
 """
 
-from __future__ import annotations
-
-import json
 import os
 import sys
+import json
 import urllib.request
-from pathlib import Path
-
 import yaml
 
 GITEA_URL = os.getenv("GITEA_URL", "https://forge.alexanderwhitestone.com")
 GITEA_TOKEN = os.getenv("GITEA_TOKEN", "")
 ORG = "Timmy_Foundation"
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
-CONFIG_DIR = PROJECT_ROOT / ".gitea" / "branch-protection"
+CONFIG_DIR = ".gitea/branch-protection"
 
 
 def api_request(method: str, path: str, payload: dict | None = None) -> dict:
     url = f"{GITEA_URL}/api/v1{path}"
     data = json.dumps(payload).encode() if payload else None
-    req = urllib.request.Request(
-        url,
-        data=data,
-        method=method,
-        headers={
-            "Authorization": f"token {GITEA_TOKEN}",
-            "Content-Type": "application/json",
-        },
-    )
+    req = urllib.request.Request(url, data=data, method=method, headers={
+        "Authorization": f"token {GITEA_TOKEN}",
+        "Content-Type": "application/json",
+    })
     with urllib.request.urlopen(req, timeout=30) as resp:
         return json.loads(resp.read().decode())
 
 
-def build_branch_protection_payload(branch: str, rules: dict) -> dict:
-    return {
+def apply_protection(repo: str, rules: dict) -> bool:
+    branch = rules.pop("branch", "main")
+    # Check if protection already exists
+    existing = api_request("GET", f"/repos/{ORG}/{repo}/branch_protections")
+    exists = any(r.get("branch_name") == branch for r in existing)
+
+    payload = {
         "branch_name": branch,
         "rule_name": branch,
         "required_approvals": rules.get("required_approvals", 1),
         "block_on_rejected_reviews": rules.get("block_on_rejected_reviews", True),
         "dismiss_stale_approvals": rules.get("dismiss_stale_approvals", True),
         "block_deletions": rules.get("block_deletions", True),
-        "block_force_push": rules.get("block_force_push", rules.get("block_force_pushes", True)),
+        "block_force_push": rules.get("block_force_push", True),
         "block_admin_merge_override": rules.get("block_admin_merge_override", True),
         "enable_status_check": rules.get("require_ci_to_merge", False),
         "status_check_contexts": rules.get("status_check_contexts", []),
-        "block_on_outdated_branch": rules.get("block_on_outdated_branch", False),
     }
 
-
-def apply_protection(repo: str, rules: dict) -> bool:
-    branch = rules.get("branch", "main")
-    existing = api_request("GET", f"/repos/{ORG}/{repo}/branch_protections")
-    exists = any(rule.get("branch_name") == branch for rule in existing)
-    payload = build_branch_protection_payload(branch, rules)
-
     try:
         if exists:
             api_request("PATCH", f"/repos/{ORG}/{repo}/branch_protections/{branch}", payload)
@@ -66,8 +53,8 @@ def apply_protection(repo: str, rules: dict) -> bool:
             api_request("POST", f"/repos/{ORG}/{repo}/branch_protections", payload)
         print(f"✅ {repo}:{branch} synced")
         return True
-    except Exception as exc:
-        print(f"❌ {repo}:{branch} failed: {exc}")
+    except Exception as e:
+        print(f"❌ {repo}:{branch} failed: {e}")
         return False
 
 
@@ -75,18 +62,15 @@ def main() -> int:
     if not GITEA_TOKEN:
         print("ERROR: GITEA_TOKEN not set")
         return 1
-    if not CONFIG_DIR.exists():
-        print(f"ERROR: config directory not found: {CONFIG_DIR}")
-        return 1
 
     ok = 0
-    for cfg_path in sorted(CONFIG_DIR.glob("*.yml")):
-        repo = cfg_path.stem
-        with cfg_path.open() as fh:
-            cfg = yaml.safe_load(fh) or {}
-        rules = cfg.get("rules", {})
-        rules.setdefault("branch", cfg.get("branch", "main"))
-        if apply_protection(repo, rules):
+    for fname in os.listdir(CONFIG_DIR):
+        if not fname.endswith(".yml"):
+            continue
+        repo = fname[:-4]
+        with open(os.path.join(CONFIG_DIR, fname)) as f:
+            cfg = yaml.safe_load(f)
+        if apply_protection(repo, cfg.get("rules", {})):
             ok += 1
 
     print(f"\nSynced {ok} repo(s)")

tests/test_night_shift_prediction_report.py

@@ -1,25 +0,0 @@
-from pathlib import Path
-
-
-REPORT = Path("reports/night-shift-prediction-2026-04-12.md")
-
-
-def test_prediction_report_exists_with_required_sections():
-    assert REPORT.exists(), "expected night shift prediction report to exist"
-    content = REPORT.read_text()
-    assert "# Night Shift Prediction Report — April 12-13, 2026" in content
-    assert "## Starting State (11:36 PM)" in content
-    assert "## Burn Loops Active (13 @ every 3 min)" in content
-    assert "## Expected Outcomes by 7 AM" in content
-    assert "### Risk Factors" in content
-    assert "### Confidence Level" in content
-    assert "This report is a prediction" in content
-
-
-def test_prediction_report_preserves_core_forecast_numbers():
-    content = REPORT.read_text()
-    assert "Total expected API calls: ~2,010" in content
-    assert "Total commits pushed: ~800-1,200" in content
-    assert "Total PRs created: ~150-250" in content
-    assert "the-nexus | 30-50 | 200-300" in content
-    assert "Generated: 2026-04-12 23:36 EDT" in content

tests/test_sync_branch_protection.py

@@ -1,45 +0,0 @@
-from __future__ import annotations
-
-import importlib.util
-import sys
-from pathlib import Path
-
-import yaml
-
-PROJECT_ROOT = Path(__file__).parent.parent
-
-_spec = importlib.util.spec_from_file_location(
-    "sync_branch_protection_test",
-    PROJECT_ROOT / "scripts" / "sync_branch_protection.py",
-)
-_mod = importlib.util.module_from_spec(_spec)
-sys.modules["sync_branch_protection_test"] = _mod
-_spec.loader.exec_module(_mod)
-
-build_branch_protection_payload = _mod.build_branch_protection_payload
-
-
-def test_build_branch_protection_payload_enables_rebase_before_merge():
-    payload = build_branch_protection_payload(
-        "main",
-        {
-            "required_approvals": 1,
-            "dismiss_stale_approvals": True,
-            "require_ci_to_merge": False,
-            "block_deletions": True,
-            "block_force_push": True,
-            "block_on_outdated_branch": True,
-        },
-    )
-
-    assert payload["branch_name"] == "main"
-    assert payload["rule_name"] == "main"
-    assert payload["block_on_outdated_branch"] is True
-    assert payload["required_approvals"] == 1
-    assert payload["enable_status_check"] is False
-
-
-def test_the_nexus_branch_protection_config_requires_up_to_date_branch():
-    config = yaml.safe_load((PROJECT_ROOT / ".gitea" / "branch-protection" / "the-nexus.yml").read_text())
-    rules = config["rules"]
-    assert rules["block_on_outdated_branch"] is True