chore(specs): move clean-repo-enterprise spec from 020 to 023

2026-03-03 19:50:53 +03:00
parent da24fb9253
commit 19898b1570
10 changed files with 1549 additions and 0 deletions
--- a/specs/023-clean-repo-enterprise/plan.md
+++ b/specs/023-clean-repo-enterprise/plan.md
@@ -0,0 +1,170 @@
+# Implementation Plan: Clean Repository Enterprise Preparation
+
+**Branch**: `023-clean-repo-enterprise` | **Date**: 2026-03-03 | **Spec**: [`spec.md`](./spec.md)  
+**Input**: Feature specification from [`/specs/023-clean-repo-enterprise/spec.md`](./spec.md)
+
+## Summary
+
+Подготовить enterprise clean-профиль поставки, который:
+1) исключает тестовые/демо-данные из дистрибутива,  
+2) блокирует любые внешние интернет-источники ресурсов,  
+3) допускает загрузку ресурсов только с внутренних серверов компании,  
+4) предоставляет обязательную проверку compliance и аудитный отчёт перед выпуском.
+
+Ключевой UX фиксируется как интерактивный TUI сценарий на основе [`ux_reference.md`](./ux_reference.md): оператор в одном консольном интерфейсе запускает проверку, видит прогресс по этапам, нарушения и итоговый статус (`COMPLIANT`/`BLOCKED`).
+
+## Technical Context
+
+**Language/Version**: Python 3.9+ (backend scripts/services), Shell (release tooling)  
+**Primary Dependencies**: FastAPI stack (existing backend), ConfigManager, TaskManager, файловые утилиты, internal artifact registries  
+**Storage**: PostgreSQL (конфигурации/метаданные), filesystem (артефакты дистрибутива, отчёты проверки)  
+**Testing**: pytest (backend), contract checks для release compliance, smoke checks для TUI flow  
+**Target Platform**: Linux server в изолированной корпоративной сети  
+**Project Type**: web-service + operational CLI/TUI tooling  
+**Performance Goals**:  
+- стандартный запуск проверки clean/compliance ≤ 15 минут на типовой релиз-кандидат;  
+- формирование человекочитаемого отчёта сразу после завершения проверки.  
+**Constraints**:  
+- Полный запрет на внешние интернет-загрузки в enterprise clean-профиле;  
+- все ресурсы только с внутренних серверов компании;  
+- выпуск блокируется при любом нарушении data purity или source isolation.  
+**Scale/Scope**:  
+- 1 enterprise release flow;  
+- 1 TUI сценарий подготовки/проверки;  
+- 3–6 новых/обновлённых модулей проверки и отчётности;  
+- документация и контракты в пределах feature-папки.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- **I. Semantic Protocol Compliance**: PASS  
+  План предусматривает формальные контракты в [`contracts/modules.md`](./contracts/modules.md) с `[DEF]`/`@TAG` и закрывающими якорями.
+- **II. Modular Plugin Architecture**: PASS  
+  Логика будет интегрирована через существующие сервисы/плагины и централизованную конфигурацию через `ConfigManager`; hardcode-источники запрещаются политикой clean-profile.
+- **III. Unified Frontend Experience**: PASS (N/A for web UI changes)  
+  Для фичи primary UX — TUI (`ncurses`-совместимый). Изменений веб-компонентов, нарушающих правила `requestApi/fetchApi`, не планируется.
+- **IV. Security & RBAC**: PASS  
+  Проверка соответствия и выпускные действия остаются под существующей auth/RBAC моделью и аудитом.
+- **V. Independent Testability**: PASS  
+  В спецификации определены независимые пользовательские сценарии с отдельной проверяемостью.
+- **VI. Asynchronous Execution**: PASS  
+  Длительная проверка может быть оформлена как task-flow с отчётом; блокировок API на долгих операциях не планируется.
+
+**Gate Result (pre-research)**: PASS
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/023-clean-repo-enterprise/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│   ├── modules.md
+│   └── api.yaml
+└── tasks.md
+```
+
+### Source Code (repository root)
+
+```text
+backend/
+├── src/
+│   ├── api/
+│   ├── core/
+│   ├── services/
+│   └── scripts/
+└── tests/
+
+frontend/
+└── src/  # Без изменений в рамках этой фичи (primary UX = TUI script)
+```
+
+**Structure Decision**: Выбрана структура web application с упором на backend + operational TUI tooling; изменения фронтенда не требуются для MVP enterprise clean-подготовки.
+
+## Phase 0 — Outline & Research Plan
+
+Цель: снять неопределённости и принять архитектурные решения до контрактов.
+
+Исследовательские направления:
+1. Политика классификации артефактов (что считать test/demo/load data и как исключать без повреждения system-init).  
+2. Политика source isolation (детекция и запрет внешних internet endpoints, allowlist внутренних серверов).  
+3. Формат compliance-отчёта для релизного аудита (минимальный обязательный набор полей).  
+4. Паттерн интеграции TUI-проверки в существующий release workflow (ручной запуск + CI gate).
+
+Выход Phase 0: заполненный [`research.md`](./research.md) без `NEEDS CLARIFICATION`.
+
+## Phase 1 — Design & Contracts Plan
+
+Цель: спроектировать сущности, контракты и API/интерфейсы для реализации.
+
+1. Проверка соответствия UX из [`ux_reference.md`](./ux_reference.md):
+   - состояния `READY/RUNNING/COMPLIANT/BLOCKED` должны быть отражены в контракте TUI-модуля (`@UX_STATE`);
+   - ошибки `Data Purity`, `External Source`, `Internal Source Unavailable` должны иметь контракт восстановления.
+2. Модель данных:
+   - ReleaseCandidate, CleanProfilePolicy, ResourceSourceRegistry, ComplianceCheckReport, DistributionManifest.
+3. Семантические контракты:
+   - модуль orchestration проверки;
+   - модуль policy engine;
+   - модуль source isolation validator;
+   - модуль report generator;
+   - TUI module (CRITICAL UX-contract).
+4. API/контракты:
+   - схема запуска проверки и получения результата;
+   - контракт структуры violation entries.
+5. Quickstart:
+   - изолированный запуск в корпоративной сети без внешнего интернета.
+
+Выход Phase 1:
+- [`data-model.md`](./data-model.md)
+- [`contracts/modules.md`](./contracts/modules.md)
+- [`contracts/api.yaml`](./contracts/api.yaml)
+- [`quickstart.md`](./quickstart.md)
+
+## Phase 2 — Task Planning Approach
+
+На этапе `/speckit.tasks` задачи будут разбиты на независимые user-story инкременты:
+
+- US1 (P1): формирование clean-дистрибутива без test/demo-data.
+- US2 (P1): source isolation и internal-only resource policy.
+- US3 (P2): release compliance gate + отчётность.
+- US4 (P3): операционный runbook + onboarding сценарий.
+
+Для каждой истории будут определены:
+- независимый тест;
+- набор backend задач;
+- проверка контракта;
+- критерии готовности.
+
+## Post-Design Constitution Re-Check
+
+Проверка после подготовки артефактов Phase 1 ([`research.md`](./research.md), [`data-model.md`](./data-model.md), [`contracts/modules.md`](./contracts/modules.md), [`contracts/api.yaml`](./contracts/api.yaml), [`quickstart.md`](./quickstart.md)):
+
+- **I. Semantic Protocol Compliance**: PASS
+  Контракты оформлены через `[DEF:...:Module]` и закрывающие `[/DEF:...:Module]` в [`contracts/modules.md`](./contracts/modules.md).
+- **II. Modular Plugin Architecture**: PASS
+  Дизайн опирается на существующие модульные сервисы и централизованную конфигурацию, без hardcode-конфигураций clean-политики.
+- **III. Unified Frontend Experience**: PASS (N/A for web UI changes)
+  Целевой UX реализуется как TUI (`ncurses`-совместимый), что согласовано со [`ux_reference.md`](./ux_reference.md).
+- **IV. Security & RBAC**: PASS
+  Введён блокирующий compliance-gate при внешних источниках и запрещённых данных, отчётность предусмотрена для аудита.
+- **V. Independent Testability**: PASS
+  Зафиксированы независимые сценарии проверки clean/compliance и recovery flow в [`quickstart.md`](./quickstart.md).
+- **VI. Asynchronous Execution**: PASS
+  Длительная проверка проектируется как orchestrated run с поэтапным статусом и финальным отчётом, без требований к блокирующим long-running API вызовам.
+
+**Gate Result (post-design)**: PASS
+
+**Operational Note**: в tooling обнаружено предупреждение о конфликте numeric prefix `020` между [`specs/023-clean-repo-enterprise`](./) и [`specs/020-task-reports-design`](../020-task-reports-design). Это не блокирует текущий план-файл, но требует governance-решения для устранения неоднозначности при запуске стандартных `speckit`-скриптов.
+
+## Complexity Tracking
+
+> Fill ONLY if Constitution Check has violations that must be justified
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| None at planning stage | N/A | N/A |