Document portable SDD workflow and Storybook catalog

2026-09-07 22:22:13 +03:00
parent 8721e93849
commit 024e240303
8 changed files with 510 additions and 197 deletions
@@ -6,11 +6,17 @@
 policy, common reading pointers, audit routing и `../references/**` policy
 задаёт root `AGENTS.md`.

-Canonical SDD authority находится в `wealth-ledger-specs`, физически в
-`../specs/openspec` от этого репозитория. Любая OpenSpec command, читающая или
-изменяющая change, должна использовать `--store wealth-ledger-specs`.
+Для SDD roles, approvals и ownership читайте
+[governance](development/engineering-governance.md); native planning и completion
+в 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

@@ -28,7 +34,9 @@ Gate non-mutating запускает committed Markdown rules и `git diff --che

 ## Boundaries

- `architecture/` — текущее устройство, `features/` — поставленное поведение, `adr/` — устойчивые решения, `development/` — процесс и Completion Evidence, `audits/` — immutable snapshots.
+- `architecture/` — текущее устройство, `features/` — поставленное поведение,
+  `adr/` — устойчивые решения, `development/` — процесс и navigation к canonical
+  evidence, `audits/` — immutable snapshots. Legacy dated evidence не переписывается.
 - Indexes должны вести к новым документам.
 - Feature docs описывают фактический поток, API и ограничения, но не повторяют OpenSpec requirements/design/tasks.
 - Для диаграмм использовать Mermaid в Markdown. Не хранить application code, secrets или competing SDD artifacts.
@@ -4,10 +4,16 @@

 - [Frontend workflow](frontend-workflow.md) — Node 22, локальный запуск и
  frontend verification.
+- [UI-каталог Storybook](ui-catalog.md) — запуск, шесть групп реальных компонентов
+  и композиций, безопасные примеры и границы проверки интерфейса.
 - [Backend workflow](backend-workflow.md) — bootstrap backend, локальные
  non-mutating gates и границы e2e.
- [Audit remediation registry](audit-remediation.md) — текущий статус findings, следующий OpenSpec change и evidence завершённых улучшений.
- [Engineering governance](engineering-governance.md) — Change Owner, SDD approvals, Delivery Map, risk-based testing, build-versus-buy и hard guardrails.
- [OpenSpec authority и lifecycle](openspec-authority-and-lifecycle.md) — единственный SDD store, границы постоянной документации и условия archive.
- [Token-efficient agent workflow](agent-token-efficiency.md) — lazy context routing, session handoff, evidence batching и protocol активного pilot.
+- [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.
+- [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 и его границы.
@@ -1,81 +1,155 @@
 # Token-efficient agent workflow

-## Статус и границы
+## Authority и границы

-Эта инструкция описывает действующий guidance для сокращения повторной передачи
-agent context. Она не меняет SDD lifecycle, approvals, canonical gates, semantic
-verification или independent review и не является hard guardrail.
+Этот документ — vendor-neutral authority для context discipline: recovery,
+fingerprint bindings, bounded reads и observed evidence. Lifecycle ownership
+принадлежит [Engineering governance](engineering-governance.md), native команды
+— [OpenSpec lifecycle](openspec-authority-and-lifecycle.md). Эти процедуры
+выполняются без обязательных skills, session adapter, telemetry или service.

-Исходный baseline сохранён в
-[аудите Codex-сессий 26.08.2026](../audits/codex-sessions-token-audit-2026-08-26.md).
-Raw rollout logs не коммитятся. Числовой budget не блокирует delivery без
-отдельного утверждённого change, детерминированной non-mutating проверки и
-controlled positive/negative evidence.
-
-Guidance ниже остаётся non-blocking: он не заменяет required authority или
-verification и не повышается до hard guardrail без отдельного evidence-backed
-change.
+Исходный наблюдаемый baseline сохранён в
+[аудите сессий 26.08.2026](../audits/codex-sessions-token-audit-2026-08-26.md).
+Raw logs и числовые token budgets не становятся delivery gates. Экономия
+контекста не оправдывает пропуск relevant authority или ослабление verification.

 ## Routing context

-До чтения supporting documentation агент определяет:
+До supporting reads определите текущую роль, разрешённый outcome и affected
+repositories. Прочитайте их local `AGENTS.md` для boundaries и canonical gates,
+затем только применимую authority:

-1. тип работы и текущую SDD-фазу, если change versioned;
-2. affected repositories и их canonical gates;
-3. capability или source identity, нужные для следующего решения.
-
-После этого загружается только применимый context:
-
-| Trigger | Обязательный context |
+| Trigger | Context |
 | --- | --- |
-| Versioned SDD planning или Apply | Native OpenSpec instruction, возвращённые `contextFiles` и локальные `AGENTS.md` affected areas |
-| Engineering policy, approval, testing, delivery или archive | Релевантный раздел `engineering-governance.md` |
-| Cross-service flow или архитектурная граница | `architecture/system-overview.md` и применимые ADR/feature docs |
-| Domain или API semantics | Релевантный термин `architecture/domain-glossary.md` и canonical contract/spec |
-| Работа по известному Audit ID | Найденная через поиск запись и связанное evidence в `audit-remediation.md` |
-| Диагностика agent token usage или этот pilot | Этот playbook и применимый dated audit snapshot |
+| Planning или Implementation | Native instruction и каждый возвращённый context file |
+| 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 |
+| Известный Audit ID | Найденная запись `audit-remediation.md` и её source/evidence |
+| Validation | Approved artifacts, delivery inventory, relevant checks и findings |
+| Finalization | Текущий независимый verdict с binding и существующие delivery facts |

-Supporting material загружается on demand, если возникший вопрос меняет
-семантику, архитектуру, audit disposition или обязательный gate. Guidance нельзя
-использовать как основание пропустить необходимую authority.
+В новой роли canonical artifacts читаются заново только в необходимом scope.
+В том же context повторно читаются изменившиеся relevant inputs. История чата
+не заменяет artifact и не является обязательным prerequisite.

-## Handoff между agent-сессиями
+## Recovery и handoff

-Approved planning artifact, завершённый implementation slice или verification
-outcome являются естественной границей новой Codex task. Минимальный handoff:
+При наличии session adapter mutable state является единственным navigation
+pointer. Прочитайте только его текущий self-contained immutable record, затем
+phase-specific authority. Без adapter тот же актуальный envelope передаётся
+в доступном рабочем контексте; отдельный versioned verdict или planning store
+ради handoff не создаётся.

-```text
-Change: <identity>
-Approved through: <explicitly approved artifact>
-Current phase: <phase>
-Affected areas: <areas>
-Unresolved blockers: <none or list>
-Next allowed outcome: <one outcome>
-```
+Envelope содержит только change identity, текущую роль/outcome, affected areas,
+observed approval bindings, completed/remaining task IDs, краткие observed checks,
+blockers и один следующий допустимый outcome. Для продолжения после Validation
+он также сохраняет её verdict, relevant inventory и fingerprint; Finalization
+retry не должен требовать восстановления цепочки старых records. Requirements,
+Design, Tasks и acceptance scenarios остаются в canonical OpenSpec.

-Planning content не копируется: новая task читает его из canonical OpenSpec
-store. Если явный approval недоступен в новой task, агент повторно запрашивает
-его и не выводит решение владельца только из наличия artifact.
+Первичное `approved` записывается только после явного решения Change Owner,
+со ссылкой на наблюдённый источник решения, artifact identity и fingerprint.
+При recovery совпадение позволяет продолжить без повторного approval. Отсутствие
+binding, включая legacy state, требует явного решения; mismatch сбрасывает
+approval изменённого artifact и всех downstream artifacts. Approval status
+сохраняет наблюдение, но не доказывает личность или решение владельца сам по себе.

-Для handoff Apply → Verify дополнительно передаются фактический scope изменённых
-areas и unresolved failures. Полная история tool calls не передаётся.
+Порядок сохранения: `canonical outcome → immutable record → state pointer`.
+Сначала создаётся новый 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 batch заканчивается перед следующим смысловым решением:
-
- заранее независимые read-only lookups выполняются вместе;
- adaptive discovery, side effects и approval boundaries остаются
-  последовательными;
- discovery начинается с `rg` или другого identity search, затем читает
-  релевантный диапазон;
- diff сначала сужается через status/stat/name-only, затем раскрывает affected
-  paths;
- successful command result сохраняет exact command identity, exit status и
-  существенную summary;
- failure или неоднозначная summary расширяет diagnostics до достаточной причины;
- semantic verification и reviewer всегда получают полный relevant evidence.
-
-Статический лимит строк или tool tokens не применяется: он может скрыть
-единственный диагностический сигнал. Compact output — способ убрать заведомо
-нерелевантный шум, а не обрезать доказательства.
+Один batch заканчивается перед следующим смысловым решением. Независимые
+read-only inputs получают вместе; adaptive discovery, side effects и approvals
+остаются последовательными. Начните с `rg`/identity search или Git status/stat,
+затем раскройте relevant paths. Successful output сохраняет команду, exit status
+и существенный outcome; failure, semantic verification и review получают весь
+relevant evidence. Произвольный лимит строк не должен скрывать диагностический
+сигнал. Контекст оценивается вместе с качеством checks, findings и rework,
+а не по сокращению tokens отдельно.
@@ -14,10 +14,18 @@
  `confirmed` ещё может быть active, а `rejected` — accepted как проверенное
  решение ничего не внедрять.
 - Одновременно допускается не более одного `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 либо ссылки на явное решение владельца.
 - При смене статуса обновляется только этот реестр; 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

 - 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.
