diff --git a/development/README.md b/development/README.md index b69d198..6b2d2bc 100644 --- a/development/README.md +++ b/development/README.md @@ -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 для diff --git a/development/agent-token-efficiency.md b/development/agent-token-efficiency.md index 58c9c7d..bf8c755 100644 --- a/development/agent-token-efficiency.md +++ b/development/agent-token-efficiency.md @@ -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, diff --git a/development/engineering-governance.md b/development/engineering-governance.md index fcbb9ec..74e3142 100644 --- a/development/engineering-governance.md +++ b/development/engineering-governance.md @@ -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 оценивает все четыре области: diff --git a/development/frontend-workflow.md b/development/frontend-workflow.md index 59e710b..c0d2eca 100644 --- a/development/frontend-workflow.md +++ b/development/frontend-workflow.md @@ -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, затем diff --git a/development/openspec-authority-and-lifecycle.md b/development/openspec-authority-and-lifecycle.md index a02e53a..9be4898 100644 --- a/development/openspec-authority-and-lifecycle.md +++ b/development/openspec-authority-and-lifecycle.md @@ -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, чтобы избежать diff --git a/development/ui-catalog.md b/development/ui-catalog.md index 80e55b7..9d5ca0f 100644 --- a/development/ui-catalog.md +++ b/development/ui-catalog.md @@ -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. Это готовность к пилоту: продуктовая фича автоматически не назначена, +сквозной продуктовый пилот не проводился и его успешность не заявляется.