129 lines
8.1 KiB
Markdown
129 lines
8.1 KiB
Markdown
## 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. |
|