Контрольный список развёртывания

Шаги предварительной проверки перед развёртыванием экосистемы Apothem на новой машине, её совместным использованием с другими или признанием её готовой к продакшену.

1. Валидность YAML

• Все файлы правил разбираются без ошибок YAML — блок frontmatter открывается ---, закрывается --- и не содержит осиротевшего контента за пределами блока
• Все файлы делегированных исполнителей разбираются без ошибок YAML
• Все файлы команд разбираются без ошибок YAML
• Все файлы навыков SKILL.md разбираются без ошибок YAML

Проверка: python scripts/dev/validate_ecosystem.py разбирает frontmatter каждого артефакта и помечает ошибки YAML и отсутствующие обязательные поля. Для специальной проверки осиротевших элементов списка: rg -n "^- " src/apothem/rules/*.md.

2. Полнота frontmatter

Для каждого типа артефакта убедитесь, что обязательные поля присутствуют:

Правила (src/apothem/rules/*.md)

• name — идентификатор в kebab-case, совпадающий с именем файла
• version — semver MAJOR.MINOR.PATCH (например, "X.Y.Z")
• updated — дата ISO 8601 (например, "2026-04-20")
• description — однострочное резюме
• scope — "always-on" или "path-filtered"
• portability — "universal", "universal-with-windows-caveats", "unix-only" или "windows-only"
• pathFilter — присутствует и является корректной glob-строкой для правил с фильтрацией по пути; отсутствует для всегда активных правил

Команды (src/apothem/commands/*.md)

• name — имя команды в kebab-case
• version, updated, description, argument-hint присутствуют
• disable-model-invocation присутствует и намеренно (true для команд, предназначенных только для руководства)
• effort, portability проверены там, где присутствуют (необязательны по schema)

Делегированные исполнители

Путь:

src/apothem/agents/*.md

• name, version, updated, description присутствуют
• tools — список разрешённых инструментов через запятую
• disallowedTools — явно перечисляет запрещённые инструменты
• maxTurns — задан (с комментарием-обоснованием, если > 10)
• permissionMode — НЕ должен быть "bypassPermissions" — используйте "default"
• memory: false, если постоянная память не предусмотрена намеренно

Навыки (src/apothem/skills/*/SKILL.md)

• name, version, updated, description присутствуют
• user-invocable — объявлено (true/false)

3. Безопасность

• Ни один делегированный исполнитель не использует permissionMode: "bypassPermissions" — это обходит интерактивное подтверждение для операций Write/Bash
• Списки tools исполнителя минимальны — только те инструменты, которые исполнителю действительно нужны
• Исполнители с доступом к Bash обоснованы и имеют ограничения maxTurns
• Ни в одном артефакте нет жёстко прописанных путей, токенов или секретов
• Хуки в settings.json имеют разумные таймауты (≤ 60 секунд) и не выполняют произвольный код из пользовательского ввода

4. Целостность перекрёстных ссылок

• Каждое правило, перечисленное в таблице src/apothem/rules/, существует на диске по указанному пути
• Каждая команда, перечисленная в таблице src/apothem/commands/, существует на диске
• Каждый делегированный исполнитель, перечисленный в таблице реестра src/apothem/agents/, существует на диске
• Каждый навык, перечисленный в таблице src/apothem/skills/, существует на диске
• Каждый хук в таблице src/apothem/hooks/ имеет соответствующую запись в settings.json
• Все файлы src/apothem/rules/*.md, на которые ссылается столбец Implements в CLAUDE.md, существуют

5. Покрытие предписаний

• Каждое CM-N, упомянутое в CLAUDE.md, имеет место применения (либо файл правила, либо явное встроенное определение)
• Ни один файл правила не противоречит другому (особенно в части масштабирования серьёзности)
• Разграничение трёх граней CM-21 соблюдается — ни одно правило не претендует на владение гранью CM-21 другого правила

6. Функциональные дымовые тесты

Сначала запустите поверхность проверки на Python — она быстрая, автономная и отлавливает структурные регрессии:

• pytest tests — модульные тесты среды выполнения хуков, все зелёные
• python scripts/dev/validate_hooks.py — проверка структуры хуков + гигиены только-Python пройдена
• python scripts/dev/validate_ecosystem.py — полное дерево + frontmatter + проверки делегированных хуков пройдены
• python scripts/dev/chaos_pass.py — каждая настроенная команда хука возвращает корректный JSON-конверт при деградированных входных данных

Затем живые сценарии:

• /plan-spec --interactive (или /plan-spec <sample-file>) — завершает приём/уточнение без ошибок уровня команды
• /plan-generate --dry-run — выдаёт предпросмотр структуры без записи файлов
• /plan-status на полном наборе плана — возвращает точные количества фаз
• Диспетчеризация делегированного исполнителя: исполнитель codebase-explorer, вызванный с небольшим охватом, завершается в пределах maxTurns и возвращает структурированный вывод

7. Актуальность документации

• CHANGELOG.md (в корне экосистемы) отражает каждое изменение артефакта с момента последнего выпуска; раздел следующего выпуска заполнен до того, как ляжет тег, или каждое изменение уже включено в опубликованный раздел
• site/content/docs/developer-guide.mdx точно описывает текущую структуру артефактов
• site/content/docs/reference/artifact-schema.mdx соответствует полям frontmatter, фактически присутствующим в артефактах
• site/content/docs/reference/settings-reference.mdx соответствует фактической конфигурации хуков в settings.json
• README.md согласован с деревом на диске

8. Переносимость (при совместном использовании с другими)

• Все пути в командах хуков не зависят от среды или используют раскрытие ~
• Команды хуков используют форму exec и избегают строк команд, специфичных для конкретной оболочки
• Ни в одном артефакте нет жёстко прописанных путей C:\Users\username или /home/username
• settings.json использует одну таблицу охвата событий хуков и канонический путь к модулю диспетчеризации

9. Согласование версий

• version в CLAUDE.md является наивысшей среди всех артефактов в дереве (или, по соглашению, равна версии самого недавно повышенного артефакта)
• version каждого артефакта совпадает с заявленным semver (MAJOR.MINOR.PATCH)
• CHANGELOG.md содержит ровно запись о выпуске для целевой версии перед тегированием
• Поле updated каждого артефакта соответствует дате его последнего изменяющего поведение редактирования или позже
• Ни один артефакт не несёт version ниже версии, на которой его в последний раз изменяли (без регрессий)
• src/apothem/skills/plan-suite/SKILL.md и src/apothem/skills/plan-suite/master-template.md закреплены на одной и той же линии версии шаблона

Утверждение

Развёртывание одобрено: ___________________ Дата: ___________________ Развёрнутая версия экосистемы: ___________________