Прикладная часть 13. Практический зачёт: собрать production SDD-контур

Статус: Рекомендация. Эта часть не вводит новый механизм. Она собирает второй том в один проверяемый маршрут по образцу практического зачёта первого тома. Цель — доказать, что вы можете пройти production-сценарий SDD от legacy-следа до решения, которое допускается фактами, а не уверенностью агента.

Зачёт лучше выполнять после глав 1–12. Если вы читаете том выборочно, используйте эту часть как карту недостающих артефактов: любой пробел в пакете capstone/ показывает, к какой главе нужно вернуться. Если неясно, как связать файлы в один кейс, вернитесь к части 0: она задаёт лабораторную рамку AgentClinic-production и объясняет, что считать учебным минимумом.

Цель

К концу зачёта у вас должен быть один связный пакет доказательств для AgentClinic-production:

• восстановленное требование с провенансом;
• исправленная контролируемо дефектная спецификация;
• constitution.md с неизменяемыми и изменяемыми правилами;
• минимум один контрпример и одна запись дуэли;
• локальный Spec CI или его runnable-аналог;

• judgment.md или запись прецедента;
• бюджетный и anti-Goodhart-контроль;
• шлюз готовности (readiness gate) и список блокеров;
• диагностический чек-лист антипаттернов.

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

Итоговый кейс

Работайте с одним production-инцидентом. Рекомендуемый основной кейс — high_memory_usage, потому что он проходит через нормализацию вебхука, readiness-шлюз и пробный прогон из части 11. autoscale_200pct можно выбрать вместо него, если вы делаете зачёт вокруг дуэли и файлового арбитража. Не смешивайте два кейса в одном зачёте.

Минимальная постановка:

• AgentClinic-production получил алерт от Grafana или PagerDuty;
• legacy-следы неполны: часть правил известна из пост-мортема, часть — из QWEN.md, часть — из устной практики;
• автоматическая ремедиация выглядит полезной, но может нарушить лимит радиуса последствий, бюджет ярусов или anti-Goodhart-инвариант;
• перед допуском нужно доказать, что спецификация, план, проверка и readiness не противоречат друг другу.

Структура пакета

Создайте каталог:

capstone/
  README.md
  genealogy.md
  poisoned-spec.md
  fixed-spec.md
  constitution.md
  validation.md
  judgment.md
  budget-note.md
  goodhart-note.md
  readiness.md
  antipattern-audit.md

Если работаете в реальном проекте, имена можно адаптировать. Но роли файлов должны остаться теми же: происхождение, дефект, исправление, правила, факты, арбитраж, бюджет, метрики, готовность и аудит процесса.

Перед заполнением своего пакета откройте [examples/templates/capstone-dossier.md](examples/templates/capstone-dossier.md). Это эталонный «золотой путь» первого прохода по high_memory_usage: он показывает, сколько фактов достаточно для зачёта, не превращая главу в большой production-документ.

Используйте его как ограничитель размера. Если ваш capstone/README.md или validation.md выходит заметно длиннее эталона, сначала проверьте, не попали ли в него артефакты полного трека: scorebook, metric_network, полный out/duel.json, весь budget plan или подробная история чата.

В главах 1–12 ищите блок «Как это попадает в capstone/». Он важнее полного списка артефактов главы при первом проходе. Если блок говорит перенести одну строку, одного принятого кандидата, один защитный инвариант или один readiness-вердикт, не расширяйте пакет доказательств до всех файлов полного production-трека.

Перед началом запишите в capstone/README.md пять строк-заготовок:

Incident-case:
Главный риск:
Ключевая проверка:
Главный блокер:
Следующее исправление:

Для маршрута по умолчанию первая строка должна быть Incident-case: high_memory_usage. Если выбран autoscale_200pct, укажите это сразу и не добавляйте high_memory_usage как второй равноправный кейс.

Если эти строки нельзя заполнить, пакет ещё не собран вокруг одного кейса.

Минимальный учебный сценарий

Учебный кейс

Возьмите high_memory_usage из [examples/real-api/](examples/real-api/) как маршрут по умолчанию. Если вместо него выбран autoscale_200pct из [examples/tribunal/](examples/tribunal/), прямо напишите это в capstone/README.md и не добавляйте high_memory_usage как второй равноправный кейс. Цель — собрать не идеальный production-процесс, а маленький воспроизводимый пакет доказательств: один инцидент, один дефект спецификации, один контрпример или readiness-вывод, один список блокеров.

