Document portable UI design packages and Storybook workflow

2026-09-07 22:48:16 +03:00
parent 024e240303
commit ac6c1ecc60
6 changed files with 97 additions and 9 deletions
@@ -11,7 +11,8 @@
 - [Audit remediation registry](audit-remediation.md) — статусы findings, следующий
  OpenSpec change и ссылки на canonical archived Completion Evidence.
 - [Engineering governance](engineering-governance.md) — SDD roles и approvals,
-  Delivery Map, независимая Validation, completion safeguards и risk-based testing.
+  единый UI/UX-пакет Design, 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 для
@@ -21,7 +21,7 @@ repositories. Прочитайте их local `AGENTS.md` для boundaries и c

 | Trigger | Context |
 | --- | --- |
-| Planning или Implementation | Native instruction и каждый возвращённый context file |
+| Planning или Implementation | Native instruction и каждый возвращённый context file; применимые материалы через canonical Design |
 | Approval, роль, testing, Delivery Map или completion | Релевантный раздел governance |
 | Cross-area architecture | `architecture/system-overview.md`, нужные ADR/feature docs |
 | Domain или API semantics | Термин в `architecture/domain-glossary.md`, canonical contract/spec |
@@ -78,7 +78,12 @@ Fingerprint имеет вид `sha256:<64 lowercase hex digits>` и связыв
 и config files. Unrelated concurrent change исключается по объяснённой границе,
 а не потому, что мешает получить прежний fingerprint.

