diff --git a/AGENTS.md b/AGENTS.md index 99785a6..6c7a6b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. diff --git a/development/README.md b/development/README.md index 9f0c12c..b69d198 100644 --- a/development/README.md +++ b/development/README.md @@ -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 и его границы. diff --git a/development/agent-token-efficiency.md b/development/agent-token-efficiency.md index 86c95c9..58c9c7d 100644 --- a/development/agent-token-efficiency.md +++ b/development/agent-token-efficiency.md @@ -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: -Approved through: -Current phase: -Affected areas: -Unresolved blockers: -Next allowed 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//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 отдельно. diff --git a/development/audit-remediation.md b/development/audit-remediation.md index ba5dfca..1053a2c 100644 --- a/development/audit-remediation.md +++ b/development/audit-remediation.md @@ -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. diff --git a/development/engineering-governance.md b/development/engineering-governance.md index b00bbb1..fcbb9ec 100644 --- a/development/engineering-governance.md +++ b/development/engineering-governance.md @@ -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//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 и ссылки остаются +историческими и не переносятся задним числом. diff --git a/development/frontend-workflow.md b/development/frontend-workflow.md index b85c77a..59e710b 100644 --- a/development/frontend-workflow.md +++ b/development/frontend-workflow.md @@ -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, затем diff --git a/development/openspec-authority-and-lifecycle.md b/development/openspec-authority-and-lifecycle.md index 9949dfd..a02e53a 100644 --- a/development/openspec-authority-and-lifecycle.md +++ b/development/openspec-authority-and-lifecycle.md @@ -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 --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 --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 --change --json --store wealth-ledger-specs +``` -Structural validation выполняется native OpenSpec CLI с -`--store wealth-ledger-specs` и не означает approval. +`` — `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 --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 --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 --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 --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. diff --git a/development/ui-catalog.md b/development/ui-catalog.md new file mode 100644 index 0000000..80e55b7 --- /dev/null +++ b/development/ui-catalog.md @@ -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).