Codex Protocol Guardian

Die Positionierung ist festgelegt als „lokaler MCP-Governance-Kern + Standard-Delivery-Adapter“. Der Regelkreis ist: Vertrag -> Entwicklungsvalidierung -> Build/Release -> Installation/Einbindung -> MCP-Smoke-Test -> Diagnose -> Upgrade/Rollback. Der Kern validiert ausschließlich lokale Struktur, Protokoll und Archivierung; er zieht keine externen Plattformdaten heran, betreibt keine zentrale Konsole und orchestriert keine Agenten.

MCP-Governance-Paket, das Codex-Entwicklungsaufgaben an ein Anforderungspaket, ein aktives Kandidaten-Subjekt, eine ausführbare Spezifikation, unabhängige Gates und ein rückverfolgbares Review-Paket koppelt. Dieses Paket startet keine Sub-Agenten, exportiert keine Rollen-Prompts, führt keine Tasks aus und schreibt keinen Laufzeitzustand. Es validiert Governance-Nachweise und kann unveränderliche Befundarchive anhängen; es genehmigt niemals eigene Arbeit. Legacy-Rollen-, Dispatch- und Sub-Agent-Module sind nicht Teil der Paketoberfläche.

Struktur

project-root
|-- pyproject.toml
|-- README.md
|-- src\agent_team_mcp
|   |-- server.py
|   |-- tools.py
|   |-- protocol_guardian.py
|   `-- data
|       |-- protocol_guardian.json
|       `-- protocols
|           |-- protocol-driven-development.md
|           |-- module-interface-boundary.md
|           |-- code-size-governance.md
|           |-- acceptance-alignment.md
|           `-- traceability-checkpoint.md
`-- tests

Der MCP-Server gibt sich als codex-protocol-guardian aus.

Related MCP server: workflow-compliance-enforcer

Grenze der Oberfläche

Das Governance-Paket hat keine erforderliche oder auffindbare Skill-Oberfläche. Legacy-Rollen-, Prompt-, Dispatch- und Sub-Agent-Module wurden aus dem Paket entfernt. Da Frontend-, Externes-Tool- und Webnovel-Material optionale Domäneninhalte ist, werden diese Inhalte nicht in den Standard-Governance-Kontext geladen. Neuer Code muss die unten aufgeführten öffentlichen Governance-Funktionen verwenden.

Der Quellbaum verändert sich historisch vor, damit "Skill"-Dokumente weiterhin verfügbar sind, aber der Paket-Build und der Ressourcen-Lader enthalten nur Governance-Protokolle und die ausführbare Vorlage. Legacy-Skill-, Rollen- und Prompt-Daten sind keine ladbare Paket-Ressource.

Werkzeuge

• list_protocols: Gibt das Protokoll-Manifest, die erforderlichen Artefakte, Workflow-Phasen, harte Gates und die öffentliche Tool-Liste zurück.

• export_protocol_context: Gibt den vollständigen Protokollkontext, geladene Protokollkörper, Hashes, erforderliche Artefakte, Workflow, harte Gates und zusätzliche Anweisungen zurück.

• export_execution_plan_template: Gibt Startvorlagen für die erforderlichen .codex/protocol/*-Artefakte zurück, einschließlich der Vorlage für die ausführbare Spezifikation und der erforderlichen Modulgrenzen- und Kommunikationskapazitätserklärung vor der Entwicklung.

• audit_alignment_packet: Gibt an, ob ein endgültiges Paket Anforderungen, Plan, Abnahmeprotokoll, Rückverfolgbarkeit, geänderte Dateien, Validierungsfinger, ein unabhängiges Review-Signal, Kandidatenautorität, Zerlegung, Lösungsentwurf, Scope und Konvergenz-Gate-Nachweis enthält. Fehlende Governance-Nachweise blockieren den Ablauf; Es gibt keinen Legacy-Bypass.

• validate_candidate_manifest: Validiert das Manifest des einzelnen aktiven Kandidaten.

• transition_candidate: Wendet ein einzel-gültiges Lebenszyklusereignis ohne Mutation an.

• classify_review_finding: Entscheidet, ob ein Befund im Kandidaten bleibt oder einen Nachfolger erfordert.

• validate_requirements_decomposition: Validiert die eingefrorenen atomaren Anforderungen, bevor der Entwurf beginnt.

• validate_solution_design: Validiert die Alternativen, exakte Anforderungsbindung, Module Boundary und Summe.

• validate_change_scope: Lehnt Änderungen außerhalb der Design-Zulassstete ab.

• validate_finding_ledger: Validiert Befundfingerabdrücke, Schließung-Nachweise, Nachfolgerentwicklung und Recurrenbsblockierung.

• validate_finding_archive: Validiert das persistierte Befundarchiv und die Eltern-Kandidaten-Kette.

• read_finding_archive: lädt und überprüft einen rela-tiven Archivpfand unter der konfigurierten Governance-Archiv-Wurzel.

• append_finding_archive: Hängt eine Governance-Aufzeichnung mit voraussichtlichen Digest-Konflikt und atomarer Ersetzung an; sie unterbindet absolute Pfade und ..-Traversierung.

Erforderliche Artefakte

Codex sollte diese Dateien während einer Entwicklungsaufgabe im Zielprojekt speichern:

.codex/protocol/current/requirements.md
.codex/protocol/current/specification.md
.codex/protocol/current/execution_plan.md
.codex/protocol/current/acceptance_protocol.md
.codex/protocol/current/traceability.md
.codex/protocol/current/decision_log.md

Das Paket schreibt keinen Laufzeitzustand. Seine einzige Schreiboperation ist das explizite append_finding_archive-Governance-Artefakt, das einen erwarteten Digest und atomares Ersetzen verwendet, um "lost updates" zu verhindern. Das Archiv-Wurzelverzeichnis wird explizit über GOVERNANCE_ROOT oder von AGENT_TEAM_MCP_ARCHIVE_ROOT respektive aus AGENT_TEAM_MCP_GOVERNANCE_ROOT und AGENT_TEAM_MCP_PROJECT_NAMESPACE abgeleitet. Ohne diese Einstellungen wird es unter .codex/protocol/current/archives installiert. Alle unterstützte Hosts sollten dieselbe Governance-Wurzel und denselben Namespace verwenden.

Optionale Vision-Unterstützung

Das Projekt zusätzliches agent-vision-toolkit als optionalem Skill unter src/agent_team_mcp/data/optional_scripts/agent-vision-toolkit liegen. Rufen Sie die Operation vision_assistance mit der Modell-Fähigkeit im Parameter auf:

• vision_capable=true liefert mode=skip und setzt den Skill nicht frei.

• vision_capable=false liefert den vision-skills-Eintrag, die Tool-Zuordnung, Trigger und den sichtbaren Effekt für ein reines Textmodell zurück.

Dies ist reiner Vertrag. Es installiert keine Abhängigkeiten, ruft keine Vision-API auf, liest keine Zugangsdaten, proxyfährt keinen Modellverkehr und ändert keine Host-Konfiguration. Der integrierte Skill benötigt bei der Nutzung weiterhin eine extern konfigurierte Vision-API. Die Standard-OpenAI-Kompatiblen Kandidaten sind GLM-4.6V-Flash und GLM-4.1V-Thinking-Flash; Sie konfigurieren sie über VISION_API_KEY. In der Projektumgebungs, und der Schlüssel sollte nicht zu ausschlechtlich verwalten sein. VISION_MODUL wählt den primären Kandidaten aus, VISION_MODELS liefer die mit Komma getrennte Fallback-Liste.

Kopieren Sie für die lokale Projektumgebung die Projekte von src/agent_team_mcp/data/optional_skills/agent-vision-toolkit/.env.example in die Root als .env und fügen Sie die Vision_API_KEY hinzu. Die Root-Datei .env` wird vom Sourcecontrol ignoriert und automatisch durch den Skill geladen.

Options auf externer Basis für das "External OCR Module Adapter" (V1)

Der V1-Modell-Pool und der Intent-Router liegen außerhalb des Governance-Checkouts. Legen Sie OCR_MODULE_ROOT auf das lokale Verzeichnis dieses Moduls, wenn Sie bei die optionale vision_assist-Adapteroperation verwenden. Die Akzeptiert eine JSON-Anfrage mit einem erforderlichen Boolean vision_capable; native Aufrufer mit vision capability entfernen sich in skip zurück, während reine Textaufrufer an die externe Adapter-Root weitergereicht werden.

Das externe Modul besitzt statischen GLM-ModellKandidaten, Intent-Regeln, Provider-Aufrufe und ergebnisbereiche. Seine lokale .env enthält die Provider-Konfiguration. V1 fügt bewusst keine Rechte, Mandanten, Warteschlangen, Service Discovery, Verteilung von Last, Cloud-Orchestrierung oder Management-UI hinzu.

list_protocols macht die Paket-/Protokoll-Version, Kompatibilitätsrichtlinie, Deprecation-Richtlinie, unterstützte Hosts, stdio Transport und Archiv-Root-Strategie offen. Die Version wird einmal aus version.py ausgelesen. Aktuelle Versionen akzeptieren nur schema_version == 1; Migration wurde bewusst nicht implementiert, bis es einen versionierten Leser und einen Migrations-Befehl gibt.

Lokale Laufzeit-Prüfung

Installerst dieses Checkout in die Projektumgebung, bevor MCP startet:

python -m pip install --editable .
python scripts\verify_runtime_source.py
python -m pip install --requirement requirements-lock.txt

Nach der Neuinstallation des Pakets neu, startet den MCP-Prozess neu oder melden sie sich erneuter MCP-Prozess unter neu an. Damit verwendete Paketmanifeste und -Protokoll ressourcen kommen aus diesem Checkout.

Workflows

1. Bevor Sie Änderungen vornehmen, laden Sie export_protocol_context.

2. Erstellen oder aktualisieren Sie die erforderlichen Protokoll-Artefakte.

3. Vergeben Sie stabile Anforderungs-IDs (R1, R2, ...) und Akzeptanz-IDs (A1, A2, ...).

4. Frieren Sie den Anforderungs-Zerlegeungsprozess ein, bevor Security Entwurf geschrieben wird, also jedes Element ein beobachtbares Ergebnis, Grenzen, Nicht-Ziele, für gute und eine Akzeptanz-Nummer.

5. Validieren Sie eine Lösungs-Design gegen die eingefrorene Zerlegung. Das Design muss Alternativen auswählen, public interfaces, Verantwortlichkeiten, verbotene Duties, allowed files, und scope digest entfklären.

6. Bauen Sie specifikation.md aus dem aus hermaschbar ausführbaren Spezifikationstandard. Jede Regel wird gegen eine Produktions-Input-Prognose getestet.

7. Halten Sie ein aktives Kandidatenthema. Harchend abgelehnte und ersetzte Kandidaten werden zwangsweise mit replaces und superseded_by verknüpft.

8. Jede Material, Design oder Scope-Mängel führt einen Nachfolger; kleinere Mängel können im aktuellen Kandidaten behoben werden.

9. Jedes Paket muss einen Befundkette enthalten. Wiederholte Fingerprints, die von Nachfolgekette erben, blockieren die Freigabe des Freigebens, bis Nachweis über Grund entstanden ist.

10. Fünfen Sie über unabhängige Gates für Scope-Drift, Reviews, Unabhängigkeit von Reviews, CI-Vollständigkeit, Traceforward-Scale, Artsharing-Artifact-Stifts, Laufzeit-Akzeptanz-Grenze. Für den vollständigen CebeicCI-Zyklus ebenfalls fest: Zweigschutz, Review-Schutz, Codeowners-Approving, Entfernen von veralteten Stale-Reviews und Merge-Block-Queue-Richtlinie.

11. Tragen Sie Prozessmetriken getrennt ein: Zeit im Status, Reviews-Iterationen, superseded-Anzahl, Rejectionsrate, offene Blocker, Lead-Time, Change-Fail-Rate, Dauer. Setzen.

12. In jedem Fall, bevor jedes Code-Diff ausgeführt wird, deklarieren Sie Phase, Requirement-IDs, Are-IDs, erlaubte Dateien, und erwartete Nachweise.

13. Sie definieren vor dem Abrufen von Dateien für eine Feature-Komponente gilt: einzelne öffentliche Interface, interne HTTP-Trennung, Dependenz Directions, erwartete Traffic, ordering/idempotency, Backpressure, et al. Ein einzelnes publikier Netzinterface darf nicht alle Arbeit serialisieren.

14. Teilen Sie, internen Dateien nach Verantwortung und Änderungs-Grund auf. Verwenden Sie keine stehende feste Anzahl von Zeilenzahlen, schreiben Sie nicht all diese Facade, Logik, Speicher und externen Kommunication. Alternative einzelnverantwortliche, keine

15. Verfolgen Sie nach jedem Edit die Werte gegen Requirements, specification, execution-plan, acceptance-protocol, traceability, und non-goals.

16. Erfassen Sie Edits und Planänderungen in decision_log.md.

17. Run Validierung und prüfungs-Paket.

18. Eigene Test gelten als Testat. Der finale Claim besteht aus.

Unterstützungs-Matrix

Die erste Version unterstützt nur Stdio. Cursor, VS Code, Windsurf, Gemini, Remote-HTTP, OAuth, Multitenant-Gateways und zentral Steuerung sind separate Adapter oder Projekte.

Claude Code-Projekt-Adapter (Optionale Fallback)

Dieses Check-Out enthält eine CCS-gezielte Claire-Config in .mcp.json. Es ist bewusst unterschiedlich von der Codex-Konfiguration und zeigt scripts/claude_code_mcp_server.py: startet das Verzeichnis src, bevor der bestehende FastMCP-Server läuft.

Installieren Sie die MCP-Abhängigkeit in die Python-Umgebung für Claude Code und prüfen Sie den Projekt-Server:

python -m pip install -e ".[mcp]"
claude mcp list
claude mcp get agent-team-governance

Dieser Project-Adapter wird nur für isolatus mit Tests und bindliche Projekt-Override genutzt. Er ist keine globale Registrierung. Er expowert nur bestehende Governance-Werkzeuge; er Spawnt keine Agents, routed keine Aufgaben und tut keine Codex MCP- process.

Claude Desktop-Adapter global

For normale Claude DesktopDeployment, installieren und registrieren einer benutzerspezifische Kopie, die auszusam. ausui Tools. Das Skript um das Packet in ein dedikierte Benutzer-venv installiert und Kümmert sich um agent-team-governance-desktop ein global in Claude-Config eingefügt, ohne die andere Server entfert. Erkennt auch Den Store-Origin "__3_Storage". %LOCALAPPDATA%` erkannt und schaltet auf den alten Pfad „%APPDATA%\Claude\claude_desktop_config.json“ zugleich, dabei:

cd <project-root>
.\scripts\register_claude_desktop.ps1

Neustarten Sie Claude Desktop nach Registrier. Dieser global-Eintrag ist unabhängig von Checkout-Umgebung. Das Skript schreibt ein .bak-BackUp, ersetzt config über time. Bei einem MCP-Smoke fits das Auto, it casts back.

Deinstallieren Sie mit scripts\unregister_claude_desktop.ps1.

Desktop startet diesen MCP-Server auf dem Windows-Host, während die Agent-Shell in einer pro Sitzung erstellten Linux-VM läuft. Die Registrierung setzt daher AGENT_TEAM_MCP_GOVERNANCE_ROOT und AGENT_TEAM_MCP_PROJECT_NAMESPACE, anstatt sich auf das cwd des Host-Prozesses zu verlassen. Archivdateien werden unter <governance_root>\<namespace>\archives geschrieben.

Um ein bestimmtes Desktop-Profil anzusprechen, übergeben Sie -ConfigPath explizit. Dies ist nützlich, wenn die App mit einem migrierten Benutzerdatenverzeichnis ausgeführt wird:

.\scripts\register_claude_desktop.ps1 `
  -ConfigPath "$env:LOCALAPPDATA\Claude-3p\claude_desktop_config.json"

Claude Code CLI Globaler Adapter

Registrieren Sie für Claude-Code-CLI-Sitzungen einen benutzerbezogenen Eintrag, der auf dieses Checkout verweist. Das Installationsprogramm schreibt ~/.claude/.mcp.json, behält eine .bak-Kopie und stellt die Datei wieder her, wenn die Installation oder die Smoke-Validierung fehlschlägt. Der Standard-Namespace ist agent-team-mcp-cli; übergeben Sie für jedes Projekt einen projektspezifischen Namespace, da der globale CLI-Eintrag keine Projektisolation ableitet:

cd <project-root>
.\scripts\register_claude_code_cli.ps1 -ProjectNamespace "billing"

Das Skript registriert agent-team-governance-cli mit einem absoluten Wrapper-Pfad, sodass der Server aus jedem Arbeitsverzeichnis auffindbar ist. Überprüfen Sie dies aus einem anderen Verzeichnis:

Set-Location $env:TEMP
claude mcp get agent-team-governance-cli
claude mcp list

Der Wrapper priorisiert immer das src-Verzeichnis dieses Checkouts, bevor das Paket importiert wird. Die Deinstallation stellt die bearbeitete Konfiguration über denselben Sicherungspfad wieder her: scripts\unregister_claude_code_cli.ps1.

OpenCode CLI Globaler Adapter

Registrieren Sie für OpenCode-CLI-Sitzungen einen benutzerbezogenen lokalen Stdio-Eintrag mit demselben checkout-gebundenen Server. OpenCode verwendet auf jeder Plattform, einschließlich Windows, ein XDG-artiges Konfigurationsverzeichnis: Standardmäßig wird der Eintrag nach %USERPROFILE%\.config\opencode\opencode.jsonc geschrieben; eine vorhandene opencode.json hat Vorrang, wenn beide Dateien existieren. XDG_CONFIG_HOME hat Vorrang, wenn es gesetzt ist. Das Skript behält benachbarte mcp-Einträge, speichert vor dem Bearbeiten eine .bak-Kopie und legt ein stabiles Archiv-Root auf Benutzerebene sowie einen Projekt-Namespace fest:

cd <project-root>
.\scripts\register_opencode_cli.ps1 -ProjectNamespace "billing"
opencode mcp list

Der resultierende OpenCode-Eintrag ist mcp.agent-team-governance-opencode mit type: "local", einem Befehlsarray, das den absoluten Python-Interpreter und den OpenCode-Wrapper enthält, sowie den beiden Governance-Umgebungsvariablen. Er stellt nur die vorhandenen Governance-Tools bereit; er verändert weder die OpenCode-Laufzeit, verwaltet Agenten noch modifiziert er die Codex-Konfiguration oder -Prozesse. Entfernen Sie nur diesen Eintrag mit scripts\unregister_opencode_cli.ps1; die vorherige Konfiguration wird als <config>.bak beibehalten.

Codex-MCP-Konfiguration

Verwenden Sie die Umgebung des Checkouts explizit, damit MCP keine benachbarte editierbare Installation mit demselben Distributionsnamen auflösen kann:

[mcp_servers.protocol_guardian]
command = "<project-root>\\.venv\\Scripts\\python.exe"
args = ["-m", "agent_team_mcp.server"]

[mcp_servers.protocol_guardian.env]
AGENT_TEAM_MCP_GOVERNANCE_ROOT = "<project-root>\\.codex\\protocol"
AGENT_TEAM_MCP_PROJECT_NAMESPACE = "agent-team-mcp-cli"

Build, Wheel und MCP-Smoke

cd <project-root>
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe scripts\verify_runtime_source.py
.\.venv\Scripts\python.exe scripts\mcp_smoke.py
.\.venv\Scripts\python.exe -m build

Die Testsuite fügt das src-Verzeichnis dieses Checkouts vor site-packages ein, sodass eine nicht verwandte editierbare Installation mit demselben Distributionsnamen kein falsch grünes Ergebnis erzeugen kann.

Um ein Release-Artefakt zu überprüfen, installieren Sie das Wheel in eine saubere virtuelle Umgebung und führen Sie python scripts/mcp_smoke.py aus. Der Smoke-Test deckt initialize, tools/list, die wichtigsten schreibgeschützten Tools und die Behandlung ungültiger Eingaben ab. Die Release-Notizen müssen die Version, den Wheel-Dateinamen, SHA-256, Schemaänderungen und Rollback-Anweisungen festhalten. requirements-lock.txt wird in CI vor dem Build installiert; pip check validiert die Konsistenz und pip-audit ist das Sicherheits-Gate für Abhängigkeiten.