docs: simplify system documentation
This commit is contained in:
@@ -1,55 +0,0 @@
|
||||
---
|
||||
status: accepted
|
||||
---
|
||||
|
||||
# Native OpenSpec SDD и минимальная local orchestration
|
||||
|
||||
## Статус: историческое решение
|
||||
|
||||
[ADR 012](012-task-driven-development-with-scoped-context.md) отменяет обязательный
|
||||
SDD lifecycle. Native OpenSpec остаётся optional инструментом; repo gates сохраняются.
|
||||
|
||||
### Прежняя частичная замена
|
||||
|
||||
[ADR 011](011-native-openspec-lifecycle-with-repository-gates.md) заменяет части
|
||||
этого решения о schema v3, custom verifiers и dispatcher. Выбор native OpenSpec,
|
||||
независимых repository gates и исходное rationale сохраняются. Ниже оставлено
|
||||
историческое описание прежней реализации; текущие принципы работы описаны
|
||||
в ADR 012. Version contract этим уточнением не меняется.
|
||||
|
||||
## Исторический контекст и решение
|
||||
|
||||
На момент решения WealthLedger использовал проектную schema `wealth-ledger-sdd` version 3 с
|
||||
последовательностью `Proposal → Delta Specs → Design → Tasks → Apply`, один exact
|
||||
OpenSpec CLI contract и проверки без изменения проверяемых материалов. Это
|
||||
сохраняло единый источник правил жизненного цикла в хранилище спецификаций, выражало approval
|
||||
boundaries нативными extension points и не вводит второй workflow engine или
|
||||
monorepo control plane для четырёх независимых Git-репозиториев.
|
||||
|
||||
## Рассмотренные варианты
|
||||
|
||||
- Встроенная `spec-driven` schema отклонена: она не выражает обязательный переход Specs перед Design и не задаёт Delivery Map или проектные роли артефактов.
|
||||
- Отдельный workflow engine или custom generator отклонён: он создал бы конкурирующий формат и lifecycle authority.
|
||||
- Nx, Turborepo, Bazel, Make или just отклонены для текущего масштаба: workspace не имеет общего dependency graph, build cache или CI, а репозитории уже владеют canonical gates.
|
||||
- Versioned source tree, patch-only, programmatic generator и symlink для root
|
||||
agent entrypoints отклонены для текущего масштаба: они добавляют отдельный
|
||||
projection lifecycle поверх уже достаточных schema, docs и scripts.
|
||||
|
||||
## Исторические последствия
|
||||
|
||||
OpenSpec CLI закреплён exact version contract; новая stable release не включает
|
||||
auto-upgrade, а смена contract является отдельным SDD change со staged
|
||||
проверками совместимости. Локальная точка входа оставалась навигацией,
|
||||
а обязательные ограничения проверялись отдельно. Planning
|
||||
verifier до approval проверяет только детерминированную структуру: capability
|
||||
set, Delivery Map, rollback, task area и Requirement coverage. Он различает
|
||||
artifact-validation, неверный invocation и failure окружения, чтобы agent не
|
||||
переписывал planning artifact из-за сломанного вызова или prerequisite.
|
||||
|
||||
Dispatcher знает четыре workspace area, но не реализует build или test logic:
|
||||
он делегирует repo-owned commands. Approval identity остаётся человеческим
|
||||
workflow constraint, потому что schema моделирует порядок артефактов, но не
|
||||
личность утвердившего. Semantic review по-прежнему не заменяется structural
|
||||
checks.
|
||||
|
||||
Решение пересматривается, если OpenSpec перестанет поддерживать нужный artifact graph, появится обязательный общий CI/build graph или стоимость последовательной локальной orchestration станет существенной. В этих случаях новый ADR сравнивает native evolution с внешним engine либо monorepo platform.
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
status: superseded
|
||||
---
|
||||
|
||||
# Native OpenSpec lifecycle и repository gates
|
||||
|
||||
Обязательность описанной ниже процедуры заменена
|
||||
[ADR 012](012-task-driven-development-with-scoped-context.md). Текст сохраняет
|
||||
историческое решение; current policy — прямая работа по задаче.
|
||||
|
||||
## Контекст
|
||||
|
||||
[ADR 010](010-native-openspec-sdd-and-local-orchestration.md) сохраняет rationale
|
||||
выбора native OpenSpec и независимых repository gates. Его описание schema v3,
|
||||
custom authority/planning verifiers и dispatcher относится к прежней реализации.
|
||||
На момент решения проектная schema `wealth-ledger-sdd`
|
||||
имела version 5 и граф `Proposal → Delta Specs → Design → Tasks → Apply`.
|
||||
Порядок работы определялся средствами OpenSpec и общими правилами проекта;
|
||||
дополнительные точки входа служили навигацией по единой процедуре.
|
||||
|
||||
Версия OpenSpec CLI была зафиксирована как `1.10.0`.
|
||||
Версия schema и CLI contract — разные сведения. Фиксация версии
|
||||
не доказывает запуск прежних проверок; это решение не меняет CLI pin,
|
||||
version contract, schema или требования к tooling.
|
||||
|
||||
## Решение
|
||||
|
||||
Частично заменить ADR 010 в части прежней schema version и orchestration.
|
||||
Единым хранилищем согласования оставался `wealth-ledger-specs`.
|
||||
Процедура разделяла следующие ответственности:
|
||||
|
||||
- Согласование ролей, подтверждений, объёма поставки и обязательных проверок.
|
||||
- Планирование и применение изменений, структурную проверку и смысловое согласование требований.
|
||||
- Выбор и повторную сверку исходных знаний, восстановление контекста и повторное использование свидетельств.
|
||||
|
||||
Native OpenSpec получает structure и contextFiles текущего artifact или Apply.
|
||||
Каждое изменяемое приложение владело своей проверкой качества. Выполнение
|
||||
процедуры не зависит от custom verifier, dispatcher, skill или session adapter;
|
||||
optional entrypoints остаются navigation, без второго workflow engine.
|
||||
|
||||
## Последствия
|
||||
|
||||
Люди и автоматизированные инструменты следовали единой процедуре, а каждый
|
||||
репозиторий отвечал за собственные проверки. 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).
|
||||
Эти материалы отражают последующее упрощение процесса, а не восстанавливают
|
||||
обязательность исторической процедуры.
|
||||
@@ -1,33 +0,0 @@
|
||||
# 012. Прямая разработка с контекстом по задаче
|
||||
|
||||
**Status:** Accepted; supersedes обязательный lifecycle из ADR 010/011.
|
||||
|
||||
## Context
|
||||
|
||||
Обязательная цепочка OpenSpec artifacts не обеспечила соответствие исходному
|
||||
намерению: суженный change мог пройти все проверки, оставив backend и основные
|
||||
рекомендации исследований вне реализации. Владелец проекта выбрал прямую
|
||||
разработку без обязательного OpenSpec/SDD.
|
||||
|
||||
## Decision
|
||||
|
||||
Задача пользователя определяет результат. Рабочий контекст выбирается по
|
||||
предмету изменения: локальные правила разработки отделены от проектных фактов,
|
||||
а тематические источники объясняют соответствующую область. Общие принципы
|
||||
и согласование контракта не дублируются в независимых описаниях.
|
||||
|
||||
[Engineering governance](../development/engineering-governance.md) и
|
||||
[context discipline](../development/agent-token-efficiency.md) описывают текущую
|
||||
работу. Repo gates, trust-boundary checks, migration safety и semantic review
|
||||
сохраняются. OpenSpec используется только по явному запросу; history сохраняется.
|
||||
|
||||
## Consequences
|
||||
|
||||
Обычная задача не требует planning artifacts, role handoffs, approval fingerprints
|
||||
и archive. Сложные public/security/data решения уточняются по существу до опасной
|
||||
операции. Правильность routing проверяется на задачах и counterexamples; качество
|
||||
агента оценивается по наблюдаемым outcomes, а не по числу файлов или checkboxes.
|
||||
|
||||
Рекомендации исследований адаптируются к принятой архитектуре и существующим
|
||||
проверкам WealthLedger. Backend остаётся источником OpenAPI. Новые сервисы,
|
||||
общая инфраструктура и проверки не вводятся только ради организации контекста.
|
||||
@@ -15,11 +15,6 @@
|
||||
Это давало частичное покрытие одного агентства без покупки доступа,
|
||||
но не рейтинг любой российской облигации и не стабильный контракт API.
|
||||
|
||||
Основания выбора сохранены из исследования, а применение решения подтверждено
|
||||
backend-коммитом `235c179` (`feat: add bond details, yields and credit ratings`).
|
||||
Исходное исследование содержало также рекомендации; эта запись фиксирует
|
||||
выбранный подход, не объявляя все рекомендации реализованными.
|
||||
|
||||
## Решение
|
||||
|
||||
Использовать публичный [реестр выпусков НКР](https://ratings.ru/ratings/issues/)
|
||||
|
||||
@@ -1,39 +1,27 @@
|
||||
# 014. Актуальная OpenAPI-схема как вход frontend
|
||||
|
||||
**Статус:** принято 2026-09-13; docs, specs и frontend-инструкции приведены
|
||||
к решению. Настройка remote issues и branch protection выполняется отдельно.
|
||||
**Статус:** принято 2026-09-13.
|
||||
|
||||
## Контекст
|
||||
|
||||
Frontend и backend — независимые репозитории. Знание путей и команд backend
|
||||
в frontend связывает их внутреннее устройство. Для текущего процесса разработки
|
||||
владелец проекта принимает актуальность переданной OpenAPI-схемы как допущение;
|
||||
проверка пары revisions и дополнительное сравнение схем не требуются.
|
||||
Frontend и backend — независимые репозитории. Зависимость frontend от путей
|
||||
и команд backend связывала бы их внутреннее устройство. Предоставленная
|
||||
OpenAPI-схема служит границей между владельцем API и его потребителем.
|
||||
|
||||
## Решение
|
||||
|
||||
Backend остаётся источником HTTP-контракта согласно [ADR 002](002-nest-generated-openapi-contract.md).
|
||||
Backend остаётся источником HTTP-контракта согласно
|
||||
[ADR 002](002-nest-generated-openapi-contract.md).
|
||||
Frontend принимает предоставленную OpenAPI-схему как актуальную и генерирует
|
||||
из неё типы локально. Его команды не читают файлы соседнего backend checkout
|
||||
и не запускают backend-скрипты. Подготовка и доставка схемы находятся вне frontend.
|
||||
|
||||
Не требуется фиксировать пару SHA frontend/backend или сравнивать frontend-схему
|
||||
с runtime OpenAPI backend. Локальная проверка соответствия generated types
|
||||
входной схеме сохраняется: она не проверяет актуальность схемы относительно backend.
|
||||
Обычные CI checks по-прежнему должны проверять текущий commit изменения.
|
||||
из неё типы локально, без доступа к соседнему backend checkout.
|
||||
Подготовка и доставка схемы находятся вне frontend.
|
||||
|
||||
## Последствия
|
||||
|
||||
Задача frontend #3 ограничивается локальной генерацией из предоставленной схемы;
|
||||
экспорт backend не становится обязанностью frontend. Из frontend #2 исключается
|
||||
требование проверки явно выбранной пары revisions. Требования безопасности
|
||||
frontend #4 этим решением не меняются.
|
||||
Frontend зависит от публичного контракта, а не от внутреннего устройства
|
||||
backend. Соответствие типов входной схеме не гарантирует её актуальность:
|
||||
рассинхронизацию предоставленной схемы и работающего API frontend не выявляет
|
||||
сравнением схем. Актуальность входа остаётся принятым допущением.
|
||||
OpenAPI endpoint не является runtime-зависимостью SPA.
|
||||
|
||||
Рассинхронизацию предоставленной схемы и backend отдельный gate не обнаруживает:
|
||||
её отсутствие принято как допущение. Тесты HTTP-поведения, валидации и авторизации
|
||||
остаются нужны.
|
||||
|
||||
Решение заменяет прежнее требование сравнения runtime OpenAPI с frontend
|
||||
snapshot в [OpenAPI contract flow](../development/runtime-openapi-verification.md)
|
||||
и [спецификации генерации API](../../specs/openspec/specs/api-contract-generation/spec.md).
|
||||
Связанные remote issues и настройки защиты ветки требуют отдельного обновления.
|
||||
Текущее взаимодействие описано в [HTTP API](../architecture/http-api.md).
|
||||
|
||||
@@ -17,8 +17,5 @@
|
||||
- [007 — React Query fetch policy](007-react-query-fetch-policy.md)
|
||||
- [008 — Pino backend logging](008-pino-backend-logging.md)
|
||||
- [009 — Concurrent refresh rotation policy](009-concurrent-refresh-rotation-policy.md)
|
||||
- [010 — Native OpenSpec SDD и local orchestration](010-native-openspec-sdd-and-local-orchestration.md) — исторический; частично заменён ADR 011, обязательность SDD отменена ADR 012.
|
||||
- [011 — Native OpenSpec lifecycle и repository gates](011-native-openspec-lifecycle-with-repository-gates.md) — заменён ADR 012 в части обязательного lifecycle.
|
||||
- [012 — Прямая разработка с контекстом по задаче](012-task-driven-development-with-scoped-context.md)
|
||||
- [013 — НКР как первый источник кредитных рейтингов облигаций](013-nkr-bond-credit-ratings.md)
|
||||
- [014 — Актуальная OpenAPI-схема как вход frontend](014-trusted-openapi-input.md)
|
||||
|
||||
Reference in New Issue
Block a user