Codex Protocol Guardian

MCP-Governance-Paket, um Codex-Entwicklungsaufgaben an ein Anforderungspaket, einen aktiven Kandidatengegenstand, eine ausführbare Spezifikation, unabhängige Gates und ein rückverfolgbares Review-Paket auszurichten.

Dieses Paket erzeugt keine untergeordneten Agenten, exportiert keine Rollen-Prompts, führt keine Aufgaben aus und speichert keinen Laufzeitzustand. Es validiert Governance-Nachweise und kann unveränderliche Finding-Archive anhängen; es genehmigt niemals seine eigene Arbeit. Legacy-Rollen-, Dispatch- und Sub-Agent-Module sind nicht in der Paketoberfläche enthalten.

Struktur

<checkout-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 präsentiert sich als codex-protocol-guardian.

Oberflächengrenze

Das Governance-Paket hat keine erforderliche oder auffindbare Skill-Oberfläche. Legacy-Rollen-, Prompt-, Dispatch- und Sub-Agent-Module wurden aus dem Paket entfernt. Material zu Frontend, externen Tools und Webnovels ist optionaler Domain-Inhalt und wird nicht in den Standard-Governance-Kontext geladen. Neuer Code muss die unten aufgeführten öffentlichen Governance-Funktionen verwenden.

Der Quellbaum darf historische Skill-Dokumente als Referenz behalten, aber der Paket-Build und der Ressourcen-Loader enthalten nur Governance-Protokolle und die Vorlage der ausführbaren Spezifikation. Legacy-Skill-, Rollen- und Prompt-Daten sind keine ladbare Paketressource.

Werkzeuge

• list_protocols: gibt das Protokoll-Manifest, die erforderlichen Artefakte, die Workflow-Phasen, die harten Gates und die öffentliche Werkzeugliste zurück.

• export_protocol_context: gibt den vollständigen Protokollkontext, die geladenen Protokolltexte, Hashes, die erforderlichen Artefakte, den Workflow, die harten Gates und die 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 Spec und der vor dem Dateidesign erforderlichen Erklärung zu Modulgrenzen und Kommunikationskapazität.

• audit_alignment_packet: prüft, ob ein finales Paket Anforderungen, Plan, Akzeptanzprotokoll, Rückverfolgbarkeit, geänderte Dateien, Validierungsnachweise, ein unabhängiges Review-Signal, Kandidatenautorität, Zerlegung, Lösungsdesign, Scope und Konvergenz-Gate-Nachweise enthält. Fehlende Governance-Nachweise werden blockiert; es gibt keinen Legacy-Bypass.

• validate_candidate_manifest: validiert das Manifest des einzelnen aktiven Gegenstands.

• transition_candidate: wendet genau ein zulässiges Lebenszyklusereignis ohne Mutation an.

• classify_review_finding: entscheidet, ob ein Finding im Kandidaten verbleibt oder einen Nachfolger erfordert.

• validate_requirements_decomposition: validiert eingefrorene atomare Anforderungen, bevor das Design beginnt.

• validate_solution_design: validiert Alternativen, die exakte Anforderungsbindung, Modulgrenzen und den Scope-Digest.

• validate_change_scope: weist geänderte Dateien außerhalb der Design-Allow-Liste zurück.

• validate_finding_ledger: validiert Finding-Fingerabdrücke, Abschlussnachweise, die Nachfolger-Vererbung und die Wiederholungsblockierung.

• validate_finding_archive: validiert das persistierte Finding-Archiv und die Kette der übergeordneten Kandidaten.

• read_finding_archive: lädt und verifiziert einen relativen Archivpfad unterhalb des konfigurierten Governance-Archivstamms.

• append_finding_archive: hängt einen Governance-Datensatz mit einer Konfliktprüfung anhand des erwarteten Digests atomar an; absolute Pfade und ..-Traversierung werden abgelehnt.

Erforderliche Artefakte

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

.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 speichert keinen Laufzeitzustand. Seine einzige Schreiboperation ist der explizite append_finding_archive-Vorgang für Governance-Artefakte, der einen erwarteten Digest und atomaren Ersatz verwendet, um verlorene Aktualisierungen zu verhindern. Der Archivstamm wird über AGENT_TEAM_MCP_ARCHIVE_ROOT konfiguriert oder standardmäßig auf .codex/protocol/current/archives unter dem aktuellen Projekt gesetzt.

Lokale Laufzeitprüfung

