ss-tools/specs/023-clean-repo-enterprise/research.md

Phase 0 Research: Clean Repository Enterprise Preparation

Decision 1: Артефакты разделяются на 3 класса политики clean-профиля

Decision
Ввести формальную классификацию артефактов при подготовке enterprise clean-поставки:

1. Prohibited Artifacts — строго запрещены (test/demo/load-test payloads, примеры эксплуатационных данных, временные дампы и нецелевые локальные БД/репозитории).
2. Required System Artifacts — обязательны для работоспособного старта (системная инициализация, базовые конфигурации, служебные миграции, security bootstrap).
3. Conditional Artifacts — допускаются только при соблюдении дополнительных условий (например, шаблоны конфигурации без чувствительных данных).

Rationale
Проблема clean-подготовки не решается простым delete-list: есть риск удалить необходимые для запуска системные элементы. Разделение на 3 класса даёт детерминированную и проверяемую модель принятия решений.

Alternatives considered

• Только deny-list: отклонено, потому что высок риск ложных блокировок системных стартовых сущностей.
• Только allow-list: отклонено как слишком жёсткое для эволюции проекта; высокая операционная стоимость сопровождения без явной пользы на текущем масштабе.
• Ручная экспертная проверка без формальной модели: отклонено из-за невоспроизводимости и человеческого фактора.

---

Decision 2: Source Isolation политика — strict internal-only с явным реестром источников

Decision
Для enterprise clean-профиля принять строгую модель source isolation:

• разрешены только источники из внутреннего реестра серверов компании;
• любые внешние internet endpoints считаются нарушением и блокируют выпуск;
• отсутствие внешнего интернета трактуется как базовое эксплуатационное условие, а не деградационный режим.

Rationale
Требование пользователя и корпоративный контур задают нулевую толерантность к внешним загрузкам. Явный реестр внутренних источников обеспечивает прозрачный аудит и исключает неоднозначную интерпретацию “внутренности” ресурса.

Alternatives considered

• Soft-warning для внешних источников: отклонено, не соответствует security/compliance профилю.
• Частично разрешённые внешние зеркала: отклонено, усложняет доверенную цепочку и нарушает требование полной изоляции.
• Runtime fallback на внешние источники при недоступности внутренних: отклонено как прямое нарушение корпоративной политики.

---

Decision 3: Compliance gate должен быть обязательным и блокирующим перед выпуском

Decision
Выпуск enterprise clean-дистрибутива допускается только после обязательной проверки clean/compliance с бинарным результатом:

• COMPLIANT — выпуск разрешён;
• BLOCKED — выпуск запрещён до устранения нарушений.

Проверка должна валидировать одновременно:

1. data purity (отсутствие запрещённых payloads);
2. source isolation (только внутренние источники);
3. целостность manifest релиза.

Rationale
Снижение рисков требует enforce-механизма, а не рекомендаций. Блокирующий gate переводит требования из “договорённостей” в гарантируемый процесс релиза.

Alternatives considered

• Проверка только по запросу: отклонено из-за неполного охвата релизов.
• Постфактум аудит после выпуска: отклонено, потому что не предотвращает инцидент, а фиксирует его постфактум.
• Частичный gate только по test-data: отклонено, так как не покрывает критичный риск внешних источников.

---

Decision 4: UX контроля выпуска — интерактивный TUI (ncurses/совместимый аналог)

Decision
Операционный интерфейс подготовки/проверки фиксируется как единый интерактивный консольный TUI-flow (на ncurses или совместимом аналоге), в котором оператор:

• выбирает релиз-кандидат;
• запускает проверку;
• наблюдает поэтапный прогресс;
• получает итог и детализацию нарушений;
• экспортирует отчёт.

Rationale
Для изолированных контуров и release-операций TUI обеспечивает воспроизводимый сценарий без зависимости от веб-интерфейса и внешней инфраструктуры.

Alternatives considered

• Только non-interactive CLI: отклонено для primary UX из-за более слабой наблюдаемости этапов и восстановительных действий.
• Веб-панель: отклонено как нецелевой интерфейс для данной фичи и избыточно для операционного сценария.

---

