docs(ai): archive superseded context routing plan

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