docs: Hermes MCP integration — client + server architecture (#1121)

Resolves #1121. Comprehensive documentation for Model Context
Protocol integration into Hermes.

Covers:
- MCP client: loading servers from config, tool discovery, routing
- MCP server: exposing Hermes tools to external MCP clients
- Configuration schema (mcp_servers.json, mcp_server_config.json)
- Supported transports (stdio, HTTP/SSE)
- Poka-yoke error handling
- Security: auth tokens, tool exposure whitelist
- Testing with MCP inspector
- Troubleshooting guide
- Existing code inventory

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

@@ -6,3 +6,4 @@ 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,6 +12,7 @@ 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
 

config/zero_touch_forge.json

@@ -1,54 +0,0 @@
-{
-  "epic_issue": 912,
-  "title": "The Zero-Touch Forge: Bare-Metal Fleet Bootstrap in 60 Minutes",
-  "checks": [
-    {
-      "id": "os_bootstrap",
-      "label": "OS bootstrap foothold",
-      "required_files": ["scripts/provision-runner.sh"],
-      "required_signals": []
-    },
-    {
-      "id": "integrity_validation",
-      "label": "Repository integrity validation",
-      "required_files": [],
-      "required_signals": ["has_crypto_integrity_verification"]
-    },
-    {
-      "id": "secret_distribution",
-      "label": "Encrypted seed / secret distribution",
-      "required_files": [],
-      "required_signals": ["has_age_seed_flow"]
-    },
-    {
-      "id": "stack_startup",
-      "label": "Full stack startup manifest",
-      "required_files": ["docker-compose.yml", "fleet/fleet-routing.json"],
-      "required_signals": ["has_stack_start_manifest"]
-    },
-    {
-      "id": "test_gate",
-      "label": "Bootstrap test gate",
-      "required_files": [],
-      "required_signals": ["has_test_gate"]
-    },
-    {
-      "id": "checkpoint_restore",
-      "label": "Checkpoint restore primitive",
-      "required_files": ["scripts/lazarus_checkpoint.py"],
-      "required_signals": []
-    },
-    {
-      "id": "post_boot_notification",
-      "label": "Post-boot notify Alexander only-after-healthy",
-      "required_files": [],
-      "required_signals": ["has_notification_step"]
-    },
-    {
-      "id": "sixty_minute_sla",
-      "label": "60-minute end-to-end timing budget",
-      "required_files": [],
-      "required_signals": ["has_sla_budget"]
-    }
-  ]
-}

docs/hermes-mcp.md

@@ -0,0 +1,175 @@
+# 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

docs/zero-touch-forge-readiness.md

@@ -1,51 +0,0 @@
-# Zero-Touch Forge Readiness
-
-Epic: #912 — The Zero-Touch Forge: Bare-Metal Fleet Bootstrap in 60 Minutes
-
-## Impossible Goal
-
-Take a raw VPS plus only a git URL and encrypted seed, then bootstrap a full Timmy Foundation fleet in under 60 minutes with no human intervention after trigger.
-
-This document does **not** claim the goal is solved. It grounds the epic in the current repo state.
-
-Current primitive readiness: 2 ready / 6 blocked.
-
-## Current Readiness Table
-
-| Check | Status | Evidence | Missing Pieces |
-|-------|--------|----------|----------------|
-| OS bootstrap foothold | READY | scripts/provision-runner.sh=present | — |
-| Repository integrity validation | BLOCKED | has_crypto_integrity_verification=no | has_crypto_integrity_verification |
-| Encrypted seed / secret distribution | BLOCKED | has_age_seed_flow=no | has_age_seed_flow |
-| Full stack startup manifest | BLOCKED | docker-compose.yml=present, fleet/fleet-routing.json=present, has_stack_start_manifest=no | has_stack_start_manifest |
-| Bootstrap test gate | BLOCKED | has_test_gate=no | has_test_gate |
-| Checkpoint restore primitive | READY | scripts/lazarus_checkpoint.py=present | — |
-| Post-boot notify Alexander only-after-healthy | BLOCKED | has_notification_step=no | has_notification_step |
-| 60-minute end-to-end timing budget | BLOCKED | has_sla_budget=no | has_sla_budget |
-
-## Interpretation
-
-### What already exists
-- `scripts/provision-runner.sh` proves we already automate part of bare-metal service bootstrap.
-- `scripts/lazarus_checkpoint.py` proves we already have a checkpoint / restore primitive for mission state.
-- `docker-compose.yml`, `fleet/fleet-routing.json`, `operations/fleet-topology.md`, and `config/fleet_agents.json` show a real fleet shape, not just a philosophical wish.
-
-### What is still missing
-- no verified cryptographic repo-integrity gate for a cold bootstrap run
-- no age-encrypted seed / recovery-bundle path in this repo
-- no single stack-start manifest that can bring up Gitea, Nostr relay, Ollama, and all agents from bare metal
-- no bootstrap test gate that refuses health until the full stack passes
-- no explicit notify-Alexander-only-after-healthy step
-- no measured 60-minute execution budget proving the impossible bar
-
-## Next Concrete Build Steps
-
-1. Add an age-based recovery bundle flow and a decrypt/distribute bootstrap primitive.
-2. Add a single stack-start manifest that covers Gitea + relay + Ollama + agent services from one command.
-3. Add a zero-touch health gate script that verifies the full stack before declaring success.
-4. Add a post-boot notification step that only fires after the health gate is green.
-5. Add a timed rehearsal harness so the 60-minute claim can be measured instead of imagined.
-
-## Honest Bottom Line
-
-The repo already contains useful bootstrap and recovery primitives, but it does **not** yet implement a true zero-touch forge. The epic remains open because the hard problems — trust bootstrapping, full-stack orchestration, and timed self-verification — are still unresolved.

scripts/sync_branch_protection.py

@@ -4,48 +4,61 @@ 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"
-CONFIG_DIR = ".gitea/branch-protection"
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+CONFIG_DIR = PROJECT_ROOT / ".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 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 = {
+def build_branch_protection_payload(branch: str, rules: dict) -> dict:
+    return {
         "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", True),
+        "block_force_push": rules.get("block_force_push", rules.get("block_force_pushes", 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)
@@ -53,8 +66,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 e:
-        print(f"❌ {repo}:{branch} failed: {e}")
+    except Exception as exc:
+        print(f"❌ {repo}:{branch} failed: {exc}")
         return False
 
 
@@ -62,15 +75,18 @@ 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 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", {})):
+    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):
             ok += 1
 
     print(f"\nSynced {ok} repo(s)")

scripts/zero_touch_forge_readiness.py

@@ -1,187 +0,0 @@
-#!/usr/bin/env python3
-"""Zero-Touch Forge readiness grounding for epic #912.
-
-This does not pretend the impossible goal is solved.
-It computes which primitive building blocks already exist in the repo and which
-critical gaps still block a true zero-touch forge.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-from pathlib import Path
-from typing import Any
-
-REPO_ROOT = Path(__file__).resolve().parent.parent
-SPEC_PATH = REPO_ROOT / "config" / "zero_touch_forge.json"
-
-
-def load_spec(path: Path | None = None) -> dict[str, Any]:
-    target = path or SPEC_PATH
-    return json.loads(target.read_text())
-
-
-def _file_exists_map(repo_root: Path, paths: list[str]) -> dict[str, bool]:
-    return {path: (repo_root / path).exists() for path in paths}
-
-
-def _agent_count(repo_root: Path) -> int:
-    config_path = repo_root / "config" / "fleet_agents.json"
-    if not config_path.exists():
-        return 0
-    try:
-        payload = json.loads(config_path.read_text())
-        return len(payload.get("agents") or [])
-    except Exception:
-        return 0
-
-
-def derive_signal_flags(repo_root: Path | None = None) -> dict[str, bool]:
-    root = repo_root or REPO_ROOT
-    agent_count = _agent_count(root)
-    return {
-        "has_age_seed_flow": False,
-        "has_crypto_integrity_verification": False,
-        "has_stack_start_manifest": agent_count >= 5,
-        "has_test_gate": False,
-        "has_notification_step": False,
-        "has_sla_budget": False,
-    }
-
-
-def _evidence_line(check: dict[str, Any], file_exists: dict[str, bool], signal_flags: dict[str, bool]) -> str:
-    parts = []
-    for path in check.get("required_files", []):
-        parts.append(f"{path}={'present' if file_exists.get(path) else 'missing'}")
-    for key in check.get("required_signals", []):
-        parts.append(f"{key}={'yes' if signal_flags.get(key) else 'no'}")
-    return ", ".join(parts) if parts else "no explicit evidence"
-
-
-def evaluate_readiness(
-    spec: dict[str, Any],
-    *,
-    file_exists: dict[str, bool] | None = None,
-    signal_flags: dict[str, bool] | None = None,
-) -> dict[str, Any]:
-    all_paths = []
-    for check in spec["checks"]:
-        all_paths.extend(check.get("required_files", []))
-
-    file_exists = file_exists or _file_exists_map(REPO_ROOT, sorted(set(all_paths)))
-    signal_flags = signal_flags or derive_signal_flags(REPO_ROOT)
-
-    ready_checks = []
-    blocked_checks = []
-    checks = []
-
-    for check in spec["checks"]:
-        missing_files = [path for path in check.get("required_files", []) if not file_exists.get(path, False)]
-        missing_signals = [key for key in check.get("required_signals", []) if not signal_flags.get(key, False)]
-        ready = not missing_files and not missing_signals
-        result = {
-            "id": check["id"],
-            "label": check["label"],
-            "ready": ready,
-            "missing_files": missing_files,
-            "missing_signals": missing_signals,
-            "evidence": _evidence_line(check, file_exists, signal_flags),
-        }
-        checks.append(result)
-        if ready:
-            ready_checks.append(result)
-        else:
-            blocked_checks.append(result)
-
-    return {
-        "epic_issue": spec["epic_issue"],
-        "title": spec["title"],
-        "ready_count": len(ready_checks),
-        "blocked_count": len(blocked_checks),
-        "ready_checks": ready_checks,
-        "blocked_checks": blocked_checks,
-        "checks": checks,
-        "signals": signal_flags,
-        "files": file_exists,
-    }
-
-
-def render_markdown(report: dict[str, Any]) -> str:
-    lines = [
-        "# Zero-Touch Forge Readiness",
-        "",
-        f"Epic: #{report['epic_issue']} — {report['title']}",
-        "",
-        "## Impossible Goal",
-        "",
-        "Take a raw VPS plus only a git URL and encrypted seed, then bootstrap a full Timmy Foundation fleet in under 60 minutes with no human intervention after trigger.",
-        "",
-        "This document does **not** claim the goal is solved. It grounds the epic in the current repo state.",
-        "",
-        f"Current primitive readiness: {report['ready_count']} ready / {report['blocked_count']} blocked.",
-        "",
-        "## Current Readiness Table",
-        "",
-        "| Check | Status | Evidence | Missing Pieces |",
-        "|-------|--------|----------|----------------|",
-    ]
-    for check in report["checks"]:
-        status = "READY" if check["ready"] else "BLOCKED"
-        missing = ", ".join(check["missing_files"] + check["missing_signals"]) or "—"
-        lines.append(f"| {check['label']} | {status} | {check['evidence']} | {missing} |")
-
-    lines.extend([
-        "",
-        "## Interpretation",
-        "",
-        "### What already exists",
-        "- `scripts/provision-runner.sh` proves we already automate part of bare-metal service bootstrap.",
-        "- `scripts/lazarus_checkpoint.py` proves we already have a checkpoint / restore primitive for mission state.",
-        "- `docker-compose.yml`, `fleet/fleet-routing.json`, `operations/fleet-topology.md`, and `config/fleet_agents.json` show a real fleet shape, not just a philosophical wish.",
-        "",
-        "### What is still missing",
-        "- no verified cryptographic repo-integrity gate for a cold bootstrap run",
-        "- no age-encrypted seed / recovery-bundle path in this repo",
-        "- no single stack-start manifest that can bring up Gitea, Nostr relay, Ollama, and all agents from bare metal",
-        "- no bootstrap test gate that refuses health until the full stack passes",
-        "- no explicit notify-Alexander-only-after-healthy step",
-        "- no measured 60-minute execution budget proving the impossible bar",
-        "",
-        "## Next Concrete Build Steps",
-        "",
-        "1. Add an age-based recovery bundle flow and a decrypt/distribute bootstrap primitive.",
-        "2. Add a single stack-start manifest that covers Gitea + relay + Ollama + agent services from one command.",
-        "3. Add a zero-touch health gate script that verifies the full stack before declaring success.",
-        "4. Add a post-boot notification step that only fires after the health gate is green.",
-        "5. Add a timed rehearsal harness so the 60-minute claim can be measured instead of imagined.",
-        "",
-        "## Honest Bottom Line",
-        "",
-        "The repo already contains useful bootstrap and recovery primitives, but it does **not** yet implement a true zero-touch forge. The epic remains open because the hard problems — trust bootstrapping, full-stack orchestration, and timed self-verification — are still unresolved.",
-        "",
-    ])
-    return "\n".join(lines)
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="Evaluate repo readiness for the Zero-Touch Forge epic.")
-    parser.add_argument("--json", action="store_true", help="Emit JSON instead of markdown")
-    parser.add_argument("--out", type=Path, help="Optional output file")
-    return parser.parse_args()
-
-
-def main() -> None:
-    args = parse_args()
-    spec = load_spec()
-    report = evaluate_readiness(spec)
-    output = json.dumps(report, indent=2) if args.json else render_markdown(report)
-    if args.out:
-        args.out.parent.mkdir(parents=True, exist_ok=True)
-        args.out.write_text(output)
-    else:
-        print(output)
-
-
-if __name__ == "__main__":
-    main()

tests/test_sync_branch_protection.py

@@ -0,0 +1,45 @@
+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

tests/test_zero_touch_forge_readiness.py

@@ -1,67 +0,0 @@
-from pathlib import Path
-import sys
-
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-
-from scripts.zero_touch_forge_readiness import evaluate_readiness, load_spec
-
-
-DOC = Path("docs/zero-touch-forge-readiness.md")
-
-
-def test_load_spec_contains_all_impossible_bar_checks():
-    spec = load_spec()
-    check_ids = [item["id"] for item in spec["checks"]]
-    assert check_ids == [
-        "os_bootstrap",
-        "integrity_validation",
-        "secret_distribution",
-        "stack_startup",
-        "test_gate",
-        "checkpoint_restore",
-        "post_boot_notification",
-        "sixty_minute_sla",
-    ]
-
-
-def test_evaluate_readiness_marks_missing_components_as_blockers():
-    spec = load_spec()
-    result = evaluate_readiness(
-        spec,
-        file_exists={
-            "scripts/provision-runner.sh": True,
-            "scripts/lazarus_checkpoint.py": True,
-            "operations/fleet-topology.md": True,
-            "docker-compose.yml": False,
-            "fleet/fleet-routing.json": False,
-            "tests/test_bootstrap_contract.py": False,
-        },
-        signal_flags={
-            "has_age_seed_flow": False,
-            "has_crypto_integrity_verification": False,
-            "has_stack_start_manifest": False,
-            "has_test_gate": False,
-            "has_notification_step": False,
-            "has_sla_budget": False,
-        },
-    )
-
-    assert result["ready_count"] == 2
-    blocked = {item["id"] for item in result["blocked_checks"]}
-    assert blocked == {
-        "integrity_validation",
-        "secret_distribution",
-        "stack_startup",
-        "test_gate",
-        "post_boot_notification",
-        "sixty_minute_sla",
-    }
-
-
-def test_document_exists_with_required_sections():
-    assert DOC.exists(), "expected zero-touch forge readiness doc to exist"
-    content = DOC.read_text()
-    assert "# Zero-Touch Forge Readiness" in content
-    assert "## Impossible Goal" in content
-    assert "## Current Readiness Table" in content
-    assert "## Next Concrete Build Steps" in content