docs(broker): expand PRIVATE_SERVER.md with versatility guide and create implementation_plan.md

tests/test_deploy_freshness.py

@@ -10,8 +10,10 @@ pre-loop skill set, so it strands those same assets plus the whole
 """
 import json
 import os
+import re
 import shutil
 import subprocess
+import sys
 import tempfile
 
 import pytest
@@ -262,3 +264,91 @@ def test_d10_customization_survives_repeated_refresh(src_and_target):
         assert "Local modification detected" in res.stderr, (
             "refresh #%d overwrote nothing but also reported nothing; the "
             "user gets no signal that their edit is diverging" % n)
+
+
+# --------------------------------------------------------------------------
+# D-11 — (G-D1) PRIVATE_SERVER.md must only document MQTT_* environment
+#        variables that broker_config_from_env() actually parses.
+# --------------------------------------------------------------------------
+def test_d11_private_server_env_names_valid():
+    sys.path.insert(0, os.path.join(REPO_ROOT, ".agents", "skills", "multi-agent-mux-delegate-job", "scripts"))
+    import mqtt_common
+
+    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    assert os.path.exists(doc_path), "PRIVATE_SERVER.md missing"
+    with open(doc_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # Extract all code blocks
+    code_blocks = re.findall(r"```(?:bash|conf|yaml|)(.*?)```", content, re.DOTALL)
+    assert code_blocks, "No code blocks found in PRIVATE_SERVER.md"
+
+    # Known recognized MQTT env vars from broker_config_from_env()
+    recognized = {
+        "MQTT_BROKER", "MQTT_PORT", "MQTT_TLS", "MQTT_USERNAME", "MQTT_PASSWORD",
+        "MQTT_CLIENT_ID_PREFIX", "MQTT_CA_CERTS", "MQTT_CERTFILE", "MQTT_KEYFILE",
+        "MQTT_KEEPALIVE", "MAM_MQTT_HOST"  # checked for exclusion
+    }
+    valid_mqtt_vars = {
+        "MQTT_BROKER", "MQTT_PORT", "MQTT_TLS", "MQTT_USERNAME", "MQTT_PASSWORD",
+        "MQTT_CLIENT_ID_PREFIX", "MQTT_CA_CERTS", "MQTT_CERTFILE", "MQTT_KEYFILE",
+        "MQTT_KEEPALIVE"
+    }
+
+    for block in code_blocks:
+        found_vars = set(re.findall(r"\b(MQTT_[A-Z0-9_]+)\b", block))
+        invalid = found_vars - valid_mqtt_vars
+        assert not invalid, f"Invalid or unrecognized MQTT variables in PRIVATE_SERVER.md code blocks: {invalid}"
+
+
+# --------------------------------------------------------------------------
+# D-12 — (G-D2) PRIVATE_SERVER.md must not contain invalid MAM_MQTT_* in
+#        active configuration code blocks.
+# --------------------------------------------------------------------------
+def test_d12_private_server_no_mam_mqtt_in_code_fences():
+    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    with open(doc_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    code_blocks = re.findall(r"```(?:bash|conf|yaml|)(.*?)```", content, re.DOTALL)
+    for i, block in enumerate(code_blocks):
+        assert "MAM_MQTT_" not in block, (
+            f"Code block #{i+1} in PRIVATE_SERVER.md contains deprecated/invalid 'MAM_MQTT_*' prefix"
+        )
+
+
+# --------------------------------------------------------------------------
+# D-13 — (G-D3) nats-server launch instructions in PRIVATE_SERVER.md must
+#        use valid config blocks (mqtt {) and not HTTP port flag (-m 1883).
+# --------------------------------------------------------------------------
+def test_d13_private_server_nats_config_valid():
+    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    with open(doc_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    assert "-m 1883" not in content, (
+        "PRIVATE_SERVER.md incorrectly contains '-m 1883' (which sets HTTP port, not MQTT port)"
+    )
+    assert "mqtt {" in content, "PRIVATE_SERVER.md must document 'mqtt {' configuration block for nats-server"
+    assert "-c " in content or "-c /" in content, "PRIVATE_SERVER.md must document '-c <config>' for nats-server"
+
+
+# --------------------------------------------------------------------------
+# D-14 — (G-D4) Verification commands in PRIVATE_SERVER.md must use valid
+#        CLI flags matching the actual scripts' argparse parsers.
+# --------------------------------------------------------------------------
+def test_d14_private_server_cli_args_valid():
+    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    with open(doc_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # Extract all command invocations for registry.py and publish_event.py
+    code_blocks = "\n".join(re.findall(r"```(?:bash|)(.*?)```", content, re.DOTALL))
+
+    # Assert --job-id is not used with register command (register takes --prompt, not --job-id)
+    # and registry.py commands have correct flag formatting
+    assert "register --job-id" not in code_blocks, (
+        "PRIVATE_SERVER.md contains invalid 'register --job-id' (registry.py register auto-assigns ID and takes no --job-id flag)"
+    )
+    assert "status --job " in code_blocks, "PRIVATE_SERVER.md must include cleanup step with status --job"
+