docs: make project documentation self-contained

development/engineering-governance.md

@@ -1,103 +1,82 @@
-# Engineering governance
+# Принципы изменения и проверки системы
 
-Это общий owner решений о scope, dependencies, testing и проверке результата.
-Работа начинается с задачи пользователя и выполняется напрямую. OpenSpec/SDD
-не обязателен; прежняя [процедура](openspec-authority-and-lifecycle.md) доступна
-только по явному запросу. Исторические artifacts не переписываются.
+Ожидаемый результат определяется задачей пользователя. Сопровождение сохраняет
+ответственность подсистем, безопасность, точность данных и проверяемость результата.
+OpenSpec остаётся [необязательным средством согласования](openspec-authority-and-lifecycle.md);
+исторические свидетельства не становятся обязательной процедурой новой задачи.
 
 ## Выбор реализации
 
-Читай этот раздел при новой abstraction/dependency, refactor, multi-module
-изменении или неоднозначном ownership.
+Связное поведение принадлежит ответственной подсистеме. Существующая возможность
+используется повторно, если сохраняет нужный смысл и инварианты. Новая граница
+оправдана самостоятельной ответственностью, общей потребностью нескольких
+потребителей либо необходимостью отделить доступ и целостность данных.
 
-1. Требуемое поведение уже существует — используй его.
-2. У поведения есть подходящий owner/helper — расширь его, сохранив связность.
-3. Задачу решает платформа, стандартная библиотека или принятая dependency — используй её.
-4. Иначе добавь небольшую реализацию там, где принадлежит инвариант.
-5. Если текущая структура мешает правильному ownership, сделай необходимый связный refactor с проверкой сохранения поведения.
-
-Оптимизируй ясность всей системы. Число файлов/строк само по себе не определяет
-качество: coherent refactor лучше дублированного guard в нескольких callers.
-
-**Безопасный путь:** при неопределённом будущем reuse оставь код у ближайшего
-подходящего владельца. Выделение оправдано текущей общей ответственностью,
-несколькими реальными consumers или необходимой trust/transaction boundary.
-Один consumer не запрещает модуль с самостоятельным инвариантом, но не оправдывает
-interface/factory/registry только для воображаемой расширяемости.
-
-Примеры: фильтр одного экрана остаётся page-local; чистое денежное преобразование
-использует существующий decimal helper; запрос Prisma не требует generic repository.
-Security validation, доступность, error handling и защита данных сохраняются
-даже в маленькой реализации.
+Простота оценивается по ясности всей системы и стоимости сопровождения,
+а не по размеру изменения. Предполагаемая будущая возможность сама по себе
+не оправдывает новую подсистему. Упрощение сохраняет валидацию, доступность,
+обработку ошибок и защиту от потери данных.
 
 ## Dependencies
 
-Перед новой dependency проверь installed stack и существующий helper. Если
-подходящего решения нет, оцени поддерживаемую библиотеку, совместимость,
-maintenance/security cost и точную недостающую возможность. Собственный код
-выбирай по совокупной стоимости, а не ради отсутствия dependency любой ценой.
-
-Версии и scripts принадлежат package.json/lockfile. Frontend сохраняет exact
-versions; backend использует свою текущую policy. Transitive package не считается
-прямо принятой dependency. Не меняй весь lockfile или инструментарий ради
-устаревшей рекомендации в Markdown. Новые сервисы, CI и browser mocking требуют
-задачи, в которой они действительно нужны.
+При выборе внешней зависимости учитываются текущая потребность, совместимость,
+поддержка, безопасность и стоимость сопровождения. Использование принятой
+платформы может быть проще собственной реализации; зависимость ради одной
+воображаемой будущей возможности не является самостоятельной потребностью.
+Новый сервис или общая инфраструктура должны решать актуальную задачу.
 
 ## Risk-based testing
 
-Автоматический тест обязателен для изменённого security/privacy поведения,
-денежных вычислений, data integrity/migration, concurrency, публичного контракта,
-критического journey и подтверждённой регрессии.
+Изменения безопасности и приватности, денежных расчётов, целостности данных,
+миграций, конкурентного доступа, публичного контракта, критического сценария
+и подтверждённой регрессии требуют автоматической проверки соответствующего
+риска на наблюдаемой потребителем границе.
 
-Выбирай самую дешёвую надёжную границу, наблюдаемую потребителем. Тест нужен
-для собственного branching, преобразования или инварианта; не для каждого
-DTO, декларативной конфигурации, thin adapter или поведения библиотеки.
-Меняющийся тест тоже активирует testing convention, даже без production diff.
-Frontend coverage — anti-regression constraint; backend общего threshold не имеет.
-Не пиши тесты только ради процента или повторения Markdown.
+Статические проверки не доказывают финансовую или функциональную корректность.
+Покрытие frontend служит ограничителем регрессий; для backend общего числового
+порога нет. Проверки поведения библиотеки или проценты сами по себе не заменяют
+проверку собственного инварианта системы.
 
 ## Проверка результата
 
