From b7a56b1eb53bae0a00e18be4ed4209df70fc193b Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Wed, 9 Sep 2026 16:23:11 +0300 Subject: [PATCH] docs(ai): adopt task-driven scoped context --- AGENTS.md | 53 +-- AI_INDEX.md | 74 ++++ ...ve-openspec-sdd-and-local-orchestration.md | 17 +- ...penspec-lifecycle-with-repository-gates.md | 52 +++ ...-driven-development-with-scoped-context.md | 33 ++ adr/README.md | 4 +- architecture/README.md | 1 + architecture/http-api.md | 59 ++++ development/README.md | 28 +- development/agent-context-evals.md | 50 +++ development/agent-token-efficiency.md | 196 +++-------- development/audit-remediation.md | 24 +- development/engineering-governance.md | 328 ++++-------------- development/frontend-workflow.md | 10 +- .../openspec-authority-and-lifecycle.md | 209 ++--------- development/runtime-openapi-verification.md | 17 +- development/ui-catalog.md | 23 +- 17 files changed, 502 insertions(+), 676 deletions(-) create mode 100644 AI_INDEX.md create mode 100644 adr/011-native-openspec-lifecycle-with-repository-gates.md create mode 100644 adr/012-task-driven-development-with-scoped-context.md create mode 100644 architecture/http-api.md create mode 100644 development/agent-context-evals.md diff --git a/AGENTS.md b/AGENTS.md index 6c7a6b2..dcd1978 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,44 +1,17 @@ # Docs -## Назначение и authority +Здесь живут as-built факты, проектные решения и общие engineering conventions. +Работай напрямую по задаче пользователя; обязательного SDD lifecycle нет. -Этот репозиторий хранит durable as-built документацию WealthLedger. Shared SDD -policy, common reading pointers, audit routing и `../references/**` policy -задаёт root `AGENTS.md`. +Для поиска проектного источника начни с [AI_INDEX](AI_INDEX.md). Если задача +уже указывает точный документ (например, правка опечатки), читай его напрямую. +Architecture/features описывают текущее поведение, +ADR сохраняют rationale; audits и прежнее Completion Evidence — история. +Изменение утверждённого архитектурного решения фиксируется successor ADR, +но не требует создания OpenSpec artifacts. -Для SDD roles, approvals и ownership читайте -[governance](development/engineering-governance.md); native planning и completion -в store `wealth-ledger-specs` — -[lifecycle](development/openspec-authority-and-lifecycle.md); recovery, fingerprints -и evidence reuse — [context authority](development/agent-token-efficiency.md). -Audit-derived работа начинается с найденной записи -[remediation registry](development/audit-remediation.md). Optional agent adapters -не требуются. - -Docs фиксирует проверенное as-built состояние. Planning и Completion Evidence -принадлежат canonical `../specs/openspec`; docs не хранит их параллельную копию. - -## Canonical gate - -Перед Node-командами активировать `.nvmrc` через `nvm use --silent`; это выбирает -Node 22. Не запускать отдельную проверку версии, кроме диагностики runtime issue. -После lockfile install: - -```bash -npm ci -npm run verify -``` - -Gate non-mutating запускает committed Markdown rules и `git diff --check`. Auto-fix и network/browser link checking в gate не входят; local links affected documentation проверяются scoped review. -Актуальные scripts проверять в `package.json`/`npm run`. - -## Boundaries - -- `architecture/` — текущее устройство, `features/` — поставленное поведение, - `adr/` — устойчивые решения, `development/` — процесс и navigation к canonical - evidence, `audits/` — immutable snapshots. Legacy dated evidence не переписывается. -- Indexes должны вести к новым документам. -- Feature docs описывают фактический поток, API и ограничения, но не повторяют OpenSpec requirements/design/tasks. -- Для диаграмм использовать Mermaid в Markdown. Не хранить application code, secrets или competing SDD artifacts. - -Markdown lint и whitespace checks — hard guardrails. Стилистические пожелания без локального checker являются guidance. +Перед Node-командами: `nvm use --silent`. После `npm ci` запускай +`npm run verify` (Markdown lint + `git diff --check`, без auto-fix). +Проверь links/anchors затронутых документов отдельно. Новые документы должны +быть доступны через соответствующий index. Runtime facts сверяй с code/config; +не копируй framework docs, secrets или один контракт в несколько owners. diff --git a/AI_INDEX.md b/AI_INDEX.md new file mode 100644 index 0000000..ec55277 --- /dev/null +++ b/AI_INDEX.md @@ -0,0 +1,74 @@ +# Project knowledge index + +Открывай раздел по конкретному вопросу, затем только нужный source. +Это карта фактов, не обязательное чтение всего docs. Текущий wire contract +генерируется backend; устаревший ADR/пример кода не переопределяет его. + +## HTTP API + +| Trigger | Source | +| --- | --- | +| Endpoint, DTO, validation, status, exception/error shape | [HTTP semantics](architecture/http-api.md) | +| Изменение публичного wire contract, snapshot/generated types | [Contract workflow](development/runtime-openapi-verification.md) | +| Почему Nest — источник OpenAPI | [ADR 002](adr/002-nest-generated-openapi-contract.md) | + +## Security + +| Trigger | Source | +| --- | --- | +| Login/session/logout, cookie/access storage | [Authentication](features/authentication.md) | +| Concurrent/superseded refresh | [ADR 009](adr/009-concurrent-refresh-rotation-policy.md), [термины](architecture/domain-glossary.md#concurrent-refresh-attempt) | +| T-Bank token encryption, connection generation/cache | [Connection](features/tbank-connection.md), [ADR 004](adr/004-encrypted-per-user-tbank-token.md) | + +## Data + +Persistence source — [Prisma schema](../backend/prisma/schema.prisma), +[migrations](../backend/prisma/migrations/). [ADR 001](adr/001-prisma-sqlite-local-mvp.md) +описывает исторический выбор SQLite, не текущий список таблиц. +Transaction/ownership/migration decisions — [backend data guide](../backend/.ai/conventions/backend-data.md). + +## Integrations + +T-Bank/proto/TLS/retry/limits — [connection configuration](features/tbank-connection.md#конфигурация-и-ограничения) +и [server-side boundary](adr/003-tbank-server-side-grpc-boundary.md). +Cache generation — [connection cache](features/tbank-connection.md#граница-финансового-кэша). +Logging — [ADR 008](adr/008-pino-backend-logging.md) и +[реальный logger boundary](../backend/.ai/conventions/backend-architecture.md#logging). + +## Domain + +Начинай с точного термина в [глоссарии](architecture/domain-glossary.md): +[Money](architecture/domain-glossary.md#money), +[Portfolio Position](architecture/domain-glossary.md#portfolio-position), +[Client Cached Snapshot](architecture/domain-glossary.md#client-cached-snapshot), +[Ledger](architecture/domain-glossary.md#account-ledger), +[Realized Income](architecture/domain-glossary.md#realized-income-analytics). +Cross-area topology — [system overview](architecture/system-overview.md). + +## Features + +| Предмет задачи | Current behavior | +| --- | --- | +| Счета и их сводки | [Brokerage accounts](features/brokerage-accounts.md) | +| Позиции/суммы портфеля, backend cache | [Portfolio](features/portfolio-view.md) | +| Операции/фильтры/cursor | [Account ledger](features/brokerage-account-ledger.md) | +| Будущие выплаты | [Upcoming events](features/brokerage-account-upcoming-events.md) | +| Реализованные доходы/периоды | [Income analytics](features/brokerage-account-income-analytics.md) | +| UI recovery/error boundaries | [Frontend resilience](features/frontend-ui-resilience.md) | + +Behavioral requirements при необходимости — через [specs index](../specs/AI_INDEX.md). +Это не запускает SDD lifecycle. + +## UI + +Theme/tokens/reuse — [design system](development/design-system.md). +Существующие components/stories и ограничения — [UI catalog](development/ui-catalog.md). +Query freshness/focus policy — [ADR 007](adr/007-react-query-fetch-policy.md). + +## Engineering + +Scope/abstraction/dependency/testing — [общие правила](development/engineering-governance.md). +Routing/recovery — [context discipline](development/agent-token-efficiency.md). +Commands — [frontend](development/frontend-workflow.md) / [backend](development/backend-workflow.md). +Известный Audit ID — найденная запись [registry](development/audit-remediation.md); +читай её evidence только для этого вопроса. Historical audits не являются live rules. diff --git a/adr/010-native-openspec-sdd-and-local-orchestration.md b/adr/010-native-openspec-sdd-and-local-orchestration.md index b979bfd..089c86f 100644 --- a/adr/010-native-openspec-sdd-and-local-orchestration.md +++ b/adr/010-native-openspec-sdd-and-local-orchestration.md @@ -4,6 +4,21 @@ 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 сохраняются. Ниже оставлено +историческое описание прежней реализации; действующую процедуру определяют +authorities, указанные в ADR 011. Version contract этим уточнением не меняется. + +## Исторический контекст и решение + WealthLedger использует project-local schema `wealth-ledger-sdd` version 3 с последовательностью `Proposal → Delta Specs → Design → Tasks → Apply`, один exact OpenSpec CLI contract из `.cli-version` и тонкие non-mutating verifiers. Это @@ -20,7 +35,7 @@ monorepo control plane для четырёх независимых Git-репо agent entrypoints отклонены для текущего масштаба: они добавляют отдельный projection lifecycle поверх уже достаточных schema, docs и scripts. -## Последствия +## Исторические последствия OpenSpec CLI закреплён exact version contract; новая stable release не включает auto-upgrade, а смена contract является отдельным SDD change со staged diff --git a/adr/011-native-openspec-lifecycle-with-repository-gates.md b/adr/011-native-openspec-lifecycle-with-repository-gates.md new file mode 100644 index 0000000..50a2b4a --- /dev/null +++ b/adr/011-native-openspec-lifecycle-with-repository-gates.md @@ -0,0 +1,52 @@ +--- +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 относится к прежней реализации. +Текущая 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 направляют к ней. + +Отслеживаемый [`.cli-version`](../../specs/openspec/.cli-version) существует и +содержит `1.10.0`. Версия schema и CLI contract — разные сведения. Наличие этого +файла не доказывает запуск прежних verifiers; это решение не меняет CLI pin, +version contract, schema или требования к tooling. + +## Решение + +Частично заменить ADR 010 в части прежней schema version и orchestration. +Canonical SDD store остаётся `wealth-ledger-specs` в `specs/openspec`. +Действующая процедура принадлежит существующим owners: + +- [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 сохраняют описание своего времени. + +Structural success не подтверждает решение Change Owner, semantic compliance +или независимый PASS. Approval bindings, полный применимый context/Design +package, независимая Validation и отдельная Finalization сохраняются. +Замена orchestration не ослабляет gates и не разрешает изменение незатронутых +main-spec requirements о tooling. diff --git a/adr/012-task-driven-development-with-scoped-context.md b/adr/012-task-driven-development-with-scoped-context.md new file mode 100644 index 0000000..38c6947 --- /dev/null +++ b/adr/012-task-driven-development-with-scoped-context.md @@ -0,0 +1,33 @@ +# 012. Прямая разработка с контекстом по задаче + +**Status:** Accepted; supersedes обязательный lifecycle из ADR 010/011. + +## Context + +Обязательная цепочка OpenSpec artifacts не обеспечила соответствие исходному +намерению: суженный change мог пройти все проверки, оставив backend и основные +рекомендации исследований вне реализации. Владелец проекта выбрал прямую +разработку без обязательного OpenSpec/SDD. + +## 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) описывают текущую +работу. 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. + +Имена файлов и примерные context budgets из исследований адаптируются к +WealthLedger: FSD без widgets, Nest как OpenAPI source, существующие локальные +gates. Новые services, CI и checkers ради context architecture не добавляются. diff --git a/adr/README.md b/adr/README.md index a2504da..f4f0be5 100644 --- a/adr/README.md +++ b/adr/README.md @@ -11,4 +11,6 @@ - [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) +- [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) diff --git a/architecture/README.md b/architecture/README.md index bdf2a6d..94095f8 100644 --- a/architecture/README.md +++ b/architecture/README.md @@ -4,5 +4,6 @@ - [Обзор системы](system-overview.md) — поставленные возможности, локальные границы и основные потоки данных. +- [HTTP API и ошибки](http-api.md) — validation, error envelope и границы доказательства. - [Глоссарий домена](domain-glossary.md) — канонические значения терминов. - [ADR](../adr/README.md) — долгоживущие решения и их последствия. diff --git a/architecture/http-api.md b/architecture/http-api.md new file mode 100644 index 0000000..bd013c4 --- /dev/null +++ b/architecture/http-api.md @@ -0,0 +1,59 @@ +# HTTP API и ошибки + +## Источник контракта + +Nest controllers/DTO/Swagger metadata генерируют runtime OpenAPI. Настройка +приложения — [configureApp](../../backend/src/main.ts); frontend хранит derived +snapshot и generated TS. Изменения проходят +[contract workflow](../development/runtime-openapi-verification.md). +API имеет prefix `/api/v1`; Swagger публикуется для локальной разработки по +environment policy, а не используется frontend в runtime. + +## Validation и identity + +Global ValidationPipe использует `transform: true`, `whitelist: true`. +Unknown properties удаляются, а их rejection не обещается без +`forbidNonWhitelisted`. Runtime DTO validators и преобразования задают допустимый +вход; бизнес-ограничения и доступ к account проверяются service/access boundary. +Guard подтверждает identity; accountId из URL сам по себе не доказывает доступ. + +## Error contract + +Общий [HttpExceptionFilter](../../backend/src/common/filters/http-exception.filter.ts) +возвращает `application/problem+json` со `status` и публичным `code`. +Неожиданный exception возвращает `500` / `INTERNAL_SERVER_ERROR`, без исходного +message/stack. Типичный ответ: + +```json +{ "status": 401, "code": "UNAUTHORIZED" } +``` + +Для input validation контракт требует `400`, `VALIDATION_ERROR` и `errors` как +массив `{ pointer, detail }`, где pointer адресует поле запроса. Это требование +не считается проверенным одним Swagger snapshot: direct controller call не +запускает ValidationPipe. Текущий filter преобразует `ValidationError.constraints`, +а default Nest pipe формирует массив строк; корректность field details в +configured HTTP pipeline нужно проверять отдельно и не копировать этот seam +как доказанно полный пример. + +Документированный DTO — [ProblemDetailsDto](../../backend/src/common/decorators/api-safe-error-response.decorator.ts). +Filter не добавляет автоматически все поля из RFC (`type`, `title`, `instance`). +Не вводи дополнительные обязательные поля без согласованного изменения wire contract. +Caller выбирает поведение по public code, не по внутреннему тексту exception. + +## Domain errors и auth + +Специальный code задаётся ответственным use case; generic mapping и безопасный +envelope принадлежат filter. Auth endpoints используют свои status и cookie +operations: [Authentication](../features/authentication.md). +T-Bank token failure и временная недоступность имеют разные значения: +[Connection API](../features/tbank-connection.md#api). Raw upstream/Prisma errors +и secrets не передаются frontend. + +## Граница доказательства + +OpenAPI integration проверяет равенство schemas, а не результат каждого request. +Filter unit test проверяет безопасный unexpected error. Для изменения validation, +guard, status/cookie или domain error нужны representative configured HTTP cases; +известный e2e environment blocker не превращает отсутствующую проверку в success. +Выбор уровня и команд — [backend testing](../../backend/.ai/conventions/backend-testing.md). diff --git a/development/README.md b/development/README.md index 78121bb..feb8db8 100644 --- a/development/README.md +++ b/development/README.md @@ -1,21 +1,13 @@ # Разработка -Здесь размещаются устойчивые правила разработки, локальной проверки и поставки. Требования и планы изменений остаются в `../specs/openspec`. +Работа начинается с задачи пользователя; обязательного OpenSpec/SDD lifecycle нет. +Проектные факты выбирайте через [AI_INDEX](../AI_INDEX.md). -- [Frontend workflow](frontend-workflow.md) — Node 22, локальный запуск и - frontend verification. -- [Дизайн-система](design-system.md) — shared theme, токены и общий UI-набор. -- [UI-каталог Storybook](ui-catalog.md) — запуск, блоки Design System и Product с реальными компонентами - и композициями, безопасные примеры и границы проверки интерфейса. -- [Backend workflow](backend-workflow.md) — bootstrap backend, локальные - non-mutating gates и границы e2e. -- [Audit remediation registry](audit-remediation.md) — статусы findings, следующий - OpenSpec change и ссылки на canonical archived Completion Evidence. -- [Engineering governance](engineering-governance.md) — SDD roles и approvals, - единый UI/UX-пакет Design, Delivery Map, независимая Validation, completion - safeguards и risk-based testing. -- [OpenSpec authority и lifecycle](openspec-authority-and-lifecycle.md) — native - planning, Apply, semantic sync и archive без обязательного agent runtime. -- [Token-efficient agent workflow](agent-token-efficiency.md) — authority для - recovery, fingerprints, актуального handoff и повторного использования evidence. -- [Проверка runtime OpenAPI](runtime-openapi-verification.md) — отдельный read-only contract gate и его границы. +- [Engineering governance](engineering-governance.md) — выбор решения/dependency, risk-based tests, local gates, UI и опасные изменения. +- [Context discipline](agent-token-efficiency.md) — semantic/path routing, sources, recovery и проверка эффективности. +- [Routing eval cases](agent-context-evals.md) — реальные decision cases и counterexamples для conventions. +- [Frontend workflow](frontend-workflow.md) / [backend workflow](backend-workflow.md) — запуск и существующие checks. +- [HTTP contract workflow](runtime-openapi-verification.md) — Nest OpenAPI → snapshot → generated types и контрактная проверка. +- [Дизайн-система](design-system.md) / [UI-каталог](ui-catalog.md) — theme/tokens, реальные components/stories и ограничения. +- [Remediation registry](audit-remediation.md) — найденная запись Audit ID и historical evidence. +- [OpenSpec](openspec-authority-and-lifecycle.md) — optional legacy workflow, только по явному запросу. diff --git a/development/agent-context-evals.md b/development/agent-context-evals.md new file mode 100644 index 0000000..a03409d --- /dev/null +++ b/development/agent-context-evals.md @@ -0,0 +1,50 @@ +# Проверка agent context + +Это небольшой corpus решений для настройки routing. Выполняйте cases по текущим +AGENTS/router/conventions: сначала определите решение и необходимые источники, +затем сравните с ожиданием. Это не unit tests, повторяющие Markdown, и не новый +verification framework. Для проверки изменения правила нужны activating case, +допустимое исключение и unrelated counterexample. + +## Cases + +| Задача | Необходимый контекст / ожидаемое решение | Что не должно активироваться без новой границы | +| --- | --- | --- | +| Изменить props и layout existing finance view | Frontend UI; props остаются presentation, derived collection values — у VM | API, Prisma, architecture, tests без risk/test change | +| Исправить только продуктовую строку/Zod message | UI section «Строки и валидация»; locale/validationMessage, mandatory review | Остальные UI sections, HTTP/structure/testing | +| Добавить page-local фильтр без сети | Frontend architecture + UI; оставить у page, если нет independent capability | Новый shared abstraction/feature ради click; API | +| Добавить business summary component | Architecture + UI; business meaning и existing owner определяют placement | shared только из-за reuse; widgets layer | +| Изменить query refetch/error recovery | Frontend data + testing; cached snapshot/current generation и exact feature source | Backend data при неизменном server behavior | +| Добавить новый HTTP response field | Backend HTTP + общий contract workflow + применимые tests; Nest → snapshot → generated TS, affected client data rules | Второй editable OpenAPI в specs; ручной generated TS | +| Добавить account endpoint с новым RPC | Backend HTTP, architecture при новом use case, security/access, integrations, testing; TbankAccessService/TbankClient | Прямой gRPC из controller; доверие accountId без ownership | +| Исправить только Prisma query без HTTP/auth boundary | Backend data, testing при data-risk; existing PrismaService | Весь HTTP/security guide автоматически | +| Атомарно обновить связанные записи | Data + testing; transaction/constraint у инварианта, isolated DB proof | Generic repository; mock как доказательство реальной atomicity | +| Изменить конкурентный refresh | Security + data + testing; ADR 009; один winner, superseded не отзывает его session | Replay-history/grace window без задачи; новый coordinator | +| Изменить DTO validation error | HTTP + testing + exact error source; configured HTTP case проверяет pipe/filter pair | Success по одному direct controller call/Swagger snapshot | +| Изменить gRPC retry/deadline | Integrations + testing; bounded existing client path, controlled upstream failure | Вложенный retry loop; реальная сеть/secret | +| Добавить безопасное scalar log field | Architecture/logging; проверить allowlist и event | Весь auth guide без sensitive boundary; считать message автоматически redacted | +| Изменить только тест | Testing соответствующего repo; source guides только по проверяемой границе | Все production conventions из-за расширения `.ts` | +| Добавить dependency/adapter для одной задачи | Общий выбор/dependencies; existing owner/platform/library прежде нового кода | Новый interface только для hypothetical reuse | +| Исправить опечатку в общей документации | Docs AGENTS и затронутый source | Любые frontend/backend conventions | +| После UI начала появились mutation/schema/new files | Routing повторяется по staged/unstaged/new, новые границы читаются до решения | Продолжать по первоначальному UI-only scope | +| Отсутствует обязательный security source / источники конфликтуют | Остановить зависимое решение, восстановить факт/уточнить задачу | Догадка из соседнего code или жёсткий лимит на число документов | + +## Что измерять + +Для startup/working-set измерения перечислите ровно прочитанные файлы/sections, +инструмент подсчёта и unit (символы или tokenizer). Required source нельзя +исключать только ради хорошего числа. Число доступных файлов на диске не является +стоимостью конкретной задачи. + +Для реальной first-pass оценки выполните одинаковые задачи с одинаковой моделью, +version/tools и comparable prompts: прежний context, только новые indexes, +затем полный routing. Считайте принятие без substantive correction, iterations, +ошибки placement/contract/security, лишние abstractions и пропущенные sources. +Routing review и зелёные application tests сами по себе такого улучшения не доказывают. + +## Изменение правил + +Если нужный source не прочитан — исправьте trigger. Если source прочитан, но +не разрешает выбор — уточните decision/safe path/example. Если дефект +детерминирован — используйте подходящий existing test/linter. Не добавляйте +новый always-on paragraph для каждого отдельного случая. diff --git a/development/agent-token-efficiency.md b/development/agent-token-efficiency.md index bf8c755..3803df5 100644 --- a/development/agent-token-efficiency.md +++ b/development/agent-token-efficiency.md @@ -1,160 +1,62 @@ -# Token-efficient agent workflow +# Context discipline -## Authority и границы - -Этот документ — vendor-neutral authority для context discipline: recovery, -fingerprint bindings, bounded reads и observed evidence. Lifecycle ownership -принадлежит [Engineering governance](engineering-governance.md), native команды -— [OpenSpec lifecycle](openspec-authority-and-lifecycle.md). Эти процедуры -выполняются без обязательных skills, session adapter, telemetry или service. - -Исходный наблюдаемый baseline сохранён в -[аудите сессий 26.08.2026](../audits/codex-sessions-token-audit-2026-08-26.md). -Raw logs и числовые token budgets не становятся delivery gates. Экономия -контекста не оправдывает пропуск relevant authority или ослабление verification. +Цель — получить правила, которые меняют текущее решение, и не читать остальные +заранее. Это процедура прямой работы по задаче, без обязательных SDD artifacts, +ролей, approval fingerprints или подсчёта документов как delivery gate. ## Routing context -До supporting reads определите текущую роль, разрешённый outcome и affected -repositories. Прочитайте их local `AGENTS.md` для boundaries и canonical gates, -затем только применимую authority: +1. Определи требуемое поведение, тип решения и affected repos до supporting reads. +2. Прочитай root/local AGENTS, затем CONVENTIONS и SOURCES affected code repo. +3. Объедини сработавшие semantic, path и boundary triggers. Путь — сигнал ответственности, а не повод загружать всё по расширению `.tsx`/`.ts`. +4. Прочитай выбранные conventions или явно указанные sections до зависимого решения. При domain/API/security вопросе открой точный source через [docs index](../AI_INDEX.md). +5. Проследи ближайший существующий owner и подходящие код/тесты. Его поведение не заменяет canonical fact. +6. Повтори routing при новой потребности и по финальным staged, unstaged и новым файлам. Содержимое работы важнее первоначального названия задачи. -| Trigger | Context | -| --- | --- | -| Planning или Implementation | Native instruction и каждый возвращённый context file; применимые материалы через canonical Design | -| Approval, роль, testing, Delivery Map или completion | Релевантный раздел governance | -| Cross-area architecture | `architecture/system-overview.md`, нужные ADR/feature docs | -| Domain или API semantics | Термин в `architecture/domain-glossary.md`, canonical contract/spec | -| Известный Audit ID | Найденная запись `audit-remediation.md` и её source/evidence | -| Validation | Approved artifacts, delivery inventory, relevant checks и findings | -| Finalization | Текущий независимый verdict с binding и существующие delivery facts | +Первый проход работает без diff. Auth + refresh, например, активирует API, +security и testing вместе. Отображение query state без изменения запросов не +добавляет transport rules. Docs-only опечатка не требует frontend/backend conventions. +Обычно хватает нескольких тем; это наблюдение, не лимит. Обязательный source +нельзя пропускать ради числа файлов или token budget. -В новой роли canonical artifacts читаются заново только в необходимом scope. -В том же context повторно читаются изменившиеся relevant inputs. История чата -не заменяет artifact и не является обязательным prerequisite. +Новая граница внутри задачи требует дочитать правила до работы. Расширение +самой задачи сначала сообщи пользователю; уже данное разрешение не запрашивай +повторно. Чужой concurrent diff учитывай при разграничении ownership. + +## Источники и конфликты + +Прямое указание пользователя определяет задачу. Текущий executable HTTP contract +генерируется backend; docs описывает проектные факты/решения; conventions задают +выбор реализации; code показывает существующие аналоги. Generic framework advice +используется после проектных источников. Research содержит рекомендации, которые +нужно сверить с actual code/config, а не автоматически превращать в новый контракт. + +Если задача намеренно меняет контракт, обновляй его source и зависимые материалы +согласованно. Missing input, противоречие security/data правил или неоднозначный +контракт блокируют только зависимое решение до установления фактов/уточнения. +История чата, случайный аналог и предполагаемый путь не заменяют источник. ## Recovery и handoff -При наличии session adapter mutable state является единственным navigation -pointer. Прочитайте только его текущий self-contained immutable record, затем -phase-specific authority. Без adapter тот же актуальный envelope передаётся -в доступном рабочем контексте; отдельный versioned verdict или planning store -ради handoff не создаётся. +Для продолжения достаточно текущей задачи, сделанных изменений, remaining work, +точных checks/results и blockers. Не создавай параллельную копию требований, +Design, state registry или обязательный handoff-файл. -Envelope содержит только change identity, текущую роль/outcome, affected areas, -observed approval bindings, completed/remaining task IDs, краткие observed checks, -blockers и один следующий допустимый outcome. Для продолжения после Validation -он также сохраняет её verdict, relevant inventory и fingerprint; Finalization -retry не должен требовать восстановления цепочки старых records. Requirements, -Design, Tasks и acceptance scenarios остаются в canonical OpenSpec. +В новом контексте восстанови необходимые sources; в том же переиспользуй уже +прочитанные неизменившиеся inputs. Supporting reads добавляй по возникшему вопросу. +Git status/diff показывают staged и unstaged; новые файлы учитывай отдельно. +Relevant ignored/workspace-owned inputs (например `.env`, root AGENTS) не +теряются только потому, что Git их не показывает. Секреты в evidence не печатай. -Первичное `approved` записывается только после явного решения Change Owner, -со ссылкой на наблюдённый источник решения, artifact identity и fingerprint. -При recovery совпадение позволяет продолжить без повторного approval. Отсутствие -binding, включая legacy state, требует явного решения; mismatch сбрасывает -approval изменённого artifact и всех downstream artifacts. Approval status -сохраняет наблюдение, но не доказывает личность или решение владельца сам по себе. +## Проверка эффективности -Порядок сохранения: `canonical outcome → immutable record → state pointer`. -Сначала создаётся новый record; существующие records не перезаписываются. Перед -заменой pointer проверяется, что исходный state не изменён другим участником. -Конфликт или неполная запись остаются видимыми и не разрешаются last-write-wins. -Старые records читаются только для расследования конкретного текущего расхождения. +Используй [набор routing cases](agent-context-evals.md) для настройки новых правил. +Проверяй activating case, safe exception и unrelated counterexample по реальным +инструкциям. Source links и gates дополняют эту проверку, но не доказывают first-pass quality. -## Fingerprints - -Fingerprint имеет вид `sha256:<64 lowercase hex digits>` и связывает observation -с содержимым, а не только с именем файла, временем изменения или Git HEAD. -Одинаковая процедура применяется к approval artifact, gate inputs и PASS; -отличаются только scope и явно указанная ниже нормализация task progress. - -### Scope и inventory - -До проверки сохраните reviewed inventory: workspace-relative точные пути и -релевантные directory roots, их явные exclusions, назначение набора и список -входящих files. Directory roots должны включать новые files, способные изменить -проверяемый результат; произвольный список только уже известных изменённых files -недостаточен. Scope покрывает все actual inputs gate/review, включая dependency -и config files. Unrelated concurrent change исключается по объяснённой границе, -а не потому, что мешает получить прежний fingerprint. - -- Proposal и Tasks — соответствующий canonical файл. Design — его Markdown - и все перечисленные применимые материалы, включая exact immutable reuse - inputs. Перечень разрешается из Design, без параллельного visual registry; - missing, ambiguous или изменённый материал блокирует dependent outcome по - [UI/UX policy](engineering-governance.md#uiux-пакет-design). Сам Design не - содержит собственного digest. Delta Specs — - полный разрешённый native CLI набор `specs/**/spec.md` этого change; при - сравнении membership запрашивается заново, чтобы обнаружить additions/removals. -- PASS включает raw approved planning artifacts, relevant main baseline, - проверенные delivery files affected areas и local unversioned instructions, - если они входят в change. Runtime/gate command и environment prerequisites - сохраняются рядом с fingerprint как observed metadata. -- Для каждого Git repository candidate paths получают через - `git ls-files --cached --others --exclude-standard -z`, затем пересекают - с reviewed roots/paths и de-duplicate. Это включает tracked и nonignored - untracked, staged и unstaged working content. Workspace-owned paths вне Git - перечисляются явно; relevant ignored inputs также включаются явно. -- При сравнении заново раскрываются те же roots и добавляются paths из прежнего - inventory: исчезнувший файл остаётся entry `missing`, новый входит в набор. - Directory names не хешируются отдельно. Пути используют `/`, относительно - workspace, без `.`/`..`, абсолютного host prefix и повторов. -- Собственные navigation state, phase records и - `changes//completion-evidence.md` исключаются из self-hash. Exclusions - относятся к конкретному change, не ко всем `.agents`, `.opencode` или specs. - Ожидаемые archive/sync/evidence/registry mutations проверяются отдельно как - completion outputs; ими нельзя скрыть новое implementation изменение. - -### Детерминированное представление - -1. Для каждого entry прочитайте текущие bytes из working tree. `file` получает - mode `100755`, если установлен хотя бы один executable bit, иначе `100644`. - `symlink` получает mode `120000`, payload — bytes самого link target без - разыменования. Для отсутствующего прежнего path используйте kind `missing`, - mode `-`, digest `-`. Unresolved Git conflicts, unreadable inputs и special - files блокируют binding; приблизительный fingerprint не создаётся. -2. Только для **approval Tasks** замените ASCII prefix `b"- [x] "` на `b"- [ ] "` - у строк canonical task checkbox (`X.Y [area]` после prefix). Другие bytes, - whitespace, строки, `Covers` и `Verification` не меняются. Во всех остальных - наборах, включая gate/PASS и их Tasks, используется raw payload. Таким образом - observed progress не отменяет approval содержания, но остаётся виден review. -3. Рассчитайте lowercase SHA-256 hex digest payload каждого существующего entry. - Отсортируйте entries по UTF-8 bytes workspace-relative path. Непредставимые - в UTF-8 paths требуют явного разрешения input issue, а не замены символов. -4. Соберите byte stream: ASCII prefix `wealth-ledger-input-v1` и один NUL byte, - затем для каждого entry UTF-8 fields `path`, `kind`, `mode`, `digest`, каждый - с завершающим NUL. Пробелы, JSON, newline separators и BOM не добавляются. - SHA-256 этого stream с prefix `sha256:` — fingerprint всего набора. - -Inventory и fingerprint не содержат копии исходных artifacts. Если review -зависит от содержимого symlink target, target включается отдельным input; -хеширование только ссылки не подтверждает внешнее содержимое. Перенос файлов, -изменение mode, content или membership меняют binding. Commit/staging без -изменения этих данных его не меняют. Relevant input mutation инвалидирует PASS; -изменение planning approval fingerprint дополнительно применяет cascade policy. - -## Повторное использование evidence - -Сохранённый успешный gate повторно используется при совпадении его input scope, -fingerprint и relevant environment prerequisites. Evidence сохраняет exact -command, cwd, exit status и достаточный observed result. Неизвестный scope или -отсутствующий binding не доказывают неизменность. Нельзя заменить full gate -результатом проверки части файлов. - -Validation независимо оценивает свежесть gates и semantic/acceptance behavior; -успех Implementation tests сам по себе не даёт независимый PASS. Finalization -сверяет последний PASS до terminal mutations и потребляет его без повторения -неизменившихся checks. Expected archive move, approved semantic sync и создание -Completion Evidence проверяются как новые completion outputs; их effect не -переписывает сохранённое описание проверенного delivery input. - -## Evidence batching - -Один batch заканчивается перед следующим смысловым решением. Независимые -read-only inputs получают вместе; adaptive discovery, side effects и approvals -остаются последовательными. Начните с `rg`/identity search или Git status/stat, -затем раскройте relevant paths. Successful output сохраняет команду, exit status -и существенный outcome; failure, semantic verification и review получают весь -relevant evidence. Произвольный лимит строк не должен скрывать диагностический -сигнал. Контекст оценивается вместе с качеством checks, findings и rework, -а не по сокращению tokens отдельно. +Сравнивай startup context и реально выбранные sections, фиксируя способ измерения. +Не объявляй меньшее число файлов или зелёный application test улучшением качества +агента. Для first-pass acceptance нужны одинаковые реальные задачи/модель/tools, +наблюдённые ошибки ownership/contract/security и число исправлений. +Добавляй convention по повторяющейся decision error; уточняй trigger при missed +source; deterministic regression отдавай существующему test/linter, если он подходит. diff --git a/development/audit-remediation.md b/development/audit-remediation.md index 1053a2c..c066dba 100644 --- a/development/audit-remediation.md +++ b/development/audit-remediation.md @@ -14,18 +14,20 @@ `confirmed` ещё может быть active, а `rejected` — accepted как проверенное решение ничего не внедрять. - Одновременно допускается не более одного `active` remediation change. Пока он существует, продолжается только он. При наличии `planned` ровно одна запись отмечается следующей рекомендуемой задачей, но она не запускается параллельно active change. -- `done` требует даты и ссылки на canonical archived OpenSpec change с его - `completion-evidence.md`. Существующие delivery commits, exact verification - commands/results и independent verdict хранятся там, а не дублируются в registry. +- Новая запись `done` требует даты и ссылки на фактически выполненную работу и её проверки (например, commit/PR или существующее evidence). OpenSpec archive не является обязательным; не создавайте отдельные artifacts только ради статуса. - `deferred` и `accepted` требуют даты, rationale и review trigger либо ссылки на явное решение владельца. - При смене статуса обновляется только этот реестр; versioned audit snapshot не редактируется. -Completion procedure определена в -[OpenSpec lifecycle](openspec-authority-and-lifecycle.md#finalization-и-completion-evidence). -Новая запись `done` ссылается на evidence внутри archive. Исторические записи +Текущая проверка результата определена в +[engineering governance](engineering-governance.md#проверка-результата). +Исторические записи ниже, прежние ссылки на `completion-evidence.md` в docs и датированные audit snapshots сохраняются без переноса или переписывания задним числом. +Датированные dispositions ниже описывают проверки и решения своего времени; +они не восстанавливают прежние SDD prerequisites. Live ссылки ведут к текущим +owners, а историческое evidence сохраняется по исходным адресам. + ## Текущее состояние workflow - Bootstrap change: [`2026-08-23-establish-audit-remediation-workflow`](../../specs/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/) — `archived`; это process foundation и не закрывает ни одного Audit ID. @@ -70,14 +72,14 @@ remediation change создаётся после выбора владельце | FE26-05 | Безопасно отклонять невозможные календарные даты. | [FE-G] F-03 | already-covered | done | 06.09.2026; [FE26-E]. [Income VM](../../frontend/src/pages/account-income/ui/AccountIncomePage.vm.ts) проверяет finite date до ISO conversion; [regression tests](../../frontend/src/pages/account-income/ui/AccountIncomePage.test.tsx) покрывают invalid date и leap year. | | FE26-06 | Включить type-only dependencies в public API guardrail. | [FE-G] F-04 | already-covered | done | 06.09.2026; [FE26-E]. [dependency-cruiser](../../frontend/dependency-cruiser.cjs) включает tsPreCompilationDeps; [shared API](../../frontend/src/shared/api/index.ts) экспортирует paths. | | FE26-07 | Дать общим display/API primitives нейтральных владельцев. | [FE-G] F-05; [FE-S] F-07 | already-covered | done | 06.09.2026; [FE26-E]. [shared display](../../frontend/src/shared/lib/display.ts) владеет Money/date/logo; [apiErrorCode](../../frontend/src/shared/api/problem-details.ts) объединяет transport extraction. S F-07 расширяет тот же ownership claim API helper; повторной реализации нет. | -| FE26-08 | Синхронизировать entrypoint docs с фактическими gates. | [FE-G] F-06 | already-covered | done | 06.09.2026; [FE26-E]. [Frontend README](../../frontend/README.md), [conventions](../../frontend/docs/CONVENTIONS.md) и [workflow](frontend-workflow.md) описывают существующие команды, не обещая удалённые runtime/hygiene checks. | -| FE26-09 | Убрать механическое обязательное дробление каждого component. | [FE-G] F-07 | already-covered | done | 06.09.2026; [FE26-E]. [UI pattern](../../frontend/docs/UI-PATTERN.md) сохраняет semantic ownership и допускает tightly-coupled renderers; это guidance, а не line-count gate. Конкретное разделение крупных modules учтено отдельно FE26-13. | +| FE26-08 | Синхронизировать entrypoint docs с фактическими gates. | [FE-G] F-06 | already-covered | done | 06.09.2026; [FE26-E]. [Frontend README](../../frontend/README.md), [conventions](../../frontend/.ai/conventions/frontend-ui.md) и [workflow](frontend-workflow.md) описывают существующие команды, не обещая удалённые runtime/hygiene checks. | +| FE26-09 | Убрать механическое обязательное дробление каждого component. | [FE-G] F-07 | already-covered | done | 06.09.2026; [FE26-E]. [UI pattern](../../frontend/.ai/conventions/frontend-ui.md) сохраняет semantic ownership и допускает tightly-coupled renderers; это guidance, а не line-count gate. Конкретное разделение крупных modules учтено отдельно FE26-13. | | FE26-10 | Объединить protected query policy и endpoint query identity ownership. | [FE-G] F-08; [FE-S] F-05 | already-covered | done | 06.09.2026; [FE26-E]. [App defaults](../../frontend/src/app/ui/App.tsx), [T-Bank VM](../../frontend/src/features/tbank-connection/ui/TbankConnectionSection.vm.ts) и entity-owned options operations/portfolio; status использует общий authenticated query seam. | | FE26-11 | Централизовать test cleanup и auth reset. | [FE-S] F-02 | already-covered | done | 06.09.2026; [FE26-E]. [Test setup](../../frontend/src/test/setup.ts): RTL cleanup, auth reset, MSW handler reset в общем afterEach. | | FE26-12 | Убрать повтор server identity из Income view/model. | [FE-S] F-03 | confirmed | done | 06.09.2026; [FE26-E]. [Backend income service](../../backend/src/tbank/income-analytics.service.ts) передаёт instrumentKey; [Income VM](../../frontend/src/pages/account-income/ui/AccountIncomePage.vm.ts) проверяет и группирует готовую связь, не вычисляя identity. | | FE26-13 | Выделить самостоятельные ответственности семи крупных TSX modules. | [FE-S] F-04 | already-covered | done | 06.09.2026; [FE26-E]. Income/Events/Accounts/Account state views, [route fallback](../../frontend/src/app/routes/RouteFallback.tsx), [guards](../../frontend/src/app/routes/RouteGuards.tsx), breadcrumbs и T-Bank loaded section выделены во frontend `c97f62b`. | | FE26-14 | Устранить повтор test client policy и нестабильный cache lifetime. | [FE-S] F-06 | confirmed | done | 06.09.2026; [FE26-E]. [Test query factory](../../frontend/src/test/query.tsx) используется оставшимися auth/T-Bank harnesses; [auth test](../../frontend/src/features/auth/model/auth.test.tsx) проверяет сохранение client и seeded cache при rerender. | -| FE26-15 | Перенести компонентные стили из global CSS к владельцам. | [FE-S] F-08 | already-covered | done | 06.09.2026; [FE26-E]. [Global styles](../../frontend/src/app/styles.css) содержат базовые правила; AppShell, breadcrumbs и auth используют CSS Modules, StateView — Mantine props. | +| FE26-15 | Перенести компонентные стили из global CSS к владельцам. | [FE-S] F-08 | already-covered | done | 06.09.2026; [FE26-E]. [Global styles](../../frontend/src/shared/theme/styles.css) содержат базовые правила; AppShell, breadcrumbs и auth используют CSS Modules, StateView — Mantine props. | | FE26-16 | Исправить source connectedAt contract вместо String coercion. | [FE-S] F-09 | already-covered | done | 06.09.2026; [FE26-E]. [Backend DTO](../../backend/src/tbank/tbank-connection.dto.ts) задаёт nullable date-time string; [frontend consumer](../../frontend/src/features/tbank-connection/ui/TbankConnectionSectionLoaded.tsx) не скрывает неверный transport type через String. | | FE26-17 | Перенести auth validation и payment invariants из JSX к model owners. | [FE-S] F-10 | already-covered | done | 06.09.2026; [FE26-E]. [Auth validation](../../frontend/src/features/auth/model/validation.ts), [ledger display](../../frontend/src/entities/broker-operation/model/display.ts) владеют соответствующими правилами. | | FE26-18 | Удалить redundant position modes и test-only proxy exports. | [FE-S] F-11 | already-covered | done | 06.09.2026; [FE26-E]. [PositionCard](../../frontend/src/pages/account/ui/components/PositionCard.view.tsx) выводит mode из kind; [StateView](../../frontend/src/shared/ui/StateView.tsx) не экспортирует Mantine Button; page barrels сохраняют product surface. | @@ -137,12 +139,12 @@ authority. | SDD26-03 | Каждая task должна иметь однозначную delivery area; multi-repo implementation нужно разделять. | [D], [G], [Z] | confirmed | done | 2026-08-26; schema v2 использует `[frontend\|backend\|specs\|docs\|workspace]`; planning verifier отклоняет owner из `N/A` area. | | SDD26-04 | Добавить `Target Repositories` уже в Proposal. | [G] | rejected | accepted | 2026-08-26; Proposal остаётся owner-readable intent без implementation topology. Полный scope repositories определяется позже через обязательную Design Delivery Map. | | SDD26-05 | Явно координировать порядок и совместимость multi-repository delivery. | [D], [G] | already-covered | accepted | 2026-08-26; Delivery Map, Contract Gate Decision, Migration Plan и workspace dispatcher уже задают owners, порядок, совместимость API и canonical gates. | -| SDD26-06 | Формализовать trigger для Solution Assessment. | [D] | already-covered | accepted | 2026-08-26; [engineering governance](engineering-governance.md#build-versus-buy) и schema перечисляют auth, security, storage, integrations, observability, caching, concurrency и shared tooling. | +| SDD26-06 | Формализовать trigger для Solution Assessment. | [D] | already-covered | accepted | 2026-08-26; [engineering governance](engineering-governance.md#dependencies) и schema перечисляют auth, security, storage, integrations, observability, caching, concurrency и shared tooling. | | SDD26-07 | Не допускать Design/Apply по неутверждённым artifacts. | [D], [K], [Z] | already-covered | accepted | 2026-08-26; human approval хранится в разговоре, one-artifact entrypoints останавливаются, downstream approvals каскадно инвалидируются. Фиктивный `approval.md` или status field не создаётся. | | SDD26-08 | Разрешить partial/diff `MODIFIED` вместо полного requirement block. | [D] | rejected | accepted | 2026-08-26; native OpenSpec archive semantics требуют полного `MODIFIED`; собственный merge format создал бы второй transformation engine и риск потери scenarios. | | SDD26-09 | Дать компактные примеры сложных delta operations. | [D], [K] | confirmed | done | 2026-08-26; schema v2 добавляет `MODIFIED`, `REMOVED` и `RENAMED` examples, сохраняя minimal ADDED-first template. | | SDD26-10 | Генерировать в `spec.md` placeholders всех delta sections. | [K] | rejected | accepted | 2026-08-26; пустые sections повышают шум и риск неверной операции. Complex forms принадлежат instructions/examples, а template остаётся минимальным. | -| SDD26-11 | Явно определить DoD, verification и archive после Apply. | [D], [K], [Q] | already-covered | accepted | 2026-08-26; [engineering governance](engineering-governance.md#verify-archive-и-completion-evidence), workspace dispatcher, semantic verification, independent review и hard archive blockers уже образуют terminal protocol. Completion Evidence создаётся после факта, не в Tasks. | +| SDD26-11 | Явно определить DoD, verification и archive после Apply. | [D], [K], [Q] | already-covered | accepted | 2026-08-26; [engineering governance](engineering-governance.md#проверка-результата), workspace dispatcher, semantic verification, independent review и hard archive blockers уже образуют terminal protocol. Completion Evidence создаётся после факта, не в Tasks. | | SDD26-12 | Связать каждую task с точными Delta Requirements и отклонять uncovered requirements. | [D], [K] | confirmed | done | 2026-08-26; schema v2 использует native identity `capability path — exact Requirement heading`; planning verifier проверяет ссылки и полное покрытие без собственного ID namespace. | | SDD26-13 | Добавить Fast Track или сокращённую вторую schema для мелких fixes. | [G] | rejected | accepted | 2026-08-26; один lifecycle сохраняет предсказуемые approvals и archive blockers. Пропорциональность обеспечивают `skip_specs`, conditional assessment/rollback и узкие tasks. | | SDD26-14 | Ограничивать agent context через tool-specific `.aiignore` и список repos из Proposal. | [G] | rejected | accepted | 2026-08-26; это не portable OpenSpec invariant. Context ограничивается Delivery Map, task owner и targeted reads; dependencies/build outputs уже исключаются локальными tool/repository rules. Пересмотреть при наблюдаемом context exhaustion. | diff --git a/development/engineering-governance.md b/development/engineering-governance.md index 74e3142..bbc5911 100644 --- a/development/engineering-governance.md +++ b/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//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). diff --git a/development/frontend-workflow.md b/development/frontend-workflow.md index c0d2eca..a5ff87d 100644 --- a/development/frontend-workflow.md +++ b/development/frontend-workflow.md @@ -16,14 +16,14 @@ Storybook. Он работает без backend. Coverage Изолированные примеры реальных компонентов и композиций запускаются в Storybook через `npm run dev:catalog`. `npm run build:catalog` создаёт `storybook-static/`, -а `npm run preview:catalog` обслуживает эту статическую сборку. Шесть групп, +а `npm run preview:catalog` обслуживает эту статическую сборку. Структура каталога, работа с Docs, Controls и Actions, доступность и ограничения описаны в [UI-каталоге Storybook](ui-catalog.md). -Для UI change используйте каталог как reference существующего решения, затем -зафиксируйте применимый [пакет Design](engineering-governance.md#uiux-пакет-design) -в canonical OpenSpec. Storybook показывает реализацию и не заменяет согласованную -версию Design или независимую проверку соответствия. +Для UI задачи используйте каталог как reference существующего решения. +Ожидаемые экраны, states и interactions определите по [задаче](engineering-governance.md#ui-решения). +Storybook показывает реализацию; визуальное соответствие и доступность +проверяются отдельно от сборки. SDD-пакет для этого не обязателен. Backend остаётся источником OpenAPI. После изменения опубликованного backend-контракта разработчик обновляет в `frontend/` committed snapshot diff --git a/development/openspec-authority-and-lifecycle.md b/development/openspec-authority-and-lifecycle.md index 9be4898..195fc16 100644 --- a/development/openspec-authority-and-lifecycle.md +++ b/development/openspec-authority-and-lifecycle.md @@ -1,198 +1,35 @@ -# OpenSpec authority и lifecycle +# OpenSpec: optional legacy workflow -## Назначение +Обязательный SDD lifecycle отменён для обычной разработки. Текущие правила — +[engineering governance](engineering-governance.md), +[context discipline](agent-token-efficiency.md) и root/local AGENTS. +Задача пользователя не требует Proposal/Delta/Design/Tasks, отдельных agent roles, +Completion Evidence или archive как условия завершения. -Это исполняемая процедура canonical workflow без обязательного agent runtime. -Роли, approvals, Delivery Map и completion safeguards определяет -[Engineering governance](engineering-governance.md); чтение контекста и bindings -— [context authority](agent-token-efficiency.md). Optional skills и commands -могут выполнять те же шаги, но не заменяют эти authorities. +## Существующие материалы -## Единственный SDD store +`specs/openspec` сохраняет behavioral specs, active changes, schemas и archives. +Существующий planning artifact описывает только свой прежний scope и не доказывает +готовность нового запроса. Датированные evidence/archives не переписываются. +Нужную behavioral spec выбирай через [specs index](../../specs/AI_INDEX.md). -Canonical store — `wealth-ledger-specs`, физический root — `specs/openspec` -относительно workspace. Все команды, читающие или изменяющие change, получают -`--store wealth-ledger-specs`; cwd и nearest-root discovery не выбирают authority. -Planning artifacts, main specs, changes, Completion Evidence и archives -принадлежат только этому store. `references/**` остаётся read-only; historical -archives не переписываются. +## Если OpenSpec запрошен явно -## Native planning - -Перед Node-командами выберите runtime через применимую `.nvmrc` командой -`nvm use --silent`. Работая с change, сначала получите его фактическую структуру: +Canonical store прежнего workflow — `wealth-ledger-specs`, физически +`specs/openspec`. Перед Node-командами выбери frontend `.nvmrc`, если у specs +нет своей. Для чтения/изменения change всегда задавай store явно: ```bash openspec status --change --json --store wealth-ledger-specs -``` - -Для нового согласованного change используется native -`openspec new change --store wealth-ledger-specs`. До создания Proposal -Discovery разрешает неизвестные intent/scope вопросы. В Specification запрашивайте -только разрешённый сейчас artifact: - -```bash openspec instructions --change --json --store wealth-ledger-specs ``` -`` — `proposal`, `specs`, `design` или `tasks`. Прочитайте все -возвращённые dependencies/context files, подготовьте artifact по native -instructions, выполните доступную native structural проверку и получите -отдельный approval перед downstream artifact. Tasks instructions возвращают -Design и Delta Specs для exact `Covers`; второй context mapping не нужен. -Approval и bounded progression соблюдают governance policy. +Native status/instructions определяют фактические artifacts и schema. Получай +разрешение на именно запрошенное изменение, не выводи approval из наличия файлов. +Sync/archive меняют existing specs/history и выполняются только в рамках такой +явной задачи, после проверки ожидаемого semantic diff и сохранности данных. +Structural validation не доказывает соответствие реализации задаче. -Для Design определите -[UI/UX applicability и пакет](engineering-governance.md#uiux-пакет-design). -Прочитайте его применимые материалы, проверьте сохранённые пути, revision, -доступность и SHA-256 exports обычными файловыми операциями. Представьте весь -пакет в одном Design approval; native structural validation не проверяет -произвольные attachments или качество визуального решения автоматически. - -Новые changes используют project-local schema `wealth-ledger-sdd` из -`specs/openspec/schemas/wealth-ledger-sdd` и граф -`proposal → specs → design → tasks → apply`. `config.yaml` хранит default schema -и routing context, schema — форму artifacts и stage-specific instructions. -Проверка из `specs`: - -```bash -openspec schema validate wealth-ledger-sdd --verbose -openspec schema which wealth-ledger-sdd --json -``` - -`schema which` должен указывать project-local source. Delta template остаётся -operation-neutral guide: автор создаёт только применимые `ADDED`, `MODIFIED`, -`REMOVED`, `RENAMED` sections. Native validation проверяет структуру, не approval. - -## Implementation и Validation - -После approval Tasks получите native Apply context: - -```bash -openspec instructions apply --change --json --store wealth-ledger-specs -``` - -Прочитайте каждый возвращённый `contextFiles` и local `AGENTS.md` affected -repositories. Выберите связный batch pending Tasks, реализуйте его и выполните -релевантные checks. Зафиксируйте завершённые canonical checkboxes и observed -outcome. Remaining implementation work даёт checkpoint; вся завершённая работа -— готовность к отдельной Validation. Изменение artifact проверяется по -[approval binding](agent-token-efficiency.md#fingerprints), а semantic issue -возвращается к ответственной planning boundary. - -При применимом UI/UX scope восстановите именно согласованный пакет из Design -до зависимой реализации. Missing material, digest mismatch и external-only -reference не компенсируются историей чата или текущим внешним макетом. - -Validation читает approved planning artifacts и implementation scope, проверяет -свежесть сохранённых gate outcomes и выполняет отсутствующие affected gates. -Глобальный gate нельзя считать проверенным по более узкому fingerprint: binding -покрывает его relevant inputs. Specs gate использует native strict checks: - -```bash -openspec validate --type change --strict --store wealth-ledger-specs -openspec validate --specs --strict --store wealth-ledger-specs -``` - -Canonical gate остальных areas задан их `AGENTS.md`. Required -`runtime-openapi` дополнительно вызывает backend `npm run test:openapi-contract`. -Независимый reviewer сопоставляет реализацию с approved artifacts, acceptance -scenarios и применимыми edge cases; фиксирует `PASS`, `FAIL` или `SPEC_ISSUE`, -полный relevant evidence и reviewed input inventory/fingerprint. Он не исправляет -код, planning artifacts или Tasks. Отдельный versioned verdict artifact не -требуется: observed verdict и binding передаются в текущем handoff и затем -в canonical Completion Evidence. - -Для UI/UX reviewer читает пакет той же revision и сопоставляет применимые -экраны, состояния, взаимодействия и responsive behavior. Однозначное отклонение -реализации — `FAIL`; противоречие либо неоднозначность пакета — `SPEC_ISSUE`. -Review не исправляет интерфейс или Design package и не подменяется наличием -stories, screenshots или успешной сборкой. - -## Semantic sync перед archive - -Перед terminal mutation сверяйте все deltas с текущей main baseline. Native -structural success и planning complete не заменяют эту проверку: - -1. Используйте `artifactPaths.specs.existingOutputPaths` из текущего status JSON - как точный список deltas. Main root разрешается через - `planningHome.root/openspec/specs`; полный вложенный capability path - сохраняется. Пустой список не разрешает угадывать delta по другим файлам. - Явно выбранный subset должен целиком входить в native список; invalid path - блокирует sync, пустой subset не выполняет записей, выбор не расширяется. -2. Получите один актуальный snapshot native specs instructions той же командой - `openspec instructions specs --change --json --store wealth-ledger-specs` - либо используйте уже прочитанный неизменившийся snapshot. Ошибка команды или - invalid JSON блокирует запись; отсутствие optional `rules` в корректном ответе - означает отсутствие дополнительных правил формы. -3. Прочитайте каждую delta и соответствующую main spec. Для `ADDED` проверьте - отсутствие конфликтующей identity; `MODIFIED` содержит полный requirement - и все сохраняемые scenarios; `REMOVED`/`RENAMED` меняют только явно указанные - identities. Сохраните незатронутые requirements, scenarios и existing Purpose. - Новая capability получает утверждённый Purpose, а не placeholder. -4. Покажите ожидаемый semantic diff до записи. Если новая baseline несовместима - с approved delta, верните change к самой ранней затронутой boundary. Не - переписывайте main spec или delta, чтобы скрыть конфликт. -5. После подтверждённого соответствия native archive выполняет sync вместе с - archive. Main specs сохраняют `Purpose` и `Requirements`, без delta operation - headers. Удаление всей capability допускается только при approved retirement - и `.openspec.yaml` с `retire_capabilities: true`: исходная capability была - непустой и корректной, текущая операция удалила все requirements, не осталось - другого содержимого кроме title/Purpose/Requirements, а реальный путь лежит - внутри specs root без symlink-выхода. Иначе capability не изменяется; пустая - Requirements section не записывается. - -Отдельно запрошенный sync использует тот же semantic diff и native rules, -применяет только явно выбранные полные delta paths, затем выполняет strict -validation main specs. Он не даёт terminal status и не расширяет выбранный scope. - -## Finalization и Completion Evidence - -После актуального независимого PASS: - -1. Сверьте approvals, завершённость implementation-owned Tasks и input binding - с текущим working tree. Blocker маршрутизируется по governance; неизменившиеся - gates и independent review повторно не запускаются. -2. Проверьте существующие delivery commits affected repositories. Если - разрешённая фиксация проверенных изменений ещё нужна, сделайте её до создания - evidence и повторно сравните content fingerprints. Commit/staging без - изменения inputs не устаревает PASS. Каждый delivery commit содержит - проверенное изменение своей области; unrelated working changes сохраняются. -3. Создайте `completion-evidence.md` внутри active canonical change только из - существующих фактов: Delivery Map, commit IDs, точные commands/results, - independent verdict и его input binding. Для `N/A` сохраните причину. - Собственные evidence/state/records исключены из self-hash; отдельной - обязательной docs-мутации ради evidence нет. -4. Выполните semantic sync review выше и перед archive снова проверьте, что - кроме ожидаемых completion mechanics relevant inputs не изменились. - Запустите native archive с его validation: - - ```bash - openspec archive --yes --store wealth-ledger-specs - ``` - - `--yes` автоматизирует prompt, не снимает safeguards. `--no-validate` и - `--skip-specs` не являются обходом failed gate, stale PASS или semantic conflict. -5. Проверьте наблюдённый archive path, сохранение Completion Evidence и ожидаемый - diff sync/move. Для применимого Design package проверьте сохранение - относительной структуры Design/visuals, доступность каждого материала, - совпадение SHA-256 и exact immutable reuse references после переноса. - Утрата или замена материала блокирует завершение. Изменённые archive/main-spec outputs проходят native strict - проверку; это проверка новых completion outputs, не повторная Validation - неизменившейся реализации. Зафиксируйте разрешённые archive/sync/evidence - изменения и сообщите созданный commit ID отдельно от evidence, чтобы избежать - self-reference. Audit-derived registry получает ссылку на archive/evidence - после успешного terminal outcome, без копирования commits и gate results. - -Если archive недоступен, incomplete evidence или commit operation можно -повторить при тех же inputs — Finalization сохраняет observed blocker. -Частичный archive не повторяется вслепую: сначала установите фактические пути -и diff, затем продолжите недостающую completion operation. Неожиданное изменение -planning/delivery направляется к ответственной предыдущей роли. - -## Обновление OpenSpec - -`openspec update` сначала проверяют в isolated staging. После upstream update -проверяются fixed store, stage context, separate approvals, Apply feedback routing -и archive safeguards. Optional entrypoints остаются короткими указателями на -эту процедуру; vendor-specific command tree не является prerequisite. +Прежнее rationale — [ADR 010](../adr/010-native-openspec-sdd-and-local-orchestration.md) +и [011](../adr/011-native-openspec-lifecycle-with-repository-gates.md); +текущий выбор прямой работы — [ADR 012](../adr/012-task-driven-development-with-scoped-context.md). diff --git a/development/runtime-openapi-verification.md b/development/runtime-openapi-verification.md index 5278631..d11293b 100644 --- a/development/runtime-openapi-verification.md +++ b/development/runtime-openapi-verification.md @@ -6,16 +6,29 @@ создаёт runtime OpenAPI document и сверяет его с committed snapshot `frontend/src/shared/api/spec/openapi.json` после детерминированной canonicalization. -Это отдельный контрактный gate, а не общий verifier всех репозиториев. Он нужен -перед изменениями backend API или frontend transport contract и не заменяет +Это отдельный контрактный gate, а не общий verifier всех репозиториев. Он обязателен перед завершением задачи, меняющей +backend API или frontend transport contract и не заменяет локальные lint/typecheck команды приложений. +## Выбор и направление изменения + +1. Определите, меняется wire contract (route, request/response field, status, error shape) или только внутренний код/UI model. Во втором случае snapshot не меняется. +2. Прочитайте [HTTP semantics](../architecture/http-api.md) и нужный feature/domain source. Backend Nest controllers/DTO/Swagger metadata — единственный editable источник OpenAPI; specs repo не является вторым OpenAPI source. +3. Измените этот source и проверьте representative HTTP behavior. При изменении контракта скопируйте generated runtime OpenAPI в committed frontend snapshot, затем в frontend выполните `npm run openapi:generate`. +4. Выполните frontend `npm run openapi:check` и backend `npm run test:openapi-contract`, а также verify affected repos. Эти команды проверяют разное: schema parity не доказывает validation/auth/error behavior. + +Generated frontend TS и backend Prisma client вручную не редактируются. +Frontend domain/UI type допустим, когда он отличается от transport DTO по смыслу. +Перед compatibility-sensitive изменением оцените существующих consumers и +rollback/data constraints; одного обновления snapshot недостаточно. + ## Запуск Из корня workspace: ```bash cd backend +nvm use --silent npm run test:openapi-contract ``` diff --git a/development/ui-catalog.md b/development/ui-catalog.md index 75c23fd..ff57821 100644 --- a/development/ui-catalog.md +++ b/development/ui-catalog.md @@ -93,7 +93,7 @@ Retry демонстрирует локальный callback и не доказ Композиция сохранённых сумм показывает представление Client Cached Snapshot; сам query lifecycle не исполняется. Для запросных экранов действует -[UI Pattern](../../frontend/docs/UI-PATTERN.md): сохранение данных при refetch, +[UI Pattern](../../frontend/.ai/conventions/frontend-ui.md#состояния-и-recovery): сохранение данных при refetch, structural skeleton для initial loading и контекстный индикатор mutation. Skeleton конкретной страницы остаётся ответственностью страницы. @@ -107,17 +107,14 @@ Declarative stories не требуют искусственного unit covera coverage floors сохраняются. Клавиатура, реальные размеры и визуальное соответствие проверяются в браузере; автоматической visual regression нет. -## Использование в UI change +## Использование в UI задаче -Каталог помогает выбрать существующий компонент, его состояние и ограничения. -Затем в Design своего change зафиксируйте применимость UI/UX, выбранную -конфигурацию, затронутые экраны, состояния, взаимодействия и адаптивное поведение. -Ссылка на текущую story помогает исследовать реализацию; согласованную версию -решения сохраняет [единый пакет Design](engineering-governance.md#uiux-пакет-design). -Его материалы получает Implementation и независимый reviewer через -[OpenSpec lifecycle](openspec-authority-and-lifecycle.md). +Каталог помогает выбрать existing component, состояние и ограничения. Ожидаемое +поведение определите из задачи: экраны, states, interactions и узкий viewport. +Для сложного варианта покажите конкретный макет/пример до дорогой реализации; +простой согласованный вариант реализуйте сразу по [UI policy](engineering-governance.md#ui-решения). -Каталог и этот процесс доступны для совместного использования в отдельном -небольшом UI change. Его выбирает владелец; он проходит собственные planning -approvals. Это готовность к пилоту: продуктовая фича автоматически не назначена, -сквозной продуктовый пилот не проводился и его успешность не заявляется. +Story — reference текущей реализации. Сборка не доказывает visual match, +keyboard accessibility или работу настоящего API. Проверяйте соответствие задаче +и применимые states в браузере. Использование установленного каталога не требует +повторного approval установки или OpenSpec Design artifact.