docs(ai): adopt task-driven scoped context

development/engineering-governance.md

@@ -1,279 +1,103 @@
 # Engineering governance
 
-## Назначение
+Это общий owner решений о scope, dependencies, testing и проверке результата.
+Работа начинается с задачи пользователя и выполняется напрямую. OpenSpec/SDD
+не обязателен; прежняя [процедура](openspec-authority-and-lifecycle.md) доступна
+только по явному запросу. Исторические artifacts не переписываются.
 
-Этот документ — единственный источник устойчивой инженерной policy WealthLedger. Он определяет, как планировать и проверять изменения, но не хранит требования, design или tasks конкретного change. Нормативные change-specific артефакты находятся только в canonical OpenSpec store `wealth-ledger-specs` (`specs/openspec`).
+## Выбор реализации
 
-## Термины
+Читай этот раздел при новой abstraction/dependency, refactor, multi-module
+изменении или неоднозначном ownership.
 
-**Change Owner** — человек, который принимает текущий planning artifact и разрешает переход к следующему. Для продуктового поведения это Product Owner, для технического или процессного изменения — Engineering Owner.
+1. Требуемое поведение уже существует — используй его.
+2. У поведения есть подходящий owner/helper — расширь его, сохранив связность.
+3. Задачу решает платформа, стандартная библиотека или принятая dependency — используй её.
+4. Иначе добавь небольшую реализацию там, где принадлежит инвариант.
+5. Если текущая структура мешает правильному ownership, сделай необходимый связный refactor с проверкой сохранения поведения.
 
-**Delivery Map** — решение по каждой области `frontend`, `backend`, `specs` и `docs`: `affected` с ожидаемым результатом либо `N/A` с конкретной проверяемой причиной.
+Оптимизируй ясность всей системы. Число файлов/строк само по себе не определяет
+качество: coherent refactor лучше дублированного guard в нескольких callers.
 
-**Completion Evidence** — запись существующих delivery commits, фактической
-Delivery Map, точных verification commands с observed results и independent
-review. Finalization создаёт её внутри canonical change до archive; она
-архивируется вместе с change.
+**Безопасный путь:** при неопределённом будущем reuse оставь код у ближайшего
+подходящего владельца. Выделение оправдано текущей общей ответственностью,
+несколькими реальными consumers или необходимой trust/transaction boundary.
+Один consumer не запрещает модуль с самостоятельным инвариантом, но не оправдывает
+interface/factory/registry только для воображаемой расширяемости.
 
-**Enforceable Engineering Invariant** — обязательное правило с детерминированной non-mutating локальной проверкой, нарушение которой блокирует завершение change. Непроверяемое предпочтение является guidance, а не hard guardrail.
+Примеры: фильтр одного экрана остаётся page-local; чистое денежное преобразование
+использует существующий decimal helper; запрос Prisma не требует generic repository.
+Security validation, доступность, error handling и защита данных сохраняются
+даже в маленькой реализации.
 
-**Planning structural gate** — stage-aware проверка доступной формы и ссылочной
-целостности текущего planning artifact до запроса approval. Она не оценивает
-качество rationale и не является semantic approval.
+## Dependencies
 
-## Последовательность SDD
+Перед новой dependency проверь installed stack и существующий helper. Если
+подходящего решения нет, оцени поддерживаемую библиотеку, совместимость,
+maintenance/security cost и точную недостающую возможность. Собственный код
+выбирай по совокупной стоимости, а не ради отсутствия dependency любой ценой.
 
