Codex Protocol Guardian

MCP governance package for keeping Codex development tasks aligned to a requirements package, one active candidate subject, an executable specification, independent gates, and a traceable review packet.

This package does not spawn child agents, export role prompts, execute tasks, or write runtime state. It validates governance evidence and can append immutable finding archives; it never approves its own work. Legacy role, dispatch, and sub-agent modules are not included in the package surface.

Structure

<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

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

Surface Boundary

The governance package has no required or discoverable skill surface. Legacy role, prompt, dispatch, and sub-agent 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 by AGENT_TEAM_MCP_ARCHIVE_ROOT, or defaults to .codex/protocol/current/archives under the current project.

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.

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 = "<checkout-root>/.venv/Scripts/python.exe"
args = ["-m", "agent_team_mcp.server"]

Verify

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

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.