@@ -10,7 +10,10 @@

 **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.

@@ -35,40 +38,74 @@ Proposal → Delta Specs → Design → Tasks → Apply → Verify → Archive
  а `Verification` задаёт планируемую проверку. Tasks не содержат будущие
  результаты, 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 и сам
 исправляет технические ошибки формата. Полный change validation не объявляется
-успешным, пока downstream artifacts отсутствуют. Форматное исправление без
-изменения intent, behavior, decisions или task scope не требует reapproval;
-семантическое изменение возвращает workflow к самому раннему затронутому
-artifact.
+успешным, пока downstream artifacts отсутствуют. Несовпадение fingerprint
+утверждённого artifact сбрасывает его approval и downstream approvals;
+изменение возвращается к самой ранней затронутой planning boundary. Отметки
+выполнения Tasks не изменяют утверждённое содержание и нормализуются только
+для approval fingerprint.

 Изменение принятого 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,
-затем загружает canonical artifacts, локальные routing instructions и только
-применимую supporting authority. Полная история предыдущей agent-сессии и
-отдельный handoff artifact не являются prerequisite: после явного approval
-следующая фаза восстанавливается из canonical OpenSpec change и компактного
-handoff state. Если доступный context не подтверждает approval, решение Change
-Owner запрашивается повторно.
+Implementation выполняет связный batch approved Tasks и отмечает только
+фактически завершённую работу после релевантных checks. Если implementation-owned
+работа остаётся, нормальный outcome — `CHECKPOINT` с продолжением Implementation;
+это не blocker. `READY_FOR_VALIDATION` требует завершения всей такой работы и
+успеха её проверок. Проблема intent направляется к Proposal, observable behavior
+— к Delta Specs, архитектуры — к Design, декомпозиции — к Tasks.

