work_item: ORCH-102
stage: analysis
author_agent: analyst
status: ready-for-review
created_at: 2026-06-10
model_used: claude-opus-4-8
title: "ORCH-10a Lite-тираж: инструкция LITE_SETUP + compose-подмножество — план тестов"
framework: pytest
scope: >
  Покрывается: существование и полнота docs/deployment/LITE_SETUP.md (нормативные
  разделы FR-1, форма «команда+проверка», generic-команды без боевых литералов),
  согласованность упомянутых env-ключей с каноном .env.example, структурная
  фиксация compose-подмножества (ровно орк+watchdog, staging за профилем, без
  Plane/Gitea-сервисов), stateless-нормативы и секрет-гигиена дока, перекрёстные
  ссылки (REPLICATION.md §1, CHANGELOG), воспроизводимый smoke-чек-лист и его
  приёмочный прогон на чистом контуре, полный регресс. Вне покрытия: реальный
  e2e-тираж на новом железе заказчика (заменён прогоном на staging-песочнице —
  прецедент ORCH-101 AC-3), установка Plane/Gitea как таковых, задача 10b
  (Bundled), перенос данных (stateless по решению 10.06).
notes: >
  Задача docs-first: ожидаемый дифф — docs/** + tests/** + CHANGELOG.md
  (+ .env.watchdog.example при исходе А-4); src/** не меняется. Имя нового
  тест-модуля tests/test_lite_setup_doc.py — предложение analyst; developer может
  переименовать/разбить, сохранив покрытие TC (образец структурных док-тестов —
  tests/test_replication_smoke.py). Тесты детерминированы, без сети/LLM.
  Полный регресс tests/ обязан остаться зелёным; STAGE_TRANSITIONS/QG_CHECKS/
  check_*/machine-verdict не меняются — новые тесты входят в существующие гейты
  (check_ci_green / merge-gate re-test / coverage-гейт ORCH-027) автоматически.
  TC-09 — процедурная приёмка AC-4: прогон фиксируется tester'ом в
  13-test-report.md / 15-staging-log.md, а не автоматизируется в pytest.