- Proposal, Design и Tasks — соответствующий canonical файл. Delta Specs —
+- Proposal и Tasks — соответствующий canonical файл. Design — его Markdown
+  и все перечисленные применимые материалы, включая exact immutable reuse
+  inputs. Перечень разрешается из Design, без параллельного visual registry;
+  missing, ambiguous или изменённый материал блокирует dependent outcome по
+  [UI/UX policy](engineering-governance.md#uiux-пакет-design). Сам Design не
+  содержит собственного digest. Delta Specs —
  полный разрешённый native CLI набор `specs/**/spec.md` этого change; при
  сравнении membership запрашивается заново, чтобы обнаружить additions/removals.
 - PASS включает raw approved planning artifacts, relevant main baseline,
@@ -107,6 +107,55 @@ bounded reads, fingerprint bindings, handoff, evidence reuse и batching.
 commands и session adapters необязательны. Числовые token budgets и telemetry
 не являются условием delivery.

+## UI/UX-пакет Design
+
+UI/UX относится к существующему canonical Design и его единому approval.
+Design определяет applicability: `new/changed`, `reuse` либо `N/A` с конкретной
+причиной. Применимый scope описывает затронутые экраны, состояния, взаимодействия
+и responsive behavior; reuse указывает точную версию решения, используемую часть
+и отличия. Неизменяемая область и обоснованный N/A не требуют нового макета.
+
+Основное переносимое представление — Markdown в Design. Необходимые PNG/SVG
+exports хранятся в `visuals/` того же canonical change. Design фиксирует revision
+пакета и для каждого материала — identity, относительный путь, назначение
+(экран/состояние) и SHA-256 raw bytes отдельного файла. Встроенный Markdown
+входит в обычный Design fingerprint без собственного self-referential hash.
+SVG самодостаточен: без scripts, исполняемых handlers и внешних fonts/assets.
+
+Внешний editor, preview или текущая Storybook-витрина может быть reference;
+согласованный результат доступен из canonical пакета без внешнего runtime,
+аккаунта или изменяемого URL. Reuse из другого change указывает точный immutable
+архивный пакет и применимые материалы, а не `latest`. При переносе вызывающего
+change reuse source сохраняет store ID и путь от canonical OpenSpec root;
+пути материалов остаются относительными к исходному пакету. Пакет доступен
+после archive вместе с Design; относительная структура и identities
+материалов сохраняются.
+
+Approval относится ко всему представленному Design package. Его revision
+и digest обнаруживают изменения, но сами не подтверждают решение владельца.
+Существующие approval и PASS bindings включают перечисленные attachments
+и reuse inputs по [context authority](agent-token-efficiency.md#fingerprints).
+Смысловая замена материала или правила возвращается к Design; затронутые
+requirements — к Delta Specs, intent — к Proposal с обычным cascade approvals.
+
+Missing material, digest mismatch, неоднозначный пакет и external-only source
+блокируют зависимую работу до восстановления точных согласованных bytes либо
+решения на ответственной planning boundary. Восстановление не разрешает
+дорисовывать отсутствующее решение по памяти. Validation остаётся read-only:
+расхождение реализации с однозначным пакетом даёт `FAIL`, противоречие или
+неоднозначность planning — `SPEC_ISSUE`. Reviewer сопоставляет экраны, состояния,
+interactions и responsive behavior. Structural success, screenshots и наличие
+Storybook не означают semantic PASS; отдельный visual checker или approval
+engine не вводится.
+
+Правило применяется к новым changes и ещё не утверждённому Design. Уже approved
+Design и changes в Implementation/Validation сохраняют согласованный scope:
+owner-requested migration проходит нужную planning boundary без автоматического
+retrofit, reapproval или нового PASS. Historical archives и чужие state не
+переписываются. Доступность каталога и процесса даёт готовность к отдельному
+пилоту; его успешность подтверждает только фактически пройденный небольшой
+UI change, выбранный владельцем и получивший собственные planning approvals.
+
 ## Delivery Map и multi-repository delivery

 Design каждого change оценивает все четыре области:
@@ -20,6 +20,11 @@ Storybook. Он работает без backend. Coverage
 работа с Docs, Controls и Actions, доступность и ограничения описаны в
 [UI-каталоге Storybook](ui-catalog.md).

+Для UI change используйте каталог как reference существующего решения, затем
+зафиксируйте применимый [пакет Design](engineering-governance.md#uiux-пакет-design)
+в canonical OpenSpec. Storybook показывает реализацию и не заменяет согласованную
+версию Design или независимую проверку соответствия.
+
 Backend остаётся источником OpenAPI. После изменения опубликованного
 backend-контракта разработчик обновляет в `frontend/` committed snapshot
 `src/shared/api/spec/openapi.json` копированием backend OpenAPI document, затем
@@ -42,6 +42,13 @@ instructions, выполните доступную native structural прове
 Design и Delta Specs для exact `Covers`; второй context mapping не нужен.
 Approval и bounded progression соблюдают governance policy.

+Для Design определите
+[UI/UX applicability и пакет](engineering-governance.md#uiux-пакет-design).
+Прочитайте его применимые материалы, проверьте сохранённые пути, revision,
+доступность и SHA-256 exports обычными файловыми операциями. Представьте весь
+пакет в одном Design approval; native structural validation не проверяет
+произвольные attachments или качество визуального решения автоматически.
+
 Новые changes используют project-local schema `wealth-ledger-sdd` из
 `specs/openspec/schemas/wealth-ledger-sdd` и граф
 `proposal → specs → design → tasks → apply`. `config.yaml` хранит default schema
@@ -73,6 +80,10 @@ outcome. Remaining implementation work даёт checkpoint; вся заверш
 [approval binding](agent-token-efficiency.md#fingerprints), а semantic issue
 возвращается к ответственной planning boundary.

+При применимом UI/UX scope восстановите именно согласованный пакет из Design
+до зависимой реализации. Missing material, digest mismatch и external-only
+reference не компенсируются историей чата или текущим внешним макетом.
+
 Validation читает approved planning artifacts и implementation scope, проверяет
 свежесть сохранённых gate outcomes и выполняет отсутствующие affected gates.
 Глобальный gate нельзя считать проверенным по более узкому fingerprint: binding
@@ -92,6 +103,12 @@ scenarios и применимыми edge cases; фиксирует `PASS`, `FAIL
 требуется: observed verdict и binding передаются в текущем handoff и затем
 в canonical Completion Evidence.

+Для UI/UX reviewer читает пакет той же revision и сопоставляет применимые
+экраны, состояния, взаимодействия и responsive behavior. Однозначное отклонение
+реализации — `FAIL`; противоречие либо неоднозначность пакета — `SPEC_ISSUE`.
+Review не исправляет интерфейс или Design package и не подменяется наличием
+stories, screenshots или успешной сборкой.
+
 ## Semantic sync перед archive

 Перед terminal mutation сверяйте все deltas с текущей main baseline. Native
@@ -157,7 +174,10 @@ validation main specs. Он не даёт terminal status и не расширя
   `--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
+   diff sync/move. Для применимого Design package проверьте сохранение
+   относительной структуры Design/visuals, доступность каждого материала,
+   совпадение SHA-256 и exact immutable reuse references после переноса.
+   Утрата или замена материала блокирует завершение. Изменённые archive/main-spec outputs проходят native strict
   проверку; это проверка новых completion outputs, не повторная Validation
   неизменившейся реализации. Зафиксируйте разрешённые archive/sync/evidence
   изменения и сообщите созданный commit ID отдельно от evidence, чтобы избежать
@@ -91,9 +91,17 @@ Declarative stories не требуют искусственного unit covera
 coverage floors сохраняются. Клавиатура, реальные размеры и визуальное
 соответствие проверяются в браузере; автоматической visual regression нет.

-Каталог доступен независимо от процессного расширения UI/UX. Новый contract
-визуального пакета Design пока не поставлен: он ожидает завершения
-`optimize-session-oriented-sdd-v2` и сверки с его authority. Совместная готовность
-каталога и обновлённого процесса к пилоту ещё не подтверждена; продуктовый пилот
-не проводился. Действующий процесс описан в
+## Использование в UI change
+
+Каталог помогает выбрать существующий компонент, его состояние и ограничения.
+Затем в Design своего change зафиксируйте применимость UI/UX, выбранную
+конфигурацию, затронутые экраны, состояния, взаимодействия и адаптивное поведение.
+Ссылка на текущую story помогает исследовать реализацию; согласованную версию
+решения сохраняет [единый пакет Design](engineering-governance.md#uiux-пакет-design).
+Его материалы получает Implementation и независимый reviewer через
 [OpenSpec lifecycle](openspec-authority-and-lifecycle.md).
+
+Каталог и этот процесс доступны для совместного использования в отдельном
+небольшом UI change. Его выбирает владелец; он проходит собственные planning
+approvals. Это готовность к пилоту: продуктовая фича автоматически не назначена,
+сквозной продуктовый пилот не проводился и его успешность не заявляется.