Подготовка

• Прочитайте README выбранного runnable-примера.
• Скопируйте нужные шаблоны из [examples/templates/](examples/templates/).
• Создайте пустой каталог capstone/.
• Заранее решите, что будет считаться блокером: слабый evidence_ref, конфликт приоритета, нарушение manual_review_floor, превышение бюджета или readiness ниже порога.

Шаги

1. Заполните capstone/genealogy.md: одно восстановленное требование, минимум два источника, уровень уверенности и открытый вопрос.
2. Создайте capstone/poisoned-spec.md: внесите ровно один дефект — конфликт приоритета, цикл или скрытый выход за границы.

1. Создайте capstone/fixed-spec.md: исправьте дефект правилом-исключением, схемой или явным отрицательным требованием.
2. Заполните capstone/constitution.md: минимум два immutable_principles, одно mutable_rule с ttl, max_scope, rollback_condition, и короткий governance_protocol.
3. Запустите один runnable-пример для выбранного кейса.

• Для high_memory_usage — команды из раздела «Минимальный учебный сценарий» части 11: один положительный readiness, один блокирующий stateful, один разрешённый и один запрещённый dry-run. Команды с readiness_block_stateful.json и delete_namespace ожидаемо возвращают код 1 — это не поломка примера, а источники блокеров для capstone/validation.md.
• Для autoscale_200pct — три скрипта из раздела «Минимальный учебный сценарий» части 8: run_duel.py, check_invariants.py, write_judgment.py.

Полностью команды не дублируются здесь, чтобы зачёт не превратился в копипаст. Если у вас открыты обе главы, идите по их шагам в том же порядке.

1. Перенесите результат в capstone/validation.md: команду, ожидаемый факт, фактический результат и блокер допуска. Для real-api положительный readiness-прогон показывает допустимый путь, readiness_block_stateful.json даёт stateful-блокер, а delete_namespace показывает границу заранее согласованных действий. Если команда была из другого runnable-каталога, объясните, какой принцип переносится в основной кейс.
2. Заполните capstone/judgment.md: вердикт APPROVE, DENY или DEFERRED, причина, evidence_ref, следующий шаг. judgment.md — это запись решения по конкретному спору; повторяющийся класс конфликта дополнительно фиксируется в capstone/precedents.md пятью полями (case_id / verdict / evidence_ref / applies_to / next_check), см. часть 8.
3. Добавьте capstone/budget-note.md: что произойдёт при отказе local-coder, какой лимит защищает frontier-reviewer, когда срабатывает аварийный режим.
4. Добавьте capstone/goodhart-note.md: какая целевая метрика может начать врать и какая guard-метрика её ограничивает.

1. Заполните capstone/readiness.md: итоговая оценка, блокирующие условия, почему 23/25 с доказательствами лучше, чем 25/25 без них.
2. Пройдите диагностический чек-лист из части 12 и запишите три риска в capstone/antipattern-audit.md.
3. Завершите capstone/README.md: один абзац контекста, список команд, итоговый статус и список исправлений до production.

После шага 12 перечитайте capstone/README.md как новый ревьюер. В нём должны быть видны не все подробности, а маршрут проверки: откуда взялось требование, что было сломано, какая команда запускалась, какой вердикт получился и что блокирует production-допуск.

Минимальный capstone/README.md для первого прохода помещается в пять строк:

Incident-case: high_memory_usage
Главный риск: auto-remediation без полного audit_trace или backup evidence
Ключевая проверка: python3 scripts/check_readiness.py --readiness fixtures/readiness_block_stateful.json
Главный блокер: stateful workload без backup_verified блокирует действие
Следующее исправление: добавить evidence_ref для backup и повторить dry-run

Контрольный факт

Пакет годится для зачёта, если другой читатель может открыть capstone/README.md и ответить на пять вопросов без истории вашего чата:

1. Какое требование восстанавливалось и откуда взялись доказательства?
2. Какой дефект был внесён и чем он исправлен?
3. Какая проверка реально запускалась?
4. Почему вердикт файлового арбитража или шлюз готовности именно такой?
5. Что остаётся блокером перед production?

Если хотя бы на один вопрос нужен устный комментарий автора, пакет ещё не готов.

Ревьюируемый след

