# 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 (resolved)**: конфликт numeric prefix `020` устранён governance-решением: enterprise clean feature закреплён под уникальным префиксом `023` (ветка и feature-directory: `023-clean-repo-enterprise`). Проверка prereqs и speckit-поток выполняются с `FEATURE_DIR=specs/023-clean-repo-enterprise` без неоднозначности с [`specs/020-task-reports-design`](../020-task-reports-design).

## Implementation Traceability & Final Notes

- Статус реализации: Phase 1–7 завершены (T001–T043).
- Ключевые подтверждения polish-фазы:
  - T039: smoke TUI сценария зафиксирован в [`quickstart.md`](./quickstart.md).
  - T040: контрактная проверка API подтверждена тестом [`backend/tests/api/routes/test_clean_release_api.py`](../../backend/tests/api/routes/test_clean_release_api.py).
  - T041: создан чеклист evidence package [`checklists/release-readiness.md`](./checklists/release-readiness.md).
  - T042: governance conflict по префиксу закрыт и задокументирован.
  - T043: добавлена итоговая traceability-нотация в текущем плане.

Итог: feature готова к финальному релизному циклу с обязательным CI gate (`COMPLIANT` only) и операционной доказательной базой для аудита.

## 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 |