specs/openspec/changes/archive/2026-08-26-simplify-verification-infrastructure/design.md

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.