out/ из runnable-примеров не переносите в итоговый пакет. Финальный след — короткий capstone/ с файлами, которые отвечают на пять вопросов выше. Если вы работаете в своём репозитории, фиксируйте именно этот пакет доказательств, а не локальные каталоги прогонов.

Быстрые вопросы

Ответьте письменно, без Qwen Code.

1. Чем genealogy.md отличается от validation.md?
2. Почему контролируемо дефектная спецификация должна содержать ровно один дефект?
3. Когда теневая спецификация может попасть в QWEN.md, но не в requirements.md?
4. Почему Spec CI не заменяет Верификатора?
5. Что обязан содержать judgment.md, чтобы спор можно было повторить?

1. Почему manual_review_floor нельзя обнулять даже при хороших KPI?
2. Что делает token_health полезнее простого счёта потраченных токенов?
3. Почему readiness-балл без evidence_ref не является допуском?
4. Когда DEFERRED лучше, чем формальный APPROVE?
5. Какой антипаттерн из части 12 чаще всего разрушает ваш пакет?

Критерии оценки

Оцените пакет по 30 баллам. Пять категорий по 6 баллов отражают пять опор production-SDD: происхождение факта, его проверяемость, разрешение спора, удержание ограничителей и ясность пакета. Равный вес означает, что одна сильная категория не компенсирует слабую, а внутри каждой категории 6 пунктов покрывают типичные слепые зоны без излишней детализации.

Провенанс и спецификация — 6 баллов

• 1: genealogy.md связывает требование с минимум двумя источниками;
• 1: спорные факты не выданы за approved-требования;
• 1: poisoned/fixed-пара содержит один дефект и одно исправление;
• 1: исправление меняет проверяемый артефакт, а не только объяснение;
• 1: constitution.md разделяет immutable и mutable-слои;
• 1: mutable-правило имеет ttl, max_scope, rollback_condition.

Проверки и факты — 6 баллов

• 1: запущен минимум один runnable-пример из book2/examples/;
• 1: результат перенесён в validation.md с командой и ожиданием;
• 1: отрицательный или блокирующий сценарий описан явно;
• 1: Spec CI или его аналог проверяет связь требования и плана;
• 1: готовность или пробный прогон (dry-run) не обходят блокирующие условия;
• 1: out/ не выдан за ревьюируемый артефакт.

Арбитраж и роли — 6 баллов

• 1: judgment.md содержит вердикт, причину и evidence_ref;
• 1: роли Верификатор/Имплементор/Safety не смешаны, Координатор только ведёт judgment.md;
• 1: контрпример минимален или явно указан как не минимальный;
• 1: при споре есть DEFERRED или следующий проверяемый шаг;
• 1: прецедент записан так, чтобы его можно было применить снова;
• 1: Safety-veto или его аналог нельзя обойти большинством голосов.

Production-ограничители — 6 баллов

• 1: бюджетный сценарий описывает отказ дешёвого яруса;
• 1: frontier-reviewer ограничен по риску или квоте;
• 1: anti-Goodhart-пара связывает KPI и guard-метрику;
• 1: manual_review_floor сохранён;
• 1: readiness-балл сопровождается доказательствами;
• 1: откат (rollback) или блокер указан до допуска.

Ясность пакета — 6 баллов

• 1: capstone/README.md объясняет кейс без внешнего чата;
• 1: список команд можно повторить локально или заменить ссылкой на runnable-аналог;
• 1: блокеры отделены от улучшений;
• 1: ссылки на главы и шаблоны помогают вернуться к источнику;
• 1: диагностический чек-лист части 12 пройден;
• 1: пакет не содержит лишних механизмов, не связанных с выбранным кейсом.

25–30 баллов — production SDD-контур готов к командному ревью.

19–24 — контур пригоден для учебного прохода, но требует усилить доказательства или блокеры.

Ниже 19 — вернитесь к минимальным сценариям глав 1–12 и уменьшите размер кейса.

Что делать после зачёта

Не переносите весь пакет в production как шаблон целиком. Выберите два-три самых полезных артефакта и автоматизируйте их первыми:

• если чаще теряется происхождение требований — начните с genealogy.md;
• если CI пропускает слабые спецификации — начните со Spec CI;
• если споры повторяются — начните с judgment.md и precedents.md;
• если KPI начинают врать — начните с anti-Goodhart validation.md.

Главный результат второго тома — не набор терминов, а привычка требовать проверяемый след перед допуском опасного автоматического действия.