Decision 5: Формат compliance-отчёта должен быть одновременно машинным и операторским

Decision
Каждый прогон проверки формирует единый отчёт с двумя представлениями:

1. Structured section — формализованные поля для автоматической валидации и аудита;
2. Operator section — человекочитаемая сводка нарушений и шагов восстановления.

Минимальные поля:

• report_id;
• candidate_id;
• started_at / finished_at;
• final_status;
• checks summary (data purity / internal sources / no external endpoints / manifest consistency);
• violations[] (category, location, severity, remediation);
• execution metadata (кто запустил, профиль, версия политики).

Rationale
Без структурированного представления отчёт трудно автоматизировать; без операторской сводки — трудно использовать в day-to-day эксплуатации.

Alternatives considered

• Только текстовый лог: отклонено, слабая пригодность для автоматического контроля.
• Только machine format: отклонено, ухудшает скорость ручного triage в релизном окне.

---

Decision 6: Интеграция в release workflow — ручной запуск + обязательный CI gate

Decision
Использовать двухконтурную интеграцию:

1. Pre-release operator run (TUI) — подготовка и предварительная валидация релиз-кандидата;
2. CI gate — обязательное повторное подтверждение compliance перед финальным выпуском.

Оба прогона должны опираться на одну и ту же policy-модель.

Rationale
Это сочетает управляемость оператора и enforce-гарантию pipeline, снижая риск “локально прошло, в релиз не попало”.

Alternatives considered

• Только операторский запуск: отклонено (нет централизованной enforce-гарантии).
• Только CI без операторского шага: отклонено (хуже диагностика и устранение до релизного окна).

---

Decision 7: Вся конфигурация валидации определяется через .clean-release.yaml в корне репозитория

Decision
Ввести единый конфигурационный файл .clean-release.yaml в корне репозитория, определяющий:

• profile и scan_mode (repo | build | docker);
• prohibited_categories и prohibited_paths — классификация запрещённых артефактов;
• allowed_sources — список допустимых внутренних endpoint'ов (glob-паттерны);
• ignore_paths — исключения из сканирования;
• database_cleanup (tables + preserve) — правила очистки БД от тестовых данных.

Rationale
Централизация конфигурации в одном файле обеспечивает прозрачность и версионируемость правил. Владелец проекта явно контролирует политику clean-поставки через декларативный конфиг, что снижает операционные ошибки.

Alternatives considered

• Хранение правил в БД: отклонено — усложняет версионирование и аудит policy drift.
• Отдельные файлы для каждой секции: отклонено — фрагментация ухудшает обзорность и повышает вероятность рассинхронизации.
• Hardcode в коде: отклонено — нарушает принцип конфигурируемости и делает проект-специфичные правила невозможными.

---

Decision 8: Очистка БД от тестовых пользователей и демо-данных — обязательная стадия

Decision
Добавить стадию database_cleanup в compliance pipeline. Правила очистки задаются в секции database_cleanup файла .clean-release.yaml:

• tables — список таблиц с SQL-условиями для удаления тестовых записей;
• preserve — whitelist записей, которые MUST быть сохранены (напр. системный admin).

Rationale
Одной файловой очистки недостаточно: тестовые пользователи (test_user, sample_analyst) и демо-дашборды в БД являются таким же нарушением enterprise clean-профиля, как наличие тестовых файлов в дистрибутиве.

Alternatives considered

• Только предупреждение без очистки: отклонено — не обеспечивает SC-001 (100% отсутствие тестовых данных).
• Автоматическая очистка по паттернам имён: отклонено — высокий риск ложных удалений без явного whitelist.

---

Open Clarifications Status

По итогам Phase 0 + speckit.clarify (2026-03-04) все NEEDS CLARIFICATION сняты:

• Режимы ввода: 3 режима (папка, репозиторий, Docker-образ) — FR-015;
• Классификация артефактов: .clean-release.yaml — FR-016;
• Определение внутренних источников: allowed_sources в конфиге — FR-017;
• Область сканирования NO_EXTERNAL_ENDPOINTS: все текстовые файлы — FR-018;
• Очистка БД: секция database_cleanup — FR-019;
• Структура конфига: полная схема зафиксирована — FR-020.