docs: make project documentation self-contained

2026-09-12 13:09:37 +03:00
parent aa9afc15e4
commit 3a99af1a6e
36 changed files with 1006 additions and 703 deletions
@@ -13,3 +13,10 @@ Backend нуждается в структурированных JSON-логах
 ## Consequences

 Backend получает новую production dependency и использует Pino API для application-событий. Collector, retention и alerting остаются за пределами приложения.
+
+Логирование сосредоточено на инфраструктурной границе backend и связывает
+события с контекстом HTTP-запроса. В журнал передаются стабильное имя события
+и разрешённые скалярные поля. Неизвестные поля отбрасываются; полные запросы,
+тела ответов и секреты не являются допустимыми данными журнала. Фильтрация
+полей не защищает секрет, помещённый в свободный текст сообщения или stack:
+содержимое таких сообщений требует отдельной проверки.
@@ -14,15 +14,15 @@ SDD lifecycle. Native OpenSpec остаётся optional инструменто
 [ADR 011](011-native-openspec-lifecycle-with-repository-gates.md) заменяет части
 этого решения о schema v3, custom verifiers и dispatcher. Выбор native OpenSpec,
 независимых repository gates и исходное rationale сохраняются. Ниже оставлено
-историческое описание прежней реализации; действующую процедуру определяют
-authorities, указанные в ADR 011. Version contract этим уточнением не меняется.
+историческое описание прежней реализации; текущие принципы работы описаны
+в ADR 012. Version contract этим уточнением не меняется.

 ## Исторический контекст и решение

-WealthLedger использует project-local schema `wealth-ledger-sdd` version 3 с
+На момент решения WealthLedger использовал проектную schema `wealth-ledger-sdd` version 3 с
 последовательностью `Proposal → Delta Specs → Design → Tasks → Apply`, один exact
-OpenSpec CLI contract из `.cli-version` и тонкие non-mutating verifiers. Это
-сохраняет один lifecycle authority в `specs/openspec`, выражает approval
+OpenSpec CLI contract и проверки без изменения проверяемых материалов. Это
+сохраняло единый источник правил жизненного цикла в хранилище спецификаций, выражало approval
 boundaries нативными extension points и не вводит второй workflow engine или
 monorepo control plane для четырёх независимых Git-репозиториев.

@@ -39,8 +39,8 @@ monorepo control plane для четырёх независимых Git-репо

 OpenSpec CLI закреплён exact version contract; новая stable release не включает
 auto-upgrade, а смена contract является отдельным SDD change со staged
-compatibility fixtures. Root `.opencode` остаётся локальным non-authority
-entrypoint, а hard constraints проверяются через authority verifier. Planning
+проверками совместимости. Локальная точка входа оставалась навигацией,
+а обязательные ограничения проверялись отдельно. Planning
 verifier до approval проверяет только детерминированную структуру: capability
 set, Delivery Map, rollback, task area и Requirement coverage. Он различает
 artifact-validation, неверный invocation и failure окружения, чтобы agent не
@@ -13,40 +13,46 @@ status: superseded
 [ADR 010](010-native-openspec-sdd-and-local-orchestration.md) сохраняет rationale
 выбора native OpenSpec и независимых repository gates. Его описание schema v3,
 custom authority/planning verifiers и dispatcher относится к прежней реализации.
-Текущая project-local [schema wealth-ledger-sdd](../../specs/openspec/schemas/wealth-ledger-sdd/schema.yaml)
-имеет version 5 и граф `Proposal → Delta Specs → Design → Tasks → Apply`.
-Native instructions и общие authorities уже определяют действующую процедуру;
-optional entrypoints направляют к ней.
+На момент решения проектная schema `wealth-ledger-sdd`
+имела version 5 и граф `Proposal → Delta Specs → Design → Tasks → Apply`.
+Порядок работы определялся средствами OpenSpec и общими правилами проекта;
+дополнительные точки входа служили навигацией по единой процедуре.

-Отслеживаемый [`.cli-version`](../../specs/openspec/.cli-version) существует и
-содержит `1.10.0`. Версия schema и CLI contract — разные сведения. Наличие этого
-файла не доказывает запуск прежних verifiers; это решение не меняет CLI pin,
+Версия OpenSpec CLI была зафиксирована как `1.10.0`.
+Версия schema и CLI contract — разные сведения. Фиксация версии
+не доказывает запуск прежних проверок; это решение не меняет CLI pin,
 version contract, schema или требования к tooling.

 ## Решение

 Частично заменить ADR 010 в части прежней schema version и orchestration.
