Codex Protocol Guardian

The positioning is fixed as "local MCP governance core + standard delivery adaptation." The closed loop is: contract -> development validation -> build and release -> installation and integration -> MCP smoke test -> diagnosis -> upgrade/rollback. The core only validates local structure, protocol, and archive format; it does not pull external platform facts, does not act as a centralized console, and does not dispatch agents.

Structure

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

The MCP server advertises itself as codex-protocol-guardian.

Related MCP server: workflow-compliance-enforcer

Surface

The governance package has no required or discoverable skill surface. Legacy role, prompt, and dispatch modules were removed from the package. Frontend, external-tool, and webnovel material is optional domain content and is not loaded into the default governance context. New code must use the public governance functions listed below.

The source tree may retain historical skill documents for reference, but the package build and resource loader include only governance protocols and the executable specification template. Legacy skill, role, and prompt data is not a loadable package resource.

Tools

• list_protocols: returns the protocol manifest, required artifacts, workflow phases, hard gates, and public tool list.

• export_protocol_context: returns the full protocol context, loaded protocol bodies, hashes, required artifacts, workflow, hard gates, and instructions.

• export_execution_plan_template: returns starter templates for the required .codex/protocol/* artifacts, including the executable Spec template and the module-boundary and communication-capacity declaration required before file design.

• audit_alignment_packet: checks whether a final packet has requirements, plan, acceptance protocol, traceability, changed files, validation evidence, an independent review signal, candidate authority, decomposition, solution design, scope, and convergence gate evidence. Missing governance evidence is blocked; there is no legacy bypass.

• validate_candidate_manifest: validates the single-active-subject manifest.

• transition_candidate: applies one legal lifecycle event without mutation.

• classify_review_finding: decides whether a finding stays in the candidate or requires a successor.

• validate_requirements_decomposition: validates frozen atomic requirements before design starts.

• validate_solution_design: validates alternatives, exact requirement binding, module boundaries, and scope digest.

• validate_change_scope: rejects changed files outside the design allow-list.

• validate_finding_ledger: validates finding fingerprints, closure evidence, successor inheritance, and recurrence blocking.

• validate_finding_archive: validates the persisted finding archive and parent candidate chain.

• read_finding_archive: loads and verifies a relative archive path under the configured governance archive root.

• append_finding_archive: atomically appends a governance record with an expected-digest conflict check; absolute paths and .. traversal are rejected.

Required Artifacts

Codex should keep these files in the target project during a development task:

.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

The package does not write runtime state. Its only write operation is the explicit append_finding_archive governance-artifact operation, which uses an expected digest and atomic replacement to prevent lost updates. The archive root is configured explicitly by AGENT_TEAM_MCP_ARCHIVE_ROOT, or derived from AGENT_TEAM_MCP_GOVERNANCE_ROOT and AGENT_TEAM_MCP_PROJECT_NAMESPACE. Without either setting it defaults to .codex/protocol/current/archives under the current project. All supported hosts should use the same governance root and namespace.

Optional Vision Assistance

The project vendors agent-vision-toolkit as an optional skill under src/agent_team_mcp/data/optional_skills/agent-vision-toolkit. Call the vision_assistance operation with the model capability explicitly:

• vision_capable=true returns mode=skip and does not expose the skill.

• vision_capable=false returns the vision-skills entry, tool map, triggers, and the visible effect for a text-only model.

This is an exposure contract only. It does not install dependencies, call a vision API, read credentials, proxy model traffic, or change host configuration. The bundled skill still requires an externally configured vision API when used. Its default OpenAI-compatible candidates are GLM-4.6V-Flash and GLM-4.1V-Thinking-Flash; configure VISION_API_KEY in the project environment and keep it out of source control. VISION_MODEL selects the primary candidate, while VISION_MODELS supplies the comma-separated fallback list.

For a local project environment, copy the bundled src/agent_team_mcp/data/optional_skills/agent-vision-toolkit/.env.example to the project root as .env, then fill only VISION_API_KEY. The root .env is ignored by source control and is loaded automatically by the skill.

External OCR Module Adapter (V1)

The V1 model pool and intent router live outside this governance checkout. Set OCR_MODULE_ROOT to that module's local directory when using the optional vision_assist adapter operation. It accepts a JSON request with a required vision_capable boolean; native-vision callers return skip, while text-only callers are forwarded to the fixed external adapter root.

The external module owns the static GLM model candidates, intent rules, provider calls, and result normalization. Its local .env contains the provider configuration. V1 intentionally does not add permissions, tenants, queues, service discovery, load balancing, cloud orchestration, or management UI.

Local Runtime Check

Install this checkout into the project environment before starting MCP:

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

After reinstalling the package, restart or re-register the MCP process so its manifest and protocol resources come from this checkout.

Workflow

1. Load export_protocol_context before editing.

2. Create or refresh the required protocol artifacts.

3. Assign stable requirement ids (R1, R2, ...) and acceptance ids (A1, A2, ...).

4. Freeze a requirements decomposition before writing a solution design. Each item needs an observable result, boundaries, non-goals, dependencies, and an acceptance id.

5. Validate a solution design against the frozen decomposition. The design must choose among alternatives and declare public interfaces, responsibilities, forbidden duties, allowed files, and a scope digest.

6. Build specification.md from the packaged executable Spec standard. Execute every rule against its production input projection before planning code.

7. Keep one active candidate subject. Archive rejected and superseded subjects, linked with replaces and superseded_by.

8. A material requirement, design, or scope finding creates a successor; minor findings may be fixed in the current candidate.

9. Every governed packet must carry a finding ledger. Repeated fingerprints inherited from a successor chain block acceptance until root-cause evidence exists.

10. Report independent gates for scope drift, review independence, CI completeness, traceability closure, artifact provenance, and runtime acceptance boundary. CI completeness also requires external platform evidence for branch protection, required checks, CODEOWNER approval, stale-review dismissal, and merge-queue policy.

11. Record process metrics separately: time in state, review iterations, superseded count, rejection rate, open blockers, lead time, change-fail rate, and recovery time.

12. Before each edit, declare the phase, requirement ids, acceptance ids, allowed files, and expected evidence.

13. Before choosing files for a feature component, declare its single public interface, internal responsibility split, dependency direction, expected traffic, ordering/idempotency, backpressure, failure handling, scaling, and observability. A single public interface must not serialize all work.

14. Split internal files by responsibility and change reason. Do not use fixed line-count thresholds or put facade, business logic, storage, and external communication in one file. Single-responsibility leaf files remain valid.

15. After each edit, compare the diff against requirements, the specification, the execution plan, acceptance protocol, traceability, and non-goals.

16. Record plan deviations in decision_log.md.

17. Run validation and export a review packet.

18. Treat self-test as evidence only. Final acceptance requires independent review, CI, or explicit user approval.

Support Matrix

The first release supports local stdio only. Cursor, VS Code, Windsurf, Gemini, remote HTTP, OAuth, multi-tenant gateways, and centralized control planes are separate adapters or projects.

Claude Code Project Adapter (Optional Fallback)

This checkout includes a project-scoped Claude Code MCP configuration in .mcp.json. It is intentionally separate from Codex configuration and points at scripts/claude_code_mcp_server.py, which resolves this checkout's src directory before starting the existing FastMCP server.

Install the optional MCP dependency in the Python environment visible to Claude Code, then verify the project server:

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

This project adapter is retained for isolated tests and deliberate project overrides. It is not the global registration path. It only exposes the existing governance tools; it does not spawn agents, route tasks, or modify the Codex MCP process.

Claude Desktop Global Adapter

For normal Claude Desktop use, install and register a user-scoped copy that is available from every project. The script installs the package into a dedicated user-local venv and merges agent-team-governance-desktop into Claude's global configuration without removing other servers. It detects the Microsoft Store 3p location (%LOCALAPPDATA%\Claude-3p\claude_desktop_config.json) first and falls back to the classic %APPDATA%\Claude\claude_desktop_config.json path:

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

Restart Claude Desktop after registration. This global entry is independent of the checkout's Python environment. The script writes a .bak backup, replaces the config through a temporary file, and rolls back on a failed MCP smoke. Uninstall with scripts\unregister_claude_desktop.ps1.

Desktop starts this MCP server on the Windows host while the agent shell runs inside a per-session Linux VM. The registration therefore sets AGENT_TEAM_MCP_GOVERNANCE_ROOT and AGENT_TEAM_MCP_PROJECT_NAMESPACE instead of relying on the host process cwd. Archive files are written under <governance_root>\<namespace>\archives.

To target a specific Desktop profile, pass -ConfigPath explicitly. This is useful when the app is running with a migrated user-data directory:

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

Claude Code CLI Global Adapter

For Claude Code CLI sessions, register a user-scoped entry that points at this checkout. The installer writes ~/.claude/.mcp.json, keeps a .bak copy, and rolls back the file if installation or smoke validation fails. The default namespace is agent-team-mcp-cli; pass a project-specific namespace for each project because the global CLI entry does not infer project isolation:

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

The script registers agent-team-governance-cli with an absolute wrapper path, so the server is discoverable from any working directory. Verify it from a different directory:

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

The wrapper always prioritizes this checkout's src directory before importing the package. Uninstall restores the edited config through the same backup path: scripts\unregister_claude_code_cli.ps1.

OpenCode CLI Global Adapter

For OpenCode CLI sessions, register a user-scoped local stdio entry using the same checkout-bound server. OpenCode uses an XDG-style configuration directory on every platform, including Windows: by default the entry is written to %USERPROFILE%\.config\opencode\opencode.jsonc; an existing opencode.json takes precedence when both files exist. XDG_CONFIG_HOME takes precedence when it is set. The script keeps sibling mcp entries, stores a .bak copy before editing, and sets a stable user-level archive root plus project namespace:

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

The resulting OpenCode entry is mcp.agent-team-governance-opencode with type: "local", a command array containing the absolute Python interpreter and OpenCode wrapper, and the two governance environment variables. It exposes the existing governance tools only; it does not alter OpenCode's runtime, manage agents, or modify Codex configuration or processes. Remove only this entry with scripts\unregister_opencode_cli.ps1; the prior config is retained as <config>.bak.

Codex MCP Config

Use the checkout's environment explicitly so MCP cannot resolve a sibling editable install with the same distribution name:

[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, and 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

The test suite inserts this checkout's src directory before site-packages so an unrelated editable install with the same distribution name cannot produce a false green result.

To verify a release artifact, install the wheel into a clean virtual environment and run python scripts/mcp_smoke.py. The smoke covers initialize, tools/list, the key read-only tools, and invalid input handling. Release notes must record the version, wheel filename, SHA-256, schema changes, and rollback instructions. requirements-lock.txt is installed in CI before the build; pip check validates consistency and pip-audit is the dependency security gate.