docs/development/engineering-governance.md

Engineering governance

Назначение

Этот документ — единственный источник устойчивой инженерной policy WealthLedger. Он определяет, как планировать и проверять изменения, но не хранит требования, design или tasks конкретного change. Нормативные change-specific артефакты находятся только в canonical OpenSpec store wealth-ledger-specs (specs/openspec).

Термины

Change Owner — человек, который принимает текущий planning artifact и разрешает переход к следующему. Для продуктового поведения это Product Owner, для технического или процессного изменения — Engineering Owner.

Delivery Map — решение по каждой области frontend, backend, specs и docs: affected с ожидаемым результатом либо N/A с конкретной проверяемой причиной.

Completion Evidence — созданная после реализации и archive запись о фактической поставке: Delivery Map, archive path, commits изменённых репозиториев, точные verification commands с наблюдёнными результатами и итог independent read-only review.

Enforceable Engineering Invariant — обязательное правило с детерминированной non-mutating локальной проверкой, нарушение которой блокирует завершение change. Непроверяемое предпочтение является guidance, а не hard guardrail.

Planning structural gate — stage-aware проверка доступной формы и ссылочной целостности текущего planning artifact до запроса approval. Она не оценивает качество rationale и не является semantic approval.

Последовательность SDD

Каждый versioned change проходит один граф:

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.

AI-агент готовит только текущий разрешённый артефакт, показывает его Change Owner и останавливается. Downstream artifact создаётся только после явного approval. Если новая сессия не может подтвердить approval из доступного контекста, агент запрашивает его повторно.

До запроса approval агент запускает доступный stage planning gate и сам исправляет технические ошибки формата. Полный change validation не объявляется успешным, пока downstream artifacts отсутствуют. Форматное исправление без изменения intent, behavior, decisions или task scope не требует reapproval; семантическое изменение возвращает workflow к самому раннему затронутому artifact.

Изменение принятого upstream artifact инвалидирует approval зависимых артефактов: Proposal — Specs, Design и Tasks; Specs — Design и Tasks; Design — Tasks. Tasks не могут неявно расширять scope или менять поведение и архитектуру: работа возвращается к соответствующему upstream artifact.

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.

Risk-based testing

Автоматизированный тест обязателен, когда изменение затрагивает хотя бы один существенный риск:

• security- или privacy-sensitive поведение;
• денежные вычисления;
• целостность или миграцию данных;
• конкурентный доступ;
• публичный контракт;
• критический пользовательский journey;
• подтверждённую регрессию.

Уровень теста выбирается по наблюдаемому поведению и наиболее дешёвой надёжной границе. Тест не создаётся только потому, что появился или изменился файл. DTO без собственной логики, декларативная конфигурация, тонкий адаптер, прямолинейная оркестрация, hygiene script и поведение сторонней библиотеки проверяются существующим contract или integration gate без отдельного unit test, пока в проектном коде нет самостоятельного ветвления, преобразования, инварианта либо регрессии.

Frontend coverage gate — anti-regression constraint. Он не является причиной писать малоценные тесты декларативных файлов. Для backend нет общего числового coverage threshold; новый threshold допустим только через отдельное утверждённое обоснование защищаемого риска.

Проверка самого нового hard guardrail должна показать успешный compliant case и отказ на одном контролируемом репрезентативном нарушении. Это не превращает каждый вспомогательный script в объект unit testing.

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 и archives	specs/openspec
Исполняемое поведение	frontend и backend code и risk-based tests
Публичный API contract	backend runtime OpenAPI и committed frontend snapshot
Текущее устройство и поставленные возможности	docs/architecture и docs/features
Устойчивые архитектурные решения и причины	docs/adr
Инженерная policy и completion evidence	docs/development
Canonical source project-owned agent commands и skills	specs/agent-projection/opencode
Компактная маршрутизация AI-агентов	root и repository-local AGENTS.md

docs описывает только фактическое текущее состояние и не пересказывает Proposal, Delta Specs, Design или Tasks другим форматом. AGENTS.md не копирует архитектуру или feature documentation: он направляет к authority и перечисляет только применимые hard constraints и canonical commands.

Guardrails и local gates

CI пока отсутствует, поэтому обязательные gates выполняются локально одним и тем же способом человеком, AI-агентом и workspace verifier:

Область	Canonical gate
frontend	npm run verify в frontend
backend	npm run verify в backend
specs	bash specs/scripts/verify-workspace-change.sh <change> из workspace root
docs	npm run verify в docs

Каждый gate non-mutating и fail-fast. Auto-fix commands выполняются отдельно и не служат доказательством корректности. Runtime preflight отклоняет неподдерживаемый Node до application checks; OpenSpec preflight аналогично отклоняет несовместимую CLI version до операций со store.

Hard guardrail должен иметь исполняемую локальную проверку. Правило без надёжной проверки помечается как guidance и учитывается в review, но не выдаётся за автоматический запрет. Новые frameworks, checkers и thresholds добавляются только после оценки поддерживаемого решения, maintenance cost и реально защищаемого риска.

Root .opencode/commands и .opencode/skills являются derived projection. Изменения вносятся в versioned source под specs, распространяются explicit atomic sync и проверяются exact file/content comparison; package manifests, dependencies и machine-local state не являются authority inputs.

Текущая exact OpenSpec CLI version читается только из specs/openspec/.cli-version. Новая stable release не меняет contract автоматически. Upgrade выполняется отдельным SDD change после isolated проверки schema, agent projection, canonical store и positive/negative fixtures; историческое evidence сохраняет фактическую прежнюю version.

Verify, archive и Completion Evidence

Structural validation OpenSpec проверяет schema и форму артефактов, но не соответствие реализации. До archive обязательны:

1. успешные canonical gates всех affected areas;
2. semantic verification реализации против Proposal, Delta Specs, Design и Tasks;
3. independent read-only review без Critical и Important findings;
4. завершённый checklist без unchecked tasks.

Archive не имеет confirmation override для этих blockers. После успешного archive применяется двухфазная фиксация: сначала commits поставленных изменений и archive/sync, затем Completion Evidence с уже существующими delivery commit IDs, после чего отдельный final docs commit сохраняет evidence. Evidence ссылается на предшествующий as-built docs commit, если docs affected; при N/A сохраняет причину и не выдумывает implementation commit. Собственный final evidence commit не может ссылаться сам на себя и сообщается итогом archive workflow. Только фактические commits, выполненные команды и наблюдённые результаты могут быть evidence; planned значения и предположения не считаются завершением.