chore: use native OpenSpec validation
This commit is contained in:
@@ -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`.
|
||||
- [ ] 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`.
|
||||
Reference in New Issue
Block a user