specs/openspec/specs/engineering-change-governance/spec.md

engineering-change-governance Specification

Purpose

Определяет соразмерные и проверяемые правила инженерных решений AI-агентов, чтобы WealthLedger переиспользовал зрелые решения, тестировал существенные риски и локально отклонял код, нарушающий инварианты проекта.

Requirements

Requirement: Готовые решения оцениваются до собственной реализации

Изменение, которое вводит или существенно заменяет механизм авторизации, безопасности, хранения данных, внешней интеграции, наблюдаемости, кэширования, конкурентного доступа либо общей инфраструктуры и tooling, MUST до утверждения архитектурного решения оценить существующие поддерживаемые решения. Оценка MUST сравнивать применимые варианты по соответствию требованиям, зрелости, безопасности, эксплуатационной стоимости, ограничениям и стоимости миграции. Собственная реализация SHALL допускаться только когда подходящего готового решения нет либо его существенная несовместимость явно зафиксирована вместе с рисками такого выбора. Для изменений вне перечисленных областей отдельная оценка MUST NOT быть обязательной без конкретного риска или дорогостоящего необратимого решения.

Scenario: Существует совместимое зрелое решение

• WHEN change затрагивает одну из обязательных для оценки областей и найдено поддерживаемое решение, удовлетворяющее требованиям без неприемлемых ограничений
• THEN архитектурное решение использует это решение либо явно объясняет, почему его совокупная стоимость или риск выше выбранной альтернативы

Scenario: Подходящего решения нет

• WHEN рассмотренные зрелые решения не выполняют существенные требования или создают неприемлемый риск
• THEN собственная реализация допускается только после фиксации проверенных вариантов, конкретных разрывов, принятых рисков и условия повторного пересмотра

Scenario: Изменение не требует solution assessment

• WHEN change не относится к обязательным областям и не содержит отдельного дорогостоящего или необратимого решения
• THEN отсутствие формальной оценки готовых решений не блокирует SDD lifecycle и не создаёт дополнительный артефакт ради процесса

Requirement: Тестирование определяется риском поведения

План изменения MUST требовать автоматизированные тесты для security- и privacy-sensitive поведения, денежных расчётов, целостности и миграции данных, конкурентного доступа, публичных контрактов, критических пользовательских сценариев и подтверждённых регрессий. Изменение MUST NOT требовать новый тест только из-за появления или изменения файла. Простые декларативные структуры, DTO без собственной логики, тонкие адаптеры, прямолинейная оркестрация, hygiene scripts и поведение сторонней библиотеки SHALL проверяться существующим контрактным или интеграционным gate без отдельного unit test, если они не содержат самостоятельного ветвления, преобразования, инварианта либо ранее найденной регрессии. Существующий frontend coverage gate SHALL использоваться только как anti-regression constraint, а не как основание создавать малоценные тесты. Backend MUST NOT получать общий числовой coverage threshold только ради симметрии или процессного соответствия; такой gate требует отдельного утверждённого обоснования защищаемого риска.

Scenario: Изменяется критический инвариант

• WHEN change меняет безопасность, денежный результат, целостность данных, конкурентное поведение, публичный контракт, критический journey или исправляет регрессию
• THEN checklist содержит тест соответствующего уровня, который наблюдаемо подтверждает новый или исправленный результат

Scenario: Добавлен простой служебный скрипт

• WHEN скрипт только последовательно запускает существующие проверяемые команды, не содержит самостоятельной бизнес-логики, ветвления или преобразования данных
• THEN отдельный unit test для скрипта не является обязательным, а корректность результата подтверждается выполнением самого локального gate

Scenario: Coverage можно повысить только малоценным тестом

• WHEN новый тест повторял бы декларативную структуру или внутреннее поведение зависимости и не защищал бы самостоятельный риск проекта
• THEN агент не создаёт такой тест только ради процента coverage и сохраняет существующий anti-regression threshold

Scenario: Backend не имеет числового coverage threshold

• WHEN обязательные risk-based тесты backend проходят, а отдельный измеримый риск для общего coverage threshold не утверждён
• THEN отсутствие глобального числового threshold не считается пробелом и не блокирует change

Requirement: Enforceable Engineering Invariant имеет локальную проверку

Каждое правило, обозначенное как обязательный Enforceable Engineering Invariant, MUST иметь детерминированную non-mutating локальную проверку и MUST блокировать завершение работы при нарушении. Такие инварианты SHALL охватывать применимые правила стиля проекта, статическую корректность, архитектурные границы, публичные контракты, безопасность и критические доменные ограничения. Рекомендация, которую невозможно надёжно проверить локально, MUST быть обозначена как guidance и MUST NOT выдаваться за hard guardrail. Проверка самого hard guardrail MUST иметь evidence, что она отклоняет хотя бы одно контролируемое репрезентативное нарушение; это evidence MUST NOT превращаться в требование unit-тестировать каждый вспомогательный скрипт.

Scenario: Агент пишет код не в стиле проекта

• WHEN изменение нарушает проверяемое правило форматирования, lint, типов, импортных границ или публичного контракта проекта
• THEN обязательный локальный gate завершается с ошибкой и работа не считается завершённой