-Каждый versioned change проходит один граф:
-
-```text
-Proposal → Delta Specs → Design → Tasks → Apply → Verify → Archive
-```
-
-- Proposal формулирует намерение, границы и ожидаемый результат без технологий, API, файлов и зависимостей.
-- Delta Specs описывают изменение наблюдаемого поведения и инвариантов без изменений кода.
-- Design объясняет архитектурный способ реализации крупными частями, риски и альтернативы; он не является построчной инструкцией.
-- Tasks — implementation checklist, достаточный для выполнения Design и Specs.
-  Каждый checkbox объявляет ровно одну area, `Covers` ссылается на native
-  identity `capability path — exact Requirement heading` либо объясняет `N/A`,
-  а `Verification` задаёт планируемую проверку. Tasks не содержат будущие
-  результаты, commits или post-archive bookkeeping.
-
-### Роли и approvals
-
-Сессия исполняет одну роль: Discovery, Specification, Implementation, Validation
-или Finalization. Создание record и ожидание решения сами по себе не требуют
-новой сессии той же роли. Переход к другой роли требует независимого контекста.
-
-Specification поддерживает две bounded progression: `Proposal + Delta Specs`
-и `Design + Tasks`. Перед каждым downstream artifact требуется отдельное явное
-решение Change Owner:
-
-| Approval неизменившегося artifact | Следующий разрешённый outcome |
-| --- | --- |
-| Proposal | Delta Specs в той же Specification-сессии |
-| Delta Specs | Завершение первой пары; следующая Specification-сессия начинает Design |
-| Design | Tasks в той же Specification-сессии |
-| Tasks | Implementation в следующей роли |
-
-Сохранённый observed approval повторно используется только при совпадении
-identity и fingerprint. State не является самостоятельным доказательством
-решения владельца. Отсутствующее либо legacy approval binding требует явного
-решения; наличие файла не доказывает approval. Recovery и fingerprint procedure
-определены в [context authority](agent-token-efficiency.md).
-
-До запроса approval агент запускает доступный stage planning gate и сам
-исправляет технические ошибки формата. Полный change validation не объявляется
-успешным, пока downstream artifacts отсутствуют. Несовпадение fingerprint
-утверждённого artifact сбрасывает его approval и downstream approvals;
-изменение возвращается к самой ранней затронутой planning boundary. Отметки
-выполнения Tasks не изменяют утверждённое содержание и нормализуются только
-для approval fingerprint.
-
-Изменение принятого upstream artifact инвалидирует approval зависимых артефактов: Proposal — Specs, Design и Tasks; Specs — Design и Tasks; Design — Tasks. Tasks не могут неявно расширять scope или менять поведение и архитектуру: работа возвращается к соответствующему upstream artifact.
-
-### Implementation, Validation и Finalization
-
-Implementation выполняет связный batch approved Tasks и отмечает только
-фактически завершённую работу после релевантных checks. Если implementation-owned
-работа остаётся, нормальный outcome — `CHECKPOINT` с продолжением Implementation;
-это не blocker. `READY_FOR_VALIDATION` требует завершения всей такой работы и
-успеха её проверок. Проблема intent направляется к Proposal, observable behavior
-— к Delta Specs, архитектуры — к Design, декомпозиции — к Tasks.
-
-Validation независимо проверяет affected gates, semantic и acceptance behavior,
-применимые edge cases и выполняет independent read-only review. Она не меняет
-production implementation, planning artifacts или Tasks. Эти проверки не
-остаются implementation checkboxes. Результат `PASS`, `FAIL` или `SPEC_ISSUE`
-привязан к проверенным planning/delivery inputs по
-[context authority](agent-token-efficiency.md#fingerprints).
-
-| Результат / blocker | Ответственная следующая роль |
-| --- | --- |
-| Validation PASS на актуальных inputs | Finalization |
-| Implementation finding или unchecked implementation-owned Task | Implementation |
-| Planning issue / SPEC_ISSUE | Specification, самая ранняя затронутая boundary |
-| Отсутствующий либо устаревший PASS | Validation |
-| Retryable archive/evidence/environment failure при корректных inputs | Finalization |
-
-Finalization потребляет актуальный PASS и выполняет только completion mechanics.
-Она не повторяет неизменившуюся Validation и не исправляет implementation или
-planning. При blocker сохраняется observed cause и точный маршрут продолжения.
-
-## Context authority
-
-[Token-efficient agent workflow](agent-token-efficiency.md) единолично определяет
-bounded reads, fingerprint bindings, handoff, evidence reuse и batching.
-Обязательные safeguards этой policy действуют с любым agent runtime; skills,
-commands и session adapters необязательны. Числовые token budgets и telemetry
-не являются условием delivery.
-
-## UI/UX-пакет Design
-
-UI/UX относится к существующему canonical Design и его единому approval.
-Design определяет applicability: `new/changed`, `reuse` либо `N/A` с конкретной
-причиной. Применимый scope описывает затронутые экраны, состояния, взаимодействия
-и responsive behavior; reuse указывает точную версию решения, используемую часть
-и отличия. Неизменяемая область и обоснованный N/A не требуют нового макета.
-
-Основное переносимое представление — Markdown в Design. Необходимые PNG/SVG
-exports хранятся в `visuals/` того же canonical change. Design фиксирует revision
-пакета и для каждого материала — identity, относительный путь, назначение
-(экран/состояние) и SHA-256 raw bytes отдельного файла. Встроенный Markdown
-входит в обычный Design fingerprint без собственного self-referential hash.
-SVG самодостаточен: без scripts, исполняемых handlers и внешних fonts/assets.
-
-Внешний editor, preview или текущая Storybook-витрина может быть reference;
-согласованный результат доступен из canonical пакета без внешнего runtime,
-аккаунта или изменяемого URL. Reuse из другого change указывает точный immutable
-архивный пакет и применимые материалы, а не `latest`. При переносе вызывающего
-change reuse source сохраняет store ID и путь от canonical OpenSpec root;
-пути материалов остаются относительными к исходному пакету. Пакет доступен
-после archive вместе с Design; относительная структура и identities
-материалов сохраняются.
-
-Approval относится ко всему представленному Design package. Его revision
-и digest обнаруживают изменения, но сами не подтверждают решение владельца.
-Существующие approval и PASS bindings включают перечисленные attachments
-и reuse inputs по [context authority](agent-token-efficiency.md#fingerprints).
-Смысловая замена материала или правила возвращается к Design; затронутые
-requirements — к Delta Specs, intent — к Proposal с обычным cascade approvals.
-
-Missing material, digest mismatch, неоднозначный пакет и external-only source
-блокируют зависимую работу до восстановления точных согласованных bytes либо
-решения на ответственной planning boundary. Восстановление не разрешает
-дорисовывать отсутствующее решение по памяти. Validation остаётся read-only:
-расхождение реализации с однозначным пакетом даёт `FAIL`, противоречие или
-неоднозначность planning — `SPEC_ISSUE`. Reviewer сопоставляет экраны, состояния,
-interactions и responsive behavior. Structural success, screenshots и наличие
-Storybook не означают semantic PASS; отдельный visual checker или approval
-engine не вводится.
-
-Правило применяется к новым changes и ещё не утверждённому Design. Уже approved
-Design и changes в Implementation/Validation сохраняют согласованный scope:
-owner-requested migration проходит нужную planning boundary без автоматического
-retrofit, reapproval или нового PASS. Historical archives и чужие state не
-переписываются. Доступность каталога и процесса даёт готовность к отдельному
-пилоту; его успешность подтверждает только фактически пройденный небольшой
-UI change, выбранный владельцем и получивший собственные planning approvals.
-
-## Delivery Map и multi-repository delivery
-
-Design каждого change оценивает все четыре области:
-
-- `specs` всегда `affected` для versioned SDD change;
-- `docs` всегда `affected` для поставленной пользовательской фичи; для технического изменения допустимо `N/A`, только если as-built документация действительно не меняется;
-- `frontend` и `backend` являются `affected`, когда меняются их поведение, контракт, реализация или обязательный local gate;
-- `N/A` требует конкретной причины; пустой commit не имитирует участие репозитория.
-
-Change остаётся active, пока каждая affected область не реализована и не прошла свой canonical gate. Design содержит Contract Gate Decision: `runtime-openapi` имеет статус `required`, когда изменение затрагивает frontend и backend стороны API contract, иначе `N/A` с конкретной причиной. Успех одного репозитория не компенсирует отсутствие или failure другого.
-
-Task owner выбирается только из `frontend`, `backend`, `specs`, `docs` и
-`workspace`. Repository owner нельзя использовать для area со статусом `N/A`;
-cross-repository implementation разбивается на отдельные tasks. `workspace`
-владеет только orchestration и verification, но не подменяет repository-owned
-implementation или canonical gates.
+Версии и 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 и подтверждённой регрессии.
 
-- security- или privacy-sensitive поведение;
-- денежные вычисления;
-- целостность или миграцию данных;
-- конкурентный доступ;
-- публичный контракт;
-- критический пользовательский journey;
-- подтверждённую регрессию.
+Выбирай самую дешёвую надёжную границу, наблюдаемую потребителем. Тест нужен
+для собственного branching, преобразования или инварианта; не для каждого
+DTO, декларативной конфигурации, thin adapter или поведения библиотеки.
+Меняющийся тест тоже активирует testing convention, даже без production diff.
+Frontend coverage — anti-regression constraint; backend общего threshold не имеет.
+Не пиши тесты только ради процента или повторения Markdown.
 
-Уровень теста выбирается по наблюдаемому поведению и наиболее дешёвой надёжной границе. Тест не создаётся только потому, что появился или изменился файл. DTO без собственной логики, декларативная конфигурация, тонкий адаптер, прямолинейная оркестрация, hygiene script и поведение сторонней библиотеки проверяются существующим contract или integration gate без отдельного unit test, пока в проектном коде нет самостоятельного ветвления, преобразования, инварианта либо регрессии.
+## Проверка результата
 
-Frontend coverage gate — anti-regression constraint. Он не является причиной писать малоценные тесты декларативных файлов. Для backend нет общего числового coverage threshold; новый threshold допустим только через отдельное утверждённое обоснование защищаемого риска.
+В итерации используй targeted check из применимого convention. Перед завершением
+запусти `npm run verify` каждого изменённого code/docs repo под его `.nvmrc`
+после lockfile install. Для HTTP contract — дополнительно
+[contract checks](runtime-openapi-verification.md). Общего CI сейчас нет.
 
-Проверка самого нового hard guardrail должна показать успешный compliant case и отказ на одном контролируемом репрезентативном нарушении. Это не превращает каждый вспомогательный script в объект unit testing.
+Проверь actual staged/unstaged/new scope и результат против задачи: ownership,
+сохранение данных/контрактов, ошибки, доступность, отсутствие лишних abstractions.
+Неизменившийся успешный gate можно использовать повторно, если известны команда,
+его полный relevant input scope и неизменные prerequisites; при сомнении выполни
+его снова. Auto-fix не заменяет non-mutating gate.
 
-## Build versus buy
-
-До утверждения Design обязательна оценка зрелых поддерживаемых решений, если change вводит или существенно заменяет:
-
-- авторизацию или иной security-механизм;
-- хранение данных;
-- внешнюю интеграцию;
-- observability;
-- caching или concurrency control;
-- общую инфраструктуру или tooling.
-
-Solution Assessment сравнивает применимые варианты по соответствию требованиям, зрелости, безопасности, эксплуатационной стоимости, ограничениям и стоимости миграции. Поддерживаемое совместимое решение используется либо Design конкретно объясняет, почему его совокупная стоимость или риск выше выбранной альтернативы.
-
-Собственная реализация допустима, только если подходящего решения нет или доказана существенная несовместимость. Тогда Design фиксирует проверенные варианты, конкретные gaps, принятые риски и trigger повторного рассмотрения. Для обратимого изменения вне перечисленных областей отдельная формальная оценка не создаётся ради процесса.
-
-## Rollback contract
-
-Design фиксирует status `required`, trigger, actions, data safety и verification,
-если change меняет auth/security behavior, data integrity или migration, public
-contract либо другое существенно труднообратимое решение. Contract учитывает
-данные и compatibility, созданные после delivery, и не может зависеть от нового
-неутверждённого архитектурного решения.
-
-Для обратимого change вне этих рисков status `N/A` содержит конкретную причину.
-Отдельный rollback artifact не создаётся ради процесса.
-
-## Single Source of Truth
-
-| Вид знания | Authoritative location |
-| --- | --- |
-| Намерение, требования, Design, Tasks, changes, Completion Evidence и archives | `specs/openspec` |
-| Исполняемое поведение | `frontend` и `backend` code и risk-based tests |
-| Публичный API contract | backend runtime OpenAPI и committed frontend snapshot |
-| Текущее устройство и поставленные возможности | `docs/architecture` и `docs/features` |
-| Устойчивые архитектурные решения и причины | `docs/adr` |
-| Инженерная policy и context discipline | `docs/development` |
-| Компактная маршрутизация и локальные boundaries | root/repository-local `AGENTS.md` |
-| Необязательные runtime adapters и navigation | локальные skills, commands и session records |
-
-`docs` описывает только фактическое текущее состояние и не пересказывает Proposal, Delta Specs, Design или Tasks другим форматом. `AGENTS.md` не копирует архитектуру или feature documentation: он направляет к authority и перечисляет только применимые hard constraints и canonical commands.
+В ответе достаточно: что поставлено, как проверено, какие ограничения остались.
+Не создавай role records, fingerprints всех repositories, Completion Evidence
+или delivery commits только ради процесса. Существующие рабочие изменения
+других задач сохраняются. Нужный review не заменяется количеством checkboxes.
 
 ## Guardrails и local gates
 
-CI пока отсутствует, поэтому обязательные gates выполняются локально человеком или AI-агентом:
+- **Автоматический invariant:** существующий deterministic checker блокирует нарушение в фактическом scope с документированными исключениями.
+- **Обязательное semantic правило/процедура:** исполнитель и reviewer проверяют решение; отсутствие checker не переводит i18n, validation или authorization в пожелание.
+- **Guidance:** необязательное предпочтение, например эстетический выбор между эквивалентными вариантами.
 
-| Область | Canonical gate |
-| --- | --- |
-| frontend | `npm run verify` в `frontend` |
-| backend | `npm run verify` в `backend` |
-| specs | native strict validation из canonical store |
-| docs | `npm run verify` в `docs` |
+Не обещай enforcement, отсутствующий в config/tests. Новая автоматическая проверка
+оправдана реальным риском или повторяющимся дефектом, а не возможностью написать
+ещё один checker. Механические правила принадлежат tools; выбор правильного owner
+и полезного теста остаётся semantic judgement.
 
-Каждый gate non-mutating и fail-fast. Auto-fix commands выполняются отдельно и не служат доказательством корректности. Node 22 задан `.nvmrc` и `engines`; OpenSpec commands всегда используют canonical store.
+## UI-решения
 
-Hard guardrail должен иметь исполняемую локальную проверку. Правило без надёжной проверки помечается как guidance и учитывается в review, но не выдаётся за автоматический запрет. Новые frameworks, checkers и thresholds добавляются только после оценки поддерживаемого решения, maintenance cost и реально защищаемого риска.
+Для изменяемого UI определи ожидаемые экраны, states, interactions и responsive
+поведение из задачи. Используй существующий [каталог](ui-catalog.md) и
+[дизайн-систему](design-system.md). Сложный или неоднозначный вариант покажи
+пользователю в конкретной форме до дорогой реализации; простой согласованный
+вариант делай сразу. Визуальные материалы нужны по задаче, не как обязательный
+SDD-пакет. Сборка Storybook не доказывает доступность или визуальное соответствие.
 
-Native команды и completion procedure описаны в
-[OpenSpec lifecycle](openspec-authority-and-lifecycle.md). Они не требуют
-optional runtime adapters.
+## Изменение опасного контракта
 
-## Verify, archive и Completion Evidence
-
-Structural validation OpenSpec проверяет schema и форму артефактов, но не соответствие реализации. До archive обязательны:
-
-1. успешные canonical gates всех affected areas;
-2. native strict validation completed change и main specs из canonical store;
-3. semantic и acceptance verification против approved Proposal, Delta Specs,
-   Design и Tasks;
-4. independent read-only review без Critical и Important findings;
-5. завершённые implementation-owned Tasks и необходимая as-built документация;
-6. актуальный input-bound PASS независимой Validation и существующие delivery
-   commits для каждой affected repository area.
-
-Archive не имеет confirmation override для этих blockers. Completion Evidence
-создаётся в `specs/openspec/changes/<change>/completion-evidence.md` после
-существования всех перечисленных фактов и архивируется вместе с change.
-Evidence содержит Delivery Map, существующие commit identifiers, exact
-commands/observed results и независимый verdict с привязкой к inputs. Для
-`N/A` сохраняется конкретная причина без фиктивного commit или gate.
-
-Собственный evidence/archive commit не ссылается сам на себя: его идентификатор
-сообщается после фиксации. Отсутствующие факты не заменяются placeholders,
-unchecked Tasks или отдельным docs evidence store. При `docs: N/A` запись
-Completion Evidence не требует docs-мутации. Registry хранит ссылку на
-canonical archive и evidence; прежние датированные evidence и ссылки остаются
-историческими и не переносятся задним числом.
+При public/security/data/billing или труднообратимом выборе заранее уточни
+существенную неопределённость. Для миграции определи trigger отката, действия,
+сохранность уже созданных данных и проверку восстановления. Сначала подготовь
+конкретное reviewable решение; обычные обратимые edits не требуют ритуального approval.
+Источники и конфликтующие версии разрешай через [context discipline](agent-token-efficiency.md).