94 lines
7.7 KiB
Markdown
94 lines
7.7 KiB
Markdown
---
|
||
verdict: APPROVED
|
||
work_item: ORCH-102
|
||
stage: review
|
||
author_agent: reviewer
|
||
status: approved
|
||
created_at: 2026-06-10
|
||
model_used: claude-opus-4-8
|
||
type: review
|
||
work_item_id: ORCH-102
|
||
version: 1
|
||
---
|
||
|
||
# Review ORCH-102 — ORCH-10a Lite-тираж: LITE_SETUP.md + канон watchdog-конфига + анти-дрейф контур
|
||
|
||
## Summary
|
||
|
||
PR (`d03e29f`, docs+tests, 2378 строк) реализует все требования ТЗ и решения ADR-001 (D1–D9)
|
||
точно по спецификации; P0/P1 findings отсутствуют. Дифф строго в декларированных границах:
|
||
`docs/**`, `tests/test_lite_setup_doc.py`, `CHANGELOG.md`, `.env.watchdog.example` + `.gitignore`
|
||
(единственное разрешённое отклонение по ADR D5/ТЗ §2). **`src/**`, `docker-compose.yml`,
|
||
`Dockerfile`, `scripts/**` — ноль изменений** (AC-7 PASS, сверено по `git diff --stat`);
|
||
`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД не тронуты.
|
||
|
||
**Проверено фактически (не по описанию):**
|
||
- Полный регресс: `pytest tests/ -q` → **1789 passed** (включая 25 новых структурных тестов;
|
||
заявление CHANGELOG «25 структурных тестов» совпадает с фактом). Существующие
|
||
`test_no_host_hardcodes`/`test_replication_smoke`/`test_infra_parametrization` не ослаблены.
|
||
- **AC-1/FR-1:** `docs/deployment/LITE_SETUP.md` — 13 нормативных разделов D2 в порядке маршрута
|
||
оператора; каждый исполняемый раздел = fenced-команда + явная «Проверка:»/PASS/FAIL;
|
||
хост-специфика только плейсхолдерами. Копируемые команды сверены с фактическими контрактами
|
||
кода: флаги `onboard_project.py` (`plan|apply|verify` + `--name/--repo/--prefix/--stack/
|
||
--test-cmd/--prod-port/--staging-port/--webhook-url`) — совпадают с argparse скрипта;
|
||
exit-коды (0/2 = manual-step) — совпадают с docstring/кодом; `gen_secrets.py` печатает именно
|
||
`ORCH_PLANE_WEBHOOK_SECRET`/`ORCH_GITEA_WEBHOOK_SECRET`; `/metrics` → `schema_version: 1`
|
||
(`src/metrics.py::SCHEMA_VERSION`); ссылка на шаги 0–5/6 REPLICATION §4 — фактическая нумерация
|
||
таблицы §4 совпадает. Траблшутинг — 7 отказов (≥5 по AC-1), каждый «симптом → диагностика → лечение».
|
||
- **AC-2/FR-2 (D4):** compose не форкается; TC-04 ассертит ровно 3 сервиса, staging строго за
|
||
`profiles: [staging]`, дефолтный up = орк+watchdog, анти-`plane*`/`gitea*` — через `yaml.safe_load`.
|
||
- **AC-3/FR-3:** stateless-норматив (§12 + шапка), чистый старт, проверка чистоты через
|
||
`GET /queue`, секреты только свежевыпущенные; в fenced-блоках и `.env.watchdog.example` —
|
||
только плейсхолдеры (TC-05 + зеркальный placeholder-тест, токены пустые).
|
||
- **D5:** `.env.watchdog.example` — key-set ровно = блоку `WATCHDOG_*` `.env.example` (19 ключей,
|
||
сверено; держится TC-02b равенством множеств), шапка несёт семантику файла-носителя, C-1
|
||
ORCH-100, когерентность порта, do-not-commit; `.env.watchdog` добавлен в `.gitignore`.
|
||
- **AC-6/FR-6 (D8):** канон не форкается — статусы/env/вебхуки/smoke ссылками; «22 статуса»
|
||
защищено **импортом** `plane_sync._PLANE_NAME_TO_KEY` (не строкой); `FORBIDDEN` — импорт из
|
||
`test_no_host_hardcodes.py` (один источник истины); секрет-эвристика с негативным самочеком
|
||
(анти-вечнозелёность). Тесты детерминированы, без сети/LLM/subprocess.
|
||
- **D3 (исход А-1):** §6.4 нормативно запрещает branch protection на `main` (ADR D10 ORCH-009 /
|
||
INV-4), pre-receive не вводится, ОДИН глобальный webhook-секрет; §13.7 — симптом «HOLD».
|
||
- **Трассировка (TRACEABILITY):** правки чужих маркированных блоков сверены: REPLICATION.md §1
|
||
(ORCH-101) — ровно предусмотренное закрытие строки «Type A — Lite» → ✅ + ссылка; INFRA.md —
|
||
аддитивное расширение секрет-норматива на `.env.watchdog`; инварианты ORCH-101/009/100/040/058/
|
||
INV-4 не нарушены (инструкция им следует, ADR их цитирует). Бонус: дозаполнена пропущенная
|
||
строка adr-0036 в индексе `docs/architecture/adr/README.md` + max-номер → 0037.
|
||
|
||
## Findings
|
||
|
||
### P0 — Blocker
|
||
Нет.
|
||
|
||
### P1 — Must fix
|
||
Нет.
|
||
|
||
### P2 — Should fix
|
||
Нет.
|
||
|
||
### P3 — Nice to have (не блокирует)
|
||
- [ ] `LITE_SETUP.md` §13.3: в fenced-блоке литерал `/usr/bin/claude` — совпадает с канон-дефолтом
|
||
`ORCH_CLAUDE_BIN` (контейнерный layout, не хост-специфика), но `docker exec orchestrator
|
||
"$ORCH_CLAUDE_BIN" --version`-форма была бы устойчивее к смене дефолта (правило формы D2(б) —
|
||
ссылка на канон вместо копии значения).
|
||
- [ ] `tests/test_lite_setup_doc.py` BRICKS: кирпич `"STOP"` как подстрока всего дока слаб
|
||
(матчится любым словом STOP); фактически заякорен `test_plane_canon_is_linked_not_forked`
|
||
(STOP внутри тела §5), так что дублирование безвредно — можно убрать из BRICKS или заякорить.
|
||
|
||
## Документация
|
||
|
||
**Полностью обновлена в том же PR** (правило №2; ось 4 — PASS):
|
||
- `CHANGELOG.md` — запись ORCH-102 (фактуально точная: 25 тестов, траблшутинг ×7 — сверено);
|
||
- `CLAUDE.md` — блок «Lite-тираж (ORCH-102)»; `README.md` — способность Lite + `docs/deployment/`
|
||
в структуре; `docs/architecture/README.md` — блок Type A — Lite;
|
||
- ADR: per-work-item `06-adr/ADR-001-lite-setup-doc-canon.md` (D1–D9, исходы А-1…А-6) + сквозной
|
||
`docs/architecture/adr/adr-0037-lite-replication-canon.md` + индекс ADR обновлён;
|
||
- `docs/operations/REPLICATION.md` §1 и `docs/operations/INFRA.md` — перекрёстные ссылки (FR-7);
|
||
- **ORCH-079 (обзорные доки):** README «Известные ограничения» проверен — пунктов про
|
||
тираж/Lite в открытом списке не было и нет, закрывать/снимать нечего; противоречий факту нет.
|
||
|
||
**Handoff для tester (не finding):** AC-4 требует фиксации приёмочного smoke-прогона на чистом
|
||
контуре (staging-песочница + sandbox-проект) в `13-test-report.md` и/или `15-staging-log.md` —
|
||
эти артефакты по конвейеру создаются на стадиях testing/deploy-staging (план — TC-09
|
||
`04-test-plan.yaml`); на стадии review их отсутствие штатно.
|