-В итерации используй targeted check из применимого convention. Перед завершением
-запусти `npm run verify` каждого изменённого code/docs repo под его `.nvmrc`
-после lockfile install. Для HTTP contract — дополнительно
-[contract checks](runtime-openapi-verification.md). Общего CI сейчас нет.
+Результат оценивается по исходной задаче: сохранены ли смысл данных и контракты,
+правильно ли разграничен доступ, учтены ли ошибки и доступность интерфейса.
+Проверки приложений и документации дополняются
+[согласованием HTTP-контракта](runtime-openapi-verification.md), если он меняется.
+Общего CI сейчас нет.
 
-Проверь actual staged/unstaged/new scope и результат против задачи: ownership,
-сохранение данных/контрактов, ошибки, доступность, отсутствие лишних abstractions.
-Неизменившийся успешный gate можно использовать повторно, если известны команда,
-его полный relevant input scope и неизменные prerequisites; при сомнении выполни
-его снова. Auto-fix не заменяет non-mutating gate.
+Успешная проверка применима к тому состоянию системы и тем предпосылкам,
+на которых выполнена. При их изменении старое свидетельство не доказывает
+новый результат. Автоматическое исправление материалов и проверка без их
+изменения — разные действия.
 
-В ответе достаточно: что поставлено, как проверено, какие ограничения остались.
-Не создавай role records, fingerprints всех repositories, Completion Evidence
-или delivery commits только ради процесса. Существующие рабочие изменения
-других задач сохраняются. Нужный review не заменяется количеством checkboxes.
+[Влияние на документацию](documentation.md#обновление-вместе-с-кодом) входит
+в оценку результата: описанные понятия, сценарии, решения и ограничения
+обновляются вместе с системой. Отсутствие влияния может быть обоснованным
+результатом. Отчёт о поставке различает выполненное, проверенное и остающиеся
+ограничения; количество формальных отметок не заменяет смысловую проверку.
 
 ## Guardrails и local gates
 
-- **Автоматический invariant:** существующий deterministic checker блокирует нарушение в фактическом scope с документированными исключениями.
-- **Обязательное semantic правило/процедура:** исполнитель и reviewer проверяют решение; отсутствие checker не переводит i18n, validation или authorization в пожелание.
-- **Guidance:** необязательное предпочтение, например эстетический выбор между эквивалентными вариантами.
-
-Не обещай enforcement, отсутствующий в config/tests. Новая автоматическая проверка
-оправдана реальным риском или повторяющимся дефектом, а не возможностью написать
-ещё один checker. Механические правила принадлежат tools; выбор правильного owner
-и полезного теста остаётся semantic judgement.
+Автоматические проверки гарантируют только свойства, охваченные их областью.
+Смысловые требования — например, правильный владелец данных, авторизация,
+локализация и полезность выбранных проверок — требуют отдельной оценки.
+Предпочтение между равноценными вариантами отличается от обязательного
+инварианта. Новая автоматизация оправдана реальным риском или повторяющимся
+дефектом; её наличие само по себе не является целью.
 
 ## UI-решения
 
-Для изменяемого UI определи ожидаемые экраны, states, interactions и responsive
-поведение из задачи. Используй существующий [каталог](ui-catalog.md) и
-[дизайн-систему](design-system.md). Сложный или неоднозначный вариант покажи
-пользователю в конкретной форме до дорогой реализации; простой согласованный
-вариант делай сразу. Визуальные материалы нужны по задаче, не как обязательный
-SDD-пакет. Сборка Storybook не доказывает доступность или визуальное соответствие.
+Ожидаемые экраны, состояния, взаимодействия и поведение на разных размерах
+экрана определяются пользовательским сценарием. [Каталог](ui-catalog.md)
+и [дизайн-система](design-system.md) показывают существующую визуальную основу.
+Неоднозначный вариант можно оценить по конкретному примеру до реализации.
+Успешная сборка каталога не доказывает доступность и визуальное соответствие.
 
 ## Изменение опасного контракта
 
-При public/security/data/billing или труднообратимом выборе заранее уточни
-существенную неопределённость. Для миграции определи trigger отката, действия,
-сохранность уже созданных данных и проверку восстановления. Сначала подготовь
-конкретное reviewable решение; обычные обратимые edits не требуют ритуального approval.
-Источники и конфликтующие версии разрешай через [context discipline](agent-token-efficiency.md).
+Для публичного контракта, безопасности, данных, платежей и труднообратимого
+изменения существенная неопределённость разрешается до применения решения.
+Для миграции важны условия отката, сохранность уже созданных данных и проверка
+восстановления. Порядок разрешения конфликтов знаний описан в
+[контексте системы](agent-token-efficiency.md#источники-и-конфликты).