Codex Protocol Guardian

위치는 '로컬 MCP 거버넌스 코어 + 표준 전달 어댑터'로 고정됩니다. 폐쇄 루프는 계약 -> 개발 검증 -> 빌드 릴리스 -> 설치 연결 -> MCP 스모크 -> 진단 -> 업그레이드/롤백입니다. 코어는 로컬 구조, 프로토콜 및 아카이브 형식만 검증하며 외부 플랫폼 사실을 가져오지 않고, 중앙 콘솔을 만들지 않으며, 에이전트를 스케줄링하지 않습니다.

MCP 거버넌스 패키지로서 Codex 개발 작업을 요구사항 패키지, 하나의 활성 후보 주제, 실행 가능한 사양, 독립 게이트, 추적 가능한 검토 패킷에 맞춰 유지합니다.

이 패키지는 하위 에이전트를 생성하거나, 역할 프롬프트를 내보내거나, 작업을 실행하거나, 런타임 상태를 쓰지 않습니다. 거버넌스 증거를 검증하고 불변의 발견 아카이브를 추가할 수 있습니다. 자체 작업을 승인하지 않습니다. 레거시 역할, 디스패치 및 하위 에이전트 모듈은 패키지 표면에 포함되지 않습니다.

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

MCP 서버는 codex-protocol-guardian으로 자신을 광고합니다.

Related MCP server: workflow-compliance-enforcer

Surface Boundary

거버넌스 패키지에는 필수 또는 검색 가능한 스킬 표면이 없습니다. 레거시 역할, 프롬프트, 디스패치 및 하위 에이전트 모듈은 패키지에서 제거되었습니다. 프론트엔드, 외부 도구 및 웹소설 자료는 선택적 도메인 콘텐츠이며 기본 거버넌스 컨텍스트에 로드되지 않습니다. 새 코드는 아래 나열된 공개 거버넌스 함수를 사용해야 합니다.

소스 트리는 참조용으로 과거 스킬 문서를 보유할 수 있지만, 패키지 빌드 및 리소스 로더에는 거버넌스 프로토콜과 실행 가능한 사양 템플릿만 포함됩니다. 레거시 스킬, 역할 및 프롬프트 데이터는 로드 가능한 패키지 리소스가 아닙니다.

Tools

• list_protocols: 프로토콜 매니페스트, 필수 아티팩트, 워크플로 단계, 하드 게이트 및 공개 도구 목록을 반환합니다.

• export_protocol_context: 전체 프로토콜 컨텍스트, 로드된 프로토콜 본문, 해시, 필수 아티팩트, 워크플로, 하드 게이트 및 지침을 반환합니다.