-Canonical SDD store остаётся `wealth-ledger-specs` в `specs/openspec`.
-Действующая процедура принадлежит существующим owners:
+Единым хранилищем согласования оставался `wealth-ledger-specs`.
+Процедура разделяла следующие ответственности:

- [Engineering governance](../development/engineering-governance.md) — роли, отдельные approvals, Delivery Map, обязательность проверок и completion safeguards.
- [OpenSpec lifecycle](../development/openspec-authority-and-lifecycle.md) — native planning/apply, strict structural validation, semantic sync и completion procedure.
- [Context discipline](../development/agent-token-efficiency.md) — выбор и повторная сверка inputs, fingerprints, recovery и evidence reuse.
+- Согласование ролей, подтверждений, объёма поставки и обязательных проверок.
+- Планирование и применение изменений, структурную проверку и смысловое согласование требований.
+- Выбор и повторную сверку исходных знаний, восстановление контекста и повторное использование свидетельств.

 Native OpenSpec получает structure и contextFiles текущего artifact или Apply.
-Каждый affected repository владеет своим gate через local AGENTS. Выполнение
+Каждое изменяемое приложение владело своей проверкой качества. Выполнение
 процедуры не зависит от custom verifier, dispatcher, skill или session adapter;
 optional entrypoints остаются navigation, без второго workflow engine.

 ## Последствия

-Агент и человек используют один актуальный lifecycle. Отдельный порядок команд
-в ADR не поддерживается: точные команды находятся у lifecycle и repository
-owners. Исходные альтернативы и rationale остаются в ADR 010; historical
-archives, audits и evidence сохраняют описание своего времени.
+Люди и автоматизированные инструменты следовали единой процедуре, а каждый
+репозиторий отвечал за собственные проверки. ADR фиксировал причину этого
+разделения ответственности. Исходные альтернативы и rationale остаются
+в ADR 010; historical archives, audits и evidence сохраняют описание своего времени.

 Structural success не подтверждает решение Change Owner, semantic compliance
 или независимый PASS. Approval bindings, полный применимый context/Design
 package, независимая Validation и отдельная Finalization сохраняются.
 Замена orchestration не ослабляет gates и не разрешает изменение незатронутых
 main-spec requirements о tooling.
+
+Текущие принципы сопровождения описаны в
+[engineering governance](../development/engineering-governance.md), роль
+сохранённых требований — в [OpenSpec](../development/openspec-authority-and-lifecycle.md).
+Эти материалы отражают последующее упрощение процесса, а не восстанавливают
+обязательность исторической процедуры.
@@ -11,10 +11,10 @@

 ## Decision

-Задача пользователя определяет результат. Root/local AGENTS задают короткий
-рабочий процесс; CONVENTIONS выбирает темы; SOURCES и docs/specs indexes указывают
-точных владельцев фактов. Frontend/backend guides содержат решения, безопасные
-пути, exceptions и реальные примеры. Общие rules и contract workflow не дублируются.
+Задача пользователя определяет результат. Рабочий контекст выбирается по
+предмету изменения: локальные правила разработки отделены от проектных фактов,
+а тематические источники объясняют соответствующую область. Общие принципы
+и согласование контракта не дублируются в независимых описаниях.

 [Engineering governance](../development/engineering-governance.md) и
 [context discipline](../development/agent-token-efficiency.md) описывают текущую
@@ -28,6 +28,6 @@
 операции. Правильность routing проверяется на задачах и counterexamples; качество
 агента оценивается по наблюдаемым outcomes, а не по числу файлов или checkboxes.

-Имена файлов и примерные context budgets из исследований адаптируются к
-WealthLedger: FSD без widgets, Nest как OpenAPI source, существующие локальные
-gates. Новые services, CI и checkers ради context architecture не добавляются.
+Рекомендации исследований адаптируются к принятой архитектуре и существующим
+проверкам WealthLedger. Backend остаётся источником OpenAPI. Новые сервисы,
+общая инфраструктура и проверки не вводятся только ради организации контекста.