diff --git a/AGENTS.md b/AGENTS.md index 9c3bcb5..db1542e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,43 +1,18 @@ # Specs -## Назначение и authority +Репозиторий содержит существующие behavioral specifications и SDD history. +Для обычной разработки не создавай и не обновляй planning artifacts ради +процесса. Требование пользователя определяет работу; OpenSpec применяется +только по явному запросу. -Этот репозиторий — единственный versioned authority для change artifacts. -Workspace layout и reference policy — в root `AGENTS.md`. +Если нужна существующая behavioral spec, выбери точный target через +[AI_INDEX](AI_INDEX.md). Specs не являются вторым editable HTTP OpenAPI: +его authority — backend runtime document; workflow находится в +[docs](../docs/development/runtime-openapi-verification.md). -Canonical OpenSpec store — `wealth-ledger-specs`, физический root от workspace — -`specs/openspec` (локально `openspec`). OpenSpec commands, читающие или -изменяющие change, всегда получают `--store wealth-ledger-specs`. - -Proposal, Delta Specs, Design, Tasks, changes, Completion Evidence и archives -хранятся в `openspec`; `docs` владеет as-built документацией и общей policy. - -## Workflow и verification - -Новые changes используют project-local schema `wealth-ledger-sdd`. -Для planning, implementation, validation и завершения читай canonical lifecycle: -[`../docs/development/openspec-authority-and-lifecycle.md`](../docs/development/openspec-authority-and-lifecycle.md). - -Сначала определить current stage и capability paths через native OpenSpec -instruction; читать main specs и supporting docs только для этих paths и -affected areas. Recovery и выбор relevant evidence определяет context discipline -из [`../docs/development/agent-token-efficiency.md`](../docs/development/agent-token-efficiency.md), -а не дублируется в schema instructions. - -Для structural validation из `specs`: - -```bash -openspec schema validate wealth-ledger-sdd --verbose -openspec validate --type change --strict --store wealth-ledger-specs -openspec validate --specs --strict --store wealth-ledger-specs -``` - -Под Node 22: если локальной `.nvmrc` нет, активировать frontend `.nvmrc` -через `nvm use --silent` до перехода в specs. Native structural gate проверяет -форму; terminal safeguards определяет canonical lifecycle, доступный без skills. - -## Boundaries - -- Design содержит Delivery Map `frontend`, `backend`, `specs`, `docs` и условный Solution Assessment. -- Specs описывают observable behavior, не изменения кода; Design — architecture, не line-by-line implementation; Tasks — implementation checklist без будущего evidence. -- Application code и durable ADR принадлежат affected application/docs repos. +Архивы и чужие active changes сохраняй. Для правки индекса проверь targets, +anchors и `git diff --check`; application gates принадлежат affected repos. +Если явно запрошена работа через OpenSpec, следуй +[optional lifecycle](../docs/development/openspec-authority-and-lifecycle.md) +и используй store `wealth-ledger-specs`. Перед Node-командами выбери frontend +`.nvmrc` через `nvm use --silent`, если здесь нет своей. diff --git a/AI_INDEX.md b/AI_INDEX.md new file mode 100644 index 0000000..bf824a2 --- /dev/null +++ b/AI_INDEX.md @@ -0,0 +1,33 @@ +# Behavioral specifications index + +Эти существующие specs — источник сохранённых требований по конкретной теме. +Читай нужный requirement/scenario, если задача зависит от него; не загружай всё +дерево и не создавай OpenSpec change для обычной разработки. +As-built факты и принятие решений — через [docs index](../docs/AI_INDEX.md). +При конфликте с текущим поведением установи расхождение; не копируй устаревшее +правило или случайный код молча. + +HTTP OpenAPI имеет единственный editable source в backend, а не здесь: +[contract workflow](../docs/development/runtime-openapi-verification.md). + +| Тема / trigger | Existing spec | +| --- | --- | +| Auth/session/refresh/error contract | [User authentication](openspec/specs/user-authentication/spec.md) | +| T-Bank connection/security/cache generation | [T-Bank connection](openspec/specs/tbank-connection/spec.md) | +| Счета/сводки | [Brokerage accounts](openspec/specs/brokerage-accounts/spec.md) | +| Portfolio positions/totals/stale | [Portfolio](openspec/specs/portfolio-view/spec.md) | +| Операции/cursor/filters | [Account ledger](openspec/specs/brokerage-account-ledger/spec.md) | +| Будущие выплаты | [Upcoming events](openspec/specs/brokerage-account-upcoming-events/spec.md) | +| Доходы и периоды | [Income analytics](openspec/specs/brokerage-account-income-analytics/spec.md) | +| Shared tokens/theme | [Design system](openspec/specs/frontend-design-system/spec.md) | +| Каталог компонентов | [UI catalog](openspec/specs/frontend-ui-catalog/spec.md) | +| Loading/skeleton | [Loading presentation](openspec/specs/frontend-loading-presentation/spec.md) | +| UI error/recovery | [UI resilience](openspec/specs/frontend-ui-resilience/spec.md) | +| Query coherence/cache | [Query coherence](openspec/specs/frontend-query-coherence/spec.md), [data resilience](openspec/specs/frontend-data-resilience/spec.md) | +| OpenAPI generation | [API contract generation](openspec/specs/api-contract-generation/spec.md) | +| Logging/request context | [Structured logging](openspec/specs/backend-structured-logging/spec.md) | +| Breadcrumb/navigation | [Breadcrumbs](openspec/specs/app-breadcrumb-navigation/spec.md) | + +Process specs, active changes и archives сохраняют историю прежнего SDD workflow. +Они не являются обязательной процедурой текущей задачи. Для явно запрошенной +работы с OpenSpec используй [отдельный вход](AGENTS.md). diff --git a/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/.openspec.yaml b/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/.openspec.yaml new file mode 100644 index 0000000..e55f087 --- /dev/null +++ b/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/.openspec.yaml @@ -0,0 +1,2 @@ +schema: wealth-ledger-sdd +created: 2026-09-09 diff --git a/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/README.md b/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/README.md new file mode 100644 index 0000000..966c968 --- /dev/null +++ b/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/README.md @@ -0,0 +1,45 @@ +# clarify-agent-context-routing — закрытие + +**Дата:** 2026-09-09. **Статус:** архивирован; исходный план заменён последующим +решением пользователя. Итоговая задача реализована для frontend и backend. + +## Основание + +После первоначального переноса frontend conventions пользователь расширил +задачу: применить рекомендации исследований к обоим code repositories и убрать +обязательный OpenSpec/SDD. Решение закреплено в +[ADR 012](../../../../../docs/adr/012-task-driven-development-with-scoped-context.md). +Затем пользователь явно запросил завершение, архивацию и commits. + +Proposal, Design, Tasks и delta specs сохранены как история первоначального +scope. Отметки Tasks относятся к прежнему этапу; они не означают соответствие +итоговой структуры старому плану или проведение независимой SDD Validation. +Архивация выполняется с `--skip-specs`: delta требует обязательных SDD-фаз +и исключает backend в planning scope, поэтому её перенос в main specs +не соответствует последующему решению пользователя. + +## Поставленный результат + +- Короткие root/local AGENTS и загрузка conventions по задаче, пути и границе. +- [Frontend router](../../../../../frontend/.ai/CONVENTIONS.md), SOURCES и четыре тематических руководства. +- [Backend router](../../../../../backend/.ai/CONVENTIONS.md), SOURCES и шесть тематических руководств. +- Общие engineering rules, HTTP contract workflow и docs/specs indexes. +- [18 routing cases](../../../../../docs/development/agent-context-evals.md) с безопасными исключениями и неприменимыми контрпримерами. + +Код приложения, dependencies, runtime configuration и gates не менялись. +Основные specs и существовавшие архивы сохранены. OpenSpec остаётся optional; +эта архивация не возвращает обязательный lifecycle. + +## Проверка + +Проверки выполнены под `.nvmrc` соответствующих repositories: + +- `frontend`: `npm run verify` — exit 0; 26 test files, 147 tests, сборки приложения и Storybook. +- `backend`: `npm run verify` — exit 0; 25 suites, 107 tests, Prisma generation и Nest build. Для Prisma cache потребовался повторный запуск с разрешённым доступом вне sandbox. +- `docs`: `npm run verify` — exit 0; Markdown lint и `git diff --check`. +- Root/local AGENTS, оба `.ai` дерева и specs index: Markdown lint — 19 файлов без ошибок; scoped navigation — 60 файлов, 413 links/anchors без ошибок. +- Все 18 routing cases проверены вручную. Это не эксперимент по качеству агента; результаты не доказывают first-pass acceptance или экономию токенов. + +Runtime HTTP contract не менялся; отдельные contract/e2e проверки не запускались. +Известное ограничение общего backend e2e и непроверенная детализация validation +errors описаны в действующих документах; их исправление не входило в эту задачу. diff --git a/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/design.md b/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/design.md new file mode 100644 index 0000000..f982962 --- /dev/null +++ b/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/design.md @@ -0,0 +1,300 @@ +## Context + +Шесть frontend-local документов сейчас находятся в `frontend/docs/`. +Их README перечисляет темы, а local AGENTS одновременно служит входом и кратким +пересказом отдельных правил. Общая policy, context discipline, lifecycle, +architecture и as-built сведения уже имеют владельцев в отдельном `docs`. +Подход сохраняет это разделение и использует утверждённую Delta Spec +`specs/openspec-authority-and-lifecycle/spec.md` данного change. + +Адресная проверка текущих источников уточнила основания решений: + +- `frontend/biome.json` задаёт ошибки для declarations named components, + default exports и порядка exports с локальными исключениями. Он не задаёт + общего запрета непереведённых JSX-строк; TypeScript такого запрета не добавляет. +- `@testing-library/user-event` не объявлен напрямую в `frontend/package.json`, + но присутствует в lockfile через Storybook. Интерактивные тесты используют + `fireEvent` из объявленного `@testing-library/react`. +- Project-local schema `wealth-ledger-sdd` имеет version 5. Отслеживаемый Git + файл `specs/openspec/.cli-version` существует и содержит `1.10.0`. + ADR 010 описывает прежние schema v3, custom verifiers и dispatcher; + текущие lifecycle и entrypoints направляют к native OpenSpec и repo gates. +- Storybook уже поставлен. Workflow summary содержит прежнее число групп, + тогда как каталог описывает актуальную структуру у собственного владельца. + +Это основания для уточнения документации, а не для изменения tooling или +исправления других main-spec requirements. Planning остаётся только в store +`wealth-ledger-specs`; исторические источники не становятся объектом миграции. + +## Goals / Non-Goals + +**Goals:** сохранить локальные правила при смене пути, определить единственного +владельца каждого решения о контексте и дать исполнителю точный способ отличать +обязательное чтение и review от автоматического enforcement и guidance. +Design фиксирует соответствие сохраняемого содержания конечным владельцам; +отдельный постоянный реестр для этого не нужен. + +**Non-Goals:** изменение application runtime, API, auth, данных, dependencies, +schema graph или canonical gates; новый context framework, instruction layer, +checker, dispatcher, scoring либо token limit. Bundle-budget drift, +backend e2e, переносимость Completion Evidence и массовое переустройство +conventions остаются вне этого change. + +## Decisions + +### 1. Существующие источники сохраняют ownership + +`frontend/.ai/` полностью заменяет `frontend/docs/` как место локальных правил. +В нём непосредственно лежат `README.md`, `CONVENTIONS.md`, `STRUCTURE.md`, +`API-LAYER.md`, `UI-PATTERN.md` и `TESTING.md`. Это relocation существующего +набора, без вложенного дерева, metadata, нового AGENTS или второго index. +Старые поддерживаемые копии и redirect stubs не остаются. + +Frontend AGENTS направляет к `.ai/README.md` для выбора применимых документов, +сохраняет local gate и краткие boundaries. README приложения предоставляет +тот же вход и полезные прямые ссылки. Краткие pointers в AGENTS не заменяют +текст владельца и не требуют автоматически читать весь набор conventions. + +Общая authority остаётся в `docs/development`: context discipline владеет +выбором и повторным определением inputs, lifecycle — входом по фазе и native +процедурой, governance — approvals, ролями и обязательностью проверок. +Architecture, ADR и as-built сведения остаются в своих текущих docs-разделах. +Frontend router ссылается на эти источники вместо копирования policy. + +Альтернатива с двумя поддерживаемыми каталогами оставляет неоднозначный owner. +Новый registry или metadata layer создаёт дополнительную синхронизацию без +нового поведения; шесть существующих документов уже соответствуют границам. + +### 2. Один локальный router выбирает объединение применимых тем + +Таблица маршрутов принадлежит `frontend/.ai/README.md`. Она использует +содержание предстоящего решения, а не только расширение файла или название +задачи. Одновременно действующие triggers объединяются: + +| Содержание изменения | Локальный документ в `.ai/` | +| --- | --- | +| Создание/перенос module или slice, cross-slice imports и public API boundaries | `STRUCTURE.md` | +| React declarations, props, exports, продуктовые строки и Zod messages | `CONVENTIONS.md` | +| Container/VM/view, формы, query states, skeleton, retry/recovery | `UI-PATTERN.md` | +| HTTP client, generated types, query/mutation, Bearer и refresh | `API-LAYER.md` | +| Изменение самих тестов либо поведения с testing risk trigger | `TESTING.md` | + +Например, UI props и presentation требуют conventions и UI pattern; auth +refresh добавляет API и testing по security/concurrency risk. Наличие query +state во view само по себе не требует API rules, пока не затронуты получение +данных, query/mutation или transport boundary. Router не дублирует список +risk triggers: их полная policy остаётся в governance с указателем из TESTING. + +### 3. Повторный routing расширяет существующую context discipline + +В `docs/development/agent-token-efficiency.md` уточняется существующий раздел +Routing context. Фаза и affected areas определяются до supporting reads; +применимость inputs сверяется до первого зависимого решения, при новой области +или границе и перед handoff. Первая сверка работает и при отсутствии diff. + +Перед handoff основанием служат фактические staged, unstaged и новые файлы +вместе с содержанием работы. Используется существующая inventory procedure +этого же документа: учитывается working content tracked и nonignored untracked +files, relevant ignored и workspace-owned inputs перечисляются явно. +Чужой concurrent diff учитывается при разграничении ownership, но не даёт +полномочий присвоить его текущему change. Второй manifest не вводится. + +Новая граница в пределах approved scope означает загрузку её правил до +зависимой работы. Необходимость изменить intent, observable behavior, +architecture или Tasks означает возврат к соответствующей самой ранней +planning boundary. Само уточнение чтения не требует повторного approval; +расширение разрешённой работы следует существующей cascade policy. + +В existing lifecycle достаточно коротких указателей на эту сверку в native +planning, Implementation/Validation и перед передачей результата. Отдельная +таблица фаз и контекста там не создаётся: владельцем mapping остаётся context +authority, а конкретные dependencies/contextFiles возвращает native instruction +разрешённого artifact или Apply. + +При recovery восстанавливаются canonical artifacts и их approval bindings, +все обязательные native inputs, применимые risk inputs и согласованный Design +package текущей фазы. В том же контексте неизменившиеся прочитанные inputs +переиспользуются по действующей policy. Missing input, неоднозначная версия +или digest mismatch блокируют зависимое решение. Краткий handoff, внешний +каталог и число документов не заменяют обязательные источники. + +### 4. Перенос сохраняет требования и действующие исключения + +Следующая таблица относится только к этому Design: это соответствие исходного +содержания конечному owner для semantic review переноса. Она не становится +постоянным convention registry. Правила по возможности остаются в одноимённом +перенесённом документе; полезные краткие pointers между ними сохраняются. + +| Исходное содержание | Конечный владелец | Что должно сохраниться | +| --- | --- | --- | +| `frontend/docs/README.md`: назначение набора, темы, общая policy и источник версий/scripts | `frontend/.ai/README.md` | Компактный router, ссылки на общие authorities; фактические dependencies и scripts определяет конфигурация проекта. | +| `frontend/docs/STRUCTURE.md` и FSD boundary из AGENTS | `frontend/.ai/STRUCTURE.md` | Локальные слои `app → pages → features → entities → shared`, без `widgets`; slice public API через `index.ts`, alias `@/` и запрет обхода public API. Владение theme/tokens, общий public API для app и Storybook, границы shared/ui и ссылка на дизайн-систему. | +| `frontend/docs/CONVENTIONS.md`: общие Must | `frontend/.ai/CONVENTIONS.md` | Biome style, type-only imports, правила enum/namespace, exact dependency versions, colocated tests, Conventional Commits и действующая pre-commit процедура. Public API и gate pointers сохраняют связь с владельцами. | +| `frontend/docs/CONVENTIONS.md`: i18n и Zod | `frontend/.ai/CONVENTIONS.md` | Продуктовые строки в locale через `useTranslation()`; Zod messages через `validationMessage(key)`. Обязательность сохраняется при semantic review без обещания общего автоматического запрета JSX-строк. | +| `frontend/docs/CONVENTIONS.md`: React component style | `frontend/.ai/CONVENTIONS.md` | Const-valued named components, export rules, `FC`, named props, `PropsWithChildren`, отсутствие inline props typing и destructuring parameters, читаемый нижний export block и прямые barrel re-exports. Storybook CSF default meta/direct story exports и конфигурационные default-export exceptions сохраняются в фактическом scope Biome; synthetic story data не подменяют i18n продукта. | +| File roles в `CONVENTIONS.md` и VM/view rules в `UI-PATTERN.md` | `frontend/.ai/CONVENTIONS.md` и `frontend/.ai/UI-PATTERN.md` соответственно | Container вызывает page VM; VM владеет data/auth/route inputs, state selection, domain grouping и derived presentation data; view получает props. Сохраняются запрет data/auth/router/navigation/VM hooks во view, допустимые translation/form-context/UI-only hooks и formatter одного значения. Разбиение по semantic responsibility, flat views и исключение для маленького tightly-coupled renderer не заменяются line-count rule. | +| `frontend/docs/API-LAYER.md` и API boundary из AGENTS | `frontend/.ai/API-LAYER.md` | Backend OpenAPI как authority; committed snapshot и generated types, offline generation/drift check, запрет ручного редактирования generated и дублирования transport DTO. Только typed shared clients, отсутствие прямых fetch в features/pages/entities и прямых T-Bank calls, slice ownership cache keys/policies. Bearer принадлежит shared authenticated fetch; auth endpoints исключены; single-flight refresh и один retry `UNAUTHORIZED`; query/mutation не задают Authorization. | +| `frontend/docs/UI-PATTERN.md`: формы и recovery | `frontend/.ai/UI-PATTERN.md` | React Hook Form, Zod resolver и FormProvider; form state в container/VM, context fields во view; блокирование действий при submit; field errors и сетевой Alert с сохранением ввода. Known API errors/retry локальны, непойманные route errors принадлежат route-keyed ErrorBoundary. | +| `frontend/docs/UI-PATTERN.md`: query states и skeleton | `frontend/.ai/UI-PATTERN.md` | Loading/error/empty/loaded без успешных данных; Client Cached Snapshot при refetch и его ошибке с progress, предупреждением и retry, отдельно от server stale/fallback. Page/section ownership structural skeleton, доступная busy-область, декоративные shapes без данных, интерактивности и фокуса; сохранение shell, neutral auth skeleton до ready. Mutation loading и cached-snapshot progress остаются контекстными indicators. | +| `frontend/docs/TESTING.md` | `frontend/.ai/TESTING.md` | Risk-based selection и ссылка на governance, observable behavior/AAA, validation без запроса при невалидной форме, route access/redirect и recovery cases, finance states и route-boundary reset. MSW только из Vitest setup, без browser worker/mock development mode; transport headers/retry через MSW. Один coverage-backed Vitest в gate, короткий локальный test run, coverage как anti-regression constraint без тестов ради процента. | +| Canonical gates и lifecycle safeguards в entrypoints | Local AGENTS affected repos и текущие `docs/development` authorities | Выбор Node по `.nvmrc`, repo-owned gates, fixed store, отдельные approvals, fingerprints, независимая Validation и Finalization. Их определения не копируются в новый локальный workflow. | + +Неточность testing helper исправляется внутри TESTING: описывается используемый +`fireEvent` из Testing Library с ожиданием наблюдаемого async outcome. +Транзитивный `user-event` не объявляется отсутствующим на диске или напрямую +принятым проектом. Замена текста не меняет тестовую инфраструктуру и не требует +переписывания существующих тестов. + +### 5. Enforcement описывается у владельца правила + +В AGENTS и conventions различаются три категории: автоматическое блокирование +существующей проверкой, обязательная процедура/semantic review и guidance. +Автоматический статус указывается только для фактически проверяемого scope; +исключения описываются рядом. Component declarations и export rules сохраняют +Biome enforcement, а `FC`/props conventions и полнота i18n остаются обязательными +для review. Успех type/style checks не доказывает локализацию всех строк. + +Раздел Guardrails общей governance уточняется в той же классификации: +определение Enforceable Engineering Invariant сохраняется для детерминированных +проверок, но отсутствие checker не переводит явно обязательную semantic policy +в guidance. Необязательные эстетические предпочтения остаются guidance. +Так общий owner и frontend instructions не дают противоположных указаний. + +Новый автоматический запрет здесь не создаётся. Existing gates сохраняют свои +inputs и ответственность; structural validation не получает полномочий +подтверждать semantic compliance, approval или независимый PASS. + +### 6. Текущая навигация обновляется без переписывания истории + +Действующие входы обнаруживаются по старым путям и разрешаются относительно +файла-источника, включая локальные anchors. Текущий адресный inventory содержит +frontend AGENTS/README, UI-каталог и live ссылки на conventions/UI pattern в +remediation registry. Для registry меняются только эти адреса: Audit IDs, +dispositions, статусы, даты, формулировки findings и evidence links сохраняются. + +В текущих main specs, schema и optional `.opencode/commands` ссылок на старые +frontend paths не найдено. Optional entrypoints уже направляют к lifecycle и +context authority, поэтому отдельная их редакция не нужна. Root AGENTS также +сохраняет действующий routing. При последующей адресной сверке новая активная +ссылка включается только в пределах разрешённой области; чужой approved +artifact нельзя переписывать для чистого результата поиска. + +Historical OpenSpec archives, dated audits, прежнее Completion Evidence и +сохранённые датированные research/browser snapshots не редактируются. +Generated graph/cache outputs не являются поддерживаемыми instructions и не +регенерируются ради смены пути. Совпадение старого пути само по себе не означает +сломанный действующий маршрут. Отказ от redirect stub делает текущие пропуски +видимыми и сохраняет единственного владельца правил. + +### 7. ADR и workflow summaries направляют к текущей процедуре + +По правилу `docs/adr/README.md` замена решения оформляется новым ADR со ссылкой +на прежний. В `docs/adr` добавляется ADR 011 +`011-native-openspec-lifecycle-with-repository-gates.md`, фиксирующий уже +действующий native lifecycle и repo-owned gates. Он содержит контекст, решение +и последствия этой замены, ссылки на governance/lifecycle/context authority +и на ADR 010; новый процесс или самостоятельный порядок команд не вводится. + +В ADR 010 сохраняются исходное rationale и рассмотренные альтернативы, а +заменённые части про schema v3, custom verifiers и dispatcher получают явную +историческую квалификацию и ссылку на successor. Сохраняющийся выбор native +OpenSpec и независимых repo gates не объявляется отвергнутым. Index отражает +частичную замену. Такой подход предпочтительнее полного переписывания ADR 010 +под сегодняшний текст или примечания без successor, нарушающего ADR policy. + +Документация различает текущую schema version и наличие `.cli-version`; +удаление этого файла не утверждается. Его наличие также не выдаётся за +доказательство запуска прежнего verifier. Этот change не меняет version +contract, CLI pin, schema или untouched requirements о tooling. + +Числовая структура Storybook принадлежит `docs/development/ui-catalog.md`. +`frontend-workflow.md` ссылается на этот owner без собственного числа групп. +Frontend entrypoints точно описывают уже поставленный каталог и его участие +в существующем gate. Использование каталога разрешено как существующей +инфраструктуры; ограничения на добавление новых инструментов сохраняются. +Reference каталога не заменяет отдельный Design approval и независимую Validation. + +### 8. Доказательство опирается на routing scenarios и existing gates + +Semantic review сопоставляет перенос с таблицей сохранения и применяет +утверждённые сценарии Delta Specs к получившимся маршрутам. Для UI-only, +API/auth, изменения тестов, структуры и строк проверяется состав применимых +документов; docs-only опечатка служит неприменимым контрпримером к обязательному +чтению всех frontend conventions. + +Scope expansion рассматривается отдельно внутри approved границ и за ними; +handoff включает unstaged/new inputs, recovery — весь обязательный пакет, +а недоступный input должен оставлять явный blocker. Это проверка принятия +решений по содержанию, без unit tests, повторяющих Markdown, и без нового +checker. Ссылочная проверка и сохранение исторических bytes дополняют +canonical gates affected областей; они не подменяют независимую Validation. + +## UI/UX Applicability and Package + +**Applicability and scope:** `N/A`. Change меняет расположение и содержание +инженерных инструкций, не экраны, состояния, interactions или responsive +behavior приложения/каталога. Макеты, PNG/SVG exports и immutable visual reuse +inputs не нужны. Весь Design package — этот Markdown-файл. + +## Delivery Map + +| Area | Status | Architectural outcome or N/A reason | +| --- | --- | --- | +| frontend | `affected` | Единственный набор conventions непосредственно в `.ai/`, локальный router, точные инструкции и актуальная навигация; runtime, dependencies и gate не меняются. Область проходит свой canonical gate. | +| backend | `N/A` | Не меняются backend behavior, contract, implementation, local instructions или gate. Backend delivery и backend-only проверки не требуются этим change. | +| specs | `affected` | Canonical planning и уточнение capability `openspec-authority-and-lifecycle` по approved Delta Specs; native structural checks. Синхронизация main specs остаётся штатной completion operation, historical archives сохраняются. | +| docs | `affected` | Context discipline и lifecycle pointers, точная классификация обязательности, историческая квалификация ADR 010 с successor, workflow summary и действующие links. Общая as-built authority остаётся на месте; область проходит canonical docs gate и scoped link review. | + +### Contract Gate Decision + +| Gate | Status | Reason | +| --- | --- | --- | +| runtime-openapi | `N/A` | Ни backend runtime contract, ни frontend snapshot/generated types не меняются. Сохранение описания typed API и auth ownership не является изменением сторон API contract. | + +## Risks / Trade-offs + +- Перенос с сокращением может потерять оговорки. Одноимённые владельцы, + ограниченные точечные редакции и таблица сохранения делают semantic diff + проверяемым; массовая консолидация текста не нужна. +- Без redirect старый live link перестанет работать. Scoped review отличает + действующую навигацию от неизменяемых исторических ссылок и проверяет targets + после relocation, в том числе переходы между независимыми repositories. +- Ручной routing может пропустить вторую тему. Объединение triggers и повторные + сверки по фактическому scope снижают риск; автоматический анализ не обещается. +- Классификация без checker может быть воспринята как ослабление. Явная + mandatory-review категория и согласованный текст общей governance сохраняют + обязательность i18n, validation и прочих semantic требований. +- ADR может смешать историческое и действующее решение. Частичная замена, + successor и точные ссылки сохраняют rationale и отделяют текущую процедуру + от старой реализации; untouched spec drift не скрывается редакцией этого Design. + +Build-versus-buy trigger отсутствует: общая tooling/infrastructure не вводится +и существенно не заменяется, используются уже принятые Markdown owners, +native OpenSpec и repository gates. Формальная Solution Assessment не нужна. + +## Migration Plan + +После отдельных planning approvals перенос выполняется как согласованный +documentation batch: сначала сохраняется одноимённый frontend набор и его +содержание, затем переключаются локальные и межрепозиторные входы. Target paths +и активная навигация должны сходиться до передачи реализации в Validation; +промежуточное смешение старых и новых путей не является завершённой поставкой. + +В том же delivery приводятся в соответствие общая context discipline, +классификация enforcement и описание действующего workflow/ADR. Это изменение +существующих owners, без дублирования правил в schema или optional adapters. +Исторические artifacts сохраняются; canonical Proposal и Delta Specs этого +change не редактируются ради переноса ссылок, описывающих исходное состояние. + +Проверяемая реализация передаётся отдельной Validation с фактическим inventory. +Canonical gates всех affected областей, independent verdict, semantic sync и +Completion Evidence остаются на своих lifecycle boundaries. Ошибка ссылки или +потерянное требование устраняется в реализации; противоречие утверждённому +approach возвращается к соответствующему planning artifact. + +### Rollback Contract + +| Field | Decision | +| --- | --- | +| Status | `N/A` | +| Reason | Обратимая документационная relocation не меняет auth/security behavior, данные, публичный API contract или труднообратимое решение. При откате связанный набор frontend/doc navigation возвращается согласованно средствами Git; пользовательские данные и runtime migration отсутствуют. | diff --git a/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/proposal.md b/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/proposal.md new file mode 100644 index 0000000..ef6af92 --- /dev/null +++ b/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/proposal.md @@ -0,0 +1,96 @@ +## Why + +Действующие инструкции не всегда однозначно показывают, какие локальные правила +нужны для конкретного изменения и когда выбор контекста следует пересмотреть. +Отдельные формулировки смешивают автоматическое блокирование с обязательным +review или описывают прежнюю процедуру как актуальную. Это создаёт риск пропуска +требований и неоправданной уверенности в успешных проверках. + +Discovery завершена; первый этап согласован как уточнение существующих +источников и перенос frontend-local conventions. Сейчас нужно закрепить +границы этого этапа, сохранив действующие требования и lifecycle safeguards. + +## What Changes + +- Сохранить один актуальный набор всех шести frontend-local документов в + согласованной `frontend/.ai/` вместо `frontend/docs/`, с компактным входом по + типу изменения и работающей действующей навигацией. Общая engineering policy, + architecture, ADR и as-built документация остаются у общего docs authority. +- Сделать выбор локального контекста однозначным для изменений структуры и + импортов, компонентов и продуктовых строк, представления и восстановления + состояний, взаимодействия с сервером, а также тестов и поведения с testing + risk trigger. Несвязанная задача не требует чтения всех conventions. +- Закрепить в существующей context authority проверку маршрутизации до первого + зависимого решения, при обнаружении новой области или границы и перед handoff + по фактическому набору staged, unstaged и новых файлов. Расширение обнаруженного + scope не разрешает выходить за approved planning boundaries. +- Сохранить обязательное получение всех native contextFiles, применимых risk + inputs и согласованного Design package при работе и recovery независимо от + количества документов. Фаза определяет нужный контекст; новый workflow или + параллельный context map не возникает. +- Различать реально автоматизированные запреты, обязательные процедуры и + semantic review, а также необязательное guidance. Исправление неточного + обещания проверки не ослабляет обязательность локализации, правил валидации + и остальных действующих требований. Рекомендации по тестированию соответствуют + установленной инфраструктуре и используемым практикам. +- Обозначить исторический статус заменённых частей архитектурного решения и + направить к текущей принятой процедуре с сохранением rationale и правил + ведения ADR. Изменяемая информация о каталоге интерфейса принадлежит его + документу-владельцу; workflow ссылается на него. Использование уже поставленного + каталога не требует повторного согласования его добавления. +- Сохранить содержание всех переносимых требований к структуре и границам + модулей, локализации и валидации, стилю компонентов с действующими исключениями, + типизированному доступу к данным и авторизации, разделению данных и + представления, состояниям и доступности интерфейса, восстановлению после + ошибок и тестированию. Canonical gates, отдельные approvals, fingerprints, + независимая Validation и Finalization сохраняются. + +Ожидаемый результат — применимые правила доступны до зависящего от них решения, +актуальные ссылки разрешаются, а перенос не оставляет двух поддерживаемых копий +и не теряет требований. Это относится как к отдельной UI-, API- или testing-задаче, +так и к расширению scope и recovery; неприменимые conventions остаются вне +обязательного контекста несвязанной задачи. + +Вне scope: + +- Изменение runtime-поведения frontend/backend и массовый рефакторинг conventions. +- Восстановление bundle budget checker, разрешение связанного spec drift, + восстановление backend e2e и переработка переносимости Completion Evidence. +- Новые instruction layers, реестры conventions, метаданные, context frameworks, + CI, hooks, dispatchers, checker frameworks, telemetry или dependency packages. +- Scoring, числовой token gate или ограничение числа обязательных документов. +- Перенос всей документации проекта в локальные инструкции frontend. +- Переписывание historical archives, dated audit snapshots и старого Completion + Evidence; их прежние пути сохраняют исторический контекст. +- Повторный аудит workspace и последующие этапы улучшения guardrails. + +## Capabilities + +### New Capabilities + +Нет. + +### Modified Capabilities + +- `specs/openspec-authority-and-lifecycle/spec.md`: уточнить обязательный выбор + контекста по фазе и фактическому scope, моменты повторной проверки маршрутизации + и применимость локальных conventions без пропуска обязательных inputs или + обхода approval boundaries. Остальные действующие инварианты сохраняются. + +## Impact + +Изменение затрагивает AI-агентов, разработчиков, Change Owner и независимых +reviewers, которые планируют, выполняют и проверяют работу в workspace. + +- **frontend** — расположение и маршрутизация локальных conventions, точность + инструкций и действующая навигация; поведение приложения не меняется. +- **docs** — context discipline, актуальные workflow summaries, навигация и + историческая квалификация заменённых частей ADR при сохранении общей authority. +- **specs** — canonical planning и уточнение существующего требования о выборе + контекста; без дублирующего planning store и изменения исторических artifacts. +- **backend — N/A**: первый этап не меняет его поведение, контракт, реализацию, + локальные инструкции или gate. + +Согласование направления не является approval этого Proposal или downstream +artifacts. Каждый следующий artifact и переход роли сохраняет отдельную +границу canonical lifecycle. diff --git a/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/specs/openspec-authority-and-lifecycle/spec.md b/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/specs/openspec-authority-and-lifecycle/spec.md new file mode 100644 index 0000000..ad0fce4 --- /dev/null +++ b/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/specs/openspec-authority-and-lifecycle/spec.md @@ -0,0 +1,243 @@ +## MODIFIED Requirements + +### Requirement: Agent context следует текущей SDD-фазе + +Project-owned agent workflow SHALL начинать каждую работу с определения текущей +SDD-фазы и affected delivery areas, а затем SHALL загружать canonical artifacts, +локальные routing instructions и supporting authority, применимые к этой фазе и +этим areas. Переход в новую agent-сессию после утверждения planning artifact +SHALL использовать canonical artifact и явное решение Change Owner как основание +продолжения. Workflow MUST NOT требовать полную историю предыдущей сессии или +отдельный handoff/context artifact, дублирующий OpenSpec authority. Supporting +material, не влияющий на текущую фазу, затронутую область, доменную семантику или +обязательный gate, SHALL загружаться только при появлении наблюдаемой +необходимости. + +Workflow SHALL проверять применимость контекста до первого зависимого решения, +при обнаружении новой области или границы и перед handoff по фактическому scope, +включая staged, unstaged и новые файлы. Проверка SHALL учитывать содержание +изменения, а не только первоначальное описание задачи или наличие staging. +Обнаружение нового scope MUST NOT разрешать выход за утверждённые planning +boundaries: требующее пересмотра intent, behavior, architecture или Tasks +расширение SHALL возвращаться к самой ранней затронутой boundary до зависимой +работы. + +Workflow MUST получать все возвращённые native contextFiles, применимые risk +inputs и согласованный Design package текущей фазы независимо от количества +документов. Это правило SHALL действовать и при recovery; уже прочитанные +неизменившиеся inputs в том же контексте MAY переиспользоваться по существующей +context discipline. Недоступный обязательный input MUST оставаться явным +блокером зависимого решения, а не заменяться историей чата или догадкой. +Маршрутизация MUST опираться на существующую context authority и MUST NOT +вводить параллельный workflow, scoring, числовой token gate или лимит числа +обязательных документов. + +#### Scenario: Утверждённый artifact передаётся в новую сессию + +- **WHEN** Change Owner явно утверждает текущий planning artifact и следующая agent-сессия продолжает change на разрешённой downstream-фазе +- **THEN** workflow восстанавливает работу из canonical change artifacts, owner approval и применимых routing instructions без обязательной передачи полной истории обсуждения или создания второго handoff artifact + +#### Scenario: Работа ограничена одной delivery area + +- **WHEN** текущая фаза затрагивает одну определённую delivery area и не требует cross-system или доменной оценки +- **THEN** workflow загружает authority и локальные instructions этой area, а нерелевантные architecture, domain и repository materials остаются lazy context + +#### Scenario: Supporting material становится необходимым + +- **WHEN** во время работы возникает вопрос, влияющий на domain semantics, cross-area architecture, audit disposition или обязательный gate +- **THEN** workflow загружает соответствующий authoritative material до принятия решения и не использует token-efficiency guidance как основание пропустить требуемый контекст + +#### Scenario: Предстоит первое зависимое решение + +- **WHEN** агент определил фазу и affected areas и готовится принять первое + решение, зависящее от локальных правил или иной authority +- **THEN** он определяет применимые inputs по содержанию задачи и получает их + до этого решения, даже если работа ещё не создала diff + +#### Scenario: В пределах approved scope обнаружена новая граница + +- **WHEN** текущая работа выявляет ранее неучтённую границу, уже разрешённую + утверждёнными planning artifacts +- **THEN** workflow пересматривает применимость контекста и получает недостающие + правила этой границы до зависимой работы, не требуя нового approval только + из-за уточнения набора чтения + +#### Scenario: Новая область требует расширения approved scope + +- **WHEN** обнаруженная область требует изменения утверждённого intent, + behavior, architecture или checklist +- **THEN** workflow загружает применимый контекст для оценки расхождения, + сообщает основание возврата к самой ранней затронутой planning boundary и + не начинает зависимую работу до требуемого approval + +#### Scenario: Перед handoff есть изменения вне staged diff + +- **WHEN** агент готовит handoff, а unstaged или новые файлы выявляют + применимую область или правило, отсутствующие в первоначальном scope +- **THEN** workflow учитывает их вместе со staged изменениями, пересматривает + обязательный контекст и передаёт фактический scope и оставшиеся blockers; + отсутствие staging не позволяет пропустить эту область + +#### Scenario: Recovery требует нескольких обязательных источников + +- **WHEN** новая сессия восстанавливает разрешённую фазу, для которой нужны + native contextFiles, risk inputs и согласованный Design package +- **THEN** она получает весь применимый набор и именно согласованную версию + Design, даже если краткий handoff перечисляет лишь часть источников или + документов больше, чем агент первоначально ожидал прочитать + +#### Scenario: Обязательный материал недоступен + +- **WHEN** необходимый для текущего решения input отсутствует либо согласованную + версию Design package нельзя однозначно восстановить +- **THEN** workflow сообщает конкретный blocker и не принимает зависимое решение + до восстановления input либо разрешения вопроса на нужной planning boundary + +## ADDED Requirements + +### Requirement: Frontend-local conventions имеют единый вход по содержанию изменения + +Участник workflow SHALL получать один актуальный набор frontend-local +conventions через компактный router, выбирающий документы по содержанию +изменения. Router SHALL направлять создание или перенос module/slice и +cross-slice imports к правилам структуры; declarations, props, exports, +продуктовые строки и сообщения валидации — к conventions; разделение +container/VM/view, формы, query states, skeleton и retry/recovery — к правилам +UI; HTTP client, generated types, query/mutation, Bearer и refresh — к правилам +API; изменение самих тестов или поведения с testing risk trigger — к правилам +тестирования. При сочетании triggers участник MUST получать все применимые +документы, а не выбирать один взаимоисключающий маршрут. + +Router MUST ссылаться на применимые общие authorities вместо пересказа их +содержания. Несвязанная задача MUST NOT требовать чтения всех conventions. +Перенос SHALL сохранять полезное содержание всех шести существующих документов, +обязательные требования и действующие исключения, не оставляя двух +поддерживаемых копий. Общая engineering policy, architecture, ADR и as-built +documentation MUST сохранять своих существующих владельцев. + +Все применимые действующие ссылки SHALL разрешаться к актуальным владельцам +после переноса, включая ссылки из optional entrypoints, если они затронуты. +Historical archives, dated audit snapshots и прежнее Completion Evidence +MUST оставаться неизменными; их старые пути MUST NOT считаться действующей +навигацией, требующей переписывания. + +#### Scenario: UI-only изменение не затрагивает данные и testing risk + +- **WHEN** задача меняет только представление и props существующего компонента + без изменения структуры модулей, взаимодействия с сервером, тестов или + поведения с testing risk trigger +- **THEN** router направляет к UI rules и component conventions; правила API, + структуры и тестирования не становятся обязательными только из-за того, + что изменён frontend + +#### Scenario: Меняются ownership авторизации или refresh + +- **WHEN** задача затрагивает формирование авторизации запросов либо + координацию refresh +- **THEN** router включает правила API и тестирования по security/concurrency + risk, а применимый contract и domain context остаётся обязательным независимо + от того, меняется ли интерфейс + +#### Scenario: Меняются сами тесты + +- **WHEN** задача изменяет тесты без изменения production behavior +- **THEN** router включает testing conventions; отсутствие изменения + production behavior не отменяет этот trigger, а остальные документы + выбираются по фактически затронутым границам + +#### Scenario: Создаётся slice с импортом другого slice + +- **WHEN** задача создаёт или переносит slice либо меняет cross-slice import +- **THEN** router включает structural conventions и public API boundaries до + решения о размещении или импорте, даже если внешнее поведение сохраняется + +#### Scenario: Меняются только продуктовые строки или сообщения валидации + +- **WHEN** задача меняет продуктовый текст либо пользовательские сообщения + валидации без изменения структуры, UI-state logic, API и тестов +- **THEN** router включает conventions локализации и валидации, не требуя + остальных локальных документов при отсутствии их triggers + +#### Scenario: Задача не относится к frontend conventions + +- **WHEN** задача исправляет опечатку в общей документации, не меняет + frontend-local instructions и не затрагивает frontend behavior или boundaries +- **THEN** workflow использует применимые общие и docs-local authorities без + обязательного чтения frontend conventions + +#### Scenario: Участник открывает действующую ссылку после переноса + +- **WHEN** участник переходит к frontend-local conventions из действующей + навигации после их переноса +- **THEN** ссылка ведёт к единственному актуальному владельцу, где сохранены + применимые требования и исключения; прежнее расположение не содержит второй + поддерживаемой копии правил + +#### Scenario: Старый путь встречается в historical artifact + +- **WHEN** прежний путь к conventions встречается в historical archive, + dated audit snapshot или старом Completion Evidence +- **THEN** artifact и его историческая ссылка сохраняются без переписывания; + актуальный маршрут определяется действующими entrypoints + +### Requirement: Активные инструкции точно описывают обязательность и способ обеспечения правил + +Активные instructions SHALL различать автоматическое блокирование существующим +gate, обязательную процедуру или semantic review и необязательное guidance. +Инструкция MUST NOT обещать автоматическую проверку, которой нет в текущей +конфигурации. Отсутствие автоматической проверки MUST NOT превращать обязательное +требование локализации, валидации или другой действующий invariant в пожелание. +Успех structural checks MUST NOT объявляться semantic approval или независимым +Validation PASS. + +Testing guidance SHALL соответствовать объявленным зависимостям и используемой +тестовой инфраструктуре; наличие пакета только как транзитивной зависимости +MUST NOT представляться как его прямое принятие проектом. Исправление guidance +в рамках этого этапа MUST NOT требовать нового dependency package или менять +runtime behavior. + +Заменённые части действующего ADR SHALL иметь явную историческую квалификацию +и направление к текущей принятой процедуре с сохранением rationale и правил +ведения ADR. Документация MUST опираться на фактическое состояние, а не повторять +неподтверждённое утверждение об удалении или наличии инструмента. Числовые +детали UI-каталога SHALL принадлежать его документу-владельцу; workflow summaries +SHALL ссылаться на него. Использование уже поставленного каталога MUST NOT +трактоваться как новое добавление, требующее повторного approval установки. + +#### Scenario: Автоматическая проверка не блокирует непереведённую строку + +- **WHEN** текущие style и type checks допускают произвольную непереведённую + продуктовую строку +- **THEN** инструкции сохраняют обязательную локализацию и semantic review, + не обещают автоматический запрет такой строки и не считают успешный gate + доказательством выполнения этого требования + +#### Scenario: Нарушение действительно блокируется существующим gate + +- **WHEN** текущее tooling детерминированно отклоняет нарушение документированного + component style в применимом scope +- **THEN** инструкция описывает это правило как автоматически проверяемое + с сохранением действующих исключений, не переводя его в guidance + +#### Scenario: Рекомендованный testing helper не объявлен напрямую + +- **WHEN** прежнее guidance рекомендует helper из пакета, не объявленного + прямой dependency, а действующие тесты используют доступные средства +- **THEN** guidance согласуется с принятой инфраструктурой без добавления + пакета ради прежнего текста; транзитивная доступность описывается точно + +#### Scenario: Часть ADR описывает заменённую процедуру + +- **WHEN** описание схемы или orchestration в ADR отличается от текущей + принятой процедуры +- **THEN** участник может отличить историческую часть решения от действующей + процедуры и перейти к её authority; rationale и исторические artifacts + сохраняются, а неподтверждённое удаление инструмента не утверждается + +#### Scenario: Workflow ссылается на существующий UI-каталог + +- **WHEN** участник использует уже поставленный каталог как reference +- **THEN** он получает актуальные числовые детали у документа-владельца без + второй копии в workflow и без повторного approval добавления каталога; + требования к отдельному approval Design package и независимой Validation + продолжают действовать diff --git a/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/tasks.md b/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/tasks.md new file mode 100644 index 0000000..53c803e --- /dev/null +++ b/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/tasks.md @@ -0,0 +1,57 @@ +## 1. Frontend-local conventions и входы + +До первых delivery edits сохранить в рабочем контексте исходный inventory по +context authority, включая staged/unstaged/new inputs и bytes защищённых +historical paths для проверки 3.2. Новый versioned artifact для этого не нужен. + +- [x] 1.1 [frontend] Перенести все шесть документов из `docs/` непосредственно в `.ai/`, сохранив одноимённых владельцев и содержание по таблице сохранения в Design; убрать прежний поддерживаемый набор без redirect stubs и второго registry. + - **Covers:** `openspec-authority-and-lifecycle` — `Frontend-local conventions имеют единый вход по содержанию изменения` + - **Verification:** Сопоставить исходные документы и перенос по каждой строке таблицы Design, включая FSD без widgets, i18n/validationMessage, React/Storybook exceptions, typed API/auth/refresh, VM/view, cached snapshot, skeleton accessibility, recovery и MSW/risk-based testing; проверить наличие только шести согласованных файлов непосредственно в `.ai/` и отсутствие второй поддерживаемой копии в `docs/`. +- [x] 1.2 [frontend] Сделать `.ai/README.md` компактным router с объединением triggers и ссылками на общие authorities; направить к нему `AGENTS.md` и README приложения, обновив их прямые ссылки на conventions и сохранив local gate и boundaries. + - **Covers:** `openspec-authority-and-lifecycle` — `Frontend-local conventions имеют единый вход по содержанию изменения` + - **Verification:** Проверить все пять маршрутов Design и сочетание нескольких triggers; проследить локальные входы до существующего target и применимого раздела, убедиться, что AGENTS/README не предписывают читать весь набор без triggers и не копируют общую policy. +- [x] 1.3 [frontend] Уточнить обязательность и enforcement в AGENTS и перенесённых conventions; согласовать TESTING с используемым `fireEvent` и объявленными зависимостями, а описание Storybook — с уже поставленной инфраструктурой. + - **Covers:** `openspec-authority-and-lifecycle` — `Активные инструкции точно описывают обязательность и способ обеспечения правил` + - **Verification:** Сверить автоматические утверждения и исключения с текущим `biome.json`, а testing guidance — с `package.json`, lockfile и интерактивными тестами; проверить сохранение mandatory i18n/validationMessage и React review conventions, точное описание транзитивного user-event, доступность существующего каталога без повторного approval установки и отсутствие изменений dependencies, runtime или gate. + +## 2. Общая context authority и текущая документация + +- [x] 2.1 [docs] Дополнить Routing context в `development/agent-token-efficiency.md` повторной сверкой до первого зависимого решения, при новой границе и перед handoff по staged/unstaged/new inputs; добавить короткие ссылки на эту процедуру в применимых фазах `development/openspec-authority-and-lifecycle.md`. + - **Covers:** `openspec-authority-and-lifecycle` — `Agent context следует текущей SDD-фазе` + - **Verification:** Проверить различие новой границы внутри approved scope и расширения intent/behavior/architecture/Tasks, полноту native contextFiles/risk inputs/Design package при recovery, reuse неизменившихся inputs и явный blocker при missing input; убедиться, что сохранены существующие fingerprints/approval boundaries и не созданы второй context map, workflow, scoring или лимит чтения. +- [x] 2.2 [docs] Уточнить Guardrails в `development/engineering-governance.md`: отделить автоматические Enforceable Engineering Invariants от обязательных процедур/semantic review и необязательного guidance, согласовав общую policy с frontend instructions. + - **Covers:** `openspec-authority-and-lifecycle` — `Активные инструкции точно описывают обязательность и способ обеспечения правил` + - **Verification:** Сопоставить governance с результатом 1.3: отсутствие checker не снимает явно обязательное требование, существующее автоматическое блокирование сохраняет свой статус, эстетические предпочтения остаются guidance; проверить сохранение canonical gates, approvals, fingerprints, независимой Validation и отсутствия новых checkers. +- [x] 2.3 [docs] Добавить ADR 011 `adr/011-native-openspec-lifecycle-with-repository-gates.md` о действующем native lifecycle и repo gates; обозначить частичную историческую замену ADR 010 и обновить ADR index, сохранив rationale и рассмотренные альтернативы. + - **Covers:** `openspec-authority-and-lifecycle` — `Активные инструкции точно описывают обязательность и способ обеспечения правил` + - **Verification:** Проверить соответствие `adr/README.md`, контекст/решение/последствия нового ADR, взаимные ссылки и указатели к текущим authorities; сверить формулировки schema v3/v5, прежних verifiers/dispatcher и сохранённого `.cli-version` с актуальными источниками, без изменения version contract, schema и untouched main requirements. +- [x] 2.4 [docs] Обновить текущие ссылки на frontend conventions в UI-каталоге и remediation registry; убрать дублируемое число групп каталога из frontend workflow, оставив ссылку на `development/ui-catalog.md` как owner этих сведений. + - **Covers:** `openspec-authority-and-lifecycle` — `Frontend-local conventions имеют единый вход по содержанию изменения`; `openspec-authority-and-lifecycle` — `Активные инструкции точно описывают обязательность и способ обеспечения правил` + - **Verification:** Проверить targets и anchors изменённых ссылок после переноса; в registry сравнить diff только live адресов conventions/UI pattern, сохранив Audit IDs, dispositions, статусы, даты, findings и evidence links; проверить отсутствие второй числовой сводки в workflow и сохранение Design approval/Validation при использовании существующего Storybook. + +## 3. Implementation-owned проверка согласованного поведения + +- [x] 3.1 [workspace] Пройти routing scenarios Delta Specs по итоговым instructions, проверяя выбор обязательного контекста и неприменимые контрпримеры без добавления тестов, повторяющих Markdown. + - **Covers:** `N/A` — задача не вводит самостоятельного observable behavior; это необходимая cross-area проверка frontend router и общей context discipline по решению 8 Design перед передачей реализации в независимую Validation. + - **Verification:** Для UI-only props/presentation проверить CONVENTIONS + UI-PATTERN без необоснованных API/STRUCTURE/TESTING; для auth/refresh — API-LAYER + TESTING и применимый contract/domain context; для изменения только тестов, slice/imports или строк — соответствующие triggers. Docs-only опечатка не должна требовать frontend conventions. Отдельно пройти первое решение без diff, supporting input по новой необходимости, новую границу внутри approved scope и расширение за его пределы, handoff с unstaged/new files, recovery полного обязательного пакета и missing-input blocker; сохранить observed outcomes в рабочем контексте без нового versioned registry или независимого verdict. +- [x] 3.2 [workspace] Проверить межрепозиторную навигацию и границы документационного переноса по фактическому inventory, включая сохранение исторических inputs и отсутствие непредусмотренных изменений. + - **Covers:** `N/A` — самостоятельное поведение не добавляется; согласованный перенос между независимыми репозиториями требует cross-area проверки ссылок и сохранения inputs по решениям 4 и 6 Design, которую один repository gate не покрывает. + - **Verification:** Найти старые paths в действующих entrypoints и проверить все применимые targets/anchors, включая optional entrypoints при наличии совпадений; отличить historical references и generated graph/cache outputs от live navigation. Сравнить historical archives, dated audits, прежнее Completion Evidence и датированные research/browser snapshots с исходным inventory по bytes; по staged/unstaged/new scope проверить сохранение root/optional routing при отсутствии затронутых ссылок, неизменность runtime/dependencies/gates и соблюдение read-only references policy. + +## 4. Repository-owned delivery и canonical gates + +Нормативный deliverable `specs` — canonical change, подготовленный Specification. +Design не предусматривает отдельную implementation-редакцию schema или main +specs: задача 4.3 проверяет эту repository-owned поставку. Semantic sync остаётся +на границе Finalization. Backend и `runtime-openapi` имеют `N/A` по Delivery Map. +Независимая Validation не является checkbox этой реализации. + +- [x] 4.1 [frontend] Выполнить canonical frontend gate на итоговом frontend delivery после переноса и уточнения инструкций. + - **Covers:** `N/A` — новое observable behavior не вводится; repository-owned проверка обязательна для affected frontend delivery по Delivery Map, хотя runtime и gate остаются прежними. + - **Verification:** Из `frontend` выполнить `nvm use --silent`, lockfile install `npm ci` и `npm run verify`; сохранить exact commands, cwd, exit status, существенный observed output и relevant input inventory/fingerprint по context authority. Проверить, что tracked outputs не изменены самим non-mutating gate. +- [x] 4.2 [docs] Выполнить canonical docs gate на итоговой policy, ADR и действующей навигации. + - **Covers:** `N/A` — это необходимая repository-owned проверка affected docs delivery по Delivery Map, не отдельное spec-level поведение и не замена scoped link review из 2.4 и 3.2. + - **Verification:** Из `docs` выполнить `nvm use --silent`, lockfile install `npm ci` и `npm run verify`; сохранить exact commands, cwd, exit status, существенный observed output и relevant input inventory/fingerprint по context authority, без запуска auto-fix как доказательства корректности. +- [x] 4.3 [specs] Проверить полноту и целостность repository-owned canonical change на текущем native inventory и выполнить specs gate, сохраняя утверждённые planning inputs. + - **Covers:** `N/A` — нормативное specs delivery уже выражено canonical artifacts этого change; задача обеспечивает его обязательную repository-owned structural проверку по Delivery Map без дополнительной мутации ради участия specs, нового поведения или переноса completion operations в Implementation. + - **Verification:** Активировать frontend `.nvmrc` через `nvm use --silent` до перехода в `specs`; выполнить `openspec status --change clarify-agent-context-routing --json --store wealth-ledger-specs`, `openspec schema validate wealth-ledger-sdd --verbose`, `openspec validate clarify-agent-context-routing --type change --strict --json --store wealth-ledger-specs` и `openspec validate --specs --strict --store wealth-ledger-specs`. По native inventory сверить approval bindings с действующей нормализацией task progress; сохранить exact commands, cwd, exit status, существенный observed output и relevant input inventory/fingerprint. При изменённом planning input вернуть работу к ответственной boundary, не исправлять approved содержание неявно.