Scenario: Правило является только рекомендацией

• WHEN команда не может определить детерминированную локальную проверку сформулированного предпочтения
• THEN правило документируется как guidance, а агент не использует его как самостоятельную причину объявить корректную реализацию невалидной

Scenario: Добавляется новый hard guardrail

• WHEN change объявляет новое правило блокирующим
• THEN completion evidence подтверждает как успешный compliant case, так и обнаружение контролируемого representative violation

Requirement: Труднообратимое изменение имеет rollback contract

Design MUST определять rollback trigger, rollback actions, data safety и rollback verification, когда change затрагивает auth или security behavior, data integrity или migration, public contract либо другое существенно труднообратимое решение. Rollback contract MUST учитывать данные и совместимость, созданные после поставки change, и MUST быть выполним без нового неутверждённого архитектурного решения. Когда указанные риски неприменимы, Design SHALL фиксировать конкретную проверяемую причину N/A и MUST NOT создавать отдельный artifact или формальный rollback plan ради процесса.

Scenario: Change мигрирует данные

• WHEN Design изменяет хранимые данные способом, который может потребовать возврата
• THEN он определяет trigger, безопасные действия отката, судьбу новых данных и проверку восстановленного состояния до утверждения Tasks

Scenario: Change меняет публичный контракт

• WHEN Design вводит несовместимое изменение публичного контракта
• THEN rollback contract объясняет восстановление совместимости и проверяемое условие успешного отката

Scenario: Rollback risk отсутствует

• WHEN change не затрагивает auth, security, данные, публичный контракт или другое труднообратимое решение
• THEN Design указывает конкретную причину N/A без создания дополнительного rollback artifact

Requirement: Token-efficient execution сохраняет delivery evidence

Project-owned agent guidance SHALL направлять AI-агента к совместному получению независимых read-only evidence, targeted чтению найденных диапазонов, сужению diff по затронутым paths и компактному представлению успешных command results. Такая оптимизация MUST сохранять exit status, существенный observed outcome и всё evidence, необходимое для текущего решения, canonical gate, semantic verification или independent review. При failure, неоднозначности или существенном расхождении workflow SHALL расширить diagnostics соразмерно наблюдаемой проблеме. Предпочтения по batching и размеру output SHALL оставаться guidance и MUST NOT блокировать корректную delivery без отдельного детерминированного hard guardrail.

Scenario: Требуются несколько независимых read-only результатов

• WHEN агент до следующего смыслового решения заранее знает несколько независимых source, status или diff запросов
• THEN workflow направляет получить их одним evidence batch и вернуть только релевантные результаты без промежуточного model round-trip после каждого запроса

Scenario: Canonical gate проходит успешно

• WHEN обязательная verification command завершается успешно и её полный output не нужен для последующего смыслового решения
• THEN agent context сохраняет точную command identity, exit status и существенную итоговую summary без обязательного переноса полного verbose log

Scenario: Verification завершается ошибкой

• WHEN compact command result сообщает failure или не позволяет определить причину
• THEN workflow получает достаточные diagnostics для локализации ошибки и не скрывает необходимые failure details ради соблюдения output budget

Scenario: Independent review требует полный relevant diff

• WHEN reviewer должен проверить весь фактический scope реализации против утверждённых artifacts
• THEN token-efficient guidance не исключает relevant diff или evidence, необходимые для semantic conclusion

Requirement: Token-efficiency оценивается на завершённых фазах вместе с качеством

Token-efficiency pilot SHALL сравнивать resource usage на успешно завершённую SDD-фазу, включая cumulative input, количество model calls, глубину контекста и объём tool outputs, вместе с outcome indicators: результатами обязательных gates, количеством циклов исправления и findings independent review. Снижение resource usage MUST NOT считаться улучшением, если сопоставимая работа чаще не завершается, требует больше исправлений либо ухудшает verification или review outcomes. До накопления репрезентативных сопоставимых наблюдений числовые budgets SHALL оставаться guidance и MUST NOT становиться самостоятельным completion blocker.

Scenario: Resource usage снизился без ухудшения результата

• WHEN pilot показывает меньше cumulative input или model calls на сопоставимую завершённую фазу, а canonical gates, fix cycles и review findings не ухудшились
• THEN изменение может быть представлено Engineering Owner как наблюдаемое улучшение с указанным measurement scope и ограничениями

Scenario: Дешёвая фаза создаёт больше rework

• WHEN вариант workflow использует меньше токенов, но чаще получает failed gates, дополнительные fix cycles или более серьёзные review findings
• THEN pilot не представляет этот вариант как token-efficiency improvement

Scenario: Наблюдений недостаточно для обязательного порога

• WHEN pilot ещё не содержит репрезентативных сопоставимых завершённых фаз или надёжной локальной проверки
• THEN model-call, context-depth и tool-output budgets остаются guidance и не блокируют delivery

Scenario: Числовой budget предлагается как hard guardrail

• WHEN последующий change предлагает сделать token budget обязательным completion condition
• THEN он должен определить защищаемый риск, детерминированную non-mutating проверку и controlled compliant/violation evidence по общему contract Enforceable Engineering Invariant