docs(ai): archive superseded context routing plan

This commit is contained in:
2026-09-09 16:23:19 +03:00
parent fbb7193e90
commit bcb10da21c
8 changed files with 790 additions and 39 deletions
@@ -0,0 +1,2 @@
schema: wealth-ledger-sdd
created: 2026-09-09
@@ -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 описаны в действующих документах; их исправление не входило в эту задачу.
@@ -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 отсутствуют. |
@@ -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.
@@ -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
продолжают действовать
@@ -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 содержание неявно.