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