Document portable SDD workflow and Storybook catalog

This commit is contained in:
2026-09-07 22:22:13 +03:00
parent 8721e93849
commit 024e240303
8 changed files with 510 additions and 197 deletions
+13 -5
View File
@@ -6,11 +6,17 @@
policy, common reading pointers, audit routing и `../references/**` policy policy, common reading pointers, audit routing и `../references/**` policy
задаёт root `AGENTS.md`. задаёт root `AGENTS.md`.
Canonical SDD authority находится в `wealth-ledger-specs`, физически в Для SDD roles, approvals и ownership читайте
`../specs/openspec` от этого репозитория. Любая OpenSpec command, читающая или [governance](development/engineering-governance.md); native planning и completion
изменяющая change, должна использовать `--store wealth-ledger-specs`. в store `wealth-ledger-specs` —
[lifecycle](development/openspec-authority-and-lifecycle.md); recovery, fingerprints
и evidence reuse — [context authority](development/agent-token-efficiency.md).
Audit-derived работа начинается с найденной записи
[remediation registry](development/audit-remediation.md). Optional agent adapters
не требуются.
Docs обновляется до фактического проверенного состояния affected change и не представляет planned behavior как поставленное. Artifact ownership и Completion Evidence определены в [`development/engineering-governance.md`](development/engineering-governance.md); audit-derived работа начинается с [`development/audit-remediation.md`](development/audit-remediation.md). Docs фиксирует проверенное as-built состояние. Planning и Completion Evidence
принадлежат canonical `../specs/openspec`; docs не хранит их параллельную копию.
## Canonical gate ## Canonical gate
@@ -28,7 +34,9 @@ Gate non-mutating запускает committed Markdown rules и `git diff --che
## Boundaries ## Boundaries
- `architecture/` — текущее устройство, `features/` — поставленное поведение, `adr/` — устойчивые решения, `development/` — процесс и Completion Evidence, `audits/` — immutable snapshots. - `architecture/` — текущее устройство, `features/` — поставленное поведение,
`adr/` — устойчивые решения, `development/` — процесс и navigation к canonical
evidence, `audits/` — immutable snapshots. Legacy dated evidence не переписывается.
- Indexes должны вести к новым документам. - Indexes должны вести к новым документам.
- Feature docs описывают фактический поток, API и ограничения, но не повторяют OpenSpec requirements/design/tasks. - Feature docs описывают фактический поток, API и ограничения, но не повторяют OpenSpec requirements/design/tasks.
- Для диаграмм использовать Mermaid в Markdown. Не хранить application code, secrets или competing SDD artifacts. - Для диаграмм использовать Mermaid в Markdown. Не хранить application code, secrets или competing SDD artifacts.
+10 -4
View File
@@ -4,10 +4,16 @@
- [Frontend workflow](frontend-workflow.md) — Node 22, локальный запуск и - [Frontend workflow](frontend-workflow.md) — Node 22, локальный запуск и
frontend verification. frontend verification.
- [UI-каталог Storybook](ui-catalog.md) — запуск, шесть групп реальных компонентов
и композиций, безопасные примеры и границы проверки интерфейса.
- [Backend workflow](backend-workflow.md) — bootstrap backend, локальные - [Backend workflow](backend-workflow.md) — bootstrap backend, локальные
non-mutating gates и границы e2e. non-mutating gates и границы e2e.
- [Audit remediation registry](audit-remediation.md) — текущий статус findings, следующий OpenSpec change и evidence завершённых улучшений. - [Audit remediation registry](audit-remediation.md) — статусы findings, следующий
- [Engineering governance](engineering-governance.md) — Change Owner, SDD approvals, Delivery Map, risk-based testing, build-versus-buy и hard guardrails. OpenSpec change и ссылки на canonical archived Completion Evidence.
- [OpenSpec authority и lifecycle](openspec-authority-and-lifecycle.md) — единственный SDD store, границы постоянной документации и условия archive. - [Engineering governance](engineering-governance.md) — SDD roles и approvals,
- [Token-efficient agent workflow](agent-token-efficiency.md) — lazy context routing, session handoff, evidence batching и protocol активного pilot. Delivery Map, независимая Validation, completion safeguards и risk-based testing.
- [OpenSpec authority и lifecycle](openspec-authority-and-lifecycle.md) — native
planning, Apply, semantic sync и archive без обязательного agent runtime.
- [Token-efficient agent workflow](agent-token-efficiency.md) — authority для
recovery, fingerprints, актуального handoff и повторного использования evidence.
- [Проверка runtime OpenAPI](runtime-openapi-verification.md) — отдельный read-only contract gate и его границы. - [Проверка runtime OpenAPI](runtime-openapi-verification.md) — отдельный read-only contract gate и его границы.
+137 -63
View File
@@ -1,81 +1,155 @@
# Token-efficient agent workflow # Token-efficient agent workflow
## Статус и границы ## Authority и границы
Эта инструкция описывает действующий guidance для сокращения повторной передачи Этот документ — vendor-neutral authority для context discipline: recovery,
agent context. Она не меняет SDD lifecycle, approvals, canonical gates, semantic fingerprint bindings, bounded reads и observed evidence. Lifecycle ownership
verification или independent review и не является hard guardrail. принадлежит [Engineering governance](engineering-governance.md), native команды
— [OpenSpec lifecycle](openspec-authority-and-lifecycle.md). Эти процедуры
выполняются без обязательных skills, session adapter, telemetry или service.
Исходный baseline сохранён в Исходный наблюдаемый baseline сохранён в
[аудите Codex-сессий 26.08.2026](../audits/codex-sessions-token-audit-2026-08-26.md). [аудите сессий 26.08.2026](../audits/codex-sessions-token-audit-2026-08-26.md).
Raw rollout logs не коммитятся. Числовой budget не блокирует delivery без Raw logs и числовые token budgets не становятся delivery gates. Экономия
отдельного утверждённого change, детерминированной non-mutating проверки и контекста не оправдывает пропуск relevant authority или ослабление verification.
controlled positive/negative evidence.
Guidance ниже остаётся non-blocking: он не заменяет required authority или
verification и не повышается до hard guardrail без отдельного evidence-backed
change.
## Routing context ## Routing context
До чтения supporting documentation агент определяет: До supporting reads определите текущую роль, разрешённый outcome и affected
repositories. Прочитайте их local `AGENTS.md` для boundaries и canonical gates,
затем только применимую authority:
1. тип работы и текущую SDD-фазу, если change versioned; | Trigger | Context |
2. affected repositories и их canonical gates;
3. capability или source identity, нужные для следующего решения.
После этого загружается только применимый context:
| Trigger | Обязательный context |
| --- | --- | | --- | --- |
| Versioned SDD planning или Apply | Native OpenSpec instruction, возвращённые `contextFiles` и локальные `AGENTS.md` affected areas | | Planning или Implementation | Native instruction и каждый возвращённый context file |
| Engineering policy, approval, testing, delivery или archive | Релевантный раздел `engineering-governance.md` | | Approval, роль, testing, Delivery Map или completion | Релевантный раздел governance |
| Cross-service flow или архитектурная граница | `architecture/system-overview.md` и применимые ADR/feature docs | | Cross-area architecture | `architecture/system-overview.md`, нужные ADR/feature docs |
| Domain или API semantics | Релевантный термин `architecture/domain-glossary.md` и canonical contract/spec | | Domain или API semantics | Термин в `architecture/domain-glossary.md`, canonical contract/spec |
| Работа по известному Audit ID | Найденная через поиск запись и связанное evidence в `audit-remediation.md` | | Известный Audit ID | Найденная запись `audit-remediation.md` и её source/evidence |
| Диагностика agent token usage или этот pilot | Этот playbook и применимый dated audit snapshot | | Validation | Approved artifacts, delivery inventory, relevant checks и findings |
| Finalization | Текущий независимый verdict с binding и существующие delivery facts |
Supporting material загружается on demand, если возникший вопрос меняет В новой роли canonical artifacts читаются заново только в необходимом scope.
семантику, архитектуру, audit disposition или обязательный gate. Guidance нельзя В том же context повторно читаются изменившиеся relevant inputs. История чата
использовать как основание пропустить необходимую authority. не заменяет artifact и не является обязательным prerequisite.
## Handoff между agent-сессиями ## Recovery и handoff
Approved planning artifact, завершённый implementation slice или verification При наличии session adapter mutable state является единственным navigation
outcome являются естественной границей новой Codex task. Минимальный handoff: pointer. Прочитайте только его текущий self-contained immutable record, затем
phase-specific authority. Без adapter тот же актуальный envelope передаётся
в доступном рабочем контексте; отдельный versioned verdict или planning store
ради handoff не создаётся.
```text Envelope содержит только change identity, текущую роль/outcome, affected areas,
Change: <identity> observed approval bindings, completed/remaining task IDs, краткие observed checks,
Approved through: <explicitly approved artifact> blockers и один следующий допустимый outcome. Для продолжения после Validation
Current phase: <phase> он также сохраняет её verdict, relevant inventory и fingerprint; Finalization
Affected areas: <areas> retry не должен требовать восстановления цепочки старых records. Requirements,
Unresolved blockers: <none or list> Design, Tasks и acceptance scenarios остаются в canonical OpenSpec.
Next allowed outcome: <one outcome>
```
Planning content не копируется: новая task читает его из canonical OpenSpec Первичное `approved` записывается только после явного решения Change Owner,
store. Если явный approval недоступен в новой task, агент повторно запрашивает со ссылкой на наблюдённый источник решения, artifact identity и fingerprint.
его и не выводит решение владельца только из наличия artifact. При recovery совпадение позволяет продолжить без повторного approval. Отсутствие
binding, включая legacy state, требует явного решения; mismatch сбрасывает
approval изменённого artifact и всех downstream artifacts. Approval status
сохраняет наблюдение, но не доказывает личность или решение владельца сам по себе.
Для handoff Apply → Verify дополнительно передаются фактический scope изменённых Порядок сохранения: `canonical outcome → immutable record → state pointer`.
areas и unresolved failures. Полная история tool calls не передаётся. Сначала создаётся новый record; существующие records не перезаписываются. Перед
заменой pointer проверяется, что исходный state не изменён другим участником.
Конфликт или неполная запись остаются видимыми и не разрешаются last-write-wins.
Старые records читаются только для расследования конкретного текущего расхождения.
## Fingerprints
Fingerprint имеет вид `sha256:<64 lowercase hex digits>` и связывает observation
с содержимым, а не только с именем файла, временем изменения или Git HEAD.
Одинаковая процедура применяется к approval artifact, gate inputs и PASS;
отличаются только scope и явно указанная ниже нормализация task progress.
### Scope и inventory
До проверки сохраните reviewed inventory: workspace-relative точные пути и
релевантные directory roots, их явные exclusions, назначение набора и список
входящих files. Directory roots должны включать новые files, способные изменить
проверяемый результат; произвольный список только уже известных изменённых files
недостаточен. Scope покрывает все actual inputs gate/review, включая dependency
и config files. Unrelated concurrent change исключается по объяснённой границе,
а не потому, что мешает получить прежний fingerprint.
- Proposal, Design и Tasks — соответствующий canonical файл. Delta Specs —
полный разрешённый native CLI набор `specs/**/spec.md` этого change; при
сравнении membership запрашивается заново, чтобы обнаружить additions/removals.
- PASS включает raw approved planning artifacts, relevant main baseline,
проверенные delivery files affected areas и local unversioned instructions,
если они входят в change. Runtime/gate command и environment prerequisites
сохраняются рядом с fingerprint как observed metadata.
- Для каждого Git repository candidate paths получают через
`git ls-files --cached --others --exclude-standard -z`, затем пересекают
с reviewed roots/paths и de-duplicate. Это включает tracked и nonignored
untracked, staged и unstaged working content. Workspace-owned paths вне Git
перечисляются явно; relevant ignored inputs также включаются явно.
- При сравнении заново раскрываются те же roots и добавляются paths из прежнего
inventory: исчезнувший файл остаётся entry `missing`, новый входит в набор.
Directory names не хешируются отдельно. Пути используют `/`, относительно
workspace, без `.`/`..`, абсолютного host prefix и повторов.
- Собственные navigation state, phase records и
`changes/<change>/completion-evidence.md` исключаются из self-hash. Exclusions
относятся к конкретному change, не ко всем `.agents`, `.opencode` или specs.
Ожидаемые archive/sync/evidence/registry mutations проверяются отдельно как
completion outputs; ими нельзя скрыть новое implementation изменение.
### Детерминированное представление
1. Для каждого entry прочитайте текущие bytes из working tree. `file` получает
mode `100755`, если установлен хотя бы один executable bit, иначе `100644`.
`symlink` получает mode `120000`, payload — bytes самого link target без
разыменования. Для отсутствующего прежнего path используйте kind `missing`,
mode `-`, digest `-`. Unresolved Git conflicts, unreadable inputs и special
files блокируют binding; приблизительный fingerprint не создаётся.
2. Только для **approval Tasks** замените ASCII prefix `b"- [x] "` на `b"- [ ] "`
у строк canonical task checkbox (`X.Y [area]` после prefix). Другие bytes,
whitespace, строки, `Covers` и `Verification` не меняются. Во всех остальных
наборах, включая gate/PASS и их Tasks, используется raw payload. Таким образом
observed progress не отменяет approval содержания, но остаётся виден review.
3. Рассчитайте lowercase SHA-256 hex digest payload каждого существующего entry.
Отсортируйте entries по UTF-8 bytes workspace-relative path. Непредставимые
в UTF-8 paths требуют явного разрешения input issue, а не замены символов.
4. Соберите byte stream: ASCII prefix `wealth-ledger-input-v1` и один NUL byte,
затем для каждого entry UTF-8 fields `path`, `kind`, `mode`, `digest`, каждый
с завершающим NUL. Пробелы, JSON, newline separators и BOM не добавляются.
SHA-256 этого stream с prefix `sha256:` — fingerprint всего набора.
Inventory и fingerprint не содержат копии исходных artifacts. Если review
зависит от содержимого symlink target, target включается отдельным input;
хеширование только ссылки не подтверждает внешнее содержимое. Перенос файлов,
изменение mode, content или membership меняют binding. Commit/staging без
изменения этих данных его не меняют. Relevant input mutation инвалидирует PASS;
изменение planning approval fingerprint дополнительно применяет cascade policy.
## Повторное использование evidence
Сохранённый успешный gate повторно используется при совпадении его input scope,
fingerprint и relevant environment prerequisites. Evidence сохраняет exact
command, cwd, exit status и достаточный observed result. Неизвестный scope или
отсутствующий binding не доказывают неизменность. Нельзя заменить full gate
результатом проверки части файлов.
Validation независимо оценивает свежесть gates и semantic/acceptance behavior;
успех Implementation tests сам по себе не даёт независимый PASS. Finalization
сверяет последний PASS до terminal mutations и потребляет его без повторения
неизменившихся checks. Expected archive move, approved semantic sync и создание
Completion Evidence проверяются как новые completion outputs; их effect не
переписывает сохранённое описание проверенного delivery input.
## Evidence batching ## Evidence batching
Один evidence batch заканчивается перед следующим смысловым решением: Один batch заканчивается перед следующим смысловым решением. Независимые
read-only inputs получают вместе; adaptive discovery, side effects и approvals
- заранее независимые read-only lookups выполняются вместе; остаются последовательными. Начните с `rg`/identity search или Git status/stat,
- adaptive discovery, side effects и approval boundaries остаются затем раскройте relevant paths. Successful output сохраняет команду, exit status
последовательными; и существенный outcome; failure, semantic verification и review получают весь
- discovery начинается с `rg` или другого identity search, затем читает relevant evidence. Произвольный лимит строк не должен скрывать диагностический
релевантный диапазон; сигнал. Контекст оценивается вместе с качеством checks, findings и rework,
- diff сначала сужается через status/stat/name-only, затем раскрывает affected а не по сокращению tokens отдельно.
paths;
- successful command result сохраняет exact command identity, exit status и
существенную summary;
- failure или неоднозначная summary расширяет diagnostics до достаточной причины;
- semantic verification и reviewer всегда получают полный relevant evidence.
Статический лимит строк или tool tokens не применяется: он может скрыть
единственный диагностический сигнал. Compact output — способ убрать заведомо
нерелевантный шум, а не обрезать доказательства.
+9 -1
View File
@@ -14,10 +14,18 @@
`confirmed` ещё может быть active, а `rejected` — accepted как проверенное `confirmed` ещё может быть active, а `rejected` — accepted как проверенное
решение ничего не внедрять. решение ничего не внедрять.
- Одновременно допускается не более одного `active` remediation change. Пока он существует, продолжается только он. При наличии `planned` ровно одна запись отмечается следующей рекомендуемой задачей, но она не запускается параллельно active change. - Одновременно допускается не более одного `active` remediation change. Пока он существует, продолжается только он. При наличии `planned` ровно одна запись отмечается следующей рекомендуемой задачей, но она не запускается параллельно active change.
- `done` требует даты, archive path OpenSpec change, commit для каждого затронутого Git-репозитория и точных non-mutating verification commands с observed results. - `done` требует даты и ссылки на canonical archived OpenSpec change с его
`completion-evidence.md`. Существующие delivery commits, exact verification
commands/results и independent verdict хранятся там, а не дублируются в registry.
- `deferred` и `accepted` требуют даты, rationale и review trigger либо ссылки на явное решение владельца. - `deferred` и `accepted` требуют даты, rationale и review trigger либо ссылки на явное решение владельца.
- При смене статуса обновляется только этот реестр; versioned audit snapshot не редактируется. - При смене статуса обновляется только этот реестр; versioned audit snapshot не редактируется.
Completion procedure определена в
[OpenSpec lifecycle](openspec-authority-and-lifecycle.md#finalization-и-completion-evidence).
Новая запись `done` ссылается на evidence внутри archive. Исторические записи
ниже, прежние ссылки на `completion-evidence.md` в docs и датированные audit
snapshots сохраняются без переноса или переписывания задним числом.
## Текущее состояние workflow ## Текущее состояние workflow
- Bootstrap change: [`2026-08-23-establish-audit-remediation-workflow`](../../specs/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/) — `archived`; это process foundation и не закрывает ни одного Audit ID. - Bootstrap change: [`2026-08-23-establish-audit-remediation-workflow`](../../specs/openspec/changes/archive/2026-08-23-establish-audit-remediation-workflow/) — `archived`; это process foundation и не закрывает ни одного Audit ID.
+88 -38
View File
@@ -10,7 +10,10 @@
**Delivery Map** — решение по каждой области `frontend`, `backend`, `specs` и `docs`: `affected` с ожидаемым результатом либо `N/A` с конкретной проверяемой причиной. **Delivery Map** — решение по каждой области `frontend`, `backend`, `specs` и `docs`: `affected` с ожидаемым результатом либо `N/A` с конкретной проверяемой причиной.
**Completion Evidence** — созданная после реализации и archive запись о фактической поставке: Delivery Map, archive path, commits изменённых репозиториев, точные verification commands с наблюдёнными результатами и итог independent read-only review. **Completion Evidence** — запись существующих delivery commits, фактической
Delivery Map, точных verification commands с observed results и independent
review. Finalization создаёт её внутри canonical change до archive; она
архивируется вместе с change.
**Enforceable Engineering Invariant** — обязательное правило с детерминированной non-mutating локальной проверкой, нарушение которой блокирует завершение change. Непроверяемое предпочтение является guidance, а не hard guardrail. **Enforceable Engineering Invariant** — обязательное правило с детерминированной non-mutating локальной проверкой, нарушение которой блокирует завершение change. Непроверяемое предпочтение является guidance, а не hard guardrail.
@@ -35,40 +38,74 @@ Proposal → Delta Specs → Design → Tasks → Apply → Verify → Archive
а `Verification` задаёт планируемую проверку. Tasks не содержат будущие а `Verification` задаёт планируемую проверку. Tasks не содержат будущие
результаты, commits или post-archive bookkeeping. результаты, commits или post-archive bookkeeping.
AI-агент готовит только текущий разрешённый артефакт, показывает его Change Owner и останавливается. Downstream artifact создаётся только после явного approval. Если новая сессия не может подтвердить approval из доступного контекста, агент запрашивает его повторно. ### Роли и approvals
Сессия исполняет одну роль: Discovery, Specification, Implementation, Validation
или Finalization. Создание record и ожидание решения сами по себе не требуют
новой сессии той же роли. Переход к другой роли требует независимого контекста.
Specification поддерживает две bounded progression: `Proposal + Delta Specs`
и `Design + Tasks`. Перед каждым downstream artifact требуется отдельное явное
решение Change Owner:
| Approval неизменившегося artifact | Следующий разрешённый outcome |
| --- | --- |
| Proposal | Delta Specs в той же Specification-сессии |
| Delta Specs | Завершение первой пары; следующая Specification-сессия начинает Design |
| Design | Tasks в той же Specification-сессии |
| Tasks | Implementation в следующей роли |
Сохранённый observed approval повторно используется только при совпадении
identity и fingerprint. State не является самостоятельным доказательством
решения владельца. Отсутствующее либо legacy approval binding требует явного
решения; наличие файла не доказывает approval. Recovery и fingerprint procedure
определены в [context authority](agent-token-efficiency.md).
До запроса approval агент запускает доступный stage planning gate и сам До запроса approval агент запускает доступный stage planning gate и сам
исправляет технические ошибки формата. Полный change validation не объявляется исправляет технические ошибки формата. Полный change validation не объявляется
успешным, пока downstream artifacts отсутствуют. Форматное исправление без успешным, пока downstream artifacts отсутствуют. Несовпадение fingerprint
изменения intent, behavior, decisions или task scope не требует reapproval; утверждённого artifact сбрасывает его approval и downstream approvals;
семантическое изменение возвращает workflow к самому раннему затронутому изменение возвращается к самой ранней затронутой planning boundary. Отметки
artifact. выполнения Tasks не изменяют утверждённое содержание и нормализуются только
для approval fingerprint.
Изменение принятого upstream artifact инвалидирует approval зависимых артефактов: Proposal — Specs, Design и Tasks; Specs — Design и Tasks; Design — Tasks. Tasks не могут неявно расширять scope или менять поведение и архитектуру: работа возвращается к соответствующему upstream artifact. Изменение принятого upstream artifact инвалидирует approval зависимых артефактов: Proposal — Specs, Design и Tasks; Specs — Design и Tasks; Design — Tasks. Tasks не могут неявно расширять scope или менять поведение и архитектуру: работа возвращается к соответствующему upstream artifact.
## Token-efficient agent execution ### Implementation, Validation и Finalization
Agent workflow сначала определяет текущую SDD-фазу и affected delivery areas, Implementation выполняет связный batch approved Tasks и отмечает только
затем загружает canonical artifacts, локальные routing instructions и только фактически завершённую работу после релевантных checks. Если implementation-owned
применимую supporting authority. Полная история предыдущей agent-сессии и работа остаётся, нормальный outcome — `CHECKPOINT` с продолжением Implementation;
отдельный handoff artifact не являются prerequisite: после явного approval это не blocker. `READY_FOR_VALIDATION` требует завершения всей такой работы и
следующая фаза восстанавливается из canonical OpenSpec change и компактного успеха её проверок. Проблема intent направляется к Proposal, observable behavior
handoff state. Если доступный context не подтверждает approval, решение Change — к Delta Specs, архитектуры — к Design, декомпозиции — к Tasks.
Owner запрашивается повторно.
Независимые read-only evidence следует получать одним batch до следующего Validation независимо проверяет affected gates, semantic и acceptance behavior,
смыслового решения. Compact successful output сохраняет command identity, exit применимые edge cases и выполняет independent read-only review. Она не меняет
status и существенный outcome; failure, semantic verification и independent production implementation, planning artifacts или Tasks. Эти проверки не
review получают достаточные diagnostics и полный relevant scope. Эти правила и остаются implementation checkboxes. Результат `PASS`, `FAIL` или `SPEC_ISSUE`
числовые budgets являются guidance, пока отдельный утверждённый change не привязан к проверенным planning/delivery inputs по
предоставит детерминированную non-mutating проверку и controlled evidence нового [context authority](agent-token-efficiency.md#fingerprints).
hard guardrail.
Эффективность оценивается на завершённую SDD-фазу вместе с gate outcomes, fix | Результат / blocker | Ответственная следующая роль |
cycles, interrupted attempts и review findings. Меньший token usage при большем | --- | --- |
rework или худшем verification result не считается улучшением. Операционный | Validation PASS на актуальных inputs | Finalization |
routing, handoff envelope и pilot protocol находятся в lazy | Implementation finding или unchecked implementation-owned Task | Implementation |
[Token-efficient agent workflow](agent-token-efficiency.md). | Planning issue / SPEC_ISSUE | Specification, самая ранняя затронутая boundary |
| Отсутствующий либо устаревший PASS | Validation |
| Retryable archive/evidence/environment failure при корректных inputs | Finalization |
Finalization потребляет актуальный PASS и выполняет только completion mechanics.
Она не повторяет неизменившуюся Validation и не исправляет implementation или
planning. При blocker сохраняется observed cause и точный маршрут продолжения.
## Context authority
[Token-efficient agent workflow](agent-token-efficiency.md) единолично определяет
bounded reads, fingerprint bindings, handoff, evidence reuse и batching.
Обязательные safeguards этой policy действуют с любым agent runtime; skills,
commands и session adapters необязательны. Числовые token budgets и telemetry
не являются условием delivery.
## Delivery Map и multi-repository delivery ## Delivery Map и multi-repository delivery
@@ -135,13 +172,14 @@ contract либо другое существенно труднообратим
| Вид знания | Authoritative location | | Вид знания | Authoritative location |
| --- | --- | | --- | --- |
| Намерение, требования, Design, Tasks, changes и archives | `specs/openspec` | | Намерение, требования, Design, Tasks, changes, Completion Evidence и archives | `specs/openspec` |
| Исполняемое поведение | `frontend` и `backend` code и risk-based tests | | Исполняемое поведение | `frontend` и `backend` code и risk-based tests |
| Публичный API contract | backend runtime OpenAPI и committed frontend snapshot | | Публичный API contract | backend runtime OpenAPI и committed frontend snapshot |
| Текущее устройство и поставленные возможности | `docs/architecture` и `docs/features` | | Текущее устройство и поставленные возможности | `docs/architecture` и `docs/features` |
| Устойчивые архитектурные решения и причины | `docs/adr` | | Устойчивые архитектурные решения и причины | `docs/adr` |
| Инженерная policy и completion evidence | `docs/development` | | Инженерная policy и context discipline | `docs/development` |
| Компактная маршрутизация AI-агентов и локальные entrypoints | root/repository-local `AGENTS.md` и workspace `.opencode` | | Компактная маршрутизация и локальные boundaries | root/repository-local `AGENTS.md` |
| Необязательные runtime adapters и navigation | локальные skills, commands и session records |
`docs` описывает только фактическое текущее состояние и не пересказывает Proposal, Delta Specs, Design или Tasks другим форматом. `AGENTS.md` не копирует архитектуру или feature documentation: он направляет к authority и перечисляет только применимые hard constraints и canonical commands. `docs` описывает только фактическое текущее состояние и не пересказывает Proposal, Delta Specs, Design или Tasks другим форматом. `AGENTS.md` не копирует архитектуру или feature documentation: он направляет к authority и перечисляет только применимые hard constraints и canonical commands.
@@ -160,12 +198,9 @@ CI пока отсутствует, поэтому обязательные gate
Hard guardrail должен иметь исполняемую локальную проверку. Правило без надёжной проверки помечается как guidance и учитывается в review, но не выдаётся за автоматический запрет. Новые frameworks, checkers и thresholds добавляются только после оценки поддерживаемого решения, maintenance cost и реально защищаемого риска. Hard guardrail должен иметь исполняемую локальную проверку. Правило без надёжной проверки помечается как guidance и учитывается в review, но не выдаётся за автоматический запрет. Новые frameworks, checkers и thresholds добавляются только после оценки поддерживаемого решения, maintenance cost и реально защищаемого риска.
Root `.opencode/commands` и `.opencode/skills` являются локальными Native команды и completion procedure описаны в
non-authority entrypoints. Они должны соблюдать fixed store, one-artifact [OpenSpec lifecycle](openspec-authority-and-lifecycle.md). Они не требуют
approvals и hard archive blockers, но не имеют отдельного versioned projection optional runtime adapters.
source.
OpenSpec schema и changes валидируются native CLI с явным canonical store.
## Verify, archive и Completion Evidence ## Verify, archive и Completion Evidence
@@ -173,8 +208,23 @@ Structural validation OpenSpec проверяет schema и форму арте
1. успешные canonical gates всех affected areas; 1. успешные canonical gates всех affected areas;
2. native strict validation completed change и main specs из canonical store; 2. native strict validation completed change и main specs из canonical store;
3. semantic verification реализации против Proposal, Delta Specs, Design и Tasks; 3. semantic и acceptance verification против approved Proposal, Delta Specs,
Design и Tasks;
4. independent read-only review без Critical и Important findings; 4. independent read-only review без Critical и Important findings;
5. завершённый checklist без unchecked tasks. 5. завершённые implementation-owned Tasks и необходимая as-built документация;
6. актуальный input-bound PASS независимой Validation и существующие delivery
commits для каждой affected repository area.
Archive не имеет confirmation override для этих blockers. После успешного archive применяется двухфазная фиксация: сначала commits поставленных изменений и archive/sync, затем Completion Evidence с уже существующими delivery commit IDs, после чего отдельный final docs commit сохраняет evidence. Evidence ссылается на предшествующий as-built docs commit, если docs affected; при `N/A` сохраняет причину и не выдумывает implementation commit. Собственный final evidence commit не может ссылаться сам на себя и сообщается итогом archive workflow. Только фактические commits, выполненные команды и наблюдённые результаты могут быть evidence; planned значения и предположения не считаются завершением. Archive не имеет confirmation override для этих blockers. Completion Evidence
создаётся в `specs/openspec/changes/<change>/completion-evidence.md` после
существования всех перечисленных фактов и архивируется вместе с change.
Evidence содержит Delivery Map, существующие commit identifiers, exact
commands/observed results и независимый verdict с привязкой к inputs. Для
`N/A` сохраняется конкретная причина без фиктивного commit или gate.
Собственный evidence/archive commit не ссылается сам на себя: его идентификатор
сообщается после фиксации. Отсутствующие факты не заменяются placeholders,
unchecked Tasks или отдельным docs evidence store. При `docs: N/A` запись
Completion Evidence не требует docs-мутации. Registry хранит ссылку на
canonical archive и evidence; прежние датированные evidence и ссылки остаются
историческими и не переносятся задним числом.
+9 -1
View File
@@ -3,15 +3,23 @@
Frontend требует Node 22. В `frontend/` чистая установка и полный локальный quality gate выполняются так: Frontend требует Node 22. В `frontend/` чистая установка и полный локальный quality gate выполняются так:
```bash ```bash
nvm use --silent
npm ci npm ci
npm run verify npm run verify
``` ```
`verify` проверяет OpenAPI drift, TypeScript, Biome, один coverage-backed запуск Vitest, Knip, `verify` проверяет OpenAPI drift, TypeScript, Biome, один coverage-backed запуск Vitest, Knip,
FSD dependency rules и production build. Он работает без backend. Coverage FSD dependency rules, runtime graph stories и отдельные сборки приложения и
Storybook. Он работает без backend. Coverage
остаётся anti-regression constraint; правила выбора тестов зафиксированы в остаётся anti-regression constraint; правила выбора тестов зафиксированы в
[engineering governance](engineering-governance.md). [engineering governance](engineering-governance.md).
Изолированные примеры реальных компонентов и композиций запускаются в Storybook
через `npm run dev:catalog`. `npm run build:catalog` создаёт `storybook-static/`,
а `npm run preview:catalog` обслуживает эту статическую сборку. Шесть групп,
работа с Docs, Controls и Actions, доступность и ограничения описаны в
[UI-каталоге Storybook](ui-catalog.md).
Backend остаётся источником OpenAPI. После изменения опубликованного Backend остаётся источником OpenAPI. После изменения опубликованного
backend-контракта разработчик обновляет в `frontend/` committed snapshot backend-контракта разработчик обновляет в `frontend/` committed snapshot
`src/shared/api/spec/openapi.json` копированием backend OpenAPI document, затем `src/shared/api/spec/openapi.json` копированием backend OpenAPI document, затем
+145 -85
View File
@@ -2,117 +2,177 @@
## Назначение ## Назначение
Этот документ описывает фактически настроенный OpenSpec workflow WealthLedger. Общие определения, approval policy, risk-based testing и build-versus-buy находятся в [Engineering governance](engineering-governance.md). Это исполняемая процедура canonical workflow без обязательного agent runtime.
Роли, approvals, Delivery Map и completion safeguards определяет
[Engineering governance](engineering-governance.md); чтение контекста и bindings
— [context authority](agent-token-efficiency.md). Optional skills и commands
могут выполнять те же шаги, но не заменяют эти authorities.
## Единственный SDD store ## Единственный SDD store
- Canonical store: `wealth-ledger-specs`. Canonical store — `wealth-ledger-specs`, физический root — `specs/openspec`
- Физический root: `specs/openspec` относительно workspace. относительно workspace. Все команды, читающие или изменяющие change, получают
- Requirements, Delta Specs, Design, Tasks, changes и archives хранятся только в этом store. `--store wealth-ledger-specs`; cwd и nearest-root discovery не выбирают authority.
- Команда, читающая или изменяющая change, всегда получает `--store wealth-ledger-specs`; cwd и nearest-root discovery не выбирают authority проекта. Planning artifacts, main specs, changes, Completion Evidence и archives
- Versioned framework-specific planning artifacts вне `specs/openspec`, включая `superpowers/plans`, запрещены. `references/**` остаётся read-only исключением. принадлежат только этому store. `references/**` остаётся read-only; historical
archives не переписываются.
Native OpenSpec CLI валидирует schema, changes и main specs с явным store; ## Native planning
historical archives не переписываются.
## Project-local schema Перед Node-командами выберите runtime через применимую `.nvmrc` командой
`nvm use --silent`. Работая с change, сначала получите его фактическую структуру:
Новые changes по умолчанию используют schema `wealth-ledger-sdd` version 3 из ```bash
`specs/openspec/schemas/wealth-ledger-sdd`. Её граф: openspec status --change <change> --json --store wealth-ledger-specs
```text
proposal → specs → design → tasks → apply
``` ```
OpenSpec обеспечивает structural order, а явное решение Change Owner — переход Для нового согласованного change используется native
между артефактами. Agent создаёт один текущий artifact и останавливается для `openspec new change <change> --store wealth-ledger-specs`. До создания Proposal
approval. Роли артефактов и cascade rules определены в governance policy; Discovery разрешает неизвестные intent/scope вопросы. В Specification запрашивайте
исполняемые templates и instructions принадлежат schema. Каждая instruction только разрешённый сейчас artifact:
начинается компактным блоком `Critical Rules`; основной explanatory prose
написан по-русски, а exact OpenSpec headings, tokens и normative keywords
сохраняются на английском.
Delta Spec template является operation-neutral comment guide. Он перечисляет ```bash
`ADDED`, `MODIFIED`, `REMOVED` и `RENAMED`, но не создаёт активную operation openspec instructions <artifact> --change <change> --json --store wealth-ledger-specs
section. Автор добавляет только применимые sections и не оставляет пустых. ```
Structural validation выполняется native OpenSpec CLI с `<artifact>` — `proposal`, `specs`, `design` или `tasks`. Прочитайте все
`--store wealth-ledger-specs` и не означает approval. возвращённые dependencies/context files, подготовьте artifact по native
instructions, выполните доступную native structural проверку и получите
отдельный approval перед downstream artifact. Tasks instructions возвращают
Design и Delta Specs для exact `Covers`; второй context mapping не нужен.
Approval и bounded progression соблюдают governance policy.
Project-local schema проверяется из `specs`: Новые changes используют project-local schema `wealth-ledger-sdd` из
`specs/openspec/schemas/wealth-ledger-sdd` и граф
`proposal → specs → design → tasks → apply`. `config.yaml` хранит default schema
и routing context, schema — форму artifacts и stage-specific instructions.
Проверка из `specs`:
```bash ```bash
openspec schema validate wealth-ledger-sdd --verbose openspec schema validate wealth-ledger-sdd --verbose
openspec schema which wealth-ledger-sdd --json openspec schema which wealth-ledger-sdd --json
``` ```
`schema which` должен указывать project-local source. `specs/openspec/config.yaml` хранит default schema и компактный routing context, а не копию полной policy. `schema which` должен указывать project-local source. Delta template остаётся
operation-neutral guide: автор создаёт только применимые `ADDED`, `MODIFIED`,
`REMOVED`, `RENAMED` sections. Native validation проверяет структуру, не approval.
## Stage context и handoff ## Implementation и Validation
До supporting reads agent определяет текущую OpenSpec-фазу и affected areas. После approval Tasks получите native Apply context:
Native instruction и возвращённые `contextFiles` задают planning context;
repository-local `AGENTS.md` добавляет только routing и canonical gate своей
area. Architecture, glossary, audit registry и подробный operational playbook
загружаются по применимому trigger, а не blanket-набором перед любой задачей.
После явного approval planning artifact следующая фаза может начаться в новой ```bash
Codex task. Handoff сохраняет change identity, последний approved artifact, openspec instructions apply --change <change> --json --store wealth-ledger-specs
current phase, affected areas, unresolved blockers и один следующий outcome. ```
Содержание artifacts повторно не пересказывается и остаётся в canonical store.
Если явный approval нельзя подтвердить из новой task, agent повторно запрашивает
его до создания downstream artifact.
Apply → Verify использует ту же boundary, добавляя фактический implementation Прочитайте каждый возвращённый `contextFiles` и local `AGENTS.md` affected
scope и unresolved failures без полной истории tool calls. Подробная форма repositories. Выберите связный batch pending Tasks, реализуйте его и выполните
handoff и evidence-batching guidance описаны в релевантные checks. Зафиксируйте завершённые canonical checkboxes и observed
[Token-efficient agent workflow](agent-token-efficiency.md). outcome. Remaining implementation work даёт checkpoint; вся завершённая работа
— готовность к отдельной Validation. Изменение artifact проверяется по
[approval binding](agent-token-efficiency.md#fingerprints), а semantic issue
возвращается к ответственной planning boundary.
## Agent entrypoints и обновление OpenSpec Validation читает approved planning artifacts и implementation scope, проверяет
свежесть сохранённых gate outcomes и выполняет отсутствующие affected gates.
Root `.opencode/commands` и `.opencode/skills` — локальные non-authority Глобальный gate нельзя считать проверенным по более узкому fingerprint: binding
entrypoints. Они удобны для работы агента, но не являются SDD source of truth и покрывает его relevant inputs. Specs gate использует native strict checks:
не имеют отдельного versioned projection source. Нормативный contract хранится
в schema, `AGENTS.md`, governance и non-mutating scripts.
`openspec update` не запускается напрямую из workspace root. Новую upstream
version сначала проверяют в isolated staging и повторно накладывают минимальные
project constraints: fixed store, one-artifact-at-a-time, stage planning gate,
Apply feedback routing и hard archive blockers. Authority fixtures проверяют
version preflight, permissive archive, conditional store selection и второй
`openspec` root как failures.
## Реализация и проверка change
Design содержит Delivery Map для `frontend`, `backend`, `specs` и `docs`.
Перед archive canonical gates каждого affected repository выполняются по одному
разу. `specs` проверяется всегда native strict validation. При required
`runtime-openapi` запускают backend `npm run test:openapi-contract`; этот status
допустим лишь при affected frontend и backend.
Tasks имеют
формат `X.Y [area] action` и indented `Covers`/`Verification`; каждый Delta
Requirement покрывается точной ссылкой хотя бы один раз, а `workspace` остаётся
только owner orchestration/verification. Для `N/A` verifier отклоняет пустой,
separator-only или unresolved placeholder, а содержательность rationale
подтверждается semantic review.
Apply читает planning artifacts только из `contextFiles`, возвращённых native
`openspec instructions apply --json`, затем repository-local `AGENTS.md`
affected areas. Второй context mapping не поддерживается. Без reapproval можно
исправить только Markdown heading, typo без изменения нормативного смысла или
table alignment; Requirement, Scenario, architecture и planned Verification
являются semantic changes.
Перед archive отдельно подтверждаются native structural и semantic gates:
```bash ```bash
openspec validate <change> --type change --strict --store wealth-ledger-specs openspec validate <change> --type change --strict --store wealth-ledger-specs
openspec validate --specs --strict --store wealth-ledger-specs openspec validate --specs --strict --store wealth-ledger-specs
``` ```
Structural success не доказывает соответствие реализации. Semantic verification Canonical gate остальных areas задан их `AGENTS.md`. Required
сопоставляет реализацию с Proposal, Delta Specs, Design и Tasks, затем требуется `runtime-openapi` дополнительно вызывает backend `npm run test:openapi-contract`.
independent read-only review без Critical и Important findings. Независимый reviewer сопоставляет реализацию с approved artifacts, acceptance
scenarios и применимыми edge cases; фиксирует `PASS`, `FAIL` или `SPEC_ISSUE`,
полный relevant evidence и reviewed input inventory/fingerprint. Он не исправляет
код, planning artifacts или Tasks. Отдельный versioned verdict artifact не
требуется: observed verdict и binding передаются в текущем handoff и затем
в canonical Completion Evidence.
Archive отклоняется при незавершённом artifact approval, unchecked task, failed affected-area gate, отсутствующей semantic verification или independent review. Confirmation override для этих условий отсутствует. Completion Evidence создаётся только после archive и delivery commits по двухфазному протоколу [Engineering governance](engineering-governance.md); final evidence commit не подменяется незакрытым task. ## Semantic sync перед archive
Перед terminal mutation сверяйте все deltas с текущей main baseline. Native
structural success и planning complete не заменяют эту проверку:
1. Используйте `artifactPaths.specs.existingOutputPaths` из текущего status JSON
как точный список deltas. Main root разрешается через
`planningHome.root/openspec/specs`; полный вложенный capability path
сохраняется. Пустой список не разрешает угадывать delta по другим файлам.
Явно выбранный subset должен целиком входить в native список; invalid path
блокирует sync, пустой subset не выполняет записей, выбор не расширяется.
2. Получите один актуальный snapshot native specs instructions той же командой
`openspec instructions specs --change <change> --json --store wealth-ledger-specs`
либо используйте уже прочитанный неизменившийся snapshot. Ошибка команды или
invalid JSON блокирует запись; отсутствие optional `rules` в корректном ответе
означает отсутствие дополнительных правил формы.
3. Прочитайте каждую delta и соответствующую main spec. Для `ADDED` проверьте
отсутствие конфликтующей identity; `MODIFIED` содержит полный requirement
и все сохраняемые scenarios; `REMOVED`/`RENAMED` меняют только явно указанные
identities. Сохраните незатронутые requirements, scenarios и existing Purpose.
Новая capability получает утверждённый Purpose, а не placeholder.
4. Покажите ожидаемый semantic diff до записи. Если новая baseline несовместима
с approved delta, верните change к самой ранней затронутой boundary. Не
переписывайте main spec или delta, чтобы скрыть конфликт.
5. После подтверждённого соответствия native archive выполняет sync вместе с
archive. Main specs сохраняют `Purpose` и `Requirements`, без delta operation
headers. Удаление всей capability допускается только при approved retirement
и `.openspec.yaml` с `retire_capabilities: true`: исходная capability была
непустой и корректной, текущая операция удалила все requirements, не осталось
другого содержимого кроме title/Purpose/Requirements, а реальный путь лежит
внутри specs root без symlink-выхода. Иначе capability не изменяется; пустая
Requirements section не записывается.
Отдельно запрошенный sync использует тот же semantic diff и native rules,
применяет только явно выбранные полные delta paths, затем выполняет strict
validation main specs. Он не даёт terminal status и не расширяет выбранный scope.
## Finalization и Completion Evidence
После актуального независимого PASS:
1. Сверьте approvals, завершённость implementation-owned Tasks и input binding
с текущим working tree. Blocker маршрутизируется по governance; неизменившиеся
gates и independent review повторно не запускаются.
2. Проверьте существующие delivery commits affected repositories. Если
разрешённая фиксация проверенных изменений ещё нужна, сделайте её до создания
evidence и повторно сравните content fingerprints. Commit/staging без
изменения inputs не устаревает PASS. Каждый delivery commit содержит
проверенное изменение своей области; unrelated working changes сохраняются.
3. Создайте `completion-evidence.md` внутри active canonical change только из
существующих фактов: Delivery Map, commit IDs, точные commands/results,
independent verdict и его input binding. Для `N/A` сохраните причину.
Собственные evidence/state/records исключены из self-hash; отдельной
обязательной docs-мутации ради evidence нет.
4. Выполните semantic sync review выше и перед archive снова проверьте, что
кроме ожидаемых completion mechanics relevant inputs не изменились.
Запустите native archive с его validation:
```bash
openspec archive <change> --yes --store wealth-ledger-specs
```
`--yes` автоматизирует prompt, не снимает safeguards. `--no-validate` и
`--skip-specs` не являются обходом failed gate, stale PASS или semantic conflict.
5. Проверьте наблюдённый archive path, сохранение Completion Evidence и ожидаемый
diff sync/move. Изменённые archive/main-spec outputs проходят native strict
проверку; это проверка новых completion outputs, не повторная Validation
неизменившейся реализации. Зафиксируйте разрешённые archive/sync/evidence
изменения и сообщите созданный commit ID отдельно от evidence, чтобы избежать
self-reference. Audit-derived registry получает ссылку на archive/evidence
после успешного terminal outcome, без копирования commits и gate results.
Если archive недоступен, incomplete evidence или commit operation можно
повторить при тех же inputs — Finalization сохраняет observed blocker.
Частичный archive не повторяется вслепую: сначала установите фактические пути
и diff, затем продолжите недостающую completion operation. Неожиданное изменение
planning/delivery направляется к ответственной предыдущей роли.
## Обновление OpenSpec
`openspec update` сначала проверяют в isolated staging. После upstream update
проверяются fixed store, stage context, separate approvals, Apply feedback routing
и archive safeguards. Optional entrypoints остаются короткими указателями на
эту процедуру; vendor-specific command tree не является prerequisite.
+99
View File
@@ -0,0 +1,99 @@
# UI-каталог Storybook
Storybook 10.6.0 показывает реальные компоненты и композиции WealthLedger
на общей визуальной основе приложения без входа и подключения backend.
## Запуск и сборка
Из `frontend/` выберите Node 22 и установите зависимости из lockfile:
```bash
nvm use --silent
npm ci
npm run dev:catalog
```
Storybook запускается на [localhost:6006](http://localhost:6006); браузер
автоматически не открывается. Отдельная статическая сборка и её preview:
```bash
npm run build:catalog
npm run preview:catalog
```
Результат находится в `frontend/storybook-static/`, вход — `index.html`.
Команда preview выводит адрес статической витрины в терминале. Обычный
`npm run build` сохраняет приложение в `frontend/dist/`; stories не входят
в его entrypoint и продуктовые маршруты. Публикация отдельным сервисом не настроена.
## Компоненты и работа с примерами
В дереве Storybook доступны шесть групп:
| Группа | Что показывает |
| --- | --- |
| `BrokerageAccountList` | Счета со сводкой по нескольким валютам, недоступной или пустой сводкой и длинным названием. |
| `PositionCard` | Акцию с положительным результатом, облигацию с отрицательным, прочий инструмент и позицию без оценки. |
| `RecentEvents` | Полученные события, загрузку, ошибку, пустой результат и неизвестную ожидаемую сумму. |
| `PortfolioRefreshState` с `PortfolioTotals` | Сохранённые суммы при фоновом обновлении и его ошибке, локальный retry. |
| `StateView` | Пустое состояние и ошибку, с действием и без него. |
| `AccountPageLoading` через `LoadingSkeleton` | Реальный skeleton заголовка, сводки и строк страницы счёта. |
Стандартные Mantine primitives видны внутри этих компонентов. Отдельных копий
библиотечных demos или обёрток ради каталога нет. Каталог не заявляет полноту:
отсутствие компонента не запрещает его использование в приложении.
Выберите историю в дереве, чтобы открыть её состояние в Canvas. Docs описывает
назначение, ограничения и свойства группы, а также её примеры. Controls меняют
разрешённые свойства; синтетические объекты и callbacks недоступны для редактирования.
Например, `kind` у `PositionCard` меняет вариант представления фиксированной позиции,
а разные данные инструмента выбираются отдельной историей. Actions регистрирует
локальные callbacks кнопок и retry.
Для возврата изменённых свойств используйте штатный reset args в Controls;
для повторного монтирования примера — remount в панели Canvas. Размер preview
можно менять без сброса args. Изолированный iframe позволяет отдельно проверить
компонент на узком экране; навигацией самой витрины управляет Storybook.
Preview использует экспортируемую app theme, Mantine CSS, application styles,
русскую i18n и фиксированную светлую схему без чтения сохранённой темы.
Stories находятся рядом с существующими presentation components и импортируют
их реализации. Отдельных tokens нет. Error StateView сохраняет alert semantics,
skeleton — busy-область с декоративными фигурами без фокуса. Проверяйте доступность
действий и ссылок с клавиатуры вместе с визуальным состоянием.
## Границы и сопровождение
Все счета, позиции, события и суммы вымышлены. Stories не читают application
storage, cookies, секреты или реальные пользовательские данные. Внешние логотипы
не загружаются: примеры используют буквенный fallback существующего компонента.
Storybook manager может сохранять собственные настройки витрины; telemetry отключена.
Stories не подключают AuthProvider, QueryClient, API clients и исполняемые VM.
Действия не обращаются к application API. Ссылки меняют только локальный маршрут
MemoryRouter: страница назначения не отображается, URL приложения не меняется.
Retry демонстрирует локальный callback и не доказывает восстановление API или
полный пользовательский сценарий. Loading/error относятся к выбранному примеру.
Композиция сохранённых сумм показывает представление Client Cached Snapshot;
сам query lifecycle не исполняется. Для запросных экранов действует
[UI Pattern](../../frontend/docs/UI-PATTERN.md): сохранение данных при refetch,
structural skeleton для initial loading и контекстный индикатор mutation.
Skeleton конкретной страницы остаётся ответственностью страницы.
При изменении включённого компонента проверяйте вместе с ним его пример,
описание и ограничения. `npm run verify` включает Storybook в strict TypeScript,
Biome, Vitest, Knip и dependency-cruiser, затем собирает приложение и статическую
витрину. Основная проверка FSD сохраняется; отдельный `deps:storybook` проверяет
runtime graph stories и preview, запрещая достижимость application data.
Type-only ссылки на типы VM и API стираются и не запускают запросы.
Declarative stories не требуют искусственного unit coverage, а продуктовые
coverage floors сохраняются. Клавиатура, реальные размеры и визуальное
соответствие проверяются в браузере; автоматической visual regression нет.
Каталог доступен независимо от процессного расширения UI/UX. Новый contract
визуального пакета Design пока не поставлен: он ожидает завершения
`optimize-session-oriented-sdd-v2` и сверки с его authority. Совместная готовность
каталога и обновлённого процесса к пилоту ещё не подтверждена; продуктовый пилот
не проводился. Действующий процесс описан в
[OpenSpec lifecycle](openspec-authority-and-lifecycle.md).