• export_execution_plan_template: 필수 .codex/protocol/* 아티팩트에 대한 시작 템플릿을 반환합니다. 실행 가능한 Spec 템플릿과 파일 설계 전에 필요한 모듈 경계 및 통신 용량 선언을 포함합니다.

• audit_alignment_packet: 최종 패킷에 요구사항, 계획, 승인 프로토콜, 추적성, 변경된 파일, 검증 증거, 독립 검토 신호, 후보 권한, 분해, 솔루션 설계, 범위 및 수렴 게이트 증거가 있는지 확인합니다. 누락된 거버넌스 증거는 차단됩니다. 레거시 우회는 없습니다.

• validate_candidate_manifest: 단일 활성 주제 매니페스트를 검증합니다.

• transition_candidate: 변이 없이 하나의 합법적 수명주기 이벤트를 적용합니다.

• classify_review_finding: 발견이 후보에 남아야 하는지 후속자가 필요한지 결정합니다.

• validate_requirements_decomposition: 설계 시작 전에 동결된 원자 요구사항을 검증합니다.

• validate_solution_design: 대안, 정확한 요구사항 바인딩, 모듈 경계 및 범위 다이제스트를 검증합니다.

• validate_change_scope: 설계 허용 목록 외부의 변경된 파일을 거부합니다.

• validate_finding_ledger: 발견 지문, 종결 증거, 후속자 상속 및 재발 차단을 검증합니다.

• validate_finding_archive: 지속된 발견 아카이브와 상위 후보 체인을 검증합니다.

• read_finding_archive: 구성된 거버넌스 아카이브 루트 아래의 상대 아카이브 경로를 로드하고 확인합니다.

• append_finding_archive: 예상 다이제스트 충돌 검사로 거버넌스 레코드를 원자적으로 추가합니다. 절대 경로 및 .. 탐색은 거부됩니다.

Required Artifacts

Codex는 개발 작업 중 대상 프로젝트에 다음 파일을 유지해야 합니다:

.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

패키지는 런타임 상태를 쓰지 않습니다. 유일한 쓰기 작업은 명시적 append_finding_archive 거버넌스 아티팩트 작업으로, 예상 다이제스트와 원자적 교체를 사용하여 손실된 업데이트를 방지합니다. 아카이브 루트는 AGENT_TEAM_MCP_ARCHIVE_ROOT로 명시적으로 구성되거나 AGENT_TEAM_MCP_GOVERNANCE_ROOT 및 AGENT_TEAM_MCP_PROJECT_NAMESPACE에서 파생됩니다. 두 설정이 모두 없으면 현재 프로젝트 아래의 .codex/protocol/current/archives로 기본 설정됩니다. 지원되는 모든 호스트는 동일한 거버넌스 루트와 네임스페이스를 사용해야 합니다.

Optional Vision Assistance

프로젝트는 agent-vision-toolkit을 src/agent_team_mcp/data/optional_skills/agent-vision-toolkit 아래의 선택적 스킬로 제공합니다. 모델 기능을 명시적으로 지정하여 vision_assistance 작업을 호출하십시오:

• vision_capable=true는 mode=skip을 반환하고 스킬을 노출하지 않습니다.

• vision_capable=false는 vision-skills 항목, 도구 맵, 트리거 및 텍스트 전용 모델에 대한 가시적 효과를 반환합니다.

이것은 노출 계약일 뿐입니다. 종속성을 설치하거나, 비전 API를 호출하거나, 자격 증명을 읽거나, 모델 트래픽을 프록시하거나, 호스트 구성을 변경하지 않습니다. 번들된 스킬은 사용 시 외부에서 구성된 비전 API가 여전히 필요합니다. 기본 OpenAI 호환 후보는 GLM-4.6V-Flash 및 GLM-4.1V-Thinking-Flash입니다. 프로젝트 환경에서 VISION_API_KEY를 구성하고 소스 제어에서 제외하십시오. VISION_MODEL은 기본 후보를 선택하고 VISION_MODELS는 쉼표로 구분된 대체 목록을 제공합니다.

로컬 프로젝트 환경의 경우 번들된 src/agent_team_mcp/data/optional_skills/agent-vision-toolkit/.env.example을 프로젝트 루트에 .env로 복사한 다음 VISION_API_KEY만 채우십시오. 루트 .env는 소스 제어에서 무시되며 스킬에 의해 자동으로 로드됩니다.

External OCR Module Adapter (V1)

V1 모델 풀과 의도 라우터는 이 거버넌스 체크아웃 외부에 있습니다. 선택적 vision_assist 어댑터 작업을 사용할 때 OCR_MODULE_ROOT를 해당 모듈의 로컬 디렉터리로 설정하십시오. 필수 vision_capable 부울이 있는 JSON 요청을 수락합니다. 네이티브 비전 호출자는 skip을 반환하고 텍스트 전용 호출자는 고정된 외부 어댑터 루트로 전달됩니다.

외부 모듈은 정적 GLM 모델 후보, 의도 규칙, 공급자 호출 및 결과 정규화를 소유합니다. 로컬 .env에는 공급자 구성이 포함됩니다. V1은 의도적으로 권한, 테넌트, 큐, 서비스 검색, 로드 밸런싱, 클라우드 오케스트레이션 또는 관리 UI를 추가하지 않습니다.

list_protocols는 패키지/프로토콜 버전, 스키마 호환성 및 폐기 정책, 지원되는 호스트, stdio 전송 및 아카이브 루트 전략을 노출합니다. 버전은 src/agent_team_mcp/version.py에서 한 번 가져옵니다. 현재 릴리스는 schema_version == 1만 허용합니다. 버전이 지정된 리더와 마이그레이션 명령이 존재할 때까지 마이그레이션은 의도적으로 구현되지 않습니다.

Local Runtime Check

MCP를 시작하기 전에 이 체크아웃을 프로젝트 환경에 설치하십시오:

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

패키지를 다시 설치한 후 MCP 프로세스를 다시 시작하거나 다시 등록하여 매니페스트 및 프로토콜 리소스가 이 체크아웃에서 오도록 하십시오.

Workflow

1. 편집 전에 export_protocol_context를 로드하십시오.

2. 필수 프로토콜 아티팩트를 생성하거나 새로 고치십시오.

3. 안정적인 요구사항 ID(R1, R2, ...) 및 승인 ID(A1, A2, ...)를 할당하십시오.

4. 솔루션 설계를 작성하기 전에 요구사항 분해를 동결하십시오. 각 항목에는 관찰 가능한 결과, 경계, 비목표, 종속성 및 승인 ID가 필요합니다.

5. 동결된 분해에 대해 솔루션 설계를 검증하십시오. 설계는 대안 중에서 선택하고 공개 인터페이스, 책임, 금지된 의무, 허용된 파일 및 범위 다이제스트를 선언해야 합니다.

6. 패키지된 실행 가능한 Spec 표준에서 specification.md를 빌드하십시오. 코드를 계획하기 전에 모든 규칙을 프로덕션 입력 프로젝션에 대해 실행하십시오.

7. 하나의 활성 후보 주제를 유지하십시오. 거부되고 대체된 주제는 replaces 및 superseded_by로 연결하여 아카이브하십시오.

8. 중대한 요구사항, 설계 또는 범위 발견은 후속자를 생성합니다. 사소한 발견은 현재 후보에서 수정될 수 있습니다.

9. 모든 관리 패킷은 발견 원장을携带해야 합니다. 후속자 체인에서 상속된 반복 지문은 근본 원인 증거가 있을 때까지 수락을 차단합니다.

10. 범위 드리프트, 검토 독립성, CI 완전성, 추적성 종결, 아티팩트 출처 및 런타임 수락 경계에 대한 독립 게이트를 보고하십시오. CI 완전성은 또한 분기 보호, 필수 검사, CODEOWNER 승인, 오래된 검토 해제 및 병합 큐 정책에 대한 외부 플랫폼 증거가 필요합니다.

11. 프로세스 메트릭을 별도로 기록하십시오: 상태 시간, 검토 반복, 대체 수, 거부율, 열린 차단기, 리드 타임, 변경 실패율 및 복구 시간.

12. 각 편집 전에 단계, 요구사항 ID, 승인 ID, 허용된 파일 및 예상 증거를 선언하십시오.

13. 기능 구성 요소에 대한 파일을 선택하기 전에 단일 공개 인터페이스, 내부 책임 분할, 종속성 방향, 예상 트래픽, 순서/멱등성, 백프레셔, 실패 처리, 확장 및 관찰 가능성을 선언하십시오. 단일 공개 인터페이스가 모든 작업을 직렬화해서는 안 됩니다.

14. 책임 및 변경 이유에 따라 내부 파일을 분할하십시오. 고정된 줄 수 임계값을 사용하지 말고 파사드, 비즈니스 로직, 저장소 및 외부 통신을 한 파일에 넣지 마십시오. 단일 책임 리프 파일은 유효합니다.

15. 각 편집 후 diff를 요구사항, 사양, 실행 계획, 승인 프로토콜, 추적성 및 비목표와 비교하십시오.

16. 계획 편차를 decision_log.md에 기록하십시오.

17. 검증을 실행하고 검토 패킷을 내보내십시오.

18. 자체 테스트를 증거로만 취급하십시오. 최종 수락에는 독립 검토, CI 또는 명시적 사용자 승인이 필요합니다.

Support Matrix

첫 번째 릴리스는 로컬 stdio만 지원합니다. Cursor, VS Code, Windsurf, Gemini, 원격 HTTP, OAuth, 다중 테넌트 게이트웨이 및 중앙 집중식 제어 플레인은 별도의 어댑터 또는 프로젝트입니다.

Claude Code Project Adapter (Optional Fallback)

이 체크아웃에는 .mcp.json에 프로젝트 범위의 Claude Code MCP 구성이 포함됩니다. 이는 의도적으로 Codex 구성과 분리되어 있으며 scripts/claude_code_mcp_server.py를 가리킵니다. 이 스크립트는 기존 FastMCP 서버를 시작하기 전에 이 체크아웃의 src 디렉터리를 해석합니다.

Claude Code에 표시되는 Python 환경에 선택적 MCP 종속성을 설치한 다음 프로젝트 서버를 확인하십시오:

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

이 프로젝트 어댑터는 격리된 테스트와 의도적인 프로젝트 재정의를 위해 유지됩니다. 전역 등록 경로가 아닙니다. 기존 거버넌스 도구만 노출합니다. 에이전트를 생성하거나, 작업을 라우팅하거나, Codex MCP 프로세스를 수정하지 않습니다.

Claude Desktop Global Adapter

일반적인 Claude Desktop 사용의 경우 모든 프로젝트에서 사용할 수 있는 사용자 범위 복사본을 설치하고 등록하십시오. 스크립트는 전용 사용자 로컬 venv에 패키지를 설치하고 다른 서버를 제거하지 않고 agent-team-governance-desktop을 Claude의 전역 구성에 병합합니다. 먼저 Microsoft Store 3p 위치(%LOCALAPPDATA%\Claude-3p\claude_desktop_config.json)를 감지하고 클래식 %APPDATA%\Claude\claude_desktop_config.json 경로로 대체합니다:

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

등록 후 Claude Desktop을 다시 시작하십시오. 이 전역 항목은 체크아웃의 Python 환경과 독립적입니다. 스크립트는 .bak 백업을 작성하고 임시 파일을 통해 구성을 교체하며 MCP 스모크 실패 시 롤백합니다. scripts\unregister_claude_desktop.ps1로 제거하십시오.

데스크톱은 Windows 호스트에서 이 MCP 서버를 시작하는 반면, 에이전트 셸은 세션별 Linux VM 내부에서 실행됩니다. 따라서 등록 시 호스트 프로세스 cwd에 의존하는 대신 AGENT_TEAM_MCP_GOVERNANCE_ROOT 및 AGENT_TEAM_MCP_PROJECT_NAMESPACE를 설정합니다. 아카이브 파일은 <governance_root>\<namespace>\archives 아래에 기록됩니다.

특정 데스크톱 프로필을 대상으로 하려면 -ConfigPath를 명시적으로 전달하세요. 이는 앱이 마이그레이션된 사용자 데이터 디렉터리로 실행 중일 때 유용합니다:

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

Claude Code CLI 글로벌 어댑터

Claude Code CLI 세션의 경우 이 체크아웃을 가리키는 사용자 범위 항목을 등록하세요. 설치 프로그램은 ~/.claude/.mcp.json을 작성하고 .bak 사본을 유지하며 설치 또는 스모크 검증이 실패하면 파일을 롤백합니다. 기본 네임스페이스는 agent-team-mcp-cli입니다. 글로벌 CLI 항목은 프로젝트 격리를 추론하지 않으므로 각 프로젝트에 대해 프로젝트별 네임스페이스를 전달하세요:

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

스크립트는 절대 래퍼 경로로 agent-team-governance-cli를 등록하므로 서버는 모든 작업 디렉터리에서 검색 가능합니다. 다른 디렉터리에서 확인하세요:

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

래퍼는 패키지를 가져오기 전에 항상 이 체크아웃의 src 디렉터리를 우선시합니다. 제거는 동일한 백업 경로를 통해 편집된 구성을 복원합니다: scripts\unregister_claude_code_cli.ps1.

OpenCode CLI 글로벌 어댑터

OpenCode CLI 세션의 경우 동일한 체크아웃 바인딩 서버를 사용하여 사용자 범위 로컬 stdio 항목을 등록하세요. OpenCode는 Windows를 포함한 모든 플랫폼에서 XDG 스타일 구성 디렉터리를 사용합니다. 기본적으로 항목은 %USERPROFILE%\.config\opencode\opencode.jsonc에 기록됩니다. 두 파일이 모두 존재하면 기존 opencode.json이 우선합니다. XDG_CONFIG_HOME이 설정된 경우 우선합니다. 스크립트는 형제 mcp 항목을 유지하고, 편집 전에 .bak 사본을 저장하며, 안정적인 사용자 수준 아카이브 루트와 프로젝트 네임스페이스를 설정합니다:

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

결과 OpenCode 항목은 mcp.agent-team-governance-opencode이며 type: "local", 절대 Python 인터프리터와 OpenCode 래퍼를 포함하는 명령 배열, 그리고 두 개의 거버넌스 환경 변수를 포함합니다. 기존 거버넌스 도구만 노출하며 OpenCode의 런타임을 변경하거나, 에이전트를 관리하거나, Codex 구성을 수정하거나 프로세스를 변경하지 않습니다. scripts\unregister_opencode_cli.ps1로 이 항목만 제거하세요. 이전 구성은 <config>.bak으로 유지됩니다.

Codex MCP 구성

MCP가 동일한 배포 이름을 가진 형제 편집 가능 설치를 확인할 수 없도록 체크아웃의 환경을 명시적으로 사용하세요:

[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"

빌드, 휠 및 MCP 스모크

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

테스트 스위트는 site-packages 앞에 이 체크아웃의 src 디렉터리를 삽입하여 동일한 배포 이름을 가진 관련 없는 편집 가능 설치가 잘못된 녹색 결과를 생성할 수 없도록 합니다.

릴리스 아티팩트를 검증하려면 휠을 깨끗한 가상 환경에 설치하고 python scripts/mcp_smoke.py를 실행하세요. 스모크는 initialize, tools/list, 주요 읽기 전용 도구 및 잘못된 입력 처리를 포함합니다. 릴리스 노트에는 버전, 휠 파일 이름, SHA-256, 스키마 변경 사항 및 롤백 지침을 기록해야 합니다. requirements-lock.txt는 빌드 전에 CI에 설치됩니다. pip check는 일관성을 검증하고 pip-audit은 종속성 보안 게이트입니다.