From c6dc20b153d2d6b480c53bf5c4e780c17a177476 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Mon, 7 Sep 2026 22:48:25 +0300 Subject: [PATCH] Integrate Storybook and portable UI design workflow --- .../.openspec.yaml | 2 + .../integrate-ui-ux-design-workflow/design.md | 271 ++++++++++++++++++ .../proposal.md | 89 ++++++ .../specs/agent-sdd-session-workflow/spec.md | 119 ++++++++ .../specs/frontend-ui-catalog/spec.md | 94 ++++++ .../openspec-authority-and-lifecycle/spec.md | 160 +++++++++++ .../integrate-ui-ux-design-workflow/tasks.md | 106 +++++++ .../schemas/wealth-ledger-sdd/schema.yaml | 35 ++- .../wealth-ledger-sdd/templates/design.md | 33 +++ 9 files changed, 908 insertions(+), 1 deletion(-) create mode 100644 openspec/changes/integrate-ui-ux-design-workflow/.openspec.yaml create mode 100644 openspec/changes/integrate-ui-ux-design-workflow/design.md create mode 100644 openspec/changes/integrate-ui-ux-design-workflow/proposal.md create mode 100644 openspec/changes/integrate-ui-ux-design-workflow/specs/agent-sdd-session-workflow/spec.md create mode 100644 openspec/changes/integrate-ui-ux-design-workflow/specs/frontend-ui-catalog/spec.md create mode 100644 openspec/changes/integrate-ui-ux-design-workflow/specs/openspec-authority-and-lifecycle/spec.md create mode 100644 openspec/changes/integrate-ui-ux-design-workflow/tasks.md diff --git a/openspec/changes/integrate-ui-ux-design-workflow/.openspec.yaml b/openspec/changes/integrate-ui-ux-design-workflow/.openspec.yaml new file mode 100644 index 0000000..362f78a --- /dev/null +++ b/openspec/changes/integrate-ui-ux-design-workflow/.openspec.yaml @@ -0,0 +1,2 @@ +schema: wealth-ledger-sdd +created: 2026-09-06 diff --git a/openspec/changes/integrate-ui-ux-design-workflow/design.md b/openspec/changes/integrate-ui-ux-design-workflow/design.md new file mode 100644 index 0000000..6a00bc5 --- /dev/null +++ b/openspec/changes/integrate-ui-ux-design-workflow/design.md @@ -0,0 +1,271 @@ +## Context + +Frontend использует React 19, Vite 8, Mantine 9, общую app-owned theme, светлую +схему и русскую i18n. Продуктовые presentation components уже отделены от VM и +API. Каталог использует Storybook и покрывает реальные компоненты и композиции +приложения; прежняя Vite-витрина удаляется. Продуктовые экраны не меняются. + +Поставленная baseline — schema v4 и canonical authority после завершённого +`optimize-session-oriented-sdd-v2`; его immutable bundle расположен в +`wealth-ledger-specs`, `changes/archive/2026-09-07-optimize-session-oriented-sdd-v2/` +относительно canonical OpenSpec root. +Его canonical archive содержит Completion Evidence. Процессное расширение +сохраняет поставленные bounded outcomes, approval/input binding, независимую +Validation и canonical completion ownership. Два пересекающихся MODIFIED +requirements дополнены визуальными обязанностями поверх этой baseline со всеми +её существующими scenarios. UI/UX package revision 2 ниже сохраняется. + +## Goals / Non-Goals + +**Goals:** + +- Использовать специализированную инфраструктуру витрины с готовыми stories, + controls, docs, navigation и изолированным preview. +- Показывать реальные решения WealthLedger, применимые состояния и правила + использования на общей визуальной основе приложения. +- Сохранить изоляцию демонстраций от application API, auth и пользовательских + данных, действующие FSD boundaries и canonical verification. +- Включить переносимый визуальный пакет в существующий Design после завершения + процессной зависимости, без нового lifecycle. + +**Non-Goals:** + +- Собственная navigation/controls система, каталог стандартных Mantine demos, + wrappers над примитивами ради нового имени, массовый UI refactor или редизайн. +- Полная каталогизация, отдельный publishing service, CI, browser mock mode, + автоматическая visual regression либо продуктовая фича в роли пилота. + +## Decisions + +### 1. Каталог использует Storybook на существующем Vite stack + +Выбран Storybook 10.6.0 с React/Vite framework и Docs addon той же версии. +Published peer ranges React/Vite framework включают React 19 и Vite 8. +Dependencies фиксируются точными versions в общем frontend lockfile. Другие +addons не добавляются без конкретной потребности. Storybook владеет navigation, +Controls, Docs, Actions и remount preview; собственный catalog shell удаляется. + +Локальный Storybook и static build существуют отдельно от app entrypoint и +продуктовых маршрутов. Сохраняются понятные scripts dev:catalog и build:catalog; +static output — storybook-static. Продуктовая сборка не включает stories. +Telemetry Storybook выключена. Manager может хранить собственные настройки +витрины; это не разрешает stories читать application storage, cookies или secrets. + +Общий preview decorator использует экспортируемую app theme, Mantine CSS, +application styles, русскую i18n и светлую схему без чтения сохранённой темы. +Stories находятся рядом с принадлежащими slice presentation modules и используют +относительные imports внутри slice; cross-slice imports сохраняют public API. +Storybook configuration — tooling composition, а не новый application слой. + +Примеры получают синтетические typed props. MemoryRouter используется только +для реальных components со ссылками; он не меняет URL приложения и не подключает +product routes. AuthProvider, QueryClient, API clients, page containers и runtime +VM hooks не входят в preview graph. Type-only ссылки на VM/API-derived props +допустимы: они стираются и не запускают запросы. Проверка FSD сохраняет эти связи, +а отдельный runtime pass того же dependency-cruiser проверяет именно выполняемый +graph stories/preview без ослабления основной boundary проверки. + +Внешние logos не загружаются: synthetic props используют null и реальный +fallback компонента. Retry/actions используют локальный Storybook callback. +Пример не выполняет денежные расчёты и не доказывает API recovery. Существующие +pure presentation helpers допустимы для подготовки synthetic props. + +### 2. Начальный набор представляет шесть групп решений WealthLedger + +| Группа / реальные components | Состояния и конфигурации | Применение и ограничения | +| --- | --- | --- | +| BrokerageAccountList | summary available, unavailable, empty; длинное имя и несколько валют | Выбор счёта, сводка и их реальные ограничения; synthetic account IDs и MemoryRouter, без auth/API. | +| PositionCard | stocks gain, bonds loss, other, missing valuation/identifiers | Карточка позиции с готовыми display props, null logo и реальным fallback; вычисления VM и котировки не воспроизводятся. | +| RecentEvents | loaded, loading, error, empty, missing amount | Реальная секция ближайших событий; fixed synthetic items и локальная ссылка, без запроса календаря. | +| PortfolioRefreshState вместе с PortfolioTotals | idle, refreshing, refresh error; локальный retry | Отображение сохранённых сумм при refetch/ошибке, без скрытия данных. Это presentation Client Cached Snapshot, не исполнение query lifecycle. | +| StateView | empty/error, с действием и без него | Общий компонент пустого состояния/ошибки с alert semantics и локальным callback. | +| AccountPageLoading через LoadingSkeleton | существующая структура заголовка, сводки и строк | Реальный page-owned structural loading; busy-region и декоративные shapes без фокуса. | + +Названия, назначение и ограничения находятся в Storybook Docs для каждой группы; +каждая история представляет определённое состояние. Controls изменяют только +допустимые props; synthetic объекты и callbacks не становятся URL/API inputs. +Истории с ссылками явно описывают, что полный переход на продуктовую страницу не +демонстрируется. Storybook Actions показывает локальный callback. + +Отдельный раздел стандартных Button/TextInput/Select/Checkbox/Alert/Paper не +создаётся: в текущем scope нет отличающегося contract, который оправдывает копию +Mantine docs. Эти primitives видны внутри настоящих compositions. Если появится +реальная принятая конфигурация или app-owned abstraction, она рассматривается +вместе с соответствующим изменением, без предварительных wrappers. + +### 3. UI/UX package revision 2 — существующий Storybook shell и app preview + +Применимость: **reuse** стандартного Storybook 10.6.0 manager/Docs/Controls и +**new/changed** composition начальных stories на существующей теме WealthLedger. +Процессная часть имеет UI/UX N/A, поскольку не вводит пользовательский экран. +Пакет revision 2 полностью встроен в Design: таблица групп выше и правила ниже; +отдельных attachments или изменяемых внешних макетов нет. + +- Широкая витрина использует штатное дерево историй Storybook, Canvas/Docs и + панель Controls/Actions. Выбор истории открывает её определённые synthetic args. +- Узкая витрина использует штатную адаптивную navigation Storybook. Для проверки + UI самого приложения доступен изолированный iframe preview; его область + проверяется на 320, 768 и 1280 CSS px без горизонтальной прокрутки. +- Цвета, typography, поверхности и responsive поведение внутри Canvas принадлежат + существующим компонентам и app theme. Manager не стилизуется под продукт. +- Controls отражают supported props; reset args и remount используют штатные + действия Storybook. Изменение размера preview не сбрасывает args. Собственный + сброс/счётчик и кастомный breakpoint navigation из revision 1 удаляются. +- Ошибка/loading относятся к выбранной истории. Семантика alert/busy, доступные + labels, keyboard/focus и сохранение данных при refetch остаются реальными. +- Docs объясняет назначение, состояние, synthetic-data boundary и ограничения. + Наличие истории не подтверждает полный journey или сквозной пилот процесса. + +### 4. Визуальные материалы принадлежат одному canonical Design + +Design получает компактный раздел UI/UX Applicability: `new/changed`, `reuse` +либо `N/A` с причиной. Для применимого scope он определяет экраны, состояния, +interactions и responsive rules; при reuse называет конкретную версию, часть +решения и отличия. Новый формальный макет для неизменяемой области не нужен. + +Основное переносимое представление — Markdown внутри Design. Если изображение +необходимо для однозначного результата, используются локальные PNG/SVG exports +в `visuals/` того же canonical change. Design содержит состав пакета: revision, +идентификатор каждого материала, относительный путь, назначение/экран/состояние +и SHA-256 для внешних по отношению к Markdown файлов. Содержимое самого Design +входит в его обычную identity; self-referential hash не вводится. SVG exports +самодостаточны, без scripts, внешних fonts/assets и исполняемых обработчиков. + +Внешний редактор или preview может быть вспомогательным источником, но approved +результат должен открываться из canonical пакета без аккаунта в этом сервисе. +Ссылка на изменяемый каталог также не заменяет сохранённое решение: Design +фиксирует выбранную конфигурацию и идентичность переиспользуемого источника. +Reuse из другого archive ссылается на его точный immutable пакет, а не `latest`. + +Revision описывает комплект, digest обнаруживает замену файла; ни то ни другое +не доказывает owner approval. Approval относится ко всему представленному +Design с его составом. Семантическая замена изображения, responsive rule или +interaction меняет Design и возвращает его к обычному approval boundary. +При несовместимости со Specs возврат начинается со Specs, при изменении intent — +с Proposal. Форматное исправление не маскирует визуальное изменение. + +При archive относительная структура Design/visuals переносится вместе с change. +Проверяется доступность каждого материала и совпадение его identity после +переноса; утрата файла блокирует завершение, а не компенсируется внешним URL. +Historical archives не дополняются новыми пакетами задним числом. + +### 5. Процесс расширяется в существующих владельцах + +Project-local OpenSpec schema владеет формой Design и phase instructions; +governance/lifecycle — единым правилом approval, переносимости и feedback. +Runtime-neutral authority описывает поведение без обязательного конкретного +skill, browser или design service. Локальные session skills/entrypoints только +направляют к ней и читают выбранный пакет из Design; отдельный visual handoff, +новая роль или отдельный UI/UX gate не возникают. + +Implementation и Validation получают Design штатным native context routing, +а из него — применимые материалы. Недоступность, отсутствующий материал или +несовпадение digest блокирует зависимую работу до восстановления точного пакета +либо owner decision на нужной boundary. Восстановление известных байтов не +разрешает дорисовать отсутствующее решение по памяти. + +Semantic verification сравнивает область изменения с согласованными экранами, +состояниями, interactions и responsive behavior. Однозначный visual mismatch +даёт исправление реализации; противоречие или неоднозначность самого пакета — +возврат в Specification. Validation остаётся read-only. Native structural +success, наличие screenshots и наличие каталога не дают semantic PASS. + +Проверка комплектности использует обычные файловые операции, относительные +ссылки и стандартный SHA-256; отдельный parser/registry или approval engine не +создаётся. Native structural validation не заявляется автоматической проверкой +качества макета или произвольных attachments. Содержательность applicability, +полнота пакета и визуальное соответствие остаются явными обязанностями review. +После завершения зависимости существующий approval/input binding расширяется +на перечисленные attachments, не создавая параллельной модели state. + +## Delivery Map + +| Area | Status | Architectural outcome or N/A reason | +| --- | --- | --- | +| frontend | `affected` | Storybook с шестью группами реальных компонентов/композиций, общей theme, безопасными stories, Docs и отдельной static build в canonical gate. | +| backend | `N/A` | Каталог не использует API/auth clients и реальные финансовые данные; endpoints, DTO, хранение, денежные вычисления и backend gate не меняются. | +| specs | `affected` | Новая capability каталога, расширение lifecycle/session requirements и существующей schema для полного Design package после dependency reconciliation; planning остаётся только в canonical store. | +| docs | `affected` | As-built описание доступного каталога, его границ, визуальной основы и фактически внедрённого UI/UX workflow; обновлённые routing links к canonical archive/Completion Evidence без отдельного evidence store в docs. | + +### Contract Gate Decision + +| Gate | Status | Reason | +| --- | --- | --- | +| runtime-openapi | `N/A` | Ни одна сторона API contract не изменяется; каталог изолирован от application API. | + +Workspace entrypoints — локальная non-authority orchestration. Они следуют +versioned specs/docs contract; их адаптация не подменяет repository-owned +реализацию, Delivery Map или canonical gates. + +## Solution Assessment + +| Вариант | Fit и зрелость | Стоимость и ограничения | Решение | +| --- | --- | --- | --- | +| Storybook 10.6.0 + React/Vite + Docs | Специализированная поддерживаемая витрина; готовые navigation, args/controls, docs, actions и static build. Peer ranges включают React 19 и Vite 8. | Новые devDependencies и их обновления; конфигурация и stories остаются project-owned. Совместимость build и gate проверяется при интеграции. | Выбран: снижает объём собственного catalog tooling. | +| Собственная Vite composition | Использует уже установленный stack | Требует сопровождать navigation, controls, reset, descriptions и responsive shell; малое число stories не устраняет эту стоимость. | Удаляется, конкретного gap Storybook не установлено. | +| Ladle | Готовая React-витрина | Нет потребности во втором runner при выбранном Storybook; отдельная интеграция и lifecycle. | Не выбран. | +| Mantine docs / screenshots | Полезный reference библиотеки | Не показывают реальные WealthLedger compositions и их состояния. | Вспомогательный reference, не каталог проекта. | + +Для переносимого visual package сохраняются OpenSpec, Git, Markdown и при +необходимости самодостаточные exports; Storybook показывает текущее состояние +реализации и не заменяет сохраняемую согласованную версию Design. + +## Risks / Trade-offs + +- Dependency может изменить main specs и approval model. Текущая проверка + authority не даёт права применить сегодняшние MODIFIED blocks после неё без + повторного сопоставления и нужного reapproval. +- Общая theme предотвращает drift tokens; изменение descriptions или + демонстрируемой конфигурации всё равно требует review вместе с компонентом. +- Локальные synthetic examples доказывают UI interaction, но не API, денежную + семантику или полный investment journey. Ограничение видно рядом с примером. +- Переносимые exports увеличивают размер specs repository и нуждаются в ручном + review. Используются только материалы, необходимые для конкретного Design; + временные captures не становятся частью approved пакета автоматически. +- Storybook в этом scope не предоставляет автоматическую visual regression. + Проверка клавиатуры и responsive behavior выполняется browser review; + отдельный browser test framework или числовой visual threshold не вводится скрыто. + +## Migration Plan + +1. Продолжить planning только по явным approvals текущего change. Этот Design + фиксирует решения, но не включает новые process rules сейчас. Каталог может + реализовываться после утверждения всех его planning artifacts; внедрение + процессной части дополнительно зависит от завершения predecessor change. +2. Перед process implementation подтвердить фактическое завершение + `optimize-session-oriented-sdd-v2` по canonical archive и completion evidence, + затем заново прочитать поставленную authority, schema и session routing. + Наличие всех planning files или native `isComplete` недостаточно. +3. Сопоставить пересекающиеся MODIFIED requirements с новыми main specs, + сохранив поставленные predecessor invariants и scenarios. Если их текущая + редакция требует изменения Requirement/Scenario, остановиться на Delta Specs + approval boundary; после approval повторно согласовать зависимые Design и + Tasks. Перенос future predecessor текста сейчас и автоматический merge при + archive не заменяют этот шаг. При более раннем изменении intent возврат — + к Proposal. До разрешения расхождения process implementation заблокирована. +4. Поставить Storybook и истории, удалив прежний custom catalog, а после dependency + reconciliation — согласованное расширение существующих schema, + policy и локальных adapters. Не дублировать новые predecessor rules о роли + Validation, evidence и bounded outcomes; добавить только visual package + responsibilities. Docs описывают фактически проверенное состояние. +5. Применять обновление к новым changes и к ещё не утверждённому Design активного + change. Для уже утверждённого Design сохранить его исходную approval boundary: + миграция пакета требует явного решения владельца; добавление или изменение + содержательного UI/UX решения возвращает к Design и инвалидирует Tasks, + затронутые Specs — к Specs. Для changes уже в Implementation/Validation нет + автоматического retrofit или нового PASS: owner-requested migration проходит + ту же boundary. Неизменяемые legacy changes продолжают по своему согласованному + scope; исторические archives остаются неизменными. Не мигрировать чужие state + в рамках этой поставки. +6. Завершить текущую поставку с affected gates и независимым semantic review, + сохранив Design package при archive. Готовность означает доступность каталога + и работающего процесса. Отдельный последующий небольшой UI change выбирается + владельцем, получает собственные approvals и использует оба результата; + только его наблюдённый проход позволяет заявить успешность совместного пилота. + +### Rollback Contract + +| Field | Decision | +| --- | --- | +| Status | `N/A` | +| Reason | Локальный tooling и versioned process artifacts обратимы; auth/security behavior, реальные данные, API и необратимая инфраструктура не меняются. Каталог имеет отдельный entrypoint. Возврат frontend/process редакции не удаляет canonical visual packages или archive и не восстанавливает approval автоматически. | diff --git a/openspec/changes/integrate-ui-ux-design-workflow/proposal.md b/openspec/changes/integrate-ui-ux-design-workflow/proposal.md new file mode 100644 index 0000000..1d69d9e --- /dev/null +++ b/openspec/changes/integrate-ui-ux-design-workflow/proposal.md @@ -0,0 +1,89 @@ +## Why + +WealthLedger уже имеет общую основу интерфейса, но участникам разработки +недоступен единый воспроизводимый каталог её возможностей и состояний. +Существующий Design объясняет технические решения, однако не определяет, +какой визуальный результат согласован, как передать его следующей изолированной +сессии и как установить соответствие реализации этому результату. + +Нужно связать доступную UI-основу и UI/UX-проектирование с действующим SDD, +чтобы владелец видел ожидаемый интерфейс до реализации, а исполнители +использовали одну согласованную основу и однозначный Design. Planning можно +вести сейчас; внедрение процессной части начнётся после завершения +`optimize-session-oriented-sdd-v2`. + +## What Changes + +- Развить существующую UI-основу и предоставить один доступный участникам + каталог ограниченного набора реальных компонентов и UI-композиций + WealthLedger, их вариантов, применимых состояний и правил использования. + Основное содержание показывает решения приложения; библиотечные примитивы + допустимы только как вспомогательная основа с принятыми конфигурациями. Каталог отражает реальное поведение компонентов + и общие визуальные правила приложения, позволяя выбирать готовые решения + без запуска полного пользовательского сценария. +- Включить UI/UX-проектирование в существующий Design. Объём визуальной + проработки соразмерен изменению: новый или существенно изменённый интерфейс, + переиспользование согласованного решения либо обоснованная неприменимость + UI/UX. Отсутствие влияния на интерфейс не требует формального макета. +- Сделать визуальные материалы частью единого согласуемого Design: они + объясняют затронутые экраны, состояния, взаимодействия и адаптивное поведение + в объёме конкретного change. Следующая изолированная сессия получает + однозначную версию полного пакета, а материалы остаются доступны после + архивирования change. +- Передавать согласованный визуальный результат в реализацию и независимую + проверку через существующий SDD. Существенное расхождение возвращает работу + к соответствующей planning boundary; наличие макета или каталога само по + себе не означает approval либо подтверждённое соответствие реализации. +- Подготовить основу для совместного пилота каталога и обновлённого процесса + на последующем небольшом UI change с собственными planning approvals. + Текущая поставка даёт готовность к такому пилоту; успешность сквозного + workflow можно заявить только после его фактического прохождения. +- Перед Design повторно сверить действующую canonical authority. Согласование + процесса с результатом `optimize-session-oriented-sdd-v2` не даёт права + автоматически переутверждать активные changes или переписывать archives. + +Вне scope: полный редизайн приложения, каталогизация всех компонентов, +новая продуктовая фича в роли неявного пилота, замена существующей UI-основы, +отдельная поставка дизайн-системы как самостоятельного продукта, автоматическое +преобразование макетов в реализацию и двусторонняя синхронизация. Новый lifecycle, +дополнительная SDD-роль и отдельный UI/UX approval не вводятся. Концептуальные +материалы и Discovery остаются входным контекстом, а не утверждёнными +OpenSpec-артефактами. + +## Capabilities + +### New Capabilities + +- `frontend-ui-catalog` — `specs/frontend-ui-catalog/spec.md`: участники + разработки могут воспроизводимо просматривать ограниченный набор реальных + UI-компонентов, их варианты и состояния на общей визуальной основе приложения. + +### Modified Capabilities + +- `openspec-authority-and-lifecycle` — + `specs/openspec-authority-and-lifecycle/spec.md`: полномочия Design охватывают + применимый визуальный пакет; единые approval, передача, semantic verification, + feedback routing и сохранность при archive распространяются на весь пакет. +- `agent-sdd-session-workflow` — `specs/agent-sdd-session-workflow/spec.md`: + Specification, Implementation и независимая Validation используют применимые + визуальные материалы из canonical Design при продолжении между сессиями, + сохраняя единственную роль сессии и non-authority характер handoff. + +## Impact + +Основные пользователи изменения — Change Owner, участники UI/UX-проектирования, +frontend-разработчики и AI-агенты, выполняющие planning, implementation и review. +Для пользователей приложения этот change не вводит новых инвестиционных +сценариев и не разрешает массовую смену интерфейса. + +Затрагиваются frontend как владелец общей UI-основы и каталога, specs как +владелец canonical SDD contract и docs как описание фактически поставленного +процесса и правил использования основы. Локальные agent entrypoints следуют +этому contract. Backend, денежные расчёты и публичный API не меняются. + +Точные границы поставки по всем четырём репозиториям определит Delivery Map +в Design. Действующие правила доступности, UI-состояний, границ frontend и +обязательной проверки сохраняются; каталог не вводит конкурирующую модель +пользовательского поведения. Совместимость инструментов, переносимость +визуальных материалов и применимость обновлённого процесса к активным changes +остаются вопросами последующего Design до разрешения внедрения. diff --git a/openspec/changes/integrate-ui-ux-design-workflow/specs/agent-sdd-session-workflow/spec.md b/openspec/changes/integrate-ui-ux-design-workflow/specs/agent-sdd-session-workflow/spec.md new file mode 100644 index 0000000..7e33ae7 --- /dev/null +++ b/openspec/changes/integrate-ui-ux-design-workflow/specs/agent-sdd-session-workflow/spec.md @@ -0,0 +1,119 @@ +## MODIFIED Requirements + +### Requirement: Продолжение workflow восстанавливает только нужный контекст + +Workflow SHALL однозначно определять текущую роль и разрешённый outcome из +сохранённого состояния change и одного актуального self-contained handoff. Он +MUST загружать только phase-specific canonical authority и изменившийся +relevant evidence, а не полную историю, прежние handoff-данные или уже +прочитанные неизменившиеся inputs. После появления OpenSpec change его approved +artifacts MUST быть источником intent, requirements, design и tasks. + +Specification при подготовке Design SHALL определять применимый визуальный +пакет в canonical Design. При продолжении после его approval Implementation и +Validation SHALL получать применимые визуальные материалы именно согласованной +версии из canonical Design, сохраняя одну роль сессии и не создавая копию Design +в handoff. Недоступность или неоднозначность согласованного пакета MUST быть +сообщена как блокер зависимой работы и MUST NOT компенсироваться догадкой по +истории обсуждения или текущему внешнему макету. + +#### Scenario: Пользователь продолжает change после другой сессии + +- **WHEN** пользователь запрашивает продолжение известного change +- **THEN** workflow определяет ровно одну текущую роль, читает только актуальный + handoff и применимую canonical authority этой роли + +#### Scenario: Есть история нескольких попыток + +- **WHEN** change содержит более старые records или результаты прежних попыток +- **THEN** workflow не загружает их по умолчанию и обращается к ним только для + расследования конкретной проблемы текущей роли + +#### Scenario: Независимые evidence доступны одновременно + +- **WHEN** до следующего смыслового решения нужны несколько независимых + read-only inputs +- **THEN** workflow получает их одним bounded batch и сохраняет полный relevant + scope для failure или review findings + +#### Scenario: Успешный gate уже выполнен на неизменившихся inputs + +- **WHEN** успешный gate был выполнен и его relevant inputs после этого не + изменялись +- **THEN** workflow использует сохранённый observed outcome и не повторяет gate + без причины + +#### Scenario: Specification готовит Design с визуальными материалами + +- **WHEN** Specification получила разрешение подготовить Design с применимым + UI/UX scope +- **THEN** она представляет визуальные материалы как часть одного canonical + Design и останавливается до его единого approval, не начиная другую роль + +#### Scenario: Implementation получает утверждённый визуальный Design + +- **WHEN** Implementation начинает разрешённую реализацию UI change +- **THEN** она использует применимый пакет согласованной версии из canonical + Design, а навигационный handoff не заменяет его содержимое или owner approval + +#### Scenario: Пакет невозможно однозначно восстановить + +- **WHEN** следующая роль не может получить применимые материалы или установить + согласованную версию +- **THEN** зависимая работа останавливается с конкретным блокером до + восстановления пакета либо разрешения вопроса на соответствующей planning boundary + +### Requirement: Validation остаётся независимой и без побочных исправлений + +Validation SHALL независимо выполнять affected canonical gates, semantic и +acceptance verification, проверку применимых edge cases и independent read-only +review относительно approved OpenSpec artifacts. Она MUST NOT изменять +production implementation, specification или Tasks и MUST возвращать только +PASS, FAIL либо SPEC_ISSUE с маршрутизацией к Finalization, Implementation либо +самой ранней затронутой planning boundary. Validation-owned verification и +review MUST NOT оставаться unchecked implementation Tasks. + +Для применимого UI/UX scope независимое сопоставление SHALL включать визуальные +материалы согласованной версии canonical Design и соответствующие экраны, +состояния, взаимодействия и адаптивное поведение реализации. Read-only boundary +Validation SHALL распространяться на весь визуальный пакет Design. + +#### Scenario: Реализация соответствует утверждённому change + +- **WHEN** Validation подтверждает approved requirements, affected gates, + acceptance behavior и отсутствие blocking review findings +- **THEN** она возвращает PASS и разрешает следующую сессию Finalization + +#### Scenario: Найдена проблема реализации + +- **WHEN** Validation находит несоответствие реализации утверждённому OpenSpec +- **THEN** она возвращает FAIL с точным observed finding и направляет следующую + сессию к Implementation без самостоятельного исправления + +#### Scenario: Найдена проблема спецификации + +- **WHEN** Validation находит противоречие или пробел в approved planning + artifacts +- **THEN** она возвращает SPEC_ISSUE и направляет работу к самой ранней + затронутой planning boundary без переписывания specification под реализацию + +#### Scenario: Tasks планируют независимую проверку + +- **WHEN** Tasks описывают ожидаемую semantic verification или independent + review после реализации +- **THEN** завершение Implementation не зависит от checkbox, который может + закрыть только Validation + +#### Scenario: Найдено визуальное несоответствие + +- **WHEN** наблюдаемая реализация расходится с однозначным применимым решением + согласованного визуального пакета +- **THEN** Validation возвращает FAIL с конкретным несоответствием и не + исправляет интерфейс или визуальный пакет в этой сессии + +#### Scenario: Визуальный пакет противоречит другим planning artifacts + +- **WHEN** Validation обнаруживает противоречие согласованного визуального + результата требованиям либо неоднозначность самого Design +- **THEN** она возвращает SPEC_ISSUE с основанием возврата к самой ранней + затронутой planning boundary, не выбирая новую трактовку самостоятельно diff --git a/openspec/changes/integrate-ui-ux-design-workflow/specs/frontend-ui-catalog/spec.md b/openspec/changes/integrate-ui-ux-design-workflow/specs/frontend-ui-catalog/spec.md new file mode 100644 index 0000000..e801759 --- /dev/null +++ b/openspec/changes/integrate-ui-ux-design-workflow/specs/frontend-ui-catalog/spec.md @@ -0,0 +1,94 @@ +## Purpose + +Предоставляет участникам разработки воспроизводимый обзор ограниченного набора +реальных UI-компонентов и композиций WealthLedger для выбора решений на +общей визуальной основе приложения. + +## ADDED Requirements + +### Requirement: Каталог предоставляет определённый набор реальных компонентов + +Участники разработки SHALL иметь один доступный каталог с явно определённым +ограниченным набором реальных компонентов и UI-композиций WealthLedger, их +назначением, поддерживаемыми вариантами, применимыми состояниями и правилами +использования. Основное содержание SHALL показывать решения, используемые +приложением. Библиотечные примитивы MAY быть вспомогательными примерами принятых +конфигураций, но MUST NOT подменять продуктовые компоненты и композиции. Каталог MUST демонстрировать реальное +поведение компонентов на общей визуальной основе приложения, а не независимые +имитации. Отсутствие компонента в каталоге MUST NOT означать его отсутствие в +приложении или запрет использования. + +#### Scenario: Участник выбирает готовое решение + +- **WHEN** участник просматривает включённый в каталог компонент +- **THEN** он видит его назначение, доступные варианты и состояния и может + сопоставить их с потребностью интерфейса на визуальной основе WealthLedger + +#### Scenario: Участник изучает принятый UI-паттерн + +- **WHEN** участник выбирает композицию или компонент из основного набора +- **THEN** он видит реальное решение WealthLedger, его назначение, состояния и + ограничения применения, а не только стандартный пример UI-библиотеки + +#### Scenario: Компонент не входит в начальный набор + +- **WHEN** участник ищет компонент за пределами объявленного набора +- **THEN** граница покрытия каталога остаётся явной, без заявления о полноте + каталогизации приложения + +### Requirement: Примеры воспроизводят состояния и взаимодействия изолированно + +Каталог SHALL позволять воспроизводимо просматривать объявленные варианты и +состояния без прохождения полного пользовательского сценария приложения. +Интерактивные примеры SHALL позволять наблюдать поддерживаемые взаимодействия. +Примеры MUST сохранять применимые правила доступности и UI-состояний приложения +и MUST NOT вводить конкурирующую модель их поведения. Состояния, неприменимые к +компоненту, MUST NOT требоваться только ради заполнения каталога. + +#### Scenario: Участник повторно открывает пример + +- **WHEN** участник повторно выбирает тот же объявленный вариант и состояние +- **THEN** каталог воспроизводит соответствующий пример без предварительного + прохождения инвестиционного сценария + +#### Scenario: Участник взаимодействует с компонентом + +- **WHEN** участник использует поддерживаемое взаимодействие интерактивного + примера, включая клавиатурное управление там, где оно применимо +- **THEN** доступное поведение, focus и ограничения состояния соответствуют + реальному компоненту приложения + +#### Scenario: Представлено запросное состояние + +- **WHEN** пример показывает применимое loading, error, empty или loaded + состояние либо отображение ранее полученных данных при refetch +- **THEN** пример сохраняет действующую семантику соответствующего состояния + приложения и не подменяет её новой каталоговой договорённостью + +### Requirement: Каталог сохраняет достоверность и границы демонстрации + +Каталог SHALL отражать фактические поддерживаемые возможности включённых +компонентов и общие визуальные правила приложения. Демонстрационные данные +MUST NOT требовать доступа к реальным финансовым данным или секретам пользователя; +действия в примерах MUST NOT изменять реальные пользовательские данные. Известное +ограничение воспроизведения MUST быть явно обозначено и MUST NOT представляться +как подтверждённое продуктовое поведение. + +#### Scenario: Возможность компонента изменилась + +- **WHEN** изменённая возможность включённого компонента поставляется +- **THEN** каталог показывает соответствующее фактическое поведение и не + представляет устаревший вариант как поддерживаемый + +#### Scenario: Участник выполняет демонстрационное действие + +- **WHEN** участник открывает пример или выполняет в нём действие +- **THEN** для демонстрации не требуются реальные пользовательские финансовые + данные или секреты и реальные пользовательские данные остаются неизменными + +#### Scenario: Изолированный пример имеет ограничение + +- **WHEN** пример не воспроизводит некоторый аспект полного пользовательского + сценария +- **THEN** участник видит это ограничение и не получает заявления о проверке + полного сценария на основании примера diff --git a/openspec/changes/integrate-ui-ux-design-workflow/specs/openspec-authority-and-lifecycle/spec.md b/openspec/changes/integrate-ui-ux-design-workflow/specs/openspec-authority-and-lifecycle/spec.md new file mode 100644 index 0000000..9ba2185 --- /dev/null +++ b/openspec/changes/integrate-ui-ux-design-workflow/specs/openspec-authority-and-lifecycle/spec.md @@ -0,0 +1,160 @@ +## MODIFIED Requirements + +### Requirement: SDD-артефакты имеют непересекающиеся полномочия + +Proposal SHALL выражать причину, намерение, границы и ожидаемый эффект change языком владельца и MUST NOT содержать решения по технологиям, структуре кода, файлам, API или зависимостям. Delta Specs SHALL определять только добавленное, изменённое или удалённое наблюдаемое поведение и инварианты системы без описания изменений кода. Design SHALL объяснять архитектурный способ выполнения утверждённых Specs, существенные решения, риски и альтернативы крупными частями и MUST NOT становиться построчной инструкцией реализации. Применимые UI/UX-решения и визуальные материалы SHALL входить в единый canonical Design и MUST NOT образовывать отдельный planning authority или отдельный UI/UX approval. Tasks SHALL быть implementation checklist, достаточным для выполнения Design и Specs, и MUST NOT содержать ещё не наблюдённые completion results, commit identifiers или post-archive bookkeeping. Completion Evidence SHALL фиксироваться только после фактической реализации и верификации и MUST NOT подменять planning artifact. Концептуальные материалы и Discovery SHALL оставаться входным контекстом и MUST NOT считаться утверждёнными OpenSpec artifacts. + +#### Scenario: Product Owner формулирует Proposal + +- **WHEN** владелец описывает требуемое изменение, не зная структуры кода и файлов +- **THEN** Proposal остаётся полноценным утверждаемым намерением без необходимости принимать архитектурные решения + +#### Scenario: Агент подготавливает Tasks + +- **WHEN** Proposal, Delta Specs и Design уже утверждены +- **THEN** Tasks перечисляет конкретные действия реализации и проверки, но не заявляет будущие результаты уже выполненными + +#### Scenario: Владелец согласует визуальный результат + +- **WHEN** Change Owner явно утверждает Design с применимыми визуальными материалами +- **THEN** решение распространяется на обозначенную версию всего пакета Design + в существующем approval gate без новой SDD-роли или отдельного UI/UX approval + +#### Scenario: Концепт доступен до Design + +- **WHEN** обсуждение или Discovery содержит визуальный концепт +- **THEN** его наличие не разрешает downstream planning или реализацию и не + заменяет явное утверждение соответствующего OpenSpec artifact + +## ADDED Requirements + +### Requirement: UI/UX-проработка Design соразмерна изменению + +Design SHALL явно определять применимость UI/UX: новый или существенно +изменённый интерфейс, переиспользование согласованного решения либо N/A с +конкретной причиной отсутствия влияния на интерфейс. Для применимого scope +Design SHALL давать Change Owner однозначное представление ожидаемого результата: +затронутые экраны, применимые состояния, взаимодействия и адаптивное поведение. +Ссылки на переиспользуемое решение SHALL указывать, какая его часть применима +к change и какие различия остаются. Неизменяемые части интерфейса и N/A MUST NOT +требовать формальных новых макетов. + +#### Scenario: Change существенно меняет интерфейс + +- **WHEN** Design описывает новый или существенно изменённый пользовательский + интерфейс +- **THEN** владелец может оценить затронутые экраны, применимые состояния, + взаимодействия и поведение при изменении доступного пространства до реализации + +#### Scenario: Используется согласованное решение + +- **WHEN** change переиспользует ранее согласованное UI/UX-решение +- **THEN** Design однозначно указывает применимое решение, область + переиспользования и различия без обязательного повторного рисования + +#### Scenario: Change не влияет на интерфейс + +- **WHEN** UI/UX неприменим по конкретной причине, приведённой в Design +- **THEN** пакет Design допускается без формального макета и дополнительных + UI/UX approvals + +### Requirement: Визуальный пакет Design имеет однозначную сохраняемую версию + +Canonical Design SHALL однозначно определять состав и версию своих применимых +визуальных материалов. Материалы SHALL оставаться доступны Change Owner, +исполнителю и независимому reviewer при передаче между изолированными сессиями +и после archive, без зависимости от временного контекста предыдущей сессии. +Ссылка, содержимое которой может молча измениться, MUST NOT быть единственным +свидетельством согласованной версии. Визуальные материалы MUST NOT создавать +конкурирующий versioned planning root вне canonical OpenSpec authority. + +#### Scenario: Design передаётся другому исполнителю + +- **WHEN** новая изолированная сессия получает canonical Design +- **THEN** она может однозначно найти полный применимый визуальный пакет и + определить именно ту версию, на которую распространяется approval + +#### Scenario: Визуальный источник изменился или недоступен + +- **WHEN** текущий внешний или временный источник отличается от согласованной + версии либо перестал открываться +- **THEN** согласованная версия остаётся доступна из сохраняемого пакета Design + и не заменяется молча новым содержимым + +#### Scenario: Change архивирован + +- **WHEN** участник обращается к Design после archive +- **THEN** применимые визуальные материалы согласованной версии доступны вместе + с архивным Design и сохраняют однозначную связь с ним + +### Requirement: Соответствие визуальному Design входит в semantic verification + +Реализация SHALL следовать утверждённому Design, включая его применимые +визуальные материалы. Semantic verification и независимый read-only review +SHALL сопоставлять реализованные экраны, состояния, взаимодействия и адаптивное +поведение с этим пакетом в границах change. Наличие каталога или макета MUST NOT +считаться approval или доказательством соответствия реализации. Несоответствие +реализации SHALL направляться на исправление реализации; необходимость +существенно изменить согласованный результат SHALL возвращать работу к самой +ранней затронутой planning boundary с действующими cascade approval rules. + +#### Scenario: Реализация расходится с согласованным интерфейсом + +- **WHEN** реализация не соответствует однозначному применимому решению Design +- **THEN** проверка сообщает наблюдаемое несоответствие для исправления + реализации и не объявляет соответствие только из-за наличия макета или каталога + +#### Scenario: Согласованное решение требует пересмотра + +- **WHEN** выполнить UI/UX-решение без существенного изменения утверждённого + результата невозможно либо planning artifacts противоречат друг другу +- **THEN** workflow возвращает работу к самой ранней затронутой planning + boundary, применяет cascade approval rules и не подгоняет Design под реализацию + +### Requirement: Внедрение UI/UX workflow сохраняет действующие approval boundaries + +Planning `integrate-ui-ux-design-workflow` MAY продолжаться до завершения +`optimize-session-oriented-sdd-v2`, но внедрение процессной части MUST ожидать его +завершения. Перед Design этого change workflow SHALL повторно сверить действующую +canonical authority и определить применимость обновлённого процесса к активным +changes. Обновление MUST NOT автоматически переутверждать их artifacts или +переписывать historical archives. + +#### Scenario: Предшествующий процессный change ещё не завершён + +- **WHEN** `optimize-session-oriented-sdd-v2` остаётся незавершённым +- **THEN** planning текущего change допускается в рамках явных approvals, + а внедрение его процессной части остаётся недоступным + +#### Scenario: Начинается Design интеграции + +- **WHEN** Delta Specs этого change явно утверждены и начинается Design +- **THEN** Design опирается на повторно сверенную текущую canonical authority + и явно определяет применимость процесса к активным changes + +#### Scenario: Обновлённый процесс поставляется + +- **WHEN** процессные изменения становятся доступными участникам +- **THEN** прежние approvals активных changes не считаются автоматически + обновлёнными, а historical archives сохраняются без переписывания + +### Requirement: Готовность к пилоту отделена от доказанной успешности workflow + +Поставка каталога и обновлённого процесса SHALL позволять использовать их +совместно в последующем небольшом UI change с собственными planning approvals. +Текущий change MUST NOT включать неявную продуктовую фичу в качестве пилота или +заявлять успешность сквозного workflow до его фактического прохождения. + +#### Scenario: Текущая поставка завершена + +- **WHEN** каталог и обновлённый процесс готовы к совместному использованию, + но последующий UI change ещё не прошёл workflow +- **THEN** результат описывается как готовность к пилоту без заявления об + успешном сквозном пилоте + +#### Scenario: Начинается пилотный UI change + +- **WHEN** владелец выбирает небольшой UI change для совместного использования + каталога и процесса +- **THEN** этот change проходит собственные planning approvals, а вывод о + сквозной успешности опирается только на его фактически наблюдаемый результат diff --git a/openspec/changes/integrate-ui-ux-design-workflow/tasks.md b/openspec/changes/integrate-ui-ux-design-workflow/tasks.md new file mode 100644 index 0000000..ba09692 --- /dev/null +++ b/openspec/changes/integrate-ui-ux-design-workflow/tasks.md @@ -0,0 +1,106 @@ +## 1. Подготовка в границах Design + +- [x] 1.1 [workspace] Проверить совместимость выбранного Storybook с текущими React/Vite/Node и существующими владельцами UI перед заменой catalog tooling. + - **Covers:** `N/A` — проверка Solution Assessment и архитектурных предпосылок для разрешённой замены tooling и состава витрины. + - **Verification:** Сверить published peer ranges, installed versions и ответственные presentation components; выполнить интеграционную сборку на текущем stack, сохраняя OpenSpec/Git/Markdown для процессной части. + +## 2. Storybook реальных компонентов WealthLedger + +Группа независима от завершения процессной зависимости. Реализация следует +UI/UX package revision 2; прежние checkbox не переносятся на изменённые действия. + +- [x] 2.1 [frontend] Установить Storybook React/Vite и Docs с точными версиями, общим preview decorator и отдельными dev/static entrypoints; удалить custom catalog shell и его ненужную конфигурацию. + - **Covers:** `frontend-ui-catalog` — `Каталог предоставляет определённый набор реальных компонентов`; `frontend-ui-catalog` — `Примеры воспроизводят состояния и взаимодействия изолированно`; `frontend-ui-catalog` — `Каталог сохраняет достоверность и границы демонстрации` + - **Verification:** Проверить общий lockfile, app theme/CSS/i18n/light scheme, выключенную telemetry, штатные Controls/Docs/Actions и отсутствие старого HTML/shell/demo-кода и stories в продуктовой сборке. +- [x] 2.2 [frontend] Добавить colocated stories BrokerageAccountList и PositionCard с состояниями и synthetic props из Design revision 2. + - **Covers:** `frontend-ui-catalog` — `Каталог предоставляет определённый набор реальных компонентов`; `frontend-ui-catalog` — `Примеры воспроизводят состояния и взаимодействия изолированно`; `frontend-ui-catalog` — `Каталог сохраняет достоверность и границы демонстрации` + - **Verification:** Сверить available/unavailable/empty summary и длинное имя счёта; stocks gain/bonds loss/other/missing valuation позиции. Использовать реальные view без VM/API, MemoryRouter при необходимости и null logos. +- [x] 2.3 [frontend] Добавить stories RecentEvents и композиции PortfolioRefreshState с PortfolioTotals. + - **Covers:** `frontend-ui-catalog` — `Каталог предоставляет определённый набор реальных компонентов`; `frontend-ui-catalog` — `Примеры воспроизводят состояния и взаимодействия изолированно`; `frontend-ui-catalog` — `Каталог сохраняет достоверность и границы демонстрации` + - **Verification:** Сверить loaded/loading/error/empty/missing amount событий, idle/refetch/error сохранённых сумм, локальный retry и отсутствие исчезновения данных при обновлении; не заявлять выполнение query lifecycle. +- [x] 2.4 [frontend] Добавить stories StateView и реального AccountPageLoading, описания назначения и ограничений всех шести групп. + - **Covers:** `frontend-ui-catalog` — `Каталог предоставляет определённый набор реальных компонентов`; `frontend-ui-catalog` — `Примеры воспроизводят состояния и взаимодействия изолированно`; `frontend-ui-catalog` — `Каталог сохраняет достоверность и границы демонстрации` + - **Verification:** Проверить empty/error с действием и без него, реальную page-owned skeleton structure, alert/busy semantics, доступность и отсутствие обязательных Mantine primitive demos или wrappers ради каталога. +- [x] 2.5 [frontend] Проверить безопасные story props/callbacks и адаптировать dependency-cruiser к runtime graph Storybook без ослабления FSD. + - **Covers:** `frontend-ui-catalog` — `Каталог предоставляет определённый набор реальных компонентов`; `frontend-ui-catalog` — `Примеры воспроизводят состояния и взаимодействия изолированно`; `frontend-ui-catalog` — `Каталог сохраняет достоверность и границы демонстрации` + - **Verification:** На существующем test stack проверить реальные stories/их callbacks без application network и доступа к данным пользователя; controlled runtime API import должен отклоняться, type-only references допускаются. Не тестировать собственным кодом внутренности Storybook/Mantine. +- [x] 2.6 [frontend] Включить Storybook config и stories в TypeScript, lint, Knip, dependency checks и static build canonical verify. + - **Covers:** `N/A` — интеграция tooling в существующий frontend gate по Delivery Map без нового продуктового поведения. + - **Verification:** Проверить entry discovery и обе сборки; ограничить export exceptions требуемыми Storybook default meta/config exports и прямыми CSF exports историй. Declarative CSF/config не требуют искусственного unit coverage; production coverage floors и полный type/lint/dependency scope сохраняются. +- [x] 2.7 [frontend] Проверить Storybook dev и static build в браузере по таблице и UI/UX package revision 2. + - **Covers:** `frontend-ui-catalog` — `Каталог предоставляет определённый набор реальных компонентов`; `frontend-ui-catalog` — `Примеры воспроизводят состояния и взаимодействия изолированно`; `frontend-ui-catalog` — `Каталог сохраняет достоверность и границы демонстрации` + - **Verification:** Просмотреть все stories и Docs, Controls/reset/remount, actions и keyboard; проверить preview на 320/768/1280 CSS px без overflow и сохранение args при resize. Проверить отсутствие application API/external data requests, корректные локальные ссылки и эквивалентность dev/static preview. + +## 3. Обязательная граница перед процессной частью + +Группы 4 и процессная часть группы 5 недоступны до выполнения 3.1 и 3.2. +Если prerequisite не выполнен, зависимая работа остаётся заблокированной; +наличие checklist не разрешает изменение upstream artifacts или чужих state. + +- [x] 3.1 [workspace] Подтвердить фактическое завершение optimize-session-oriented-sdd-v2 и перечитать поставленные canonical authority, schema и session routing перед процессной реализацией. + - **Covers:** `N/A` — это orchestration зависимости из Migration Plan Design, а не реализация repository-owned поведения; без неё нельзя определить действующую baseline процессного расширения. + - **Verification:** Найти canonical archive и фактическое completion evidence зависимости с подтверждением поставки; native planning complete/isComplete и наличие planning files не считать завершением. При отсутствии подтверждения оставить процессную часть заблокированной и не менять dependency artifacts/state. +- [x] 3.2 [workspace] Сопоставить текущие Delta Specs и Design с поставленной authority зависимости, особенно два пересекающихся MODIFIED requirements, и определить допустимость продолжения. + - **Covers:** `N/A` — reconciliation проверяет совместимость уже утверждённого scope с baseline перед delivery, не создавая новое поведение или самостоятельный planning authority. + - **Verification:** Сопоставить `Продолжение workflow восстанавливает только нужный контекст` и `Validation остаётся независимой и без побочных исправлений` со всеми поставленными invariants/scenarios и проверить остальные затронутые rules. Не применять MODIFIED blocks как безусловную замену: изменение Requirement/Scenario возвращает к Delta Specs и reapproval зависимых Design/Tasks; изменение intent — к Proposal, архитектуры — к Design. До разрешения несовместимости процессная реализация закрыта; автоматический merge при archive не заменяет reconciliation. + +## 4. Расширение существующего процессного contract + +После успешного reconciliation использовать поставленных владельцев и их +approval/input binding. Не переносить заранее planned predecessor rules и +не дублировать его bounded outcomes, verification ownership или evidence model. + +- [x] 4.1 [specs] Расширить существующие Design template и instructions project-local schema применимостью UI/UX и составом единого переносимого визуального пакета. + - **Covers:** `openspec-authority-and-lifecycle` — `SDD-артефакты имеют непересекающиеся полномочия`; `openspec-authority-and-lifecycle` — `UI/UX-проработка Design соразмерна изменению`; `openspec-authority-and-lifecycle` — `Визуальный пакет Design имеет однозначную сохраняемую версию`; `agent-sdd-session-workflow` — `Продолжение workflow восстанавливает только нужный контекст` + - **Verification:** Получить native Design instructions из canonical store и проверить new/changed, reuse и обоснованный N/A, экраны/состояния/interactions/responsive scope, идентичность и отличия reuse, revision и перечень материалов. Для необходимых PNG/SVG exports проверить относительные пути внутри change `visuals/` и SHA-256, самодостаточность SVG; для встроенного Markdown не вводить self-hash, отдельный authority, роль или UI/UX approval. +- [x] 4.2 [specs] Расширить применимые native phase instructions существующей schema чтением согласованного Design package, feedback routing, semantic verification и сохранностью материалов при archive. + - **Covers:** `openspec-authority-and-lifecycle` — `Визуальный пакет Design имеет однозначную сохраняемую версию`; `openspec-authority-and-lifecycle` — `Соответствие визуальному Design входит в semantic verification`; `agent-sdd-session-workflow` — `Продолжение workflow восстанавливает только нужный контекст`; `agent-sdd-session-workflow` — `Validation остаётся независимой и без побочных исправлений` + - **Verification:** Проверить native context routing к Design и от него к перечисленным материалам, блокировку зависимой работы при missing/ambiguous package или digest mismatch, feedback для implementation mismatch и SPEC_ISSUE без редактирования пакета Validation; проверить инструкции сохранения относительной структуры и identity при archive. Использовать штатные файловые операции и SHA-256 без нового parser/registry или заявления, что native structural validation проверяет произвольные attachments и визуальное качество. +- [x] 4.3 [docs] Обновить governance и lifecycle фактически внедрённым единым UI/UX contract, правилами переносимости и применимости процесса к активным changes. + - **Covers:** `openspec-authority-and-lifecycle` — `SDD-артефакты имеют непересекающиеся полномочия`; `openspec-authority-and-lifecycle` — `UI/UX-проработка Design соразмерна изменению`; `openspec-authority-and-lifecycle` — `Визуальный пакет Design имеет однозначную сохраняемую версию`; `openspec-authority-and-lifecycle` — `Соответствие визуальному Design входит в semantic verification`; `openspec-authority-and-lifecycle` — `Внедрение UI/UX workflow сохраняет действующие approval boundaries` + - **Verification:** Сверить as-built policy с поставленной schema: approval всего Design, сохранённые переносимые материалы вместо external-only URL, cascade при смысловом изменении, независимый read-only review и проверка сохранности при archive. Проверить применение к новым changes и неутверждённому Design; уже утверждённый Design и changes в Implementation/Validation не получают автоматический retrofit/PASS, owner-requested migration возвращается к нужной boundary; legacy scope, чужие state и historical archives не переписываются. +- [x] 4.4 [workspace] Адаптировать локальные session skills/entrypoints как non-authority orchestration к поставленному contract визуального пакета. + - **Covers:** `N/A` — локальные adapters маршрутизируют чтение и verification versioned specs/docs authority; их адаптация предусмотрена Design и не подменяет repository-owned процессную реализацию или canonical gate. + - **Verification:** Проверить Specification, Implementation, Validation и archive routing: применимые материалы читаются через canonical Design, существующий approval/input binding охватывает перечисленные attachments без параллельной state model, handoff не копирует пакет, одна роль сессии сохраняется. Missing material/digest mismatch блокирует зависимую работу; visual mismatch даёт исправление реализации, противоречие пакета — возврат к самой ранней planning boundary; не мигрировать state чужих changes. +- [x] 4.5 [workspace] Проверить передачу, целостность и routing визуального пакета на временных невёрсионируемых примерах без изменения активных changes или archives. + - **Covers:** `N/A` — межобластная проверка обеспечивает согласованность schema, policy и локальных adapters по Design; она не реализует новое поведение и не заменяет их canonical gates. + - **Verification:** Проверить inline-only пакет, пакет с локальными exports, точный immutable reuse и обоснованный N/A; воспроизвести чтение из новой изолированной сессии и перенос структуры Design/visuals, сверить доступность и SHA-256 после переноса. Контролируемые missing file, изменённые bytes и external-only source должны приводить к конкретному блокеру; visual mismatch и противоречие Specs — к разным предусмотренным outcomes без side edits. Изменение revision/digest само по себе не подтверждает approval; существенная смена материала требует соответствующей boundary. Не объявлять эти проверки продуктовым пилотом или новым hard guardrail. + +## 5. As-built документация и готовность к последующему пилоту + +- [x] 5.1 [docs] Описать фактически доступные запуск и сборку каталога, начальный набор, общую визуальную основу, доступность, ограничения и сопровождение примеров; добавить применимые routing/index links. + - **Covers:** `frontend-ui-catalog` — `Каталог предоставляет определённый набор реальных компонентов`; `frontend-ui-catalog` — `Примеры воспроизводят состояния и взаимодействия изолированно`; `frontend-ui-catalog` — `Каталог сохраняет достоверность и границы демонстрации` + - **Verification:** После группы 2 сверить команды с поставленными frontend scripts и шесть групп Storybook с реальными view и их историями; явно описать, что отсутствие компонента не запрещает его использование, synthetic interactions не доказывают полный journey, а изменения включённых компонентов проверяются вместе с их примерами. Scoped review проверяет локальные ссылки и направление к действующему UI Pattern для query/refetch/loading semantics без копирования canonical planning artifacts. +- [x] 5.2 [docs] Описать совместное использование поставленных каталога и UI/UX workflow как готовность к отдельному небольшому UI change с собственными approvals. + - **Covers:** `openspec-authority-and-lifecycle` — `Готовность к пилоту отделена от доказанной успешности workflow` + - **Verification:** После групп 2–4 проверить доступный участнику путь от просмотра компонента к применимому Design package и отдельным planning approvals; текст не включает неявную продуктовую фичу, не назначает пилот без владельца и не заявляет сквозную успешность до фактического прохождения последующего change. + +## 6. Проверки завершённой реализации по affected areas + +Выполнять после соответствующей реализации и исправлений под Node 22, +активируя repository `.nvmrc` через `nvm use --silent`; если у specs нет +`.nvmrc`, выбрать Node через существующую frontend `.nvmrc` до перехода в specs. +Каждый canonical gate выполнить один раз на готовом состоянии; повторять +только после новых изменений, failure или нерешённой проблемы. Эта группа +планирует проверки и не утверждает их результаты или approval. + +- [x] 6.1 [frontend] Выполнить canonical frontend gate с каталогом, тестами и обеими сборками в его scope. + - **Covers:** `N/A` — gate подтверждает frontend Delivery Map после реализации каталога и не добавляет отдельное observable behavior. + - **Verification:** Из `frontend` после `nvm use --silent` выполнить `npm ci`, затем `npm run verify`; сохранить фактические команды, exit status и relevant diagnostics, не подменять gate отдельной успешной сборкой каталога. +- [x] 6.2 [specs] Выполнить native structural checks project-local schema, completed change и main specs из canonical store. + - **Covers:** `N/A` — обязательный specs gate проверяет форму versioned SDD delivery после reconciliation и процессного расширения; он не доказывает semantic соответствие или owner approval. + - **Verification:** Под выбранным Node 22 из `specs` выполнить `openspec schema validate wealth-ledger-sdd --verbose`, `openspec validate integrate-ui-ux-design-workflow --type change --strict --store wealth-ledger-specs` и `openspec validate --specs --strict --store wealth-ledger-specs`; сопоставить наблюдённые результаты с фактически поставленной authority, не синхронизировать пересекающиеся deltas в обход 3.2. +- [x] 6.3 [docs] Выполнить canonical docs gate для фактической документации каталога и процесса. + - **Covers:** `N/A` — docs gate подтверждает качество as-built delivery из групп 4–5; это verification существующего документационного результата, а не самостоятельное поведение. + - **Verification:** Из `docs` после `nvm use --silent` выполнить `npm ci`, затем `npm run verify`; дополнить результат scoped review локальных ссылок изменённых документов по docs AGENTS.md. +## 7. Независимая Validation + +После implementation-owned Tasks отдельный read-only reviewer сопоставляет все +Delta Requirements/Scenarios с реализацией, UI/UX package revision 2 и текущей +поставленной baseline. Проверка охватывает состояния, interactions, responsive +поведение, dependency reconciliation, сохранность пакета, approval boundaries +и границу готовности к пилоту. Актуальные gate outcomes используются с input +binding. Результат PASS/FAIL/SPEC_ISSUE не является implementation checkbox; +reviewer не меняет production code, specifications или Tasks. Critical/Important +finding, failed gate либо недоказанное соответствие блокируют завершение. +Backend и runtime-openapi остаются N/A по причинам Design. diff --git a/openspec/schemas/wealth-ledger-sdd/schema.yaml b/openspec/schemas/wealth-ledger-sdd/schema.yaml index f0ead9f..523aa09 100644 --- a/openspec/schemas/wealth-ledger-sdd/schema.yaml +++ b/openspec/schemas/wealth-ledger-sdd/schema.yaml @@ -1,5 +1,5 @@ name: wealth-ledger-sdd -version: 4 +version: 5 description: WealthLedger SDD workflow - proposal → specs → design → tasks → apply artifacts: - id: proposal @@ -114,6 +114,22 @@ artifacts: migration, public contract или другого труднообратимого решения; иначе `N/A` с конкретным Reason. + UI/UX Package: + - Определи применимость `new/changed`, `reuse` или `N/A` с конкретной + причиной. Для применимого scope покажи экраны, состояния, interactions + и responsive поведение; для reuse назови точную immutable версию, + используемую часть и отличия. Неизменяемой области не нужен новый макет. + Immutable reuse locator содержит store ID и путь от OpenSpec root, + чтобы archive вызывающего change не менял разрешение источника. + - Пакет входит в единый Design approval: revision, inline Markdown и + перечень необходимых локальных PNG/SVG в `visuals/` этого change с + относительным path, назначением и SHA-256 каждого файла. SVG должен быть + самодостаточным, без scripts, handlers, external fonts/assets. Для + inline Design self-hash не вводится; external-only URL не заменяет пакет. + - Сохраняй применимые материалы и exact archived reuse доступными без + временного чата или внешнего аккаунта. General package/approval rules + задаёт canonical governance, input binding — context authority. + Solution Assessment: Включи section внутри Design, если change вводит или существенно заменяет auth, security, storage, external integration, observability, caching, @@ -161,6 +177,14 @@ artifacts: - После записи используй native OpenSpec validation с `--store wealth-ledger-specs`. + Design Input: + - Прочитай применимый UI/UX пакет согласованной revision из Design, + включая перечисленные материалы; отсутствие или неоднозначность пакета + блокирует зависимую decomposition до восстановления или Design boundary. + - Планируй implementation-owned проверки состояний, interactions и + responsive scope. Независимую Validation не превращай в checkbox, + который может закрыть только reviewer. + Testing: Автоматические tests обязательны для security/privacy, денежных расчётов, data integrity/migration, concurrency, public contracts, critical journeys @@ -200,6 +224,15 @@ apply: - При recovery соблюдай artifact approval binding и повторно используй актуальные результаты checks по canonical context authority; state или planning completeness сами по себе approval не подтверждают. + - Из canonical Design прочитай применимый визуальный пакет: revision, + перечисленные материалы и exact immutable reuse. Проверь доступность, + SHA-256 и согласованный input binding до зависимой работы; missing file, + ambiguous package, digest mismatch или external-only source дают blocker, + а не разрешение восстановить решение по догадке. + - Следуй согласованным экранам, состояниям, interactions и responsive scope. + Несоответствие реализации исправляй в Implementation; изменение самого + решения возвращай к самой ранней затронутой planning boundary. Передача + и archive package следуют canonical lifecycle без копии пакета в handoff. - Feedback routing: intent/scope → Proposal; observable behavior → Delta Specs; architecture/rollback → Design; decomposition/ownership/coverage → Tasks. Останови downstream work, сообщи evidence и инвалидируй approvals от diff --git a/openspec/schemas/wealth-ledger-sdd/templates/design.md b/openspec/schemas/wealth-ledger-sdd/templates/design.md index 060d199..5e0deef 100644 --- a/openspec/schemas/wealth-ledger-sdd/templates/design.md +++ b/openspec/schemas/wealth-ledger-sdd/templates/design.md @@ -14,6 +14,39 @@ +## UI/UX Applicability and Package + + + +**Applicability and scope:** + +**Package revision:** + + + +**Screens, states and interactions:** + +**Responsive behavior:** + +**Reused source and differences:** + + + +| Material ID | Relative path | Screen/state and purpose | SHA-256 | +| --- | --- | --- | --- | +| | | | | + + + ## Delivery Map | Area | Status | Architectural outcome or N/A reason |