tests:
  - id: TC-01
    type: unit
    description: >
      LITE_SETUP.md существует по канонному пути (docs/deployment/, исход А-3 —
      синхронизировать с ADR) и несёт ВСЕ нормативные разделы FR-1: рамка/границы
      Lite, предусловия хоста (зависимости, uid/gid, getent group docker), перенос
      кода, конфигурация (.env с нуля + gen_secrets.py + ORCH_PROJECTS_JSON),
      Plane (статусы/токен/webhook+HMAC), Gitea (репо/токен/webhook), LLM
      (claude CLI), Telegram (трекер + watchdog-бот + chat-id), запуск+health-чек,
      регистрация проекта, smoke, stateless-проверка, траблшутинг (AC-1 / FR-1).
    module: tests/test_lite_setup_doc.py
    expected: PASS

  - id: TC-02
    type: unit
    description: >
      Форма «каждый шаг — команда/проверка»: нормативные разделы содержат fenced
      code blocks с исполняемыми командами и явные маркеры проверки
      (PASS/FAIL/«Проверка:»); ключевые кирпичи присутствуют: docker compose,
      /health, /queue, /metrics, gen_secrets.py, onboard_project.py,
      X-Plane-Signature, X-Gitea-Signature (AC-1 / FR-1, NFR-6).
    module: tests/test_lite_setup_doc.py
    expected: PASS

  - id: TC-03
    type: unit
    description: >
      Согласованность env-канона: каждый ключ ORCH_*/WATCHDOG_*, упомянутый в
      LITE_SETUP.md, существует в .env.example; обязательный набор нового хоста
      упомянут явно (ORCH_PROJECTS_JSON, ORCH_PLANE_WEBHOOK_SECRET,
      ORCH_GITEA_WEBHOOK_SECRET, ORCH_PLANE_API_TOKEN, ORCH_GITEA_TOKEN,
      ORCH_TELEGRAM_BOT_TOKEN, ORCH_TELEGRAM_CHAT_ID, WATCHDOG_TG_BOT_TOKEN,
      WATCHDOG_TG_CHAT_ID) (AC-1, AC-6 / FR-1.4, FR-6.2).
    module: tests/test_lite_setup_doc.py
    expected: PASS

  - id: TC-04
    type: unit
    description: >
      Compose-подмножество (AC-2): docker-compose.yml парсится; множество сервисов
      ровно {orchestrator, orchestrator-watchdog, orchestrator-staging};
      orchestrator-staging строго за profiles: [staging] (дефолтный up -d поднимает
      ровно орк+watchdog); ни одного сервиса/образа plane*/gitea*; LITE_SETUP.md
      документирует состав дефолтного запуска (AC-2 / FR-2).
    module: tests/test_lite_setup_doc.py
    expected: PASS

  - id: TC-05
    type: unit
    description: >
      Stateless и секрет-гигиена (AC-3): док несёт нормативную строку «боевые
      данные/задачи/секреты не копируются» и предписывает чистую БД + выпуск
      новых секретов (gen_secrets.py); проверка чистоты инстанса (первый GET
      /queue без задач) описана; в копируемых код-блоках нет боевых литералов
      (mva154, duckdns, 82.22.50.71) и секретоподобных значений — только
      плейсхолдеры <...>/$ENV_VAR (AC-3 / FR-3, NFR-3).
    module: tests/test_lite_setup_doc.py
    expected: PASS

  - id: TC-06
    type: unit
    description: >
      Канон не форкается (AC-6): раздел Plane-статусов ссылается на golden source
      (ONBOARDING.md §1 / onboard_project.py) и явно упоминает fail-closed имена
      Confirm Deploy и STOP; при наличии дубля таблицы статусов в доке — дубль
      сверяется с plane_sync._PLANE_NAME_TO_KEY импортом (22 имени, нулевой
      дрейф); карта env и smoke даны ссылкой на REPLICATION.md (AC-6 / FR-4,
      NFR-4).
    module: tests/test_lite_setup_doc.py
    expected: PASS

  - id: TC-07
    type: unit
    description: >
      Раздел Gitea соответствует инвариантам платформы: события
      push/pull_request/status, ОДИН глобальный webhook-секрет на все репо,
      и норматив защиты main согласован с исходом А-1 ADR задачи (канон: branch
      protection НЕ включать — ADR D10 ORCH-009; инструкция не предписывает
      запрещённого) (AC-1, AC-7 / FR-1.6, §3.8 А-1).
    module: tests/test_lite_setup_doc.py
    expected: PASS

  - id: TC-08
    type: unit
    description: >
      Перекрёстная документация (AC-5): REPLICATION.md §1 (границы 10-common vs
      Lite vs Bundled) ссылается на LITE_SETUP.md / отмечает Lite реализованным;
      CHANGELOG.md содержит запись ORCH-102 (AC-5 / FR-7).
    module: tests/test_lite_setup_doc.py
    expected: PASS

  - id: TC-09
    type: integration
    description: >
      Приёмочный smoke-прогон по LITE_SETUP.md на чистом контуре (минимум:
      staging-песочница ORCH_STAGING_PORT с изолированной БД ./data/staging +
      одноразовый sandbox-проект; прецедент ORCH-101 AC-3): чек-лист REPLICATION
      §4 шаги 0–5 — конфиг резолвится, /health 200, /queue+/metrics штатны,
      onboard verify зелёный, тестовая задача дошла до артефактов 01–04; вердикт
      и контур зафиксированы в 13-test-report.md / 15-staging-log.md. Процедурная
      приёмка (исполняет tester по чек-листу), не pytest-модуль (AC-4 / FR-5).
    module: tests/manual/lite-smoke-checklist (процедура; протокол в 13/15)
    expected: PASS

  - id: TC-10
    type: integration
    description: >
      Полный регресс: pytest tests/ -q зелёный; существующие структурные тесты
      (test_no_host_hardcodes, test_replication_smoke, test_infra_parametrization,
      test_onboarding_*) не ослаблены/не правлены под задачу; дифф не трогает
      src/** (или каждое отклонение обосновано ADR), STAGE_TRANSITIONS/QG_CHECKS/
      machine-verdict/схему БД (AC-5, AC-7 / NFR-2).
    module: tests/
    expected: PASS