docs(specs): archive verification simplification change

2026-08-27 00:01:23 +03:00
parent b6c141f4f3
commit 15ce5b586d
4 changed files with 0 additions and 0 deletions
@@ -0,0 +1,10 @@
+schema: wealth-ledger-sdd
+created: 2026-08-26
+goal: Simplify verification infrastructure by removing redundant project-owned
+  wrappers while preserving native and risk-based checks.
+skip_specs: true
+affected_areas:
+  - frontend
+  - backend
+  - specs
+  - docs
@@ -0,0 +1,128 @@
+## Context
+
+Текущий workflow накладывает самописные planning, authority, version и workspace
+verifiers поверх native OpenSpec, а repository gates включают runtime preflight,
+hygiene-скрипты, meta-tests конфигурации и exact bundle baseline. Workspace
+script повторно запускает уже завершённые local gates. Runtime OpenAPI shell
+script вручную компилирует и поднимает приложение, хотя проверяемый риск —
+согласованность публичного contract — естественно принадлежит integration test.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Оставить короткие local gates, где каждая проверка владеет самостоятельным
+  инженерным инвариантом.
+- Использовать native OpenSpec validation для структуры SDD и стандартные
+  project tools для source, dependency и build quality.
+- Сохранить проверку runtime OpenAPI contract через backend integration boundary.
+- Исключить повторный запуск full repository gates через workspace dispatcher.
+
+**Non-Goals:**
+
+- Не менять application behavior, API document или persisted data.
+- Не вводить CI, монорепозиторий, workspace package manager, новую dependency
+  или новый threshold качества.
+- Не переписывать historical archives и Completion Evidence, которые описывают
+  фактические прежние команды.
+
+## Decisions
+
+### Native tools own structural and repository validation
+
+Удаляются project-owned OpenSpec planning, authority и version scripts, их
+fixtures и references. Native OpenSpec commands с explicit canonical store
+становятся единственным structural validation; lifecycle approval, semantic
+verification, completed tasks и independent review остаются человеческими
+archive conditions, а не получают новую автоматическую обёртку.
+
+Каждый affected repository сохраняет один local `verify` entrypoint, но он
+состоит только из непосредственно полезных инструментов: TypeScript,
+Biome/ESLint, Vitest/Jest, Knip, dependency-cruiser и build. `engines` и
+`.nvmrc` остаются декларацией Node 22; отдельная runtime-проверка не входит в
+pipeline. Repository hygiene scripts удаляются: version-control policy остаётся
+в `.gitignore`, а scoped diff review обнаруживает material workspace artifacts.
+
+### Contract verification moves to a Jest integration test
+
+`verify-runtime-openapi.sh` удаляется. Backend получает focused Jest contract
+test, который строит configured Nest application на той же boundary, извлекает
+runtime OpenAPI document и сопоставляет его с committed frontend snapshot после
+детерминированной canonicalization. Такой test запускается только как required
+contract gate change, затрагивающего обе стороны API contract; он не добавляется
+к каждому несвязанному backend verification run.
+
+Frontend сохраняет проверку generated types against committed snapshot. Это
+разделяет две разные гарантии: frontend snapshot согласован с generated client,
+а snapshot согласован с backend runtime contract.
+
+### Keep bounded bundle and dependency checks; remove meta-verification
+
+Dependency-cruiser продолжает проверять actual source graph. Его fixture tests
+удаляются, потому что тестируют configuration tool, а не source boundary.
+Bundle check сохраняет фиксированный maximum initial payload, но удаляет exact
+per-route baseline, baseline update command и тесты собственного measurement
+script. Fixed ceiling защищает понятный user-facing limit; exact historical
+sizes создают churn без самостоятельного performance contract.
+
+### Completion is explicit rather than dispatched
+
+`verify-workspace-change.sh` удаляется. Tasks каждого change перечисляют
+affected repository gates, а contract gate указывается только если Design
+делает его required. Перед завершением gates выполняются по одному разу в
+affected areas; semantic comparison с approved artifacts и independent review
+фиксируются отдельно. Documentation, AGENTS, schema instructions and agent
+entrypoints описывают эту прямую последовательность без shell dispatcher.
+
+## Delivery Map
+
+| Area | Status | Architectural outcome or N/A reason |
+| --- | --- | --- |
+| frontend | `affected` | Упрощённый local gate без runtime/hygiene wrappers, meta-tests dependency configuration и exact lazy-route baseline; сохранены quality tools и initial payload ceiling. |
+| backend | `affected` | Упрощённый local gate и focused Jest OpenAPI contract integration boundary вместо workspace shell script. |
+| specs | `affected` | Native OpenSpec lifecycle и explicit per-area completion заменяют project-owned verifiers and dispatcher. |
+| docs | `affected` | As-built workflow, repository entrypoints and verification strategy отражают итоговые direct gates. |
+
+### Contract Gate Decision
+
+| Gate | Status | Reason |
+| --- | --- | --- |
+| runtime-openapi | `N/A` | Change переносит способ проверки, но не изменяет frontend и backend стороны публичного API contract; новый Jest test сохраняет contract gate для будущих API changes. |
+
+## Solution Assessment
+
+| Option | Fit | Maintenance and migration cost | Decision |
+| --- | --- | --- | --- |
+| Retain project-owned wrappers and fixtures | Preserves current checks but repeats native and local work. | High ongoing cost and duplicated failure surface. | Rejected. |
+| Native OpenSpec plus direct repository tools | Covers structural validation and source-quality invariants with maintained tools already installed. | Low; documentation and task routing change once. | Chosen. |
+| New workflow runner or CI framework | Could centralize orchestration, but adds a platform not required by the stated risk. | High adoption and operating cost. | Rejected. |
+
+The existing Jest/Nest testing stack is the mature compatible mechanism for the
+runtime contract assertion, so no custom process runner or dependency is added.
+
+## Risks / Trade-offs
+
+- Removing every-run hygiene scans means an explicitly force-added ignored
+  artifact is caught by repository review rather than the full verification
+  pipeline; `.gitignore` remains the normal prevention boundary.
+- The OpenAPI test intentionally remains an opt-in contract gate, avoiding an
+  integration startup for changes that cannot alter the API.
+- Fixed bundle ceiling detects material initial-load regression but no longer
+  blocks harmless byte-level movement among lazy routes.
+
+## Migration Plan
+
+1. Replace project-owned wrappers and their references with direct native or
+   repository-owned checks.
+2. Move the runtime OpenAPI assertion to the backend Jest integration boundary
+   and remove the shell implementation.
+3. Simplify package entrypoints while retaining each selected base tool.
+4. Update as-built guidance and agent routing, then verify each affected area
+   once without the removed dispatcher.
+
+### Rollback Contract
+
+| Field | Decision |
+| --- | --- |
+| Status | `N/A` |
+| Reason | Tooling-only change has no data, auth, security behavior, public API or other difficult-to-reverse runtime decision; reverting affected repository commits restores the previous local workflow. |
@@ -0,0 +1,35 @@
+## Why
+
+Проверки change и репозиториев дополнительно проходят через самописные
+обёртки, мета-проверки и точные baseline-сравнения. Они дублируют возможности
+поддерживаемых инструментов, повторяют tool calls и усложняют обязательный
+workflow без защиты самостоятельного продуктового риска.
+
+## What Changes
+
+- Упростить verification infrastructure, оставив только проверки, которые
+  непосредственно подтверждают наблюдаемые инженерные инварианты.
+- Установить единый итоговый подход: TypeScript, Biome/ESLint, Vitest/Jest,
+  Knip, dependency-cruiser, build и native OpenSpec validation — как основные
+  автоматические доказательства; contract и semantic review остаются
+  соразмерными риску change.
+- Исключить самописные verification и meta-verification механизмы, когда они
+  лишь оркестрируют, повторяют или тестируют уже применяемые инструменты.
+- Не ослаблять проверку типов, стиля, риск-ориентированных тестов,
+  архитектурных границ, сборки, публичного API contract или проверяемых
+  repository hygiene-инвариантов.
+- Не менять application behavior, API или данные и не вводить CI, новые
+  зависимости либо новые quality thresholds.
+
+## Capabilities
+
+### New Capabilities
+
+### Modified Capabilities
+
+## Impact
+
+Затронуты локальные verification workflows frontend, backend, specs и docs,
+OpenSpec agent entrypoints и as-built process documentation. Разработчики и
+агенты получат более короткий, прозрачный набор команд; существующие базовые
+quality и contract checks сохранятся в итоговой стратегии.
@@ -0,0 +1,23 @@
+## 1. Заменить избыточное владение verification
+
+- [x] 1.1 [specs] Удалить project-owned OpenSpec scripts для planning, authority, version и workspace verification вместе с fixtures; обновить schema, store routing и agent entrypoints для native OpenSpec validation и явного завершения по областям.
+  - **Covers:** `N/A` — Proposal не содержит поведения на уровне Specs; задача реализует утверждённое в Design решение о владении tooling.
+  - **Verification:** Выполнить native strict validation change и main specs из canonical store.
+- [x] 1.2 [backend] Заменить shell verifier runtime OpenAPI на focused Jest integration contract test с явным entrypoint; упростить backend verification pipeline и удалить runtime/hygiene wrappers.
+  - **Covers:** `N/A` — Публичный API не меняется; задача переносит существующую verification boundary по утверждённому Design.
+  - **Verification:** Выполнить focused Jest contract test и один раз `npm run verify` в `backend`.
+- [x] 1.3 [frontend] Упростить frontend verification pipeline, сохранив OpenAPI generated-type, TypeScript, Biome, Vitest, Knip, dependency-cruiser, build и initial-payload checks, но удалив избыточные wrappers, meta-tests и exact lazy-route baseline behavior.
+  - **Covers:** `N/A` — Наблюдаемое frontend behavior не меняется; это утверждённое упрощение local gate.
+  - **Verification:** Выполнить один раз `npm run verify` в `frontend`.
+
+## 2. Согласовать поставленный workflow и completion evidence
+
+- [x] 2.1 [docs] Обновить as-built verification strategy, repository workflow documentation и local entrypoints для прямых native и repository gates; сохранить historical evidence как исторический факт.
+  - **Covers:** `N/A` — Documentation отражает поставленный tooling workflow и не определяет product behavior.
+  - **Verification:** Выполнить один раз `npm run verify` в `docs` и проверить scoped local links.
+- [x] 2.2 [specs] Обновить canonical SDD guidance и change lifecycle references так, чтобы archive требовал native validation, approved artifacts, semantic verification и independent review без удалённого dispatcher.
+  - **Covers:** `N/A` — Задача согласует versioned process authority с утверждённым Design; Delta Requirement отсутствует.
+  - **Verification:** Выполнить native strict change validation и strict main-spec validation из `specs`.
+- [x] 2.3 [workspace] До archive по одному разу выполнить gates affected repositories, новый focused OpenAPI contract test, semantic verification against approved artifacts и independent read-only review.
+  - **Covers:** `N/A` — Workspace владеет только cross-repository completion orchestration, заданной утверждённым Design.
+  - **Verification:** Зафиксировать один full gate на affected repository, contract test, semantic verification и review outcome без `verify-workspace-change.sh`.