specs/openspec/changes/archive/2026-08-23-make-local-verification-agent-safe/design.md

Context

Корень workspace — coordination directory, а не package-manager workspace и не Git-репозиторий. frontend, backend, specs и docs — независимые Git roots. specs/scripts/verify-openspec-authority.sh уже показывает правильное место для versioned cross-repository tooling: script определяет workspace относительно себя, а не доверяет текущей директории.

Frontend закрепляет Node 22 и имеет offline npm run verify. Для backend нет эквивалентных runtime policy и отдельных quality gates: lint запускает ESLint с --fix, base tsconfig включает тесты, а build tsconfig исключает их. Существующие e2e tests создают in-memory Nest application, но их script сначала запускает Prisma на фиксированной /tmp DB и сейчас падает до Jest. Swagger доступен по /api/docs-json при NODE_ENV=development; frontend/scripts/openapi:sync.mjs — единственный намеренный writer committed snapshot и generated types.

Goals / Non-Goals

Цели:

• Восстановить исполнимые backend gates для lint и TypeScript приложения и тестов с понятной диагностикой failures.
• Доказать отдельной read-only командой, что полный runtime OpenAPI document совпадает с committed frontend snapshot.
• Сделать Node/npm bootstrap и конкретные verification commands discoverable для агентов.
• Сохранить pre-existing working-tree state пользователя; не создавать versioned writes во время проверок.

Не входит в scope:

• CI/CD, remote verification, Docker, новый task runner, package-manager workspace или общий workspace verifier.
• Изоляция backend e2e DB, обновление Prisma packages и восстановление migration gate: WL-P2-05 и зависимый WL-P2-13 отложены из-за нестабильности Prisma 7.9.1 на Node 22.
• JSON report format, cached results, plug-in architecture, arbitrary diff bases, сохранённые hashes либо fixture/unit-test harness для process scripts.
• Изменение OpenAPI sync writer, generated frontend types, пользовательских API statuses, T-Bank integration, application features, перенос business glossary CONTEXT.md или удаление существующего OpenSpec authority fixture test.

Decisions

Backend check и fix — разные операции

Backend предоставляет lint:check без --fix, lint:fix с явным write intent и сохраняет lint как совместимый alias для lint:check. Он предоставляет отдельные команды typecheck:app и typecheck:test на основе выделенных tsconfig files. Эти команды не создают repository artifacts; build и e2e не объявляются частью нового общего verdict.

Runtime OpenAPI сверяется отдельной read-only командой

specs/scripts/verify-runtime-openapi.sh определяет workspace из собственного пути, поднимает backend с детерминированным development environment, ждёт local readiness, получает /api/docs-json и всегда завершает child process. Команда рекурсивно упорядочивает JSON object keys, сохраняя array order, записывает canonical runtime и snapshot documents во временную директорию, сравнивает их SHA-256 и выводит unified diff при различии.

Она никогда не вызывает openapi:sync, не записывает frontend snapshot и не обновляет generated types. Это узкий контрактный gate, а не orchestration interface для всех репозиториев.

Bootstrap и документация задают один contract

Оба приложения требуют Node 22 и npm ci. Scoped AGENTS.md перечисляют только реально существующие non-mutating verification commands и явно отделяют писатели lint:fix и openapi:sync. Durable development documentation показывает prerequisites и границы отдельной runtime-contract команды.

Prisma findings явно отложены, а не маскируются обходом

prisma migrate deploy 7.9.1 воспроизводимо возвращает пустой schema-engine error как на фиксированной, так и на уникальной временной SQLite DB; включение engine diagnostics меняет результат. На 2026-08-23 опубликованная latest stable version также 7.9.1. Не вводится второй migration mechanism и не обновляются зависимости без подтверждённого stable candidate. Реестр фиксирует дату, причину и trigger review: следующая stable Prisma должна трижды применить existing migrations к чистой DB на Node 22.

Risks / Trade-offs

• [Runtime backend не стартует или child process остаётся после ошибки] → command создаёт cleanup trap до запуска backend и сохраняет фактический exit status.
• [Canonicalization скрывает различие контрактов] → нормализуется только порядок object keys; arrays и каждое JSON field остаются частью SHA-256 input.
• [Prisma schema engine остаётся недоступным на supported runtime] → WL-P2-05 и WL-P2-13 остаются deferred до опубликованной stable версии, прошедшей оговорённый reproduction gate.
• [Ignored artifacts путаются с versioned writes] → отдельные команды не считают build или e2e своим успехом и документируют свои временные ресурсы.

Migration Plan

Не нужны migration production data или deployment sequence. Разработчики запускают npm ci под Node 22 в каждом application repository, используют npm run lint:fix только осознанно и запускают runtime OpenAPI check отдельно из workspace. Rollback — обычный revert independently versioned changes; он не меняет committed API artifacts или persistent user data.