Codex Protocol Guardian

Codex 개발 작업을 요구사항 패키지, 단일 활성 후보 주제, 실행 가능한 명세, 독립 게이트, 추적 가능한 검토 패킷에 정렬하기 위한 MCP 거버넌스 패키지입니다.

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

구조

<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

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

표면 경계

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

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

도구

• 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: 예상 다이제스트 충돌 검사와 함께 거버넌스 레코드를 원자적으로 추가합니다. 절대 경로와 .. 탐색은 거부됩니다.

필수 산출물

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로 구성되며, 기본값은 현재 프로젝트의 .codex/protocol/current/archives입니다.

로컬 런타임 확인

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

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

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

워크플로

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. 각 편집 후 변경 사항을 요구사항, 명세, 실행 계획, 수용 프로토콜, 추적성, 비목표와 비교합니다.

16. 계획 편차를 decision_log.md에 기록합니다.

17. 검증을 실행하고 검토 패킷을 내보냅니다.

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

Codex MCP 구성

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

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

확인

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

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