-Независимые read-only evidence следует получать одним batch до следующего
-смыслового решения. Compact successful output сохраняет command identity, exit
-status и существенный outcome; failure, semantic verification и independent
-review получают достаточные diagnostics и полный relevant scope. Эти правила и
-числовые budgets являются guidance, пока отдельный утверждённый change не
-предоставит детерминированную non-mutating проверку и controlled evidence нового
-hard guardrail.
+Validation независимо проверяет affected gates, semantic и acceptance behavior,
+применимые edge cases и выполняет independent read-only review. Она не меняет
+production implementation, planning artifacts или Tasks. Эти проверки не
+остаются implementation checkboxes. Результат `PASS`, `FAIL` или `SPEC_ISSUE`
+привязан к проверенным planning/delivery inputs по
+[context authority](agent-token-efficiency.md#fingerprints).

-Эффективность оценивается на завершённую SDD-фазу вместе с gate outcomes, fix
-cycles, interrupted attempts и review findings. Меньший token usage при большем
-rework или худшем verification result не считается улучшением. Операционный
-routing, handoff envelope и pilot protocol находятся в lazy
-[Token-efficient agent workflow](agent-token-efficiency.md).
+| Результат / blocker | Ответственная следующая роль |
+| --- | --- |
+| Validation PASS на актуальных inputs | Finalization |
+| Implementation finding или unchecked implementation-owned Task | Implementation |
+| 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

@@ -135,13 +172,14 @@ contract либо другое существенно труднообратим

 | Вид знания | Authoritative location |
 | --- | --- |
-| Намерение, требования, Design, Tasks, changes и archives | `specs/openspec` |
+| Намерение, требования, Design, Tasks, changes, Completion Evidence и archives | `specs/openspec` |
 | Исполняемое поведение | `frontend` и `backend` code и risk-based tests |
 | Публичный API contract | backend runtime OpenAPI и committed frontend snapshot |
 | Текущее устройство и поставленные возможности | `docs/architecture` и `docs/features` |
 | Устойчивые архитектурные решения и причины | `docs/adr` |
-| Инженерная policy и completion evidence | `docs/development` |
-| Компактная маршрутизация AI-агентов и локальные entrypoints | root/repository-local `AGENTS.md` и workspace `.opencode` |
+| Инженерная policy и context discipline | `docs/development` |
+| Компактная маршрутизация и локальные 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.

@@ -160,12 +198,9 @@ CI пока отсутствует, поэтому обязательные gate

 Hard guardrail должен иметь исполняемую локальную проверку. Правило без надёжной проверки помечается как guidance и учитывается в review, но не выдаётся за автоматический запрет. Новые frameworks, checkers и thresholds добавляются только после оценки поддерживаемого решения, maintenance cost и реально защищаемого риска.

-Root `.opencode/commands` и `.opencode/skills` являются локальными
-non-authority entrypoints. Они должны соблюдать fixed store, one-artifact
-approvals и hard archive blockers, но не имеют отдельного versioned projection
-source.
-
-OpenSpec schema и changes валидируются native CLI с явным canonical store.
+Native команды и completion procedure описаны в
+[OpenSpec lifecycle](openspec-authority-and-lifecycle.md). Они не требуют
+optional runtime adapters.

 ## Verify, archive и Completion Evidence

@@ -173,8 +208,23 @@ Structural validation OpenSpec проверяет schema и форму арте

 1. успешные canonical gates всех affected areas;
 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;
-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 и ссылки остаются
+историческими и не переносятся задним числом.
@@ -3,15 +3,23 @@
 Frontend требует Node 22. В `frontend/` чистая установка и полный локальный quality gate выполняются так:

 ```bash
+nvm use --silent
 npm ci
 npm run verify
 ```

 `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; правила выбора тестов зафиксированы в
 [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-контракта разработчик обновляет в `frontend/` committed snapshot
 `src/shared/api/spec/openapi.json` копированием backend OpenAPI document, затем
@@ -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

- Canonical store: `wealth-ledger-specs`.
- Физический root: `specs/openspec` относительно workspace.
- Requirements, Delta Specs, Design, Tasks, changes и archives хранятся только в этом store.
- Команда, читающая или изменяющая change, всегда получает `--store wealth-ledger-specs`; cwd и nearest-root discovery не выбирают authority проекта.
- Versioned framework-specific planning artifacts вне `specs/openspec`, включая `superpowers/plans`, запрещены. `references/**` остаётся read-only исключением.
+Canonical store — `wealth-ledger-specs`, физический root — `specs/openspec`
+относительно workspace. Все команды, читающие или изменяющие change, получают
+`--store wealth-ledger-specs`; cwd и nearest-root discovery не выбирают authority.
+Planning artifacts, main specs, changes, Completion Evidence и archives
+принадлежат только этому store. `references/**` остаётся read-only; historical
+archives не переписываются.

-Native OpenSpec CLI валидирует schema, changes и main specs с явным store;
-historical archives не переписываются.
+## Native planning

-## Project-local schema
+Перед Node-командами выберите runtime через применимую `.nvmrc` командой
+`nvm use --silent`. Работая с change, сначала получите его фактическую структуру:

-Новые changes по умолчанию используют schema `wealth-ledger-sdd` version 3 из
-`specs/openspec/schemas/wealth-ledger-sdd`. Её граф:
-
-```text
-proposal → specs → design → tasks → apply
+```bash
+openspec status --change <change> --json --store wealth-ledger-specs
 ```

-OpenSpec обеспечивает structural order, а явное решение Change Owner — переход
-между артефактами. Agent создаёт один текущий artifact и останавливается для
-approval. Роли артефактов и cascade rules определены в governance policy;
-исполняемые templates и instructions принадлежат schema. Каждая instruction
-начинается компактным блоком `Critical Rules`; основной explanatory prose
-написан по-русски, а exact OpenSpec headings, tokens и normative keywords
-сохраняются на английском.
+Для нового согласованного change используется native
+`openspec new change <change> --store wealth-ledger-specs`. До создания Proposal
+Discovery разрешает неизвестные intent/scope вопросы. В Specification запрашивайте
+только разрешённый сейчас artifact:

-Delta Spec template является operation-neutral comment guide. Он перечисляет
-`ADDED`, `MODIFIED`, `REMOVED` и `RENAMED`, но не создаёт активную operation
-section. Автор добавляет только применимые sections и не оставляет пустых.
+```bash
+openspec instructions <artifact> --change <change> --json --store wealth-ledger-specs
+```

-Structural validation выполняется native OpenSpec CLI с
-`--store wealth-ledger-specs` и не означает approval.
+`<artifact>` — `proposal`, `specs`, `design` или `tasks`. Прочитайте все
+возвращённые 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
 openspec schema validate wealth-ledger-sdd --verbose
 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.
-Native instruction и возвращённые `contextFiles` задают planning context;
-repository-local `AGENTS.md` добавляет только routing и canonical gate своей
-area. Architecture, glossary, audit registry и подробный operational playbook
-загружаются по применимому trigger, а не blanket-набором перед любой задачей.
+После approval Tasks получите native Apply context:

-После явного approval planning artifact следующая фаза может начаться в новой
-Codex task. Handoff сохраняет change identity, последний approved artifact,
-current phase, affected areas, unresolved blockers и один следующий outcome.
-Содержание artifacts повторно не пересказывается и остаётся в canonical store.
-Если явный approval нельзя подтвердить из новой task, agent повторно запрашивает
-его до создания downstream artifact.
+```bash
+openspec instructions apply --change <change> --json --store wealth-ledger-specs
+```

-Apply → Verify использует ту же boundary, добавляя фактический implementation
-scope и unresolved failures без полной истории tool calls. Подробная форма
-handoff и evidence-batching guidance описаны в
-[Token-efficient agent workflow](agent-token-efficiency.md).
+Прочитайте каждый возвращённый `contextFiles` и local `AGENTS.md` affected
+repositories. Выберите связный batch pending Tasks, реализуйте его и выполните
+релевантные checks. Зафиксируйте завершённые canonical checkboxes и observed
+outcome. Remaining implementation work даёт checkpoint; вся завершённая работа
+— готовность к отдельной Validation. Изменение artifact проверяется по
+[approval binding](agent-token-efficiency.md#fingerprints), а semantic issue
+возвращается к ответственной planning boundary.

-## Agent entrypoints и обновление OpenSpec
-
-Root `.opencode/commands` и `.opencode/skills` — локальные non-authority
-entrypoints. Они удобны для работы агента, но не являются SDD source of truth и
-не имеют отдельного 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:
+Validation читает approved planning artifacts и implementation scope, проверяет
+свежесть сохранённых gate outcomes и выполняет отсутствующие affected gates.
+Глобальный gate нельзя считать проверенным по более узкому fingerprint: binding
+покрывает его relevant inputs. Specs gate использует native strict checks:

 ```bash
 openspec validate <change> --type change --strict --store wealth-ledger-specs
 openspec validate --specs --strict --store wealth-ledger-specs
 ```

-Structural success не доказывает соответствие реализации. Semantic verification
-сопоставляет реализацию с Proposal, Delta Specs, Design и Tasks, затем требуется
-independent read-only review без Critical и Important findings.
+Canonical gate остальных areas задан их `AGENTS.md`. Required
+`runtime-openapi` дополнительно вызывает backend `npm run test:openapi-contract`.
+Независимый 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.
@@ -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).