Installieren Sie diesen Checkout in die Projektumgebung, bevor Sie MCP starten:

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

Starten Sie den MCP-Prozess nach der Neuinstallation des Pakets neu oder registrieren Sie ihn erneut, damit dessen Manifest und Protokollressourcen aus diesem Checkout stammen.

Workflow

1. Laden Sie export_protocol_context, bevor Sie mit der Bearbeitung beginnen.

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

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

4. Frieren Sie eine Anforderungszerlegung ein, bevor Sie ein Lösungsdesign schreiben. Jedes Element benötigt ein beobachtbares Ergebnis, Grenzen, Nicht-Ziele, Abhängigkeiten und eine Akzeptanz-ID.

5. Validieren Sie ein Lösungsdesign gegen die eingefrorene Zerlegung. Das Design muss zwischen Alternativen wählen und öffentliche Schnittstellen, Verantwortlichkeiten, verbotene Aufgaben, zulässige Dateien und einen Scope-Digest deklarieren.

6. Erstellen Sie specification.md aus dem im Paket enthaltenen Standard für die ausführbare Spec. Führen Sie jede Regel gegen ihre Produktions-Eingabeprojektion aus, bevor Sie Code planen.

7. Behalten Sie genau einen aktiven Kandidatengegenstand bei. Archivieren Sie abgelehnte und abgelöste Gegenstände, verknüpft mit replaces und superseded_by.

8. Ein wesentliches Anforderungs-, Design- oder Scope-Finding erzeugt einen Nachfolger; kleinere Findings können im aktuellen Kandidaten behoben werden.

9. Jedes governance-pflichtige Paket muss ein Finding-Ledger enthalten. Wiederholte Fingerabdrücke, die aus einer Nachfolgerkette geerbt wurden, blockieren die Annahme, bis Nachweise zur Grundursache vorliegen.

10. Melden Sie unabhängige Gates für Scope-Drift, Review-Unabhängigkeit, CI-Vollständigkeit, Rückverfolgbarkeitsabschluss, Artefakt-Herkunft und die Laufzeit-Akzeptanzgrenze. CI-Vollständigkeit erfordert außerdem externe Plattformnachweise für Branch-Schutz, erforderliche Checks, CODEOWNER-Genehmigung, das Verwerfen veralteter Reviews und die Merge-Queue-Richtlinie.

11. Erfassen Sie Prozessmetriken getrennt: Verweildauer im Zustand, Review-Iterationen, Anzahl abgelöster Gegenstände, Ablehnungsrate, offene Blocker, Durchlaufzeit, Änderungsfehlerrate und Wiederherstellungszeit.

12. Deklarieren Sie vor jeder Bearbeitung die Phase, die Anforderungs-IDs, die Akzeptanz-IDs, die zulässigen Dateien und die erwarteten Nachweise.

13. Deklarieren Sie vor der Auswahl von Dateien für eine Feature-Komponente deren einzelne öffentliche Schnittstelle, interne Verantwortungsverteilung, Abhängigkeitsrichtung, erwarteten Datenverkehr, Reihenfolge/Idempotenz, Backpressure, Fehlerbehandlung, Skalierung und Beobachtbarkeit. Eine einzelne öffentliche Schnittstelle darf nicht die gesamte Arbeit serialisieren.

14. Teilen Sie interne Dateien nach Verantwortlichkeit und Änderungsgrund auf. Verwenden Sie keine festen Zeilenzahl-Schwellenwerte und fassen Sie Fassade, Geschäftslogik, Speicherung und externe Kommunikation nicht in einer Datei zusammen. Blattdateien mit einer einzigen Verantwortlichkeit bleiben gültig.

15. Vergleichen Sie nach jeder Bearbeitung den Diff mit den Anforderungen, der Spezifikation, dem Ausführungsplan, dem Akzeptanzprotokoll, der Rückverfolgbarkeit und den Nicht-Zielen.

16. Halten Sie Planabweichungen in decision_log.md fest.

17. Führen Sie die Validierung aus und exportieren Sie ein Review-Paket.

18. Behandeln Sie Selbsttests nur als Nachweis. Die endgültige Annahme erfordert unabhängiges Review, CI oder eine ausdrückliche Benutzerfreigabe.

Codex-MCP-Konfiguration

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

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

Verifizieren

cd <checkout-root>
python -m pytest -q
python -m ruff check .
python scripts/verify_runtime_source.py

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