Codex Protocol Guardian

Пакет управления MCP для поддержания соответствия задач разработки Codex пакету требований, одному активному субъекту-кандидату, исполняемой спецификации, независимым шлюзам и прослеживаемому пакету ревью.

Этот пакет не порождает дочерних агентов, не экспортирует ролевые промпты, не выполняет задачи и не записывает состояние выполнения. Он проверяет свидетельства управления и может добавлять неизменяемые архивы замечаний; он никогда не одобряет собственную работу. Устаревшие модули ролей, диспетчеризации и субагентов не входят в поверхность пакета.

Структура

<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/*, включая шаблон исполняемой спецификации и декларацию границ модулей и коммуникационной емкости, требуемую до проектирования файлов.

• 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. Назначьте стабильные идентификаторы требований (R1, R2, ...) и идентификаторы приемки (A1, A2, ...).

4. Заморозьте декомпозицию требований перед написанием проектного решения. Каждый пункт должен иметь наблюдаемый результат, границы, не-цели, зависимости и идентификатор приемки.

5. Проверьте проектное решение на соответствие замороженной декомпозиции. Проект должен выбирать среди альтернатив и объявлять публичные интерфейсы, обязанности, запрещенные функции, разрешенные файлы и дайджест области.

6. Создайте specification.md на основе упакованного стандарта исполняемой спецификации. Выполните каждое правило на проекции производственного ввода перед планированием кода.

7. Поддерживайте один активный субъект-кандидат. Архивируйте отклоненные и замещенные субъекты, связывая их через replaces и superseded_by.

8. Существенное замечание по требованиям, проектированию или области создает преемника; незначительные замечания могут быть исправлены в текущем кандидате.

9. Каждый управляемый пакет должен содержать журнал замечаний. Повторяющиеся отпечатки, унаследованные от цепочки преемников, блокируют приемку до появления доказательств первопричины.

10. Отчитывайтесь по независимым шлюзам для расползания области, независимости ревью, полноты CI, замкнутости прослеживаемости, происхождения артефактов и границы приемки во время выполнения. Полнота CI также требует внешних свидетельств платформы: защита веток, обязательные проверки, одобрение CODEOWNER, отклонение устаревших ревью и политика очереди слияния.

11. Фиксируйте метрики процесса отдельно: время в состоянии, итерации ревью, количество замещенных, доля отклонений, открытые блокеры, время выполнения, частота отказов изменений и время восстановления.

12. Перед каждым редактированием объявляйте фазу, идентификаторы требований, идентификаторы приемки, разрешенные файлы и ожидаемые свидетельства.

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, чтобы посторонняя редактируемая установка с тем же именем дистрибутива не могла дать ложный зеленый результат.