# Codex Protocol Guardian

定位固定为“本地 MCP 治理核心 + 标准交付适配”。闭环是：
契约 -> 开发验证 -> 构建发布 -> 安装接入 -> MCP 冒烟 -> 诊断 -> 升级/回滚。
核心只校验本地结构、协议和归档格式，不拉取外部平台事实、不做集中控制台、不调度 Agent。

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

## 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 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.

`list_protocols` exposes the package/protocol version, schema compatibility and
deprecation policy, supported hosts, stdio transport, and archive-root strategy.
Version is sourced once from `src/agent_team_mcp/version.py`. The current
release accepts `schema_version == 1` only; migration is intentionally not
implemented until a versioned reader and migration command exist.

## 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.

## Support Matrix

| Host | Template / installer | Acceptance check |
| --- | --- | --- |
| Codex | TOML snippet below | python scripts/mcp_smoke.py |
| Claude Desktop | scripts/register_claude_desktop.ps1 | config plus the smoke command |
| Claude Code | scripts/register_claude_code_cli.ps1 | claude mcp get agent-team-governance-cli plus the smoke command |
| OpenCode CLI | scripts/register_opencode_cli.ps1 | opencode mcp list plus the smoke command |

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:

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

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

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

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

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

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

```toml
[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

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