# 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

```text
<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:

```text
.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:

```text
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:

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

## Verify

```powershell
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.