specs/openspec/changes/archive/2026-09-09-clarify-agent-context-routing/design.md

## 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 отсутствуют. |