docs(ORCH-057): staging gate log — SUCCESS (8/10, C9a/C9b infra-waived)

Staging suite exit 0; all REAL checks green, C9a/C9b INFRA-WAIVED (ORCH-061).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env.example

@@ -372,6 +372,34 @@ ORCH_SECURITY_SCAN_TIMEOUT_S=300
 ORCH_SECURITY_DEP_AUDIT_FAIL_CLOSED=false
 ORCH_SECURITY_SECRETS_BLOCK=true
 
+# ORCH-027: coverage-gate (deterministic test-coverage) on the deploy-staging ->
+# deploy edge, run AFTER the merge-gate and BEFORE image-freshness. Measures line
+# coverage of src/ with pytest-cov in the per-branch worktree, compares to an absolute
+# floor and/or the ratchet baseline of `main`; FAIL -> rollback to development +
+# developer-retry (cap 3). Verdict in the 18-coverage-report.md frontmatter
+# (coverage_status:). See ADR-001-coverage-gate.md.
+#   GATE_ENABLED       -> global kill-switch; false -> pipeline 1:1 as before ORCH-027.
+#   GATE_REPOS         -> CSV of repos where the gate is REAL; empty -> only self-hosting.
+#   MIN_PERCENT        -> absolute floor (% line coverage) for policy absolute/both.
+#   POLICY             -> absolute | baseline | both (default both).
+#   EPSILON            -> noise tolerance (%) at the boundary (anti-flap).
+#   TOOL_FAIL_CLOSED   -> strict mode: a coverage-tool error -> FAIL instead of the
+#                         default fail-open + warning (anti-loop). Default false.
+#   RUN_TIMEOUT_S      -> wall-clock budget for the pytest --cov run.
+ORCH_COVERAGE_GATE_ENABLED=true
+ORCH_COVERAGE_GATE_REPOS=
+ORCH_COVERAGE_MIN_PERCENT=0.0
+ORCH_COVERAGE_POLICY=both
+ORCH_COVERAGE_EPSILON=0.5
+ORCH_COVERAGE_TOOL_FAIL_CLOSED=false
+ORCH_COVERAGE_RUN_TIMEOUT_S=900
+
+# ORCH-099 (FND/F1a): operator off-switch for the read-only GET /metrics endpoint
+# (raw-signal snapshot for the F1b sidecar). Default true -> available out of the
+# box. false -> /metrics returns a minimal parsable body {"schema_version":1,
+# "enabled":false} (200, not 404). The endpoint is inert / read-only anyway.
+ORCH_METRICS_ENABLED=true
+
 # ORCH-021: post-deploy production monitoring + degradation reaction. After the
 # terminal deploy->done transition for an applicable repo, a reserved-agent job
 # `post-deploy-monitor` (no LLM, modelled on deploy-finalizer) probes prod over a

.task-dev.md

@@ -1,4 +1,4 @@
-Work item: ORCH-093
+Work item: ORCH-099
 Repo: orchestrator
-Branch: feature/ORCH-093-bug-merge-gitea-405-5xx-hold-p
+Branch: feature/ORCH-099-fnd-f1a-metrics-agent-liveness
 Stage: development

CHANGELOG.md

@@ -3,6 +3,23 @@
 Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу.
 
 ## [Unreleased]
+- **Лёгкий read-only `GET /metrics` — машинное «сырьё» о самом орке для sidecar F1b** (ORCH-099, FND/F1a, `feat`): добавлен версионируемый JSON-эндпоинт `GET /metrics`, отдающий снимок внутреннего состояния орка для будущего отдельного sidecar-наблюдателя F1b (`watchdog/`) — наблюдатель отделён от наблюдаемого (BRD §1): орк отдаёт ТОЛЬКО факты, которые знает лишь он сам; пороги/алерты/история/Telegram — на стороне F1b. **Аддитивно, строго read-only, never-raise:** `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict ключи / схема БД — **не тронуты**; `/health`/`/status`/`/queue` — байт-в-байт прежние. ADR: `docs/work-items/ORCH-099/06-adr/ADR-001-metrics-endpoint.md`, сквозной `docs/architecture/adr/adr-0030-metrics-endpoint.md`.
+  - **Leaf-сборщик + тонкий эндпоинт (D1):** новый `src/metrics.py` (`build_metrics() -> dict`, never-raise по разделам, паттерн `serial_gate.snapshot()`) собирает конверт по-раздельно (каждый раздел в своём `try/except` → безопасный дефолт `null`/`[]`/`{}` + WARNING); эндпоинт `@app.get("/metrics")` в `src/main.py` — тонкая обёртка, возвращает результат как есть (стиль `GET /queue`). Тестируемость без ASGI: разделы проверяются прямым вызовом `build_metrics()`.
+  - **Конверт + контракт `schema_version` (D2):** `schema_version` (стартует с `1`), `generated_at` (UTC ISO-8601, часовой домен орка → дельты CPU иммунны к skew орк↔sidecar, TR-3), `clk_tck` (`os.sysconf("SC_CLK_TCK")`, базис тиков). Политика: аддитивные изменения **НЕ бампят** версию (sidecar обязан игнорировать незнакомые ключи) — бамп только при ломающем (rename/remove/retype).
+  - **Разделы сырья (D3–D7):** `stages` — незавершённые задачи (`stage NOT IN ('done','cancelled')`, ORCH-090) с `work_item`/`stage`/`age_in_stage_s`/`repo` (источник `db.get_active_tasks_for_reconcile()` + фильтр терминалов на потребителе, helper-инвариант ORCH-053/086 не тронут). `queue` — `db.job_status_counts()` (+`cancelled`-ключ дефолтом), глубина, сырьё ретраев (`db.queue_retry_stats()`: attempts/transient/в-backoff), `worker.breaker.snapshot()`, `max_concurrency`. `agents` (liveness) — по running-job (новый read-only `db.get_running_agents()`, dedicated SELECT, НЕ расширение hot-path `get_running_jobs()`): `agent`/`run_id`/`job_id`/`pid`/`runtime_s` (= `running_age_s` от `jobs.started_at`, D6)/`model`/`effort` + **CPU-сырьё** `cpu_ticks` (utime+stime из `/proc/<pid>/stat`, поля 14+15; орк дельту не считает — stateless, арбитр sidecar). `cost` — `running` (по running-job, `null` до завершения = честное сырьё) + `aggregate` (новый `db.agent_cost_totals()`, `COALESCE(SUM(...),0)` по `agent_runs`).
+  - **Never-raise сырьё для liveness (FR-6/NFR-2):** `metrics._read_cpu_ticks(pid)` — `pid is None` / нет `/proc/<pid>` / мёртвый процесс / не-Linux → `cpu_ticks: null` у этого агента, прочие поля и весь эндпоинт целы (НЕ raise). Недоступный `worker` → `breaker: null`/`max_concurrency: null`, не 500. Пустые таблицы → `stages=[]`/`agents=[]`/`cost.aggregate=нули`.
+  - **Kill-switch (D8):** `src/config.py` `metrics_endpoint_enabled: bool = True` (env `ORCH_METRICS_ENABLED` через явный `validation_alias` — документированное имя контракта реально управляет флагом). `False` → `200` с минимальным телом `{"schema_version":1,"enabled":false}` (НЕ 404 — контракт остаётся парсимым). Дефолт `True` → нулевая регрессия (эндпоинт доступен из коробки).
+  - **Контракт задокументирован (AC-7):** формат `/metrics` зафиксирован в `docs/architecture/README.md` (раздел «Сырьё-эндпоинт `/metrics`» + строка в таблице API) как стабильный контракт для F1b. Тесты: `tests/test_metrics.py` (TC-01…TC-11: конверт/4 раздела, исключение терминалов, queue-поля, liveness-сырьё + cpu_ticks на живом pid, never-raise на `pid=None`/мёртвом pid/бросающем источнике/недоступном breaker, cost-агрегат + пустая таблица, эндпоинт через handler, read-only снимок БД до/после, аддитивность `/health`//status//queue, пустое состояние, kill-switch). Полный регресс `tests/ -q` зелёный (1480 → +14). Откат: `ORCH_METRICS_ENABLED=false` (мгновенный) или удаление модуля/эндпоинта/helper'ов (без следов в БД/схеме).
+- **Детерминированный гейт покрытия тестами — защита от тихой деградации coverage перед merge в `main`** (ORCH-027, `feat`): существующие тестовые гейты (`check_ci_green`, `check_tests_passed`, merge-gate re-test) судят только по **факту** прохождения, не по **полноте** — ни один не замечает «300 строк кода, 0 тестов», и при пакетном автономном прогоне (ORCH-088) покрытие монотонно деградирует. Введён детерминированный (без LLM) под-гейт ребра `deploy-staging → deploy` по образцу security-гейта (ORCH-022): leaf `src/coverage_gate.py` (never-raise) + тонкая обёртка `check_coverage_gate` в `QG_CHECKS` + врезка `_handle_coverage_gate` в `advance_stage`. **Аддитивно:** `STAGE_TRANSITIONS` / семантика существующих `check_*` / machine-verdict ключи (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`) — байт-в-байт прежние; новая БД-таблица аддитивна (NFR-5/AC-8). См. `docs/work-items/ORCH-027/06-adr/ADR-001-coverage-gate.md`, сквозной `docs/architecture/adr/adr-0029-coverage-gate.md`.
+  - **Точка/порядок (D1, AC-2):** под-гейт исполняется **ПОСЛЕ merge-gate** (покрытие меряется на догнанном `auto_rebase_onto_main` HEAD — ровно том коде, что landed в `main`) и **ДО image-freshness** (фейл до дорогого docker-rebuild). FAIL → штатный откат на `development` (+ инкремент developer-retry, cap `MAX_DEVELOPER_RETRIES`) **и освобождение merge-lease** (merge-gate держал его на своём PASS — зеркало image-freshness rollback, TR-2). `STAGE_TRANSITIONS` не меняется (под-гейт, как security/merge/image-freshness).
+  - **Измерение (D2, FR-1/AC-1):** `python -m pytest tests/ --cov=src --cov-report=json` в изолированном per-branch worktree (`ensure_worktree`, прецедент `check_tests_local`); метрика — `totals.percent_covered` (line coverage `src/`). Измеритель инкапсулирован за `measure_coverage(repo, branch) -> float | None` (стек-расширяемость BR-6: jest/jacoco — новая ветка `measure_*`, без переписывания ядра). Тайм-аут `coverage_run_timeout_s`. Новая pip-зависимость `pytest-cov==5.0.0` (offline на момент замера). 
+  - **Чистая функция решения (D3, FR-2/AC-3):** `compute_coverage_verdict(measured, baseline, floor, policy, epsilon) -> (ok, reason)` — детерминированная, без LLM/IO. `absolute` → `measured ≥ floor−ε`; `baseline` → `measured ≥ baseline−ε`; `both` (дефолт) → оба; `baseline is None` (bootstrap) → baseline-условие не применяется (нельзя регрессировать против пустоты). `epsilon` — допуск на шум измерения (NFR-4, анти-флап у границы). Покрыто unit-тестами всех режимов/границ/epsilon.
+  - **Базовая линия + ratchet (D4/D5, FR-4/AC-4):** аддитивная БД-таблица `coverage_baseline(repo PK, coverage, source_sha, updated_at)` (`CREATE TABLE IF NOT EXISTS`, паттерн `repo_freeze`/`job_deps`; существующие таблицы не мигрируются). Хелперы `db.get_coverage_baseline`/`ratchet_coverage_baseline`/`set_coverage_baseline`/`all_coverage_baselines`. Наращивание **только вверх** в choke-point подтверждённого merge `_handle_merge_verify` (ребро `deploy → done`): `coverage_gate.ratchet_baseline_on_merge` читает измеренное из `18-coverage-report.md` (single source of truth) и применяет **атомарный compare-and-set** `UPDATE … WHERE coverage <= measured` (или `INSERT` — bootstrap) под держимым merge-lease (ORCH-043) → базовая линия никогда не падает даже при гонке. Меньшее значение базовую линию не понижает.
+  - **Условность + fail-open (D6, FR-5/FR-6/AC-5/AC-6):** `coverage_gate_applies(repo)` (локально) ПЕРВЫМ — дорогой прогон только при `applies==True`. `coverage_gate_enabled=False` → инертно (1:1 как до ORCH-027); `coverage_gate_repos` (CSV; **пусто → self-hosting only** `is_self_hosting_repo`, как security/merge/image-freshness) → enduro-trails не затронут (no-op `(True, "N/A")`). Ошибка/недоступность coverage-инструмента или непарсимая метрика → **fail-open + WARNING** по умолчанию (`coverage_tool_fail_closed=False`, анти-петля по образцу ORCH-061/022 dep-audit); флаг переключает в fail-closed.
+  - **Машинный вердикт + наблюдаемость (D7/D8, FR-7/AC-9):** артефакт `18-coverage-report.md` (frontmatter `coverage_status: PASS|FAIL` + `measured_coverage`/`baseline`/`floor`/`policy`/`epsilon`/`delta`), вердикт читается ТОЛЬКО из frontmatter через `src/frontmatter.parse_frontmatter` (ORCH-052c, регистр фиксирован); гейт сам пишет отчёт и читает вердикт обратно из того же файла (single source of truth, как `security_status:`). Read-only блок `coverage` в `GET /queue` (kill-switch/scope/policy/floor/epsilon/per-repo baselines). При FAIL — `send_telegram` с кликабельным номером (`link_for`), измеренным покрытием, порогом/базовой линией и дельтой. Опциональный ручной override `POST /coverage/baseline?repo=…&value=…` (по образцу `POST /serial-gate/unfreeze`) для легитимного разового снижения покрытия.
+  - **Self-hosting безопасность (NFR-1/NFR-3/AC-7):** leaf не импортирует `stage_engine`; любое исключение перехвачено (never-raise); гейт только мерит/читает/пишет/решает — не деплоит, не рестартит прод-контейнер, не пушит/форс-пушит `main` (структурно проверено AST-тестом TC-12). Прод-деплой ORCH-027 — строго через staging-гейт (8501), без рестарта прод-контейнера (лейбл `arch:major-change`).
+  - **Флаги (`config.py`, env `ORCH_COVERAGE_*`, `.env.example`):** `coverage_gate_enabled` (kill-switch), `coverage_gate_repos`, `coverage_min_percent` (дефолт 0.0 — безопасный раскат: no-regression ведёт ratchet-базовая линия, floor не фейлит в день один), `coverage_policy` (дефолт `both`), `coverage_epsilon` (0.5), `coverage_tool_fail_closed` (False), `coverage_run_timeout_s` (900). Откат: `ORCH_COVERAGE_GATE_ENABLED=false` → полный no-op (мгновенный обратимый kill-switch).
+  - **Инфра-предусловие:** добавить `pytest-cov` в прод/staging-образ (`requirements.txt`). При первом применимом merge базовая линия засевается фактическим покрытием `main` (bootstrap). Тесты: `tests/test_coverage_gate.py` (TC-01…TC-15: режимы/границы/epsilon verdict, ratchet up-only + bootstrap + per-repo изоляция, applies/kill-switch, fail-open/closed, never-raise, write/read-back отчёта, self-hosting AST-safety, интеграция в `advance_stage` с откатом+release lease, реальное измерение pytest-cov на фикстур-репо + тайм-аут, snapshot + неизменность `QG_CHECKS`/`STAGE_TRANSITIONS`). Обновлены анти-регресс-реестры `QG_CHECKS` (`test_config`/`test_plane_status_model`/`test_qg_registry_snapshot`/`test_stages_invariants`) и edge-тесты `test_stage_engine` (`check_coverage_gate: _pass`). Полный регресс `tests/ -q` зелёный.
 - **Live-карточка трекера: HTML-инъекция «<1м» больше не застывает карточку — экранирование всех данных-полей на границе рендера** (ORCH-095, `fix`): карточка задачи (`src/notifications.py::render_task_tracker`) шлётся/редактируется с `parse_mode=HTML`. `_fmt_minutes` для стадии < 60 с возвращает литерал `"<1м"`, который интерполировался в HTML-текст **сырым** → Telegram парсит `<1м` как открывающий тег → `editMessageText` отвечает `400 can't parse entities: Unsupported start tag "1м"` → `edit_telegram` классифицирует как `EDIT_FAILED` → `update_task_tracker` делает ранний `return` (анти-дубль ORCH-087) → **карточка застывает** (детерминированно воспроизведено 09.06 на ORCH-093, `message_id 18854`). Корневой класс шире одного `<1м`: все подставляемые **данные** (длительности, статус-лейбл, модель, эффорт, токены/стоимость) вставлялись сырыми; экранирован был только заголовок (`esc_title`) и href/label внутри `plane_issue_link`. **Аддитивно, never-raise, без нового поведения конвейера:** `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / транспорт нотификаций / схема БД — **не тронуты** (затронут ровно один модуль индикативного слоя); kill-switch не требуется (исправление дефекта корректности, откат = `git revert`).
   - **Экранирование на границе рендера, не в источнике (ADR-001 D1/D2, AC-1/AC-2):** новый модуль-локальный хелпер `_esc(x) = html.escape(str(x))` (never-raise → `""` на исключении) оборачивает каждое подставляемое **данные-значение** (категория D) ровно один раз в точке интерполяции в `render_task_tracker`/`_stage_line`: длительности (`_fmt_minutes`/`_capped_review_str`), статус-лейбл (`_card_status_label`), модель (`short_model_name`), эффорт (`_run_effort`), токены/стоимость (`fmt_tokens`/`fmt_cost`). Функции-источники остаются **HTML-агностичными** (данные, не разметка): `src/usage.py` и `_fmt_minutes` не тронуты — `_fmt_minutes` продолжает возвращать `"<1м"`, безопасность даёт escape на границе (`&lt;1м` рендерится оператору визуально идентично `<1м` → видимый формат не меняется).
   - **Категория M (намеренная разметка) неприкосновенна (D5, AC-3):** кликабельный номер задачи `num_html` (`plane_issue_link`, внутри уже экранированы href+label), `link_for(...)` в строке «⏳ ждёт …», `_done_link(...)` («🔗 PR #n · 📦 Внедрено») и уже-экранированный `esc_title` через `_esc` **не** проходят → остаются валидным HTML, номер остаётся кликабельным. Двойное экранирование (`&amp;lt;`) структурно исключено: D-слот → `_esc` ровно один раз, M-слот → as-is.

CLAUDE.md

@@ -153,6 +153,51 @@ created → analysis → architecture → development → review → testing →
   `docs/work-items/ORCH-090/06-adr/ADR-001-stop-cancel-task.md`,
   `docs/architecture/adr/adr-0026-stop-cancel-task.md`.
 
+## Гейт покрытия тестами (ORCH-027)
+Существующие тестовые гейты (`check_ci_green`, `check_tests_passed`, merge-gate re-test) судят
+только по **факту** прохождения, не по **полноте** — ни один не замечает «300 строк кода, 0
+тестов», и при пакетном автономном прогоне (ORCH-088) покрытие монотонно деградирует. Введён
+**детерминированный (без LLM) под-гейт ребра `deploy-staging → deploy`** по образцу security-гейта
+(ORCH-022): leaf `src/coverage_gate.py` (never-raise) + тонкая обёртка `check_coverage_gate` в
+`QG_CHECKS` + врезка `_handle_coverage_gate` в `advance_stage`. **Инвариант:** `STAGE_TRANSITIONS` /
+семантика существующих `check_*` / machine-verdict ключи (`verdict:`/`result:`/`deploy_status:`/
+`staging_status:`/`security_status:`) — байт-в-байт прежние; новая БД-таблица аддитивна (NFR-5).
+- **Точка/порядок:** **ПОСЛЕ merge-gate** (покрытие меряется на догнанном `auto_rebase_onto_main`
+  HEAD — ровно том коде, что landed в `main`) и **ДО image-freshness** (фейл до дорогого
+  docker-rebuild). Порядок под-гейтов: **security → merge → coverage → image-freshness.** FAIL →
+  штатный откат на `development` (+ инкремент developer-retry, cap `MAX_DEVELOPER_RETRIES`) **и
+  освобождение merge-lease** (merge-gate держал его на своём PASS — зеркало image-freshness rollback).
+- **Измерение:** `python -m pytest tests/ --cov=src --cov-report=json` в изолированном per-branch
+  worktree (`ensure_worktree`); метрика — `totals.percent_covered` (line coverage `src/`). Измеритель
+  за `measure_coverage(repo, branch) -> float | None` (стек-расширяемость BR-6). Тайм-аут
+  `coverage_run_timeout_s`. Новая pip-зависимость `pytest-cov`.
+- **Решение — чистая функция** `compute_coverage_verdict(measured, baseline, floor, policy, epsilon)
+  -> (ok, reason)`: `absolute` → `measured ≥ floor−ε`; `baseline` → `measured ≥ baseline−ε`; `both`
+  (дефолт) → оба; `baseline is None` (bootstrap) → baseline-условие не применяется. `epsilon` —
+  допуск на шум измерения (анти-флап у границы).
+- **Базовая линия — аддитивная БД-таблица** `coverage_baseline(repo PK, coverage, source_sha,
+  updated_at)` (`CREATE TABLE IF NOT EXISTS`; хелперы `db.get_coverage_baseline`/
+  `ratchet_coverage_baseline`/`set_coverage_baseline`). Наращивание **только вверх** в choke-point
+  подтверждённого merge `_handle_merge_verify` (ребро `deploy → done`): `ratchet_baseline_on_merge`
+  читает измеренное из `18-coverage-report.md` (single source of truth), атомарный compare-and-set
+  `UPDATE … WHERE coverage <= measured` под держимым merge-lease (ORCH-043) → базовая линия не падает
+  даже при гонке; bootstrap засевается первым применимым merge.
+- **Условность (как ORCH-22/43/58):** `coverage_gate_enabled` (kill-switch; `False` → 1:1 как до
+  ORCH-027) + `coverage_gate_repos` (CSV; **пусто → self-hosting only** `is_self_hosting_repo` →
+  enduro не затронут, no-op `(True, "N/A")`); `applies(repo)` (локально) ПЕРВЫМ — дорогой прогон
+  только при `applies==True`. Ошибка инструмента/непарсимая метрика → **fail-open + WARNING** по
+  умолчанию (`coverage_tool_fail_closed=False`, анти-петля); флаг → fail-closed.
+- **Артефакт `18-coverage-report.md`** (frontmatter `coverage_status: PASS|FAIL` +
+  `measured_coverage`/`baseline`/`floor`/`policy`/`epsilon`/`delta`), вердикт читается ТОЛЬКО из
+  frontmatter через `src/frontmatter.py` (single source of truth, как `security_status:`).
+  Наблюдаемость — read-only блок `coverage` в `GET /queue`; при FAIL — `send_telegram` с кликабельным
+  номером, измеренным/порогом/дельтой; опциональный ручной override `POST /coverage/baseline`.
+  Флаги `ORCH_COVERAGE_*` (`MIN_PERCENT`/`POLICY`/`EPSILON`/`TOOL_FAIL_CLOSED`/`RUN_TIMEOUT_S`).
+  Self-hosting-безопасно: гейт только мерит/читает/пишет/решает — не деплоит/не рестартит прод/не
+  пушит `main`. **Инфра-предусловие:** `pytest-cov` в прод/staging-образе. Детали —
+  `docs/work-items/ORCH-027/06-adr/ADR-001-coverage-gate.md`,
+  `docs/architecture/adr/adr-0029-coverage-gate.md`.
+
 ## Конвенции
 - Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)
 - Ветки: `feature/ORCH-NNN-slug`, `fix/ORCH-NNN-slug`
@@ -162,7 +207,7 @@ created → analysis → architecture → development → review → testing →
 - Машинные вердикты Quality Gate — строго YAML-frontmatter (`verdict:`, `deploy_status:`, `staging_status:`, `security_status:`), никогда проза. **ORCH-52c (ORCH-076):** парсинг frontmatter сведён к единому контракту `src/frontmatter.py` (reader `read_frontmatter_value` — BC; единый парс-примитив `parse_frontmatter`; writer `render/write_frontmatter`; валидатор схемы `validate_schema`/`REQUIRED_FIELDS` — warning-only по умолчанию, hard-fail только под kill-switch `frontmatter_validation_strict`, дефолт `False`). Пять вердикт-парсеров (`check_reviewer_verdict`, `_parse_tests_verdict`, `_parse_deploy_status`, `_parse_staging_status`, `parse_security_status`) читают через ОДНУ точку парсинга; семантика вердиктов и `STAGE_TRANSITIONS`/состав `QG_CHECKS` — 1:1. Формальная спека «стадия → обязательный выход» + обязательная frontmatter-схема — `docs/_standards/HANDOFF_PROTOCOL.md`
 
 ## Артефакты задачи (`docs/work-items/<plane-id>/`)
-`00-business-request.md`, `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml`, `06-adr/ADR-NNN-slug.md`, `07-infra-requirements.md`, `08-data-requirements.md`, `10-tech-risks.md`, `12-review.md`, `13-test-report.md`, `14-deploy-log.md`, `15-staging-log.md`, `16-post-deploy-log.md` (post-deploy наблюдение, ORCH-021), `17-security-report.md` (security-гейт: `security_status:`/secrets/deps, ORCH-022).
+`00-business-request.md`, `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml`, `06-adr/ADR-NNN-slug.md`, `07-infra-requirements.md`, `08-data-requirements.md`, `10-tech-risks.md`, `12-review.md`, `13-test-report.md`, `14-deploy-log.md`, `15-staging-log.md`, `16-post-deploy-log.md` (post-deploy наблюдение, ORCH-021), `17-security-report.md` (security-гейт: `security_status:`/secrets/deps, ORCH-022), `18-coverage-report.md` (coverage-гейт: `coverage_status:`/measured/baseline, ORCH-027).
 
 **Стандарт документов (ORCH-075, ORCH-52b):** структура каждого дока, карта «стадия→агент→документ→гейт→machine-key» и конвенция ADR-naming зафиксированы в `docs/_standards/PIPELINE_DOCS.md` (golden source); копируемые скелеты — в `docs/_templates/`. Перед написанием номерного дока бери скелет из `docs/_templates/` и не меняй имя machine-key frontmatter (регистр чувствителен — иначе гейт упадёт ложно).
 

docs/_standards/PIPELINE_DOCS.md

@@ -2,7 +2,7 @@
 
 > **Назначение.** Единая карта «стадия → агент → документ → категория → гейт/механизм →
 > frontmatter machine-key» + конвенция ADR-naming. Это **golden source структуры** номерных
-> документов work item (`00-business-request.md` … `17-security-report.md`), который каждая
+> документов work item (`00-business-request.md` … `18-coverage-report.md`), который каждая
 > агентская роль пишет на своей стадии.
 >
 > **Статус истины (важно).** Манифест **документирует** текущее поведение гейтов, но НЕ является
@@ -60,6 +60,7 @@ check_tests_passed → check_staging_status → check_deploy_status`.
 | `15-staging-log.md` | deployer | required (self-hosting) | `deploy-staging` | `check_staging_status` (self-hosting; иначе N/A — ORCH-35) | `staging_status:` (`SUCCESS` \| `FAILED`) |
 | `16-post-deploy-log.md` | post-deploy-monitor | when-applicable | пост-`done` наблюдение (ORCH-021; не ребро `STAGE_TRANSITIONS`) | информационный (гейтом не парсится) | `post_deploy_status:` (`HEALTHY` \| `DEGRADED`) |
 | `17-security-report.md` | security-гейт (детерминированный, ORCH-022) | when-applicable | под-гейт ребра `deploy-staging→deploy` | `check_security_gate` (врезка в `advance_stage`) | `security_status:` (`PASS` \| `FAIL`) |
+| `18-coverage-report.md` | coverage-гейт (детерминированный, ORCH-027) | when-applicable | под-гейт ребра `deploy-staging→deploy` (ПОСЛЕ merge-gate, ДО image-freshness) | `check_coverage_gate` (врезка в `advance_stage`) | `coverage_status:` (`PASS` \| `FAIL`) |
 
 ### Примечания манифеста (нормативные)
 
@@ -86,6 +87,7 @@ check_tests_passed → check_staging_status → check_deploy_status`.
 | `14-deploy-log.md` | `deploy_status:` | `_parse_deploy_status` | `SUCCESS` → `done`; `FAILED` → откат (БАГ-8) |
 | `15-staging-log.md` | `staging_status:` | `_parse_staging_status` | `SUCCESS` → дальше; `FAILED` → откат (self-hosting; иначе N/A) |
 | `17-security-report.md` | `security_status:` | `check_security_gate` | `PASS` → дальше; `FAIL` → откат |
+| `18-coverage-report.md` | `coverage_status:` | `check_coverage_gate` | `PASS` → дальше; `FAIL` → откат на `development` |
 
 **Информационные доки** — гейтом НЕ парсятся (структура ничего не блокирует):
 `00-business-request.md` (вход), `08-data-requirements.md`, `10-tech-risks.md`,

docs/_templates/18-coverage-report.md

@@ -0,0 +1,29 @@
+---
+coverage_status: PASS      # PASS | FAIL  (machine-key — читает check_coverage_gate)
+work_item: ORCH-NNN
+measured_coverage: 0.0      # измеренное line coverage src/ (%, float)
+baseline: 0.0              # базовая линия main на момент измерения (%, или пусто при bootstrap)
+floor: 0.0                 # абсолютный порог coverage_min_percent (%)
+policy: both               # absolute | baseline | both
+epsilon: 0.5               # допуск на шум измерения (%)
+delta: 0.0                 # measured − max(baseline, floor) (%, знаковая дельта)
+---
+
+# Coverage Report — ORCH-NNN
+
+> Детерминированный гейт покрытия (ORCH-027) — под-гейт ребра `deploy-staging→deploy` (врезка в
+> `advance_stage`, ПОСЛЕ merge-gate, ДО image-freshness; не строка `STAGE_TRANSITIONS`). Машинный
+> вердикт читается ТОЛЬКО из `coverage_status:`. `PASS` → дальше; `FAIL` → откат на `development`.
+> Измерение — `pytest --cov=src --cov-report=json` в изолированном worktree. Source of truth
+> измеренного значения для ratchet базовой линии (`_handle_merge_verify`, ребро `deploy→done`).
+
+## Verdict
+<PASS / FAIL: measured X% vs floor F% / baseline B% (policy=…, epsilon=…), delta=±D%.>
+
+## Measurement
+<Инструмент (pytest-cov/coverage.py), команда, line coverage src/ = X%; либо fail-open WARNING
+при ошибке инструмента (coverage_tool_fail_closed=False).>
+
+## Policy
+<Режим (absolute|baseline|both), порог floor, базовая линия main, epsilon, какое условие
+нарушено при FAIL.>

docs/architecture/adr/README.md

@@ -31,11 +31,16 @@ Per-work-item решения живут в `docs/work-items/<id>/06-adr/ADR-NNN-
 | adr-0023 | Обзорная ось reviewer + закрытие эпика 52 | accepted | 2026-06-09 | ORCH-079 |
 | adr-0024 | Disk-watchdog — heartbeat-сигнал заполнения хост-ФС | proposed | 2026-06-09 | ORCH-063 |
 | adr-0025 | Build-cache-pruner — авто-prune docker build cache на хосте | proposed | 2026-06-09 | ORCH-062 |
+| adr-0026 | STOP / отмена задачи — системный терминал `cancelled` | proposed | 2026-06-09 | ORCH-090 |
+| adr-0027 | Merge-актор — ретрай транзиентных ошибок Gitea + гард «ветка уже в `main`» | proposed | 2026-06-09 | ORCH-093 |
+| adr-0028 | Terminal-window-aware гард deploy-фазовых статусов Plane | proposed | 2026-06-09 | ORCH-094 |
+| adr-0029 | Гейт покрытия тестами — edge sub-gate + ratchet-базовая линия | proposed | 2026-06-10 | ORCH-027 |
+| adr-0030 | Лёгкий read-only `/metrics` — сырьё о самом орке для sidecar (F1b) | proposed | 2026-06-10 | ORCH-099 |
 
 > ⚠️ Историческая коллизия: номер `0007` занят двумя файлами —
 > `adr-0007-reconciler.md` (ORCH-053) и `adr-0007-executable-self-deploy.md`
 > (ORCH-036). Оба accepted; для новых сквозных ADR использовать следующий
-> свободный номер (текущий максимум — `0020`).
+> свободный номер (текущий максимум — `0030`).
 > adr-0014 **amends** adr-0013 (меняет критерий merge-verify на «SHA-в-main»).
 > adr-0016 **amends** adr-0013/0014 (гарантирует открытый код-PR перед merge_pr, ORCH-082).
 > adr-0020 реализует машинный слой к adr-0019 (ORCH-52b→52c).

docs/architecture/adr/adr-0029-coverage-gate.md

@@ -0,0 +1,92 @@
+---
+work_item: ORCH-027
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# adr-0029: Гейт покрытия тестами — edge sub-gate + ratchet-базовая линия
+
+- **Статус:** proposed
+- **Дата:** 2026-06-10
+- **Задача:** ORCH-027
+- **Детальный ADR:** `docs/work-items/ORCH-027/06-adr/ADR-001-coverage-gate.md`
+
+## Контекст
+Оркестратор автономен: `developer` пишет код без человека-фильтра, `tester` сам решает, хватает
+ли тестов. Существующие тестовые гейты судят только по факту прохождения, не по полноте:
+`check_ci_green` (exit-code CI), `check_tests_passed` (LLM-вердикт `tester`'а), merge-gate
+re-test (exit-code). Ни один не замечает «300 строк кода, 0 тестов». При пакетном автономном
+прогоне (ORCH-088) это монотонная деградация покрытия. Нужна детерминированная метрика — по духу
+как security-гейт (adr-0012).
+
+## Решение
+Детерминированный (без LLM) **гейт покрытия как под-гейт ребра `deploy-staging → deploy`**,
+рядом с security-gate (ORCH-022), merge-gate (ORCH-043), image-freshness (ORCH-058). Паттерн —
+leaf-модуль `src/coverage_gate.py` (never-raise) + обёртка в `QG_CHECKS` (`check_coverage_gate`)
++ врезка `_handle_coverage_gate` в `advance_stage`. `STAGE_TRANSITIONS` не меняется.
+
+- **Порядок: security → merge → `coverage` → image-freshness.** Coverage идёт **ПОСЛЕ
+  merge-gate** (ветка догнана на свежий `origin/main` → меряем покрытие того кода, что landed) и
+  **ДО image-freshness** (фейлить дёшево до docker-rebuild). На этой точке merge-lease **held** →
+  **FAIL обязан освободить lease** при откате (как image-freshness rollback; в отличие от
+  security, который идёт до захвата lease).
+- **Измеритель:** `pytest-cov` (`coverage.py`), `python -m pytest tests/ --cov=src
+  --cov-report=json` в изолированном worktree (`ensure_worktree`); метрика —
+  `totals.percent_covered`. Тайм-аут `coverage_run_timeout_s`. Скоуп — `src/` (не тесты).
+- **Чистая функция** `compute_coverage_verdict(measured, baseline, floor, policy, epsilon)`:
+  `absolute` (≥floor−ε), `baseline` (≥baseline−ε, ratchet), `both` (дефолт). `baseline=None` →
+  bootstrap (только absolute). FAIL → откат на `development` + developer-retry (cap
+  `MAX_DEVELOPER_RETRIES`), дословный reason в `task_desc` (ORCH-046).
+- **Базовая линия — аддитивная БД-таблица** `coverage_baseline(repo PK, coverage, source_sha,
+  updated_at)` (`CREATE TABLE IF NOT EXISTS`, паттерн `repo_freeze`/`job_deps`). Выбор БД над
+  файлом-в-репо: нет git-churn/конфликтов на ratchet, restart-safe, атомарное обновление.
+- **Ratchet-up** в choke-point подтверждённого merge `_handle_merge_verify` (ребро
+  `deploy → done`, ORCH-071/073): читает измеренное покрытие из `18-coverage-report.md`,
+  атомарный compare-and-set `UPDATE ... WHERE coverage <= measured` (базовая линия не падает).
+  Под held merge-lease + per-repo сериализацией merge (ORCH-043) — двойная анти-гонка.
+- **Артефакт `18-coverage-report.md`** с frontmatter `coverage_status: PASS|FAIL` (+
+  `measured_coverage`/`baseline`/`floor`/`policy`/`delta` + аддитивная 52c-схема); вердикт
+  читается ТОЛЬКО из frontmatter через `src/frontmatter.py` (single source of truth).
+- **Условность (как ORCH-35/43/58):** `coverage_gate_enabled` + `coverage_gate_repos` (пусто →
+  только self-hosting `orchestrator`); вне области → no-op pass. `applies(repo)` ПЕРВОЙ, дорогой
+  прогон — только при applies.
+- **Ошибка инструмента → fail-open + WARNING** по умолчанию (`coverage_tool_fail_closed=False`,
+  анти-петля как ORCH-061); флаг → fail-closed.
+- **Наблюдаемость:** read-only блок `coverage` в `GET /queue`; FAIL → Telegram (кликабельный
+  номер, измеренное/порог/дельта). Опциональный `POST /coverage/baseline` (ручной override).
+- **never-raise**, гейт не деплоит/не рестартит прод/не пушит в `main` (NFR-3).
+
+## Альтернативы
+- **CI-job (`check_ci_green`):** пороги/политика/baseline/артефакт плохо выражаются статусом
+  коммита; ratchet требует записи в БД. Отклонено для v1 (точка расширения).
+- **Edge `testing → deploy-staging`:** ветка не догнана на свежий `main` → метрика неточна;
+  откат не освобождает lease. Отклонено.
+- **Базовая линия в файле репо:** git-churn/конфликты на каждый ratchet. Отклонено.
+- **Новая стадия `coverage`:** «пустая» стадия без агента не имеет триггера (как ORCH-043/022).
+  Отклонено.
+- **Жёсткий absolute-порог без baseline/epsilon:** массовые ложные заворота. Отклонено.
+
+## Последствия
+- Класс «тихо просевшее покрытие» закрыт детерминированной метрикой; baseline только растёт.
+- Нулевая регрессия вне области (enduro-trails); `STAGE_TRANSITIONS`/`QG_CHECKS`-семантика/
+  вердикт-ключи (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`) —
+  байт-в-байт прежние; новая БД-таблица аддитивна.
+- Плата: ещё один «скрытый» под-гейт ребра; новая pip-зависимость (`pytest-cov`); доп. прогон
+  pytest (после merge-gate re-test, ограничен таймаутом, фейлит до rebuild); v1 — Python-only.
+- Дефолтный fail-open тихо пропускает при устойчивом сбое инструмента (с WARNING) —
+  переключаемо `coverage_tool_fail_closed`.
+- Сквозное изменение (новый QG + edge-под-гейт + новая таблица + новый артефакт) →
+  `arch:major-change`; прод-деплой строго через staging-гейт (8501), без рестарта прод-контейнера.
+- **Откат:** `coverage_gate_enabled=False` → полный no-op (мгновенный обратимый kill-switch).
+
+## Связи
+adr-0012 (security-гейт — паттерн edge-под-гейта/leaf/never-raise/fail-open), adr-0006
+(merge-gate — edge-под-гейт/откат/merge-lease), adr-0008 (image-freshness — условность/
+fail-closed/release-lease-on-rollback), adr-0003 (условный гейт / `is_self_hosting_repo`),
+adr-0009 (анти-петля ложных FAIL, ORCH-061), adr-0013/adr-0014 (merge-verify / SHA-in-main как
+source of truth — точка ratchet), adr-0015/adr-0017 (per-repo сериализация merge/serial-gate),
+adr-0020 (frontmatter-контракт — парсинг `coverage_status:`), adr-0019 (PIPELINE_DOCS — артефакт
+`18-coverage-report.md`), ORCH-9/15 (мульти-стек — будущая зависимость BR-6).

docs/architecture/adr/adr-0030-metrics-endpoint.md

@@ -0,0 +1,88 @@
+---
+work_item: ORCH-099
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# adr-0030: Лёгкий read-only `/metrics` — сырьё о самом орке для sidecar (F1b)
+
+- **Статус:** proposed
+- **Дата:** 2026-06-10
+- **Задача:** ORCH-099 (FND/F1a)
+- **Детальный ADR:** `docs/work-items/ORCH-099/06-adr/ADR-001-metrics-endpoint.md`
+
+## Контекст
+Эпик автономного саморазвития, домен 0 «Фундамент». Рамка наблюдаемости (заказчик): **наблюдатель
+отделён от наблюдаемого** — мозг мониторинга (пороги/алерты/история/Telegram) живёт в отдельном
+sidecar-контейнере **F1b** (`watchdog/`), а орк отдаёт **только сырьё**, которое знает лишь он сам.
+Сегодня такого источника нет: `/health` = `{"status":"ok"}`, `/status` = активные задачи, `/queue` —
+«человеческий» снимок, перемешанный с конфигом демонов. Нет стабильного машинного контракта для
+детекта застрявшей стадии / зависшего агента / деградации очереди / всплеска стоимости. F1b
+заблокирована этой задачей. Self-hosting: прод общий с enduro-trails ⇒ эндпоинт обязан быть строго
+read-only и never-raise.
+
+## Решение
+Новый **leaf-модуль** `src/metrics.py` (`build_metrics() -> dict`, чистый, never-raise по разделам —
+паттерн `serial_gate.snapshot()`) + тонкий эндпоинт `@app.get("/metrics")` в `src/main.py` (стиль
+`GET /queue`). Только чтение существующих таблиц (`tasks`/`jobs`/`agent_runs`) и in-memory-снапшотов
++ два read-only helper'а в `src/db.py`. `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict-
+ключи/схема БД — **не трогаются**.
+
+- **Конверт + контракт версии:** `schema_version` (старт `1`), `generated_at` (UTC ISO-8601 —
+  момент снимка, домен часов орка), `clk_tck` (`os.sysconf("SC_CLK_TCK")`), разделы
+  `stages`/`queue`/`agents`/`cost`. **Политика версии:** аддитивные изменения НЕ бампят (sidecar
+  обязан игнорировать незнакомые ключи и толерировать отсутствие опциональных); бамп — только при
+  ломающем (rename/remove/retype). Forward-compatible контракт для F1b.
+- **`stages`** — `db.get_active_tasks_for_reconcile()` + фильтр `stage NOT IN ('done','cancelled')`
+  на слое metrics (helper намеренно отдаёт `cancelled` для ORCH-086 — не трогаем его инвариант);
+  поля `work_item`/`stage`/`age_in_stage_s`/`repo`.
+- **`queue`** — `db.job_status_counts()` (+`cancelled`), глубина, сырьё ретраев
+  (`attempts`/`max_attempts`/`transient_attempts`/в-backoff), `worker.breaker.snapshot()`,
+  `max_concurrency`. Недоступный worker → `breaker: null`, не 500.
+- **`agents` (liveness)** — новый dedicated read-only helper `db.get_running_agents()` (НЕ расширение
+  hot-path `get_running_jobs()` reaper'а, ORCH-065): `agent`/`run_id`/`job_id`/`pid`/`runtime_s`
+  (= `running_age_s` от `jobs.started_at`)/`model`/`effort`. CPU-сырьё — **вариант A**: орк читает
+  `/proc/<pid>/stat` (поля 14+15, utime+stime) → `cpu_ticks`; **дельту не считает** — арбитр
+  «жив/завис» это sidecar (stateless-эмиссия). `pid is None`/мёртвый/нет `/proc`/не-Linux →
+  `cpu_ticks: null`, не ошибка.
+- **`cost`** — `running` (по running-job, часто `null` до завершения — честное сырьё, `null` ≠ ноль)
+  + `aggregate` (новый helper `db.agent_cost_totals()`, `COALESCE(SUM(...),0)` по
+  `cost_usd`/`input_tokens`/`output_tokens`/`cache_read_tokens`/`cache_creation_tokens`).
+- **Kill-switch** `metrics_endpoint_enabled` (env `ORCH_METRICS_ENABLED`, дефолт `True`): при `False`
+  → `200` с `{"schema_version":1,"enabled":false}` (контракт остаётся парсимым). Операторский
+  off-switch на общем инстансе.
+- **Never-raise:** каждый раздел — свой `try/except` + `logger.warning` + дефолт (`null`/`[]`/`{}`);
+  `build_metrics()` никогда не пробрасывает. Read-only: ни одного `INSERT/UPDATE/DELETE/CREATE/ALTER`.
+
+## Альтернативы
+- **Расширить `/queue`** — отклонено: ломает байт-в-байт контракт (BR-6) + смешивает сырьё с
+  человеческим снимком.
+- **Prometheus/OpenMetrics** — отклонено: заказчик задал тонкий кастомный sidecar (не Prometheus),
+  контракт — JSON.
+- **Орк считает CPU-дельту сам** — отклонено: требует состояния; stateful-арбитр это sidecar (C-1).
+- **Расширить SELECT `get_running_jobs()`** — отклонено: перенос инварианта hot-path reaper'а;
+  изолируем dedicated helper.
+- **Push в sidecar** — отклонено: нарушает разделение C-1; зависший орк ⇒ pull падает = сам сигнал.
+
+## Последствия
+- F1b разблокирована стабильным машинным контрактом; домен наблюдаемости стартует.
+- Строго read-only + never-raise ⇒ near-zero риск для общего прод-конвейера (enduro-trails);
+  `/health`/`/status`/`/queue` байт-в-байт; гейты/схема/machine-verdict-ключи не тронуты (NFR-5).
+- `schema_version` + аддитивно-толерантная политика ⇒ расширения не ломают F1b.
+- Плата: новая поверхность совместимости `/metrics`↔F1b (митигейшн — единый репо контракта + версия);
+  CPU-liveness Linux-специфичен (`/proc`; не-Linux → `null`). Топология/схема не меняются (sidecar и
+  его сетевая достижимость — объём F1b).
+- Новый компонент + публичный контракт → `arch:major-change` (хоть и аддитивно/read-only/обратимо);
+  прод-деплой строго через staging-гейт (8501), без рестарта прод-контейнера.
+- **Откат:** `metrics_endpoint_enabled=False` (мгновенный) или удаление модуля/эндпоинта/helper'ов —
+  без следов в БД/схеме.
+
+## Связи
+adr-0002 (job-queue/circuit-breaker — источник `queue`-сырья), adr-0011 (job-reaper —
+`get_running_jobs`/pid/liveness-семантика, изоляция hot-path), adr-0026 (терминал `{done,cancelled}`
+— фильтр `stages`), adr-0017 (serial_gate — паттерн leaf `snapshot()`/never-raise), adr-0020
+(frontmatter-контракт — стиль версионируемого контракта). Прямой потребитель — **F1b** (sidecar
+`watchdog/`, отдельная задача).

docs/epics/self-evolution.md

@@ -0,0 +1,287 @@
+# 🧬 ЭПИК: Автономное саморазвитие платформы оркестратора
+
+> **Статус:** концепция v2 (структура согласована Славой 09.06 → ждёт финального апрува → декомпозиция)
+> **Автор:** Стрим · **Дата:** 2026-06-09 · **Заказчик:** Слава
+> **Связанные:** ORCH-8 (петля самообучения), ORCH-83 (наблюдаемость), ORCH-54 (автономное внедрение, done)
+> **Источники:** память орка (инциденты 06–09.06), инвентаризация 94 задач Plane, мировые практики (STRATUS NeurIPS'25, ChaosEater ASE'25, self-healing LLM-agents arXiv'26, agentic AIOps, FinOps token-economics).
+
+---
+
+## 0. Зачем это (vision)
+
+Оркестратор уже **автономно внедряет** (ORCH-54: задача проходит analysis→prod без человека). Но автономность исполнения ≠ автономное **развитие**. Сегодня платформу развивает связка Слава+Стрим вручную: ловим инциденты → формулируем уроки → заводим задачи → апрувим.
+
+**Цель эпика:** управляемый самоподдерживающийся контур, где платформа сама замечает свои слабые места И возможности роста, предлагает улучшения как готовые задачи, проводит их через собственный конвейер (ORCH-7 self-hosting) — **под контролем человека на ключевых развилках** (safety > автономность).
+
+**Принцип баланса (коррекция Славы 09.06):** саморазвитие — это НЕ только «не падать и не косячить». Стабильная платформа, которая не растёт в возможностях, — тупик. **Рост функционала (новые фичи, стеки, удобства для заказчиков) — равноценный домен, а не следствие надёжности.** Платформа развивается по двум рукам одновременно: крепнет (надёжность/качество/экономика) И раздаётся вширь (возможности/масштаб).
+
+---
+
+## 1. Архитектура эпика: фундамент + 5 доменов + 2 вертикали
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  ВЕРТИКАЛЬ-ДВИГАТЕЛЬ 🧠        ВЕРТИКАЛЬ-ТОРМОЗ 🛑            │
+│  🔄 уроки (крепнем) +          governance / safety L0-L3      │
+│  💡 генератор идей (растём)    (ограничивает, апрувы)         │
+│ ░░░░░░░░░░░░ проходят СКВОЗЬ все домены ░░░░░░░░░░░░░░░░░░░░░ │
+├─────────────────────────────────────────────────────────────┤
+│         ДОМЕНЫ РАЗВИТИЯ (равноценные, две руки роста)         │
+│                                                               │
+│   КРЕПНЕТ ───────────────────►   РАЗДАЁТСЯ ВШИРЬ ────────►    │
+│   🛡️ D1 Надёжность              🚀 D4 Возможности (фичи)      │
+│   ✅ D2 Качество/Доверие         📈 D5 Масштаб                 │
+│   💰 D3 Экономика                                             │
+├─────────────────────────────────────────────────────────────┤
+│  ФУНДАМЕНТ (слой 0):  👁️ Наблюдаемость + 📒 Журнал уроков    │
+│  глаза и память — без них всё слепо                          │
+└─────────────────────────────────────────────────────────────┘
+       Общая метрика-объединитель: 🌡️ ГРАДУСНИК АВТОНОМНОСТИ
+       (каждый домен двигает её вверх контролируемо)
+```
+
+### Что изменилось против v1 (мои же правки по критике)
+- **Наблюдаемость вынесена в фундамент** (была внутри M1) — она питает ВСЁ.
+- **M0 разбит на 2 вертикали:** двигатель (петля) и тормоз (governance) — у них противоположная логика, нельзя в одну коробку.
+- **Добавлен домен D2 Качество/Доверие** — была дыра: надёжная платформа может стабильно генерить говнокод. Надёжность инфры ≠ корректность результата.
+- **Рост (D4+D5) — равноценные домены, не «второй эшелон»** (коррекция Славы).
+- **Градусник автономности** — сквозная измеримая цель вместо абстракции.
+
+---
+
+## 🏗️ АРХИТЕКТУРНЫЕ РАМКИ наблюдаемости (решено Славой 09.06 — constraints для архитектора)
+
+> Это НЕЗЫБЛЕМЫЕ границы (заказчик). Конкретные ADR (стек, формат метрик, точки врезки) — зона архитектора внутри этих рамок.
+
+**Принцип:** наблюдатель ОТДЕЛЁН от наблюдаемого. Мониторинг НЕ живёт внутри орка — иначе орк упал/завис/съел память → мониторинг ляжет вместе с ним, и мы слепы в самый критичный момент.
+
+**Решения Славы:**
+- **С-1. Sidecar-контейнер на том же хосте** (вариант A). Отдельный процесс/память/рестарт — орк падает, наблюдатель жив и РЕПОРТИТ это.
+- **С-1б. КОД sidecar — В РЕПО орка** (отдельная папка `watchdog/`), рантайм — ОТДЕЛЬНЫЙ контейнер. Изоляция — на уровне КОНТЕЙНЕРА, не репозитория. Плюсы: (1) конвейер орка пилит свой мониторинг сам (self-hosting ORCH-7); (2) контракт `/metrics`↔sidecar в одном репо — не разъедется (один PR/тесты); (3) один CI. Сборка: ОТДЕЛЬНЫЙ `watchdog/Dockerfile` + сервис `orchestrator-watchdog` в docker-compose.yml. Разовое инфра-действие: добавить сервис в compose + первый запуск (Слава/Стрим на хосте), дальше код watchdog катится через конвейер.
+- **С-2. Без внешнего плеча (L2).** Не усложняем второй площадкой. (Принятый риск: падёнвесь хост/Docker → наблюдатель тоже молчит; осознанно.)
+- **С-3. Тонкий стек.** НЕ Grafana+Prometheus (+5-6 контейнеров на забитый хост). Тонкий Python/Go sidecar. **Факт хоста 09.06: RAM 171Mi free / 7.7Gi, диск 92%** — ресурсы впритык, наблюдатель обязан быть лёгким.
+
+**Разделение ответственности:**
+- **Орк отдаёт только сырьё:** лёгкий read-only `/metrics` (свои внутренние данные — стадии/очередь/agent-liveness/cost, что знает только он). БЕЗ логики мониторинга/алертов/хранения. Орк лёг → endpoint недоступен = САМ сигнал тревоги.
+- **Sidecar — мозг мониторинга:** читает `/metrics` орка + хост (диск/память/CPU) + контейнеры (docker.sock read-only) + пинг Plane/Gitea/Anthropic; хранит пороги, шлёт Telegram-алерты СО СВОИМ каналом (не зависит от кода орка).
+- **Журнал уроков (F2)** — исключение: это НЕ realtime-мониторинг, а историческая память петли → допустимо в БД орка (аддитивная таблица). Не критично к падению орка в момент (запись best-effort).
+
+---
+
+## 2. ФУНДАМЕНТ (слой 0) — 👁️ Глаза и 📒 Память
+
+Без данных нечем ни чинить, ни считать, ни приоритизировать, ни учиться. Строится первым.
+
+- **F1 Наблюдаемость** (ORCH-83 [ЭПИК]): метрики agent-liveness + очередь + стадии + хост (диск/память/CPU) + контейнеры + внешние деп (Plane/Gitea/Anthropic). Эндпоинты /health /status /queue → расширить до /metrics + дашборд.
+- **F2 Журнал уроков** (ORCH-8 шаг 1): машинная структурированная таблица отклонений (тип, контекст, корень, предложение, статус) — формализовать то, что сейчас в memory/. Это «топливо» для вертикали-двигателя.
+
+---
+
+## 3. ДОМЕН D1 — 🛡️ Надёжность (Self-Repairing)
+
+**Есть:** reconciler (53), post-deploy monitor+rollback (21), merge-verify (71/73), reaper (65), disk-watchdog (63), build-prune (62).
+**Уроки:** фантом-merge, deploy-петли, транзиенты, флапп-статусы, зомби-jobs.
+
+- **D1.1** Предиктивный мониторинг (causal, не порог): «диск заполнится через N ч».
+- **D1.2** Авто-ремедиация рантайма: каталог типовых фиксов (зомби-job→requeue, stale-lease→reclaim, флапп→форс-терминал).
+- **D1.3** Транзиент-резилентность everywhere (обобщение ORCH-93): единый retry+backoff для всех внешних вызовов.
+- **D1.4** Zero-downtime деплой платформы (blue-green/canary): резервное плечо вместо окна недоступности.
+- **D1.5** Авто-rollback по SLO (расширение 21): откат по деградации latency/error-rate, не только health.
+- **D1.6** Deep agent-liveness (self-healing LLM): «думает / завис / зациклился» по reasoning+CPU+прогрессу.
+- **D1.7** Backup/restore БД+worktree (recovery после краша хоста).
+
+---
+
+## 4. ДОМЕН D2 — ✅ Качество / Доверие результата
+
+> Новый домен. Закрывает дыру: платформа может надёжно и дёшево производить плохой результат. Надёжность инфры ≠ корректность кода/аналитики.
+
+**Есть:** security-гейт (22), reviewer/tester стадии, промпт-аудит (92).
+
+- **D2.1** Code-coverage гейт (ORCH-27): защита от деградации покрытия.
+- **D2.2** Регресс-страж результата: не только «тесты зелёные», но «не сломали соседнюю фичу» (расширение regression-guard ORCH-73).
+- **D2.3** Качество аналитики: метрика «BRD не пришлось переделывать», сверка факт vs ТЗ (как сегодня ловила ложное P0).
+- **D2.4** Доверие к выходу: provenance артефактов, воспроизводимость, «деплой OK = прод реально работает» (урок ET-8).
+- **D2.5** Опциональная человеческая приёмка важных фич (ORCH-28).
+- **D2.6** Само-оценка агентов: уверенность в результате → эскалация при низкой.
+
+---
+
+## 5. ДОМЕН D3 — 💰 Экономика
+
+**Боль (ORCH-38):** developer сжёг **$13.68 на мелочь** (cache_read 18.98M — слепое сканирование src/).
+
+- **D3.1** Model-routing cascade (мир: −87%): классификатор сложности → дешёвая модель на простое, opus на сложное (ORCH-20+13).
+- **D3.2** Бюджет circuit-breaker (ORCH-23): хард-лимит $/токенов/времени → пауза+алерт.
+- **D3.3** Оценка задачи ДО старта (ORCH-20): прогноз $/время по истории.
+- **D3.4** Целевые файлы в задании (ORCH-38): analyst даёт точный список из TRZ → нет слепого сканирования. **Самый дешёвый высокий impact.**
+- **D3.5** Fast-track простых задач (ORCH-19): багфикс → урезанный цикл без architect, дешёвая модель.
+- **D3.6** Semantic caching / prompt compression (мир: −31%).
+- **D3.7** Cost-дашборд + детект аномалий.
+
+---
+
+## 6. ДОМЕН D4 — 🚀 Возможности (рост функционала)
+
+> **Равноценный домен (акцент Славы).** Это то, ради чего платформой ПОЛЬЗУЮТСЯ. Без новых возможностей надёжность бессмысленна — нечего надёжно делать. Развивается параллельно с D1-D3, а не после.
+
+**Backlog-зародыши:** ORCH-12/13/14/15/18/24/25.
+
+- **D4.1** Стеки-плагины: профили стека (web/mobile/data/ML/embedded) → агенты адаптируют процесс. Расширяемо без правки ядра. **Открывает заказчикам новые типы проектов.**
+- **D4.2** Android/мобильный стек (ORCH-15): полноценная разработка приложений.
+- **D4.3** UX/UI-дизайнер (ORCH-14): дизайнер-агент генерит макеты на аналитике, согласование с BRD.
+- **D4.4** Интерактивный аналитик (ORCH-18): живой диалог Слава↔analyst — уточнение BRD, обсуждение вариантов до старта. Удобство + качество постановки.
+- **D4.5** Тяжёлые вычисления (ORCH-12): воркер/стадия для долгих расчётов (ML-обучение, миграции данных).
+- **D4.6** База знаний проекта (ORCH-24): RAG-контекст решений/архитектуры — агенты умнее (+экономия).
+- **D4.7** Декомпозиция эпиков (ORCH-25): эпик→задачи→сборка автоматически (этот документ — кандидат №1).
+- **D4.8** Новые роли-агенты: data-engineer, ML-инженер, DevOps — по мере типов проектов.
+- **D4.9** Мультипровайдерность моделей (ORCH-13): не только Claude — выбор под задачу/стек/бюджет.
+
+---
+
+## 7. ДОМЕН D5 — 📈 Масштаб
+
+> Вторая «рука роста»: способность делать БОЛЬШЕ и ШИРЕ. Сейчас потолок — `max_concurrency=1`.
+
+**Backlog-зародыши:** ORCH-9/10; done: ORCH-6 (multi-repo), ORCH-88 (serial-batch).
+
+- **D5.1** Параллельная разработка (снять max_concurrency=1): безопасный N>1 (изоляция worktree есть, нужна merge-orchestration FIFO + защита main). **Много фич параллельно = быстрее растём.**
+- **D5.2** Turnkey-онбординг проекта (ORCH-9): команда → Plane+Gitea+агенты+инфра за минуты.
+- **D5.3** Тиражирование на новый хост (ORCH-10): перенос платформы на инфру нового заказчика (IaC-bundle).
+- **D5.4** Горизонтальный воркер-пул: очередь jobs (ORCH-1) → несколько воркеров/хостов.
+- **D5.5** Per-project лимиты ресурсов (concurrency/бюджет на проект).
+- **D5.6** Мультитенантность (отложено — SaaS-сценарий, по спросу).
+
+---
+
+## 8. ВЕРТИКАЛЬ-ДВИГАТЕЛЬ 🧠 — две турбины: реактивная + проактивная
+
+> Двигатель питается из ДВУХ источников (коррекция Славы 09.06). Реактивная турбина (уроки из боли) кормит «крепнем» (D1-D3). Проактивная (генератор идей) кормит «растём» (D4-D5). Без второй турбины рост фич зависит только от Славы — бутылочное горлышко.
+
+### 8A. Реактивная турбина 🔄 — петля самообучения из уроков (ORCH-8)
+```
+ДЕТЕКЦИЯ → ЖУРНАЛ урока → АНАЛИЗ/паттерны → ПРЕДЛОЖЕНИЕ задачи → [governance-гейт] → конвейер ORCH-7 → проверка эффекта → журнал
+```
+- **Детекция:** провал гейта, **ручное вмешательство (самый ценный сигнал — каждый ручной пинок = дыра автономности)**, ретраи/откаты/таймауты, ложные срабатывания, «деплой OK / прод сломан».
+- **Анализ (гибрид):** машина копит и предлагает черновик → Стрим фильтрует/оформляет → Слава апрувит.
+- **E1** Журнал уроков (=F2). **E2** Агент-ретроспективщик (анализ→предложение).
+
+### 8B. Проактивная турбина 💡 — генератор идей новых возможностей (НОВОЕ — запрос Славы)
+
+> Отдельный источник идей роста функционала — НЕ только требования от Славы. Проактивно предлагает новые фичи/возможности/удобства. Та же воронка: машина/агент генерит черновики → Стрим фильтрует → Слава решает.
+
+**Источники идей (вход генератора):**
+- **I1 Гэпы реализации:** чего НЕ хватило для запрошенных проектов (enduro-trails, snowbike — что было тяжело/невозможно сделать платформой → кандидат в фичу).
+- **I2 Паттерны ручного труда:** что Слава/заказчики часто делают руками ВНЕ платформы → кандидат на автоматизацию/фичу.
+- **I3 Тренды и новые технологии:** сканирование новых моделей/стеков/инструментов (web-поиск, release-notes провайдеров) → «вышла модель X / фреймворк Y — даёт новую возможность».
+- **I4 Конкурентный/рыночный анализ:** что умеют другие AI-платформы разработки (Devin, Cursor, Copilot Workspace…) → чего нет у нас.
+- **I5 Анализ собственного бэклога/истории:** паттерны типов задач → «часто просят X → стоит сделать шаблон/фичу».
+- **I6 Обратная связь заказчиков:** явные пожелания/жалобы по реализованным проектам.
+- **I7 Саморефлексия Стрим:** я вижу работу платформы изнутри каждый день — предлагаю удобства/фичи из опыта ведения.
+
+**Компоненты:**
+- **E4 Агент-идеатор (product-discovery):** по расписанию сканирует I1-I7 → генерит бэклог идей-черновиков фич (с обоснованием «зачем/кому/из какого источника»).
+- **E5 Банк идей:** отдельный реестр (не путать с журналом уроков): идея, источник, предполагаемая ценность, статус (new/отклонена/в работе).
+
+### 8C. Общий выход двигателя
+- **E3 Приоритизатор RICE:** сводит ОБА потока (уроки из 8A + идеи из 8B) в единый ранжированный бэклог по impact/cost/risk — что брать первым по всем доменам. Баланс «крепнем vs растём» — настраиваемый (квота слотов на надёжность vs фичи).
+
+---
+
+## 9. ВЕРТИКАЛЬ-ТОРМОЗ 🛑 — Governance / Safety
+
+> «Контроль и управление саморазвитием» (требование Славы). Двигатель жмёт газ — этот контур держит руль и тормоз.
+
+**Принцип (ORCH-8, незыблемо):** самомодификация платформы (промпты/скиллы/конфиги агентов/ядро) — ТОЛЬКО через PR+ревью+апрув Славы. Орк ПРЕДЛАГАЕТ, ПРИМЕНЯЕТ через свой конвейер с гейтами.
+
+**Уровни автономии (agentic AIOps maturity):**
+| Уровень | Что авто | Гейт |
+|---------|----------|------|
+| L0 reactive | только алерт | человек делает всё |
+| L1 assistive | предложить задачу+ТЗ | человек апрувит запуск |
+| L2 autonomous-bounded | гонит безопасные классы (бэкенд-фиксы) до прода | safety-гейты CI/staging/regression |
+| L3 self-modifying | менять агентов/ядро | **всегда** PR+апрув Славы, НИКОГДА не авто |
+
+- **G1** Safety-политика L0-L3 + per-class правила (что можно само, что только через Славу). Лейблы autoApprove/autoDeploy (ORCH-89) = уже зародыш.
+- **G2** Бюджет на саморазвитие: лимит $/мес, чтобы контур не жёг бесконтрольно.
+- **G3** Дашборд эволюции: метрики 5 доменов в динамике — видно, КУДА развивается платформа.
+- **G4** Kill-switch петли: остановить самогенерацию задач одним флагом.
+
+---
+
+## 10. 🌡️ Градусник автономности (сквозная метрика)
+
+Объединяющая измеримая цель эпика. Каждый домен двигает её вверх:
+- **% задач без ручного пинка** (сегодня было ~5 вмешательств: апрувы, домерж 063, sync 061).
+- **Ручных вмешательств / неделю** (тренд вниз).
+- **MTBF / MTTR** платформы (D1).
+- **$/задача, токены/задача, время/задача** (D3).
+- **Типов проектов/стеков поддержано** (D4).
+- **Задач параллельно** (D5).
+- **% уроков, ставших задачами** (двигатель).
+
+---
+
+## 11. Связь с Backlog (ничего не теряем)
+
+| Backlog | Домен/вертикаль |
+|---------|-----------------|
+| ORCH-8 петля | 🧠 Двигатель (ядро) |
+| ORCH-83 наблюдаемость | Фундамент F1 |
+| ORCH-20/23/38/19 | 💰 D3 |
+| ORCH-27/28 | ✅ D2 |
+| ORCH-12/13/14/15/18/24/25 | 🚀 D4 |
+| ORCH-9/10 | 📈 D5 |
+| ORCH-94 флапп | 🛡️ D1.2 |
+| ORCH-89 авто-лейблы | 🛑 G1 |
+
+~18 backlog-задач ложатся в структуру. Эпик их систематизирует и достраивает.
+
+---
+
+## 12. Дорожная карта (предложение)
+
+1. **Фаза 0 (фундамент):** F1 наблюдаемость + F2 журнал. Без них рулить нечем.
+2. **Фаза 1 (две руки параллельно):**
+   - крепнем: D3.4 целевые файлы + D3.2 бюджет-breaker (дешёвый impact)
+   - растём: D4.1 стеки-плагины ИЛИ D4.4 интерактив-аналитик (по спросу)
+3. **Фаза 2:** D1 надёжность (транзиент-резилентность, авто-ремедиация) + D2 качество + D5.1 параллелизм.
+4. **Фаза 3 (мозг):** E2 ретроспективщик + E3 приоритизатор + G1 safety-политика → петля замыкается, дальше платформа предлагает сама.
+
+---
+
+## ⛓️ Реализация в Plane (решено 09.06)
+
+**Ось ДОМЕНА → модули Plane** (1 задача = 1 модуль; slug в `external_id`, name с эмодзи для человека):
+
+| Модуль (name) | slug (external_id) | module_id |
+|---|---|---|
+| 👁️ Фундамент | `foundation` | 74dee25a-a44b-4c3b-ab55-1b5638b8cc1f |
+| 🧠 Мозг | `brain` | ab1afa08-14ce-4b7d-8ebc-e45ac19b2ba7 |
+| 🛡️ Надёжность | `reliability` | abd7479e-4f9b-4a56-a926-cb2ece7558ca |
+| ✅ Качество | `quality` | cbf5f8ca-dc1a-4dee-9d35-555459de2b30 |
+| 💰 Экономика | `economy` | 9b4bbab3-95d6-4b8a-8d72-379a618ea2f3 |
+| 🚀 Возможности | `features` | baa6936c-6a39-4935-ad57-31ef5ffc3041 |
+| 📈 Масштаб | `scale` | 18373528-14fa-4627-a0f6-32497ff22177 |
+
+**Ось ВЕРТИКАЛЬ → лейблы** (могут быть несколько, список короткий):
+- `engine` (36f398f7-5a1c-4eeb-847a-56c457e1da6b) — задача пришла от петли/идеатора.
+- `governance` (9eea4dd8-0fe7-473a-8c40-630fc3ab0d25) — требует апрува L3 / safety-внимания.
+- (+ существующие `autoApprove`/`autoDeploy` — ортогональны, режим автономности.)
+
+**Правило раскладки:** каждая задача эпика = 1 модуль-домен (по slug) + 0..N вертикаль-лейблов. Орк ищет/привязывает по `external_id` (не по русскому имени).
+
+⚠️ **Порядок модулей на доске:** Plane API игнорирует `sort_order` на запись (только drag-and-drop в UI). Сейчас порядок перевёрнут (Масштаб сверху) — Славе поправить мышкой (фундамент→мозг→надёжность→качество→экономика→возможности→масштаб). На машинную логику не влияет (орк по slug).
+
+---
+
+## 13. Открытые вопросы Славе
+
+1. **Структура Plane:** мега-эпик с фундаментом+5 доменами+2 вертикалями? Или эпик на каждый домен?
+2. **D4 (возможности):** какой стек/фича приоритетны для тебя/заказчиков — Android, UX/UI, тяжёлые расчёты, интерактив-аналитик? С чего рост начинать?
+3. **Баланс «крепнем vs растём»:** идти строго параллельно обеими руками, или в каждой фазе перевес в одну сторону?
+4. **Safety L3:** подтверждаешь — самомодификация ядра/агентов всегда через твой апрув?
+5. **Двигатель (E2/E4):** ретроспективщик + агент-идеатор сразу как агенты, или сначала Стрим ведёт журнал/банк идей вручную?
+8. **Генератор идей (8B):** какие из источников I1-I7 тебе ценнее (гэпы проектов / тренды-технологии / конкуренты / саморефлексия Стрим)? Генерить автономно или только по твоему запросу?
+6. **Бюджет на эпик (G2):** лимит $/мес?
+7. **Первая задача** после апрува: F1 наблюдаемость, быстрая победа D3.4, или сразу рост D4.*?

docs/work-items/ORCH-027/00-business-request.md

@@ -0,0 +1,7 @@
+# Business Request: Code coverage как гейт (защита от деградации покрытия тестами)
+
+Work Item ID: ORCH-027
+
+## Description
+
+TBD

docs/work-items/ORCH-027/01-brd.md

@@ -0,0 +1,166 @@
+---
+work_item: ORCH-027
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 01 — BRD (бизнес-требования): ORCH-027 — Code coverage как гейт (защита от деградации покрытия тестами)
+
+Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: analysis
+
+## 1. Бизнес-контекст и проблема
+
+Оркестратор ведёт **автономную** разработку: код пишет агент `developer` без человеческого
+фильтра, а на стадии `testing` агент `tester` сам решает, достаточно ли тестов. Существующие
+тестовые гейты проверяют только **факт прохождения** тестов, а не их **полноту**:
+
+- `check_ci_green` (ребро `development → review`) — зелёный прогон `pytest tests/` в Gitea CI
+  (`.gitea/workflows/ci.yml`), судит по exit-code, покрытие **не меряет**.
+- `check_tests_passed` (ребро `testing → deploy-staging`) — читает machine-verdict
+  `result:`/`verdict:`/`status:` из `13-test-report.md`; это вердикт LLM-`tester`'а, а не
+  измеренная метрика.
+- Merge-gate re-test (ORCH-043) — повторный `pytest` на догнанной ветке, тоже только exit-code.
+
+Ни один гейт не замечает, что фича добавила 300 строк кода и 0 тестов, или что багфикс
+изменил поведение без регрессионного теста. При пакетном автономном прогоне (эпик ORCH-088,
+«10–20 задач за ночь») это означает **монотонную деградацию покрытия**: каждая задача может
+«срезать угол» на тестах, и за десятки задач проект тихо теряет тестируемость. Предложено
+Стрим, одобрено Славой (`00-business-request.md`).
+
+**Задача вводит измеримый гейт покрытия**: покрытие тестами измеряется инструментально и не
+должно опускаться ниже политики (абсолютный порог и/или «не ниже базовой линии»). Это
+структурная защита от деградации, аналогичная по духу security-гейту (ORCH-022) —
+детерминированная метрика вместо доверия суждению агента.
+
+> **Self-hosting.** Гейт работает на инструменте, который в проде обслуживает все проекты из
+> общей БД и очереди (`CLAUDE.md` §self-hosting). Измерение покрытия — это исполнение тест-сьюта
+> в изолированном worktree; оно **не трогает прод-контейнер и не касается `main`**.
+
+## 2. Объём (scope)
+
+### В объёме
+- Инструментальное измерение покрытия тестами для репозитория `orchestrator` (стек Python /
+  pytest) перед слиянием ветки задачи в `main`.
+- Гейт-решение: покрытие **не ниже** заданной политики порога. Политика поддерживает два режима:
+  абсолютный порог (`%`) и «не ниже базовой линии» (no-regression / ratchet), а также их
+  комбинацию.
+- Хранение и обновление **базовой линии** покрытия (last-known покрытие `main`).
+- Наблюдаемость результата: артефакт-отчёт о покрытии с machine-readable вердиктом, строка в
+  `GET /queue`, сигнал в Telegram при провале.
+- Конфигурируемость: kill-switch + per-repo область + настраиваемый порог/политика +
+  поведение при ошибке инструмента (fail-open/closed).
+
+### Вне объёма
+- Реализация измерения покрытия для НЕ-Python стеков (jest / jacoco для будущих репозиториев) —
+  фактическая интеграция инструментов оставлена на будущее; в ORCH-027 закладывается лишь
+  расширяемость (политика и хранилище не должны быть жёстко завязаны на Python).
+- Изменение существующей семантики `check_ci_green` / `check_tests_passed` /
+  `check_reviewer_verdict` для репозиториев, где гейт покрытия выключен.
+- Принудительное доведение покрытия до 100% или установка агрессивного абсолютного порога —
+  стартовая политика консервативна (см. NFR-4).
+- Покрытие самих тестовых файлов и мутационное тестирование.
+- Выбор конкретного инструмента/механизма интеграции и его расположения в конвейере как
+  архитектурного решения — это зона архитектора (`06-adr/`); BRD/ТЗ фиксируют требования и
+  кандидатные точки, выведенные из фактического кода.
+
+## 3. Заинтересованные стороны
+
+- **Заказчик / инициатор:** Стрим (предложение), Слава (одобрение).
+- **Затрагиваются:** конвейер `orchestrator` (self-hosting); агенты `developer`/`tester`
+  (теперь обязаны держать покрытие); проект enduro-trails — **не должен быть затронут** (гейт
+  по умолчанию неактивен вне сконфигурированных репозиториев).
+- **Принимает результат:** reviewer (стадия `review`) + финальная стадия конвейера; владелец
+  (Owner) — по факту работы гейта в проде.
+
+## 4. Бизнес-требования (BR)
+
+- **BR-1 — Измерение покрытия.** Перед слиянием ветки задачи в `main` покрытие тестами
+  репозитория измеряется инструментально (исполнением тест-сьюта под coverage-инструментацией),
+  а не оценивается на глаз. Результат — числовая метрика покрытия (как минимум line coverage).
+- **BR-2 — Гейт деградации.** Если измеренное покрытие нарушает политику (ниже абсолютного
+  порога ИЛИ ниже базовой линии — в зависимости от выбранного режима), конвейер **не
+  пропускает** задачу дальше к деплою и инициирует штатный откат на `development` для доработки
+  тестов.
+- **BR-3 — Базовая линия (ratchet).** Поддерживается режим «не ниже предыдущего»: гейт
+  сравнивает покрытие ветки с зафиксированной базовой линией `main`. Базовая линия **обновляется
+  вверх** при успешном слиянии задачи в `main` (покрытие может только расти или держаться, но
+  не падать).
+- **BR-4 — Конфигурируемость и нулевая регрессия.** Гейт управляется kill-switch'ем и
+  per-repo областью (по образцу `merge_gate`/`security_gate`/`image_freshness`,
+  ORCH-035/043/058). Для репозиториев вне области (в частности enduro-trails) гейт — **полный
+  no-op**, поведение конвейера 1:1 как до задачи. Порог, политика (absolute|baseline|both) и
+  поведение при ошибке инструмента — настраиваемы.
+- **BR-5 — Наблюдаемость.** Результат измерения виден: (а) артефакт-отчёт о покрытии с
+  machine-readable вердиктом в `docs/work-items/<id>/`; (б) read-only блок в `GET /queue`;
+  (в) уведомление в Telegram при провале гейта (кликабельный номер задачи, как у прочих
+  алертов). Сообщение указывает измеренное покрытие, порог/базовую линию и дельту.
+- **BR-6 — Стек-расширяемость.** Логика политики (PASS/FAIL по метрике/базовой линии) и
+  хранилище базовой линии не зависят от конкретного инструмента; добавление измерителя для
+  другого стека (jest/jacoco) в будущем не требует переписывания ядра гейта.
+
+## 5. Нефункциональные требования (NFR)
+
+- **NFR-1 — never-raise / fail-safe.** Ядро гейта — изолированный leaf-модуль (по образцу
+  `src/security_gate.py`, `src/serial_gate.py`, `src/labels.py`): любая внутренняя ошибка
+  обрабатывается, исключение **никогда** не всплывает в `advance_stage` и не роняет конвейер
+  всех проектов.
+- **NFR-2 — Поведение при недоступности/ошибке инструмента.** По умолчанию ошибка измерения
+  (coverage-инструмент упал/недоступен) → **fail-open + громкий warning** (анти-петля,
+  прецедент ORCH-061/ORCH-022 dep-audit), переключаемое в fail-closed флагом. Дефолт не должен
+  заклинивать автономный конвейер из-за инфраструктурного сбоя.
+- **NFR-3 — Self-hosting безопасность.** Гейт только исполняет тесты в изолированном worktree,
+  читает метрику, пишет отчёт и принимает решение. Он **никогда** не вызывает деплой-хук, не
+  перезапускает прод-контейнер, не пушит/форс-пушит в `main`.
+- **NFR-4 — Консервативный старт (анти-флап).** Стартовая политика не должна массово заворачивать
+  существующие задачи: базовая линия инициализируется фактическим покрытием `main`, абсолютный
+  порог — как мягкий backstop. Допускается малый отрицательный допуск (epsilon) на шум измерения,
+  чтобы дрожание ±доли процента не заворачивало задачу.
+- **NFR-5 — Совместимость.** `STAGE_TRANSITIONS`, состав/семантика `QG_CHECKS` и `check_*`,
+  machine-verdict ключи существующих доков (`verdict:`/`result:`/`deploy_status:`/
+  `staging_status:`/`security_status:`) — не меняются. Любая новая БД-сущность — аддитивна
+  (без миграции существующих таблиц). Restart-safe.
+- **NFR-6 — Детерминизм.** Решение гейта — чистая функция от (измеренное покрытие, базовая
+  линия, порог, политика); без участия LLM в критическом пути (как security/merge/image-freshness
+  под-гейты).
+
+## 6. Допущения и ограничения
+
+- Тест-сьют `orchestrator` запускается командой `python -m pytest tests/` из корня репозитория
+  (подтверждено `.gitea/workflows/ci.yml`, `pytest.ini` `testpaths = tests`); измерение покрытия
+  накладывается на этот же прогон.
+- Coverage-инструмент для Python (`coverage.py` / `pytest-cov`) добавляется как pip-зависимость;
+  он не требует сети во время измерения.
+- Репозиторий `orchestrator` — единственный self-hosting (предикат `is_self_hosting_repo`);
+  стартовая область гейта — он. enduro-trails и прочие репозитории по умолчанию вне области.
+- Базовая линия привязана к покрытию `main`; её первичная инициализация выполняется один раз
+  (bootstrap) фактическим замером текущего `main`.
+- Тесты исполняются в per-branch worktree (`ensure_worktree`), что безопасно при параллельных
+  активных задачах (прецедент `check_tests_local`/merge-gate re-test).
+
+## 7. Критерии успеха
+
+- Покрытие тестами `orchestrator` измеряется на каждой задаче и не может опуститься ниже
+  политики, не заблокировав продвижение к деплою.
+- При выключенном флаге / вне области — конвейер ведёт себя 1:1 как до ORCH-027 (нулевая
+  регрессия для enduro-trails).
+- Сбой coverage-инструмента не заклинивает автономный конвейер (дефолт fail-open + warning).
+- Результат измерения прозрачен (отчёт + `GET /queue` + Telegram при провале).
+
+Детальные PASS/FAIL — `03-acceptance-criteria.md`.
+
+## 8. Риски
+
+- **Флап на шуме измерения** — недетерминированное покрытие (например, зависящее от порядка/
+  окружения) может дрожать у границы → ложные заворота. Митигировать epsilon-допуском (NFR-4).
+- **Петля заворотов** — слишком высокий абсолютный порог завернёт многие задачи в бесконечный
+  rework. Митигировать консервативной стартовой политикой и baseline-режимом.
+- **Гонка базовой линии** при параллельных слияниях — два слияния в `main` могут конкурентно
+  обновлять baseline. Требуется атомарное/сериализованное обновление (опереться на окно
+  сериализации merge-lease, ORCH-043).
+- **Инфраструктурная хрупкость** — coverage-инструмент недоступен/несовместим с версией pytest →
+  закрыто требованием NFR-2 (fail-open + warning).
+
+Детальная техническая проработка рисков — `10-tech-risks.md` (заполняет архитектор).

docs/work-items/ORCH-027/02-trz.md

@@ -0,0 +1,156 @@
+---
+work_item: ORCH-027
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 02 — ТЗ (TRZ): ORCH-027 — Code coverage как гейт
+
+Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: analysis
+
+> ТЗ описывает **конкретные требования к реализации**, выведенные из BRD и фактического кода.
+> Архитектурное обоснование и выбор механизма (где именно врезать гейт, как хранить базовую
+> линию, какой инструмент) — задача архитектора (`06-adr/`). Ниже зафиксированы требования и
+> **кандидатные** точки интеграции, грунтованные реальным кодом; финальное решение по каждой
+> отмеченной точке принимает архитектор.
+
+## 1. Сводка изменения
+
+Вводится **детерминированный гейт покрытия тестами** для репозитория `orchestrator`. Гейт
+измеряет покрытие исполнением тест-сьюта под coverage-инструментацией, сравнивает с политикой
+(абсолютный порог и/или базовая линия `main`) и блокирует продвижение задачи к деплою при
+деградации, инициируя штатный откат на `development`. Ядро — изолированный leaf-модуль с чистой
+логикой решения (по образцу `security_gate`/`serial_gate`), управляемый kill-switch'ем и per-repo
+областью; вне области — полный no-op. Базовая линия покрытия `main` хранится персистентно и
+обновляется вверх при слиянии (ratchet).
+
+## 2. Задействованные модули / пути
+
+| Путь | Действие | Назначение |
+|------|----------|-----------|
+| `requirements.txt` | изменить | добавить coverage-зависимость Python (`coverage.py` / `pytest-cov`; точный выбор — архитектор) |
+| `src/coverage_gate.py` | создать | **NEW leaf-модуль**: измерение покрытия (run suite под coverage в `ensure_worktree`), чистые функции `compute_coverage_verdict(measured, baseline, floor, policy, epsilon)` и классификация, чтение/запись отчёта; never-raise; импортирует только `config`/`git_worktree` (+ лениво `qg.checks.is_self_hosting_repo`/`notifications`) |
+| `src/config.py` | изменить | добавить флаги гейта (см. §6 ниже / раздел совместимости) |
+| `src/qg/checks.py` | изменить | зарегистрировать механизм проверки покрытия (новый `check_*` ЛИБО делегирование из под-гейта); **семантика существующих `check_*` не меняется** |
+| `src/stage_engine.py` | изменить *(кандидат)* | врезка под-гейта в `advance_stage` по образцу `_handle_security_gate`/`_handle_merge_gate` — если выбран механизм «edge sub-gate» (см. §3 FR-3) |
+| `src/db.py` | изменить *(кандидат)* | аддитивная таблица базовой линии покрытия (`coverage_baseline` per-repo), если базовая линия хранится в БД, а не в файле; `_ensure_column`/`CREATE TABLE IF NOT EXISTS` — без миграции существующих |
+| `.gitea/workflows/ci.yml` | изменить *(кандидат)* | если измерение делается в CI-шаге — добавить `--cov`/порог в прогон pytest; **точка измерения — решение архитектора** |
+| `src/main.py` | изменить | read-only блок `coverage` в `GET /queue` (наблюдаемость) |
+| `docs/work-items/<id>/<NN>-coverage-report.md` | создать (артефакт run-time) | отчёт о покрытии с machine-readable вердиктом (см. §4/§6); номер/имя и регистрация в `docs/_standards/PIPELINE_DOCS.md` + скелет в `docs/_templates/` — оформляет архитектор |
+| `tests/test_coverage_gate.py` | создать | unit/integration по `04-test-plan.yaml` |
+
+## 3. Функциональные требования
+
+### FR-1 — Измерение покрытия (привязка BR-1)
+Гейт исполняет тест-сьют `orchestrator` (`python -m pytest tests/`, см. `.gitea/workflows/ci.yml`)
+под coverage-инструментацией в изолированном per-branch worktree (`ensure_worktree`, прецедент
+`check_tests_local`) и извлекает числовую метрику покрытия (как минимум суммарный line coverage,
+`%`). Тайм-аут на прогон ограничен (по образцу `merge_retest_timeout_s` / `security_scan_timeout_s`).
+
+### FR-2 — Решение гейта (привязка BR-2, BR-3)
+Чистая функция `compute_coverage_verdict(measured, baseline, floor, policy, epsilon) -> (ok, reason)`:
+- `policy = absolute` → PASS ⇔ `measured >= floor - epsilon`.
+- `policy = baseline` → PASS ⇔ `measured >= baseline - epsilon`.
+- `policy = both` (дефолт) → PASS ⇔ выполнены оба условия.
+- FAIL → гейт инициирует штатный откат на `development` для доработки тестов (по образцу
+  `_handle_security_gate` / merge-gate rollback), с инкрементом счётчика developer-retry.
+- `epsilon` — малый неотрицательный допуск на шум измерения (NFR-4), настраиваемый.
+
+### FR-3 — Точка в конвейере (привязка BR-2; **кандидат, решает архитектор**)
+Бизнес-запрос указывает «на testing-гейте». Грунтованные кодом кандидаты (выбрать один):
+- **(a) Edge sub-gate** в `advance_stage` на ребре `deploy-staging → deploy` (рядом с
+  `_handle_security_gate`/`_handle_merge_gate`/`_handle_image_freshness`) — даёт гарантию «гейт
+  ДО слияния в `main`», детерминирован, владеет исходом на вмешательстве. Предпочтительно для
+  соответствия NFR-3/NFR-6.
+- **(b) Под-гейт/расширение на ребре `testing → deploy-staging`** (рядом с `check_tests_passed`).
+- **(c) CI-шаг** в `.gitea/workflows/ci.yml` (ребро `development → review`, читается
+  `check_ci_green`) — порог проверяется самим pytest-прогоном.
+Требование, инвариантное к выбору: гейт обязан отработать **до фактического merge в `main`** и не
+пропускать деградацию в `main`.
+
+### FR-4 — Базовая линия и её обновление (привязка BR-3)
+- Персистентное per-repo хранилище базовой линии покрытия `main` (БД-таблица ИЛИ файл в репо —
+  решает архитектор; при БД — аддитивная таблица, NFR-5).
+- Bootstrap: первичная инициализация фактическим замером текущего `main`.
+- Ratchet-up: при успешном слиянии задачи в `main` базовая линия обновляется значением
+  смёрженного покрытия, **только если оно ≥ текущей** (покрытие не откатывается вниз). Обновление
+  должно быть атомарным/сериализованным относительно параллельных слияний (опереться на окно
+  merge-lease, ORCH-043).
+
+### FR-5 — Условность и kill-switch (привязка BR-4)
+- `coverage_gate_enabled=False` → гейт инертен, конвейер 1:1 как до ORCH-027.
+- `coverage_gate_repos` (CSV) — область применения; **пусто → только self-hosting**
+  (`is_self_hosting_repo`, по образцу `merge_gate`/`security_gate`/`image_freshness`).
+- Вне области → no-op `(True, "Coverage gate N/A")` (прецедент `check_staging_status` для
+  не-self-hosting, ORCH-035).
+- `applies(repo)` (локальная проверка) выполняется ПЕРВОЙ; дорогой прогон измерения — только при
+  `applies==True`.
+
+### FR-6 — Поведение при ошибке инструмента (привязка NFR-2)
+Ошибка/недоступность coverage-инструмента или невозможность распарсить метрику → по умолчанию
+**fail-open + WARNING** (`coverage_tool_fail_closed=False`, прецедент `security_dep_audit_fail_closed`);
+флаг переключает в fail-closed. Поведение логируется явной observability-строкой.
+
+### FR-7 — Наблюдаемость (привязка BR-5)
+- Артефакт-отчёт `<NN>-coverage-report.md` с machine-readable вердиктом (см. §4).
+- Read-only блок `coverage` в `GET /queue` (per-repo: `enabled`/`policy`/`floor`/`baseline`/
+  последнее измеренное/вердикт).
+- При FAIL — `send_telegram` (notifying) с кликабельным номером задачи (`plane_issue_link`),
+  измеренным покрытием, порогом/базовой линией и дельтой.
+
+## 4. Изменения API
+
+- **`GET /queue`** — добавить read-only блок `coverage` (наблюдаемость; форма прочих блоков
+  `serial_gate`/`security`/`merge`). Без изменения существующих полей ответа.
+- **Опционально (решает архитектор):** ручной эндпоинт сброса/override базовой линии
+  (`POST /coverage/baseline?repo=…`) — по образцу `POST /serial-gate/unfreeze`, на случай
+  легитимного разового снижения покрытия. Если не вводится — override выполняется через конфиг.
+- Существующие webhook-роуты (`/webhook/plane`, `/webhook/gitea`) — без изменений.
+
+## 5. Изменения схемы БД
+
+Зависит от выбора хранилища базовой линии (FR-4):
+- **Если БД:** аддитивная таблица `coverage_baseline(repo TEXT PRIMARY KEY, coverage REAL,
+  updated_at, source_sha TEXT)` через `CREATE TABLE IF NOT EXISTS` (паттерн `repo_freeze`/
+  `job_deps`). Существующие таблицы — **не мигрируются** (NFR-5).
+- **Если файл в репо:** изменений схемы БД нет (базовая линия — версионируемый файл вроде
+  `.coverage-baseline.json`, читаемый/обновляемый под merge-lease).
+
+Выбор — архитектор; ТЗ требует лишь: персистентность, restart-safe, аддитивность, атомарность
+обновления.
+
+## 6. Требования к новым/изменённым QG checks
+
+- **Новый машинный вердикт покрытия.** Если гейт реализован как edge sub-gate (FR-3a/b), он
+  **сам вычисляет** вердикт (как `check_security_gate`) и пишет отчёт `<NN>-coverage-report.md`
+  с frontmatter-ключом `coverage_status:` (`PASS` | `FAIL`), читаемым обратно из того же файла
+  (single source of truth, по образцу `security_status:` в `17-security-report.md`). Имя ключа
+  фиксируется и регистр чувствителен.
+- **Реестр `QG_CHECKS`.** Допустимо добавить `check_coverage_gate` в реестр (если механизм —
+  зарегистрированный QG) ЛИБО оставить его врезкой-под-гейтом (как security/merge/image-freshness,
+  которые в `QG_CHECKS` присутствуют, но исполняются как врезки). **Семантика и состав
+  существующих `check_*` — без изменений** (NFR-5).
+- **Парсинг frontmatter** вердикта — через единый контракт `src/frontmatter.py`
+  (`parse_frontmatter`/`read_frontmatter_value`), как все вердикт-парсеры (ORCH-052c). Если
+  отчёт несёт обязательную 6-польную схему 52c — добавить её аддитивно, не трогая `coverage_status:`.
+
+## 7. Совместимость / регресс
+
+- **Обратная совместимость:** при `coverage_gate_enabled=False` или для репозитория вне
+  `coverage_gate_repos` — поведение конвейера байт-в-байт прежнее; enduro-trails не затронут.
+- **Kill-switch + поэтапный раскат:** `coverage_gate_enabled` (глобальный), `coverage_gate_repos`
+  (область). Старт — только `orchestrator`.
+- **Конфиг-флаги (итог §3/§6):** `coverage_gate_enabled` (bool), `coverage_gate_repos` (CSV),
+  `coverage_min_percent` (float, абсолютный порог), `coverage_policy` (`absolute|baseline|both`,
+  дефолт `both`), `coverage_epsilon` (float, допуск шума), `coverage_tool_fail_closed` (bool,
+  дефолт `False`), `coverage_run_timeout_s` (int). Имена env — `ORCH_COVERAGE_*`.
+- **never-raise / fail-open в hot-path:** ядро не роняет `advance_stage`; ошибка инструмента →
+  fail-open + warning по умолчанию (NFR-2). Прод-контейнер/`main`/force-push — не трогаются (NFR-3).
+- **Restart-safe:** базовая линия персистентна; in-flight измерение при рестарте переигрывается
+  штатным механизмом стадии (idempotent).
+- **Документация (golden source):** при выборе механизма архитектор регистрирует артефакт
+  `<NN>-coverage-report.md` и его machine-key в `docs/_standards/PIPELINE_DOCS.md` +
+  `docs/_templates/`, и обновляет `docs/architecture/README.md` и `CHANGELOG.md` в том же PR.

docs/work-items/ORCH-027/03-acceptance-criteria.md

@@ -0,0 +1,138 @@
+---
+work_item: ORCH-027
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 03 — Критерии приёмки (Acceptance Criteria): ORCH-027 — Code coverage как гейт
+
+Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: analysis
+
+Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL**
+(что считается провалом). Любой машинный/ручной reviewer проверяет их буквально по файлам
+репозитория.
+
+---
+
+## AC-1 — Покрытие измеряется инструментально
+
+**Условие:** на применимом репозитории конвейер измеряет покрытие тестами исполнением сьюта под
+coverage-инструментацией перед слиянием в `main`.
+- **PASS:** в коде есть путь, который запускает `pytest` под coverage в изолированном worktree и
+  извлекает числовую метрику line coverage (`%`); coverage-зависимость добавлена в `requirements.txt`.
+- **FAIL:** покрытие не измеряется инструментально, метрика берётся из прозы/вердикта LLM, либо
+  зависимость не объявлена.
+
+---
+
+## AC-2 — Гейт блокирует деградацию
+
+**Условие:** покрытие ниже политики не пропускается дальше к деплою.
+- **PASS:** при измеренном покрытии ниже порога/базовой линии (с учётом epsilon) гейт даёт FAIL и
+  инициирует штатный откат на `development` (инкремент developer-retry), задача не достигает `done`.
+- **FAIL:** задача с упавшим покрытием проходит гейт и продвигается к деплою/`done`.
+
+---
+
+## AC-3 — Чистая функция решения
+
+**Условие:** вердикт — детерминированная чистая функция от (measured, baseline, floor, policy, epsilon).
+- **PASS:** `compute_coverage_verdict(...)` покрыта unit-тестами для всех режимов
+  (`absolute`/`baseline`/`both`), границ (равно порогу), epsilon-допуска; без участия LLM.
+- **FAIL:** решение принимает LLM, либо логика недетерминирована/не покрыта тестами границ.
+
+---
+
+## AC-4 — Режим базовой линии (ratchet)
+
+**Условие:** поддержан режим «не ниже предыдущего» с обновлением базовой линии вверх при слиянии.
+- **PASS:** базовая линия персистентна per-repo; при слиянии обновляется значением смёрженного
+  покрытия только если оно ≥ текущей; bootstrap инициализирует её фактическим покрытием `main`;
+  обновление атомарно/сериализовано относительно параллельных слияний.
+- **FAIL:** базовая линия не хранится / откатывается вниз / обновляется неатомарно (гонка двух
+  слияний теряет/занижает значение).
+
+---
+
+## AC-5 — Условность и нулевая регрессия
+
+**Условие:** вне области / при выключенном флаге — поведение конвейера 1:1 как до ORCH-027.
+- **PASS:** при `coverage_gate_enabled=False` или repo ∉ `coverage_gate_repos` гейт — no-op
+  (`(True, "...N/A")`); существующая тестовая база (`pytest tests/`) зелёная; enduro-trails не
+  затронут; `applies(repo)` проверяется до дорогого прогона.
+- **FAIL:** гейт срабатывает вне области, либо выключенный флаг меняет поведение, либо есть
+  регресс существующих тестов.
+
+---
+
+## AC-6 — Fail-open по умолчанию при ошибке инструмента
+
+**Условие:** сбой/недоступность coverage-инструмента не заклинивает автономный конвейер.
+- **PASS:** при ошибке измерения и `coverage_tool_fail_closed=False` гейт даёт PASS + WARNING-лог
+  (observability-строка); флаг `=True` переключает в fail-closed (FAIL). Поведение покрыто тестом.
+- **FAIL:** ошибка инструмента по умолчанию заворачивает задачу (петля rework) либо роняет
+  `advance_stage`.
+
+---
+
+## AC-7 — never-raise / self-hosting безопасность
+
+**Условие:** ядро гейта не роняет конвейер и не трогает прод/`main`.
+- **PASS:** `src/coverage_gate.py` — leaf (не импортирует `stage_engine`); любое исключение
+  перехвачено и не всплывает в `advance_stage`; код не вызывает деплой-хук, не перезапускает
+  прод-контейнер, не пушит/форс-пушит в `main`/`master`.
+- **FAIL:** исключение из гейта всплывает в `advance_stage`; гейт трогает прод-контейнер или `main`.
+
+---
+
+## AC-8 — Совместимость контрактов
+
+**Условие:** существующие машинные контракты не изменены.
+- **PASS:** `STAGE_TRANSITIONS`, семантика существующих `check_*`, machine-verdict ключи
+  (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`) — байт-в-байт
+  прежние; любая новая БД-сущность аддитивна (без миграции существующих таблиц).
+- **FAIL:** изменена семантика/имя существующего гейта или вердикт-ключа; миграция ломает
+  существующую схему.
+
+---
+
+## AC-9 — Машинный вердикт покрытия и наблюдаемость
+
+**Условие:** результат измерения прозрачен и машинно читаем.
+- **PASS:** при FAIL — Telegram-алерт с кликабельным номером задачи, измеренным покрытием,
+  порогом/базовой линией и дельтой; `GET /queue` несёт read-only блок `coverage`; артефакт-отчёт
+  с machine-readable вердиктом (`coverage_status: PASS|FAIL`) записан и читается обратно из того
+  же файла через `src/frontmatter.py`.
+- **FAIL:** результат не виден в `GET /queue`/Telegram, либо вердикт парсится из прозы, а не из
+  frontmatter, либо имя ключа не зафиксировано (регистр).
+
+---
+
+## AC-10 — Документация обновлена (golden source)
+
+**Условие:** документация синхронизирована с изменением в том же PR.
+- **PASS:** если введён артефакт-отчёт — он зарегистрирован в `docs/_standards/PIPELINE_DOCS.md`
+  и `docs/_templates/`; обновлены `docs/architecture/README.md` (описание гейта/флагов) и
+  `CHANGELOG.md`; новые/изменённые инварианты несут маркер `ORCH-027`.
+- **FAIL:** функционал введён без обновления обзорной/стандартной документации (reviewer →
+  REQUEST_CHANGES, ORCH-079).
+
+---
+
+## Сводная матрица AC ↔ FR/BR
+
+| AC | Покрывает |
+|----|-----------|
+| AC-1 | BR-1 / FR-1 |
+| AC-2 | BR-2 / FR-2, FR-3 |
+| AC-3 | BR-2 / FR-2 / NFR-6 |
+| AC-4 | BR-3 / FR-4 |
+| AC-5 | BR-4 / FR-5 / NFR-5 |
+| AC-6 | NFR-2 / FR-6 |
+| AC-7 | NFR-1 / NFR-3 |
+| AC-8 | NFR-5 / FR-6 (§6 ТЗ) |
+| AC-9 | BR-5 / FR-7 / §6 ТЗ |
+| AC-10 | Правила агентов §2/§6 (CLAUDE.md) |

docs/work-items/ORCH-027/04-test-plan.yaml

@@ -0,0 +1,110 @@
+work_item: ORCH-027
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+title: "Code coverage gate — защита от деградации покрытия тестами"
+framework: pytest
+scope: >
+  Покрываются: чистая логика вердикта покрытия (режимы absolute/baseline/both, границы,
+  epsilon), ratchet-обновление базовой линии, условность (kill-switch + per-repo область),
+  fail-open/fail-closed при ошибке инструмента, never-raise, наблюдаемость (GET /queue,
+  Telegram при FAIL), интеграция гейта в advance_stage / точку конвейера. Вне покрытия:
+  фактические измерители не-Python стеков (jest/jacoco), мутационное тестирование.
+notes: >
+  Тесты не должны исполнять реальный прод-деплой и не трогают prod-контейнер/main.
+  Измерение покрытия в тестах мокается/стабится (фиктивная метрика), реальный pytest-прогон
+  под coverage проверяется отдельным интеграционным тестом на минимальном фикстур-репо/worktree.
+  Полный регресс tests/ должен оставаться зелёным (нулевая регрессия для enduro-trails).
+
+tests:
+  - id: TC-01
+    type: unit
+    description: "compute_coverage_verdict, policy=absolute: measured>=floor → PASS; measured<floor-epsilon → FAIL; ровно на пороге → PASS"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-02
+    type: unit
+    description: "compute_coverage_verdict, policy=baseline: measured>=baseline → PASS; ниже baseline-epsilon → FAIL (no-regression / ratchet)"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-03
+    type: unit
+    description: "compute_coverage_verdict, policy=both: PASS только при выполнении обоих условий; нарушение любого → FAIL"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-04
+    type: unit
+    description: "epsilon-допуск: дрожание покрытия в пределах epsilon у границы не заворачивает задачу (анти-флап, NFR-4)"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-05
+    type: unit
+    description: "Ratchet базовой линии: при слиянии baseline растёт до смёрженного покрытия только если >= текущей; меньшее значение не понижает baseline"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-06
+    type: unit
+    description: "Bootstrap базовой линии: первичная инициализация фактическим покрытием main при отсутствии сохранённого значения"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-07
+    type: unit
+    description: "Условность applies(repo): пустой coverage_gate_repos → только self-hosting (is_self_hosting_repo); repo вне области → no-op (True, 'N/A'), дорогой прогон не запускается"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-08
+    type: unit
+    description: "Kill-switch coverage_gate_enabled=False → гейт инертен, advance_stage ведёт себя 1:1 как до ORCH-027"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-09
+    type: unit
+    description: "Fail-open по умолчанию: ошибка/недоступность coverage-инструмента и coverage_tool_fail_closed=False → PASS + WARNING-лог; флаг True → FAIL (fail-closed)"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-10
+    type: unit
+    description: "never-raise: внутреннее исключение (битый вывод coverage, отсутствие worktree) перехватывается, не всплывает в advance_stage"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-11
+    type: unit
+    description: "Запись/чтение отчёта: write_coverage_report пишет coverage_status: PASS|FAIL во frontmatter; parse читает обратно из того же файла через src/frontmatter.py (single source of truth)"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-12
+    type: unit
+    description: "Self-hosting безопасность: гейт не вызывает деплой-хук, не перезапускает прод-контейнер, не пушит/форс-пушит в main/master"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-13
+    type: integration
+    description: "Гейт в конвейере: при measured ниже политики advance_stage не продвигает к деплою и инициирует откат на development (инкремент developer-retry); при PASS — продвигает штатно"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-14
+    type: integration
+    description: "Реальное измерение: pytest под coverage в ensure_worktree на минимальном фикстур-репо возвращает корректную метрику line coverage и тайм-аутится по coverage_run_timeout_s"
+    module: tests/test_coverage_gate.py
+    expected: PASS
+
+  - id: TC-15
+    type: integration
+    description: "Наблюдаемость: FAIL даёт Telegram-алерт с кликабельным номером (измеренное/порог/дельта); GET /queue несёт read-only блок coverage; совместимость — STAGE_TRANSITIONS/QG_CHECKS/существующие вердикт-ключи не изменены"
+    module: tests/test_coverage_gate.py
+    expected: PASS

docs/work-items/ORCH-027/06-adr/ADR-001-coverage-gate.md

@@ -0,0 +1,266 @@
+---
+work_item: ORCH-027
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# ADR-001: Гейт покрытия тестами — edge sub-gate с ratchet-базовой линией
+
+Work Item: **ORCH-027** — детерминированный гейт покрытия тестами, блокирующий деградацию
+покрытия перед слиянием ветки задачи в `main`.
+Стадия: **architecture**
+Сквозная регистрация: **`docs/architecture/adr/adr-0029-coverage-gate.md`** (решение
+кросс-каттинговое — вводит новый QG `check_coverage_gate`, новый edge-под-гейт ребра
+`deploy-staging→deploy`, новую аддитивную БД-таблицу `coverage_baseline` и новый артефакт
+`18-coverage-report.md`).
+
+## Статус
+Proposed
+
+---
+
+## Контекст
+
+Оркестратор ведёт **автономную** разработку: код пишет агент `developer` без человека-фильтра,
+а на стадии `testing` агент `tester` сам решает, достаточно ли тестов. Существующие тестовые
+гейты судят только по **факту прохождения**, не по **полноте** (сверено по коду):
+
+- `check_ci_green` (`development → review`) — exit-code `pytest tests/` в Gitea CI
+  (`.gitea/workflows/ci.yml`); покрытие не меряется.
+- `check_tests_passed` (`testing → deploy-staging`, `qg/checks.py::_parse_tests_verdict`) —
+  читает machine-verdict LLM-`tester`'а из `13-test-report.md`, а не измеренную метрику.
+- Merge-gate re-test (ORCH-043, `src/merge_gate.py`) — повторный `pytest` на догнанной ветке,
+  снова только exit-code.
+
+Ни один гейт не замечает «300 строк кода, 0 тестов» или багфикс без регрессионного теста. При
+пакетном автономном прогоне (ORCH-088, «10–20 задач за ночь») это означает **монотонную
+деградацию покрытия**: каждая задача срезает угол на тестах, и за десятки задач проект тихо
+теряет тестируемость. Нужна детерминированная метрика вместо доверия суждению агента — по духу
+аналогично security-гейту (ORCH-022, adr-0012).
+
+Требования (`01-brd.md`/`02-trz.md`/`03-acceptance-criteria.md`): измерять покрытие
+инструментально перед merge в `main` (BR-1/FR-1); блокировать деградацию относительно
+абсолютного порога и/или базовой линии (BR-2/BR-3/FR-2); хранить и наращивать базовую линию
+(ratchet, FR-4); kill-switch + per-repo область, нулевая регрессия для enduro-trails
+(BR-4/FR-5); fail-open по умолчанию при сбое инструмента (NFR-2/FR-6); never-raise и
+self-hosting-безопасность (NFR-1/NFR-3); неизменность существующих контрактов (NFR-5).
+
+## Решение
+
+### Сводка
+
+Вводим **детерминированный (без LLM) гейт покрытия** как **под-гейт ребра
+`deploy-staging → deploy`** — рядом с security-gate (ORCH-022), merge-gate (ORCH-043) и
+image-freshness (ORCH-058), исполняемый **ПОСЛЕ merge-gate и ДО image-freshness**.
+`STAGE_TRANSITIONS` не меняется; в `QG_CHECKS` добавляется `check_coverage_gate`. Паттерн —
+1:1 как у соседних под-гейтов: leaf-модуль `src/coverage_gate.py` (never-raise) + тонкая
+обёртка в `QG_CHECKS` + врезка `_handle_coverage_gate` в `advance_stage`. Базовая линия `main`
+хранится в **аддитивной БД-таблице** `coverage_baseline` и наращивается **вверх** (ratchet) в
+choke-point подтверждённого merge `_handle_merge_verify` (ребро `deploy → done`). Вердикт
+пишется в артефакт `18-coverage-report.md` (frontmatter-ключ `coverage_status:`) и читается
+обратно из того же файла (single source of truth, как `security_status:`).
+
+### D1 — Точка в конвейере: edge sub-gate `deploy-staging → deploy`, ПОСЛЕ merge-gate (FR-3a)
+
+Из трёх кандидатов TRZ FR-3 выбран **(a) edge sub-gate** на ребре `deploy-staging → deploy`
+(`advance_stage`, `src/stage_engine.py`, блок `current_stage == "deploy-staging"`). Это даёт
+структурную гарантию «гейт ДО merge в `main`» (merge выполняется детерминированным merge-актором
+в `_handle_merge_verify` на ребре `deploy → done`), детерминизм и владение исходом на
+вмешательстве — полное соответствие NFR-3/NFR-6.
+
+**Порядок среди под-гейтов: security → merge → `coverage` → image-freshness.** Обоснование:
+
+- **ПОСЛЕ merge-gate (а не первым, как security).** Merge-gate выполняет догон ветки на свежий
+  `origin/main` (`auto_rebase_onto_main` под merge-lease, ORCH-043/026). Покрытие имеет смысл
+  мерить на **догнанном** HEAD — это ровно тот код, что landed в `main`; измерение до rebase
+  показало бы покрытие устаревшей базы. Поэтому coverage **обязан** идти после merge-gate
+  (в отличие от security, который специально фейлит дёшево ДО rebase).
+- **ДО image-freshness.** Прогон pytest под coverage дорог, но дешевле полного docker-rebuild
+  staging-образа. Фейлить покрытие до rebuild — экономия (паттерн «fail before expensive
+  rebuild», 07-infra security-гейта).
+- **Merge-lease held на этой точке.** Merge-gate уже захватил merge-lease (ORCH-043). Значит
+  **FAIL coverage обязан освободить merge-lease** при откате — как делает image-freshness
+  rollback (`merge_gate.release_merge_lease`, `stage_engine.py:1165`), и **в отличие** от
+  security-gate rollback (тот идёт ДО захвата lease и lease не трогает). Это явный инвариант
+  реализации (TR-2).
+
+Привязка: BR-2/FR-3/AC-2; NFR-3/AC-7.
+
+### D2 — Измеритель: `pytest-cov` (`coverage.py`), `--cov=src` (FR-1, BR-6)
+
+В `requirements.txt` добавляется **`pytest-cov`** (плагин-обёртка над `coverage.py`). Измерение —
+прогон `python -m pytest tests/ --cov=src --cov-report=json:<tmp>/coverage.json
+--cov-report=` в изолированном per-branch worktree (`ensure_worktree`, прецедент
+`check_tests_local`/merge-gate re-test). Числовая метрика — `totals.percent_covered` из JSON
+(line coverage, `%`). Скоуп измерения — **`src/`** (не `tests/`: покрытие самих тестов вне
+объёма, BRD §«Вне объёма»). Сеть при измерении не нужна. Тайм-аут — `coverage_run_timeout_s`
+(по образцу `merge_retest_timeout_s`/`security_scan_timeout_s`).
+
+**Стек-расширяемость (BR-6/AC-… BR-6):** измеритель инкапсулирован за функцией
+`measure_coverage(repo, branch) -> float | None`; чистая логика решения
+`compute_coverage_verdict(...)` и хранилище базовой линии **не зависят** от Python/pytest.
+Добавление jest/jacoco-измерителя для будущего стека — новая ветка `measure_*`, без переписывания
+ядра. Фактическая интеграция не-Python стеков — вне объёма ORCH-027.
+
+### D3 — Чистая функция решения (FR-2, NFR-6, BR-2/BR-3)
+
+`compute_coverage_verdict(measured, baseline, floor, policy, epsilon) -> (ok: bool, reason: str)` —
+детерминированная чистая функция (без LLM, без I/O):
+
+- `policy = "absolute"` → PASS ⇔ `measured >= floor - epsilon`.
+- `policy = "baseline"` → PASS ⇔ `measured >= baseline - epsilon`.
+- `policy = "both"` (дефолт) → PASS ⇔ выполнены **оба** условия.
+- `baseline is None` (нет сохранённой базовой линии) → baseline-условие **не применяется**
+  (bootstrap: нельзя регрессировать против пустоты) → решает только absolute-часть; измеренное
+  значение засеет базовую линию при merge (D5).
+- `epsilon` — малый неотрицательный допуск на шум измерения (NFR-4/AC-4): дрожание ±доли
+  процента у границы не заворачивает задачу.
+
+FAIL → штатный откат на `development` + инкремент общего `_developer_retry_count` (cap
+`MAX_DEVELOPER_RETRIES`, затем `set_issue_blocked` + Telegram) — точно как security/merge-gate
+rollback. Дословный reason (измеренное/порог/базовая линия/дельта) встраивается в `task_desc`
+developer'а (паттерн ORCH-046). Привязка: AC-2/AC-3.
+
+### D4 — Хранилище базовой линии: аддитивная БД-таблица `coverage_baseline` (FR-4, NFR-5)
+
+Базовая линия `main` хранится в **БД**, не в файле репозитория:
+
+```sql
+CREATE TABLE IF NOT EXISTS coverage_baseline (
+    repo        TEXT PRIMARY KEY,
+    coverage    REAL NOT NULL,
+    source_sha  TEXT,
+    updated_at  TEXT NOT NULL
+);
+```
+
+(паттерн `repo_freeze`/`job_deps` — `CREATE TABLE IF NOT EXISTS`, существующие таблицы не
+мигрируются, NFR-5/AC-8; детали — `08-data-requirements.md`). **Почему БД, а не файл в репо**
+(`.coverage-baseline.json`): файл пришлось бы коммитить в `main` на каждый ratchet → git-churn,
+сам файл попадает в diff и может конфликтовать при параллельных merge, плюс он часть измеряемого
+дерева. БД-таблица — restart-safe, аддитивна, обновляется атомарно и не порождает коммитов.
+Таблица keyed by `repo` → общая прод-БД (self-hosting) безопасно разделяет базовые линии разных
+репозиториев.
+
+### D5 — Ratchet-up в choke-point подтверждённого merge (FR-4, BR-3)
+
+Базовая линия наращивается **только вверх** и **только при подтверждённом** слиянии в `main`.
+Единственный авторитетный choke-point подтверждённого merge — `_handle_merge_verify` (ребро
+`deploy → done`, ORCH-071/073, доказательство SHA-in-main). Туда добавляется never-raise врезка
+`coverage_gate.ratchet_baseline_on_merge(repo, work_item_id, branch, sha)`, вызываемая **после**
+того как merge подтверждён (`_handle_merge_verify` вернул `False` = confirmed) и **до** перехода
+в `done`:
+
+1. Читает измеренное покрытие смёрженной ветки из артефакта `18-coverage-report.md` (single
+   source of truth — то же значение, что гейт записал на ребре `deploy-staging→deploy`).
+2. **Атомарный compare-and-set:** `UPDATE coverage_baseline SET coverage=?, source_sha=?,
+   updated_at=? WHERE repo=? AND coverage <= ?` (или `INSERT` при отсутствии строки —
+   bootstrap). Условие `coverage <= measured` гарантирует, что базовая линия **никогда не
+   падает** (FR-4), даже при гонке.
+
+**Сериализация (анти-гонка, NFR-5/AC-4):** на этой точке merge-lease ещё **held** (release на
+`done`/rollback, `stage_engine.py:446`), а merge репо сериализован per-repo (ORCH-043). Плюс
+атомарный compare-and-set в SQL — **двойная защита**: даже без lease два параллельных merge не
+понизят и не потеряют значение. Bootstrap — первый merge применимого репо засевает базовую линию
+своим измеренным покрытием.
+
+### D6 — Условность, kill-switch, наблюдаемость (FR-5/FR-7, BR-4/BR-5)
+
+- **Флаги (`config.py`, env `ORCH_COVERAGE_*`):** `coverage_gate_enabled` (bool, kill-switch),
+  `coverage_gate_repos` (CSV; **пусто → только self-hosting** `is_self_hosting_repo`, по образцу
+  `merge_gate`/`security_gate`/`image_freshness`), `coverage_min_percent` (float, абсолютный
+  порог-floor), `coverage_policy` (`absolute|baseline|both`, дефолт `both`), `coverage_epsilon`
+  (float, дефолт малый, напр. `0.5`), `coverage_tool_fail_closed` (bool, дефолт `False`),
+  `coverage_run_timeout_s` (int).
+- **`applies(repo)`** (локальная проверка) выполняется **ПЕРВОЙ**; дорогой прогон измерения —
+  только при `applies==True`. Вне области → no-op `(True, "Coverage gate N/A")` (прецедент
+  `check_staging_status` для не-self, ORCH-035). При `coverage_gate_enabled=False` — гейт инертен,
+  конвейер 1:1 как до ORCH-027 (AC-5).
+- **FR-6 (ошибка инструмента):** `measure_coverage` вернул `None` (инструмент упал/недоступен/
+  метрика не распарсилась) → по умолчанию **fail-open + WARNING** (observability-строка),
+  `coverage_tool_fail_closed=True` → fail-closed (FAIL). Дефолт анти-петля (прецедент
+  ORCH-061/ORCH-022 dep-audit), чтобы инфра-сбой не заклинил автономный конвейер.
+- **FR-7 (наблюдаемость):** артефакт `18-coverage-report.md` (frontmatter `coverage_status:
+  PASS|FAIL` + `measured_coverage`/`baseline`/`floor`/`policy`/`delta`); read-only блок
+  `coverage` в `GET /queue` (`src/main.py`); при FAIL — `send_telegram` с кликабельным номером
+  (`plane_issue_link`/`link_for`), измеренным покрытием, порогом/базовой линией и дельтой.
+
+### D7 — Машинный вердикт и парсинг (§6 ТЗ, AC-9)
+
+Гейт **сам вычисляет** вердикт (как `check_security_gate`) и пишет
+`18-coverage-report.md` с YAML-frontmatter `coverage_status:` (`PASS` | `FAIL`); регистр
+чувствителен, имя фиксируется. Чтение обратно — через единый контракт `src/frontmatter.py`
+(`parse_frontmatter`/`read_frontmatter_value`, ORCH-052c), как все вердикт-парсеры. Артефакт
+несёт **аддитивно** обязательную 6-польную схему 52c, не трогая `coverage_status:`. В `QG_CHECKS`
+добавляется `check_coverage_gate` (тонкая обёртка, делегирующая в leaf); **семантика и состав
+существующих `check_*` / machine-verdict ключей (`verdict:`/`result:`/`deploy_status:`/
+`staging_status:`/`security_status:`) — байт-в-байт прежние** (NFR-5/AC-8).
+
+### D8 — Опциональный override базовой линии (FR-4 / §4 API)
+
+Для легитимного разового снижения покрытия (напр. удаление большого протестированного модуля)
+вводится опциональный ручной эндпоинт `POST /coverage/baseline?repo=<repo>&value=<float>` (по
+образцу `POST /serial-gate/unfreeze`) — устанавливает/сбрасывает базовую линию вручную.
+Альтернатива без эндпоинта — временно переключить `coverage_policy=absolute`. Эндпоинт
+рекомендован для эксплуатационной гибкости, но не критичен для v1.
+
+## Альтернативы
+
+- **Точка измерения — CI-job (`check_ci_green`, FR-3c).** Пороги/политика/базовая линия/артефакт
+  плохо выражаются статусом коммита; ratchet требует записи в общую БД, недоступную из CI-раннера
+  чисто. Коуплинг с раннером. Отклонено для v1 (точка расширения), как у security-гейта.
+- **Точка измерения — `testing → deploy-staging` (рядом с `check_tests_passed`, FR-3b).** Ветка
+  ещё не догнана на свежий `main` → измеренное покрытие может не соответствовать landed-коду;
+  откат отсюда не освобождает merge-lease иначе. Edge `deploy-staging→deploy` после merge-gate —
+  точнее. Отклонено.
+- **Базовая линия в файле репо (`.coverage-baseline.json`).** Git-churn на каждый ratchet,
+  конфликты при параллельных merge, файл — часть измеряемого дерева. Отклонено в пользу
+  аддитивной БД-таблицы (D4).
+- **Складывание измерения в merge-gate re-test (один pytest-прогон).** Снижает дабл-ран, но
+  коуплит coverage-логику с merge_gate; нарушает leaf-изоляцию ТЗ. Отклонено для v1 (возможный
+  follow-up — измерять покрытие в том же прогоне).
+- **Новый stage `coverage`.** «Пустая» стадия без агента не имеет триггера (как в ORCH-043/022).
+  Отклонено.
+- **Жёсткий абсолютный порог без baseline/epsilon.** Массовые ложные заворота → петля rework.
+  Отклонено в пользу консервативного `both` + epsilon (NFR-4).
+
+## Последствия
+
+- **+** Класс «тихо просевшее покрытие» закрыт детерминированной метрикой; защита от монотонной
+  деградации в пакетном автономном прогоне (ORCH-088). Базовая линия может только расти (ratchet).
+- **+** Нулевая регрессия: при выключенном флаге / вне области (enduro-trails) — конвейер
+  байт-в-байт прежний; `STAGE_TRANSITIONS`/`QG_CHECKS`-семантика/вердикт-ключи не тронуты.
+- **+** Self-hosting-безопасно: гейт только мерит/читает/пишет/решает; не деплоит, не рестартит
+  прод, не пушит/форс-пушит в `main` (NFR-3).
+- **−** Дополнительный прогон pytest под coverage на каждой применимой задаче (после merge-gate
+  re-test) → ещё один полный тест-ран. Митигейшн: ограничен `coverage_run_timeout_s`; фейлит до
+  дорогого image-rebuild; follow-up — слияние с merge-gate re-test.
+- **−** Ещё один «скрытый» под-гейт ребра (нет в `STAGE_TRANSITIONS`); новая pip-зависимость
+  (`pytest-cov`); v1 — Python-only (мульти-стек — точка расширения BR-6).
+- **−** Дефолтный fail-open означает, что устойчивый сбой инструмента **тихо** пропускает задачи
+  (с WARNING). Митигейшн: громкий лог + переключатель `coverage_tool_fail_closed`.
+- **Сквозное изменение** (новый QG + edge-под-гейт + новая БД-таблица + новый артефакт) →
+  лейбл `arch:major-change`; прод-деплой ORCH-027 — строго через staging-гейт (8501), без
+  рестарта прод-контейнера.
+- **Откат:** `coverage_gate_enabled=False` → полный no-op (мгновенный обратимый kill-switch).
+  Полное удаление — снять врезки `_handle_coverage_gate`/`ratchet_baseline_on_merge`, удалить
+  leaf-модуль, `check_coverage_gate` из `QG_CHECKS`, флаги, артефакт-шаблон; таблица
+  `coverage_baseline` аддитивна и может остаться (инертна).
+
+## Ссылки
+
+- BRD: `docs/work-items/ORCH-027/01-brd.md`
+- TRZ: `docs/work-items/ORCH-027/02-trz.md`
+- Acceptance: `docs/work-items/ORCH-027/03-acceptance-criteria.md`
+- Data: `docs/work-items/ORCH-027/08-data-requirements.md`
+- Risks: `docs/work-items/ORCH-027/10-tech-risks.md`
+- Сквозной ADR: `docs/architecture/adr/adr-0029-coverage-gate.md`
+- Сверено по коду: `src/stage_engine.py` (`_handle_security_gate`/`_handle_merge_gate`/
+  `_handle_image_freshness`/`_handle_merge_verify`), `src/security_gate.py`, `src/merge_gate.py`,
+  `src/qg/checks.py`, `.gitea/workflows/ci.yml`, `pytest.ini`
+- Прецеденты: adr-0012 (security-гейт), adr-0006 (merge-gate — edge-под-гейт/откат/lease),
+  adr-0008 (image-freshness — условность/fail-closed), adr-0003 (`is_self_hosting_repo`),
+  adr-0009 (анти-петля ложных FAIL), adr-0014 (SHA-in-main как source of truth для merge)

docs/work-items/ORCH-027/07-infra-requirements.md

@@ -0,0 +1,64 @@
+---
+work_item: ORCH-027
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 07 — Инфраструктурные требования: ORCH-027 — Code coverage как гейт
+
+Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: architecture
+
+> When-applicable. Топология **не меняется** (всё в существующем Docker-контейнере на одном
+> сервере mva154, SQLite, собственная очередь). Затрагивается только зависимостный и
+> конфигурационный слой.
+
+## Топология / окружение
+
+- **Без изменений топологии** — никаких новых контейнеров/сервисов/нод. Гейт исполняется внутри
+  существующего процесса оркестратора, измерение — в per-branch worktree (`ensure_worktree`),
+  как merge-gate re-test. `docs/operations/INFRA.md` — без правок.
+- **Self-hosting безопасность (NFR-3):** гейт не вызывает деплой-хук, не рестартит прод-контейнер
+  `orchestrator` (8500), не пушит в `main`. Прод-деплой ORCH-027 — **только** через
+  staging-гейт (8501) → выделенный статус «Confirm Deploy» (ORCH-059), без рестарта прод
+  случайным approve.
+
+## Зависимости
+
+| Зависимость | Где | Назначение |
+|-------------|-----|-----------|
+| `pytest-cov` (обёртка `coverage.py`) | `requirements.txt` | измерение line coverage прогоном `pytest --cov=src --cov-report=json`. Offline (сеть при измерении не нужна). Попадает в прод-образ при пересборке. |
+
+- Версия фиксируется совместимой с текущим `pytest` (см. `requirements.txt`/`pytest.ini`).
+- Новых системных пакетов в `Dockerfile` не требуется (чистый pip-пакет).
+
+## Конфигурация (env, `.env` на хосте)
+
+Новые флаги (`config.py`, префикс `ORCH_COVERAGE_*`; дефолты безопасны — нулевая регрессия):
+
+| Env | Дефолт | Назначение |
+|-----|--------|-----------|
+| `ORCH_COVERAGE_GATE_ENABLED` | `false` (раскат поэтапный) | kill-switch |
+| `ORCH_COVERAGE_GATE_REPOS` | пусто → только self-hosting | CSV область применения |
+| `ORCH_COVERAGE_MIN_PERCENT` | консервативно (напр. backstop) | абсолютный порог-floor |
+| `ORCH_COVERAGE_POLICY` | `both` | `absolute\|baseline\|both` |
+| `ORCH_COVERAGE_EPSILON` | малый (напр. `0.5`) | допуск на шум измерения |
+| `ORCH_COVERAGE_TOOL_FAIL_CLOSED` | `false` | поведение при сбое инструмента |
+| `ORCH_COVERAGE_RUN_TIMEOUT_S` | по образцу `merge_retest_timeout_s` | тайм-аут прогона |
+
+## Эксплуатационные предусловия
+
+- **Bootstrap базовой линии:** при первом merge применимого репо базовая линия `main`
+  засевается автоматически фактическим измеренным покрытием (D5). Ручной первичный замер не
+  обязателен; при необходимости — `POST /coverage/baseline?repo=orchestrator&value=<%>` (D8).
+- **Раскат:** включать `ORCH_COVERAGE_GATE_ENABLED=true` только после прод-деплоя кода и
+  прогона на staging (8501); стартовая область — только `orchestrator`.
+- **Override (легитимное снижение покрытия):** `POST /coverage/baseline` (по образцу
+  `POST /serial-gate/unfreeze`) либо временный `ORCH_COVERAGE_POLICY=absolute`.
+
+## Секреты / сеть
+
+- Новых секретов нет. Сетевого доступа при измерении нет (coverage offline).
+- enduro-trails и прочие репозитории — вне области по умолчанию, нулевое влияние.

docs/work-items/ORCH-027/08-data-requirements.md

@@ -0,0 +1,67 @@
+---
+work_item: ORCH-027
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 08 — Требования к данным: ORCH-027 — Code coverage как гейт
+
+Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: architecture
+
+> When-applicable / информационный (гейтом не парсится). Затрагивается схема БД — вводится
+> **одна аддитивная таблица** базовой линии покрытия. Существующие таблицы не мигрируются.
+
+## Изменения схемы БД
+
+Новая аддитивная таблица `coverage_baseline` (паттерн `repo_freeze`/`job_deps` —
+`CREATE TABLE IF NOT EXISTS` в `init_db`, `src/db.py`; без `ALTER`/миграции существующих):
+
+```sql
+CREATE TABLE IF NOT EXISTS coverage_baseline (
+    repo        TEXT PRIMARY KEY,   -- репозиторий (напр. "orchestrator")
+    coverage    REAL NOT NULL,      -- last-known базовая линия покрытия main (%, line coverage)
+    source_sha  TEXT,               -- SHA main, на котором зафиксирована базовая линия (аудит)
+    updated_at  TEXT NOT NULL       -- ISO-таймстамп последнего ratchet/bootstrap
+);
+```
+
+Доступ — через аддитивные read-only/мутирующие хелперы `src/db.py`:
+- `get_coverage_baseline(repo) -> float | None` (None ⇒ bootstrap-режим, базовой линии ещё нет);
+- `ratchet_coverage_baseline(repo, coverage, sha) -> bool` — **атомарный compare-and-set**:
+  `INSERT` при отсутствии строки; иначе `UPDATE ... SET coverage=?, source_sha=?, updated_at=?
+  WHERE repo=? AND coverage <= ?` (базовая линия **никогда не понижается**);
+- `set_coverage_baseline(repo, coverage, sha)` — безусловная установка (ручной override D8 /
+  `POST /coverage/baseline`).
+
+## Новые/изменённые сущности
+
+- **`coverage_baseline`** — одна строка на репозиторий; keyed by `repo`. Инвариант: `coverage`
+  монотонно не убывает через `ratchet_coverage_baseline` (только `set_coverage_baseline`/ручной
+  override может понизить — легитимный разовый случай, D8). На общей прод-БД (self-hosting)
+  строки разных репозиториев изолированы первичным ключом.
+- **Артефакт `18-coverage-report.md`** — НЕ БД-сущность: файл в `docs/work-items/<id>/`,
+  несёт frontmatter `coverage_status: PASS|FAIL` + `measured_coverage`/`baseline`/`floor`/
+  `policy`/`delta`. Source of truth измеренного значения для ratchet (D5).
+
+Существующие таблицы (`tasks`, `jobs`, `job_deps`, `repo_freeze`, `agent_runs`,
+`tracker_messages`, …) — **не изменяются** (NFR-5/AC-8).
+
+## Совместимость данных / миграции
+
+- **Аддитивность:** только `CREATE TABLE IF NOT EXISTS` — ни один существующий столбец/таблица
+  не трогается; миграции существующих данных нет.
+- **Идемпотентность:** `CREATE TABLE IF NOT EXISTS` безопасен при повторном старте; bootstrap
+  (первый `INSERT`) выполняется один раз на репозиторий.
+- **Restart-safe:** базовая линия персистентна; in-flight измерение при рестарте переигрывается
+  штатным механизмом стадии (idempotent — гейт пересчитает вердикт, ratchet — атомарный
+  compare-and-set, повтор не понизит и не задвоит).
+- **Атомарность / анти-гонка:** ratchet — единичный SQL `UPDATE ... WHERE coverage <= ?` (или
+  `INSERT`), выполняется под held merge-lease (ORCH-043, per-repo сериализация merge) → двойная
+  защита от параллельных слияний.
+- **Влияние на общую прод-БД:** одна маленькая таблица (≤ числа репозиториев строк); нулевой
+  риск для enduro-trails и прочих проектов (строки изолированы по `repo`, гейт для них no-op).
+- При `coverage_gate_enabled=False` таблица может существовать пустой/инертной — нулевая
+  регрессия.

docs/work-items/ORCH-027/10-tech-risks.md

@@ -0,0 +1,42 @@
+---
+work_item: ORCH-027
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 10 — Технические риски: ORCH-027 — Code coverage как гейт
+
+Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: architecture
+
+> Информационный (гейтом не парсится). Перечисляет риски реализации и их митигейшн.
+
+## Реестр рисков
+
+| ID | Риск | Вер. | Влия. | Митигейшн |
+|----|------|------|-------|-----------|
+| TR-1 | **Флап на шуме измерения** — недетерминированное покрытие (порядок тестов/окружение) дрожит у границы → ложные заворота, петля rework. | Сред. | Сред. | `coverage_epsilon` (NFR-4/D3): дрожание ±доли % не заворачивает. Дефолт `policy=both` мягкий; абсолютный порог — backstop, не агрессивный. |
+| TR-2 | **Не освобождён merge-lease при FAIL.** Coverage идёт ПОСЛЕ merge-gate (lease уже held) — забытый release при откате заклинит serial-gate репо (другие задачи репо в defer навсегда). | Сред. | Выс. | Явный инвариант D1: rollback coverage вызывает `merge_gate.release_merge_lease` (как image-freshness rollback, `stage_engine.py:1165`); покрыто тестом TC-13. Backstop — crash-реклейм lease по возрасту (ORCH-043). |
+| TR-3 | **Гонка базовой линии** — два параллельных слияния в `main` конкурентно обновляют baseline, теряя/занижая значение. | Низ. | Сред. | Атомарный SQL compare-and-set `UPDATE ... WHERE coverage <= ?` (D5/08-data) + held merge-lease + per-repo сериализация merge (ORCH-043) → тройная защита. Покрыто TC-05. |
+| TR-4 | **Инфра-хрупкость инструмента** — `pytest-cov` несовместим с версией pytest / упал / метрика не парсится → конвейер клинит. | Низ. | Сред. | NFR-2/FR-6/D6: дефолт fail-open + громкий WARNING (анти-петля ORCH-061); `coverage_tool_fail_closed` для строгого режима. `measure_coverage`→`None` обрабатывается, не всплывает. Покрыто TC-09. |
+| TR-5 | **Исключение всплывает в `advance_stage`** — ошибка leaf-модуля роняет конвейер ВСЕХ проектов (общий прод-инстанс). | Низ. | Выс. | NFR-1/AC-7: `src/coverage_gate.py` — leaf (не импортирует `stage_engine`), контракт never-raise; любое исключение → `(False/True, reason)` по политике fail-open/closed. Покрыто TC-10. |
+| TR-6 | **Дабл-ран pytest** — coverage-прогон после merge-gate re-test удваивает время тестов на применимой задаче. | Выс. | Низ. | Ограничен `coverage_run_timeout_s`; фейлит ДО дорогого image-rebuild; follow-up — слияние измерения с merge-gate re-test (вне объёма v1). Влияет только на self-hosting `orchestrator`. |
+| TR-7 | **Стартовая петля заворотов** — высокий `coverage_min_percent` массово заворачивает существующие задачи в rework. | Сред. | Сред. | NFR-4/D3: bootstrap инициализирует baseline фактическим покрытием `main`; absolute-порог — мягкий backstop; cap `MAX_DEVELOPER_RETRIES` → Blocked+alert вместо бесконечной петли. |
+| TR-8 | **Self-hosting побочка** — гейт случайно трогает прод-контейнер/`main`/force-push. | Низ. | Выс. | NFR-3/AC-7: гейт только мерит/читает/пишет/решает в изолированном worktree; не вызывает деплой-хук, не рестартит прод, не пушит в `main`. Покрыто TC-12. |
+| TR-9 | **Регресс контрактов** — затронуты `STAGE_TRANSITIONS`/существующие `check_*`/вердикт-ключи. | Низ. | Выс. | NFR-5/AC-8: новый QG аддитивен, edge-врезка не меняет `STAGE_TRANSITIONS`; вердикт-ключи прежних доков байт-в-байт. Покрыто TC-15. |
+
+## Сводный вывод
+
+Доминирующий класс рисков — **эксплуатация автономного self-hosting-конвейера**: самые
+тяжёлые по влиянию (TR-2 заклинивание serial-gate, TR-5 падение конвейера всех проектов, TR-8
+побочка на прод) имеют **низкую вероятность** и закрыты структурными инвариантами, повторяющими
+проверенные паттерны соседних под-гейтов (security/merge/image-freshness): leaf never-raise,
+fail-open дефолт, явный release merge-lease при откате, kill-switch. Остаточный риск для
+прод-конвейера — **низкий** при условии тестового покрытия инвариантов TR-2/TR-5/TR-8
+(`04-test-plan.yaml` TC-09…TC-13) и поэтапного раската через staging-гейт (8501).
+
+Решение **сквозное** (новый QG + edge-под-гейт + новая БД-таблица + новый артефакт) → эскалация
+лейблом **`arch:major-change`**. Возврат в анализ не требуется — ТЗ реализуемо без нарушения
+принципов архитектуры (Docker/один сервер/SQLite/собственная очередь сохранены).

docs/work-items/ORCH-027/12-review.md

@@ -0,0 +1,121 @@
+---
+verdict: APPROVED
+work_item: ORCH-027
+stage: review
+author_agent: reviewer
+status: approved
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+type: review
+work_item_id: ORCH-027
+version: 2
+---
+
+# Review ORCH-027 — Code coverage как гейт
+
+## Summary
+
+Дисциплинированная реализация детерминированного coverage-гейта строго по образцу
+security/merge/image-freshness под-гейтов. Соответствие ТЗ/ADR — полное; код качественный,
+тесты содержательны (`test_coverage_gate.py` — 30 тестов; **полный регресс `tests/ -q`
+зелёный: 1466 passed**); документация обновлена исчерпывающе.
+
+**Единственный прежний блокер закрыт.** Ревизия v1 выносила P1 за повреждённую (дословно
+продублированную) запись ORCH-095 в `CHANGELOG.md` — коммит `75c33ab docs(changelog): repair
+duplicated ORCH-095 entry body` устранил дубль: тело bullet ORCH-095 теперь присутствует ровно
+один раз (`git revert occurrences on line 16: 1`), артефакт чужой задачи восстановлен. Новых
+P0/P1 не выявлено.
+
+Проверено: 4 оси (ТЗ / ADR / качество кода / документация) + трассировка маркеров + полный
+прогон тест-сьюта.
+
+## Findings
+
+### P0 — Blocker
+- (нет)
+
+### P1 — Must fix
+- (нет) — прежний P1 (дубль записи ORCH-095 в CHANGELOG) исправлен коммитом `75c33ab`.
+
+### P2 — Should fix
+- [ ] **Несоответствие формулировки ADR-001 D7 фактическому артефакту: 6-польная схема 52c
+  не эмитится.** `ADR-001-coverage-gate.md` D7 утверждает: «Артефакт несёт **аддитивно**
+  обязательную 6-польную схему 52c, не трогая `coverage_status:`». Фактически и генератор
+  (`coverage_gate.render_coverage_report`), и скелет `docs/_templates/18-coverage-report.md`
+  эмитят только `coverage_status`/`work_item` + coverage-поля; отсутствуют 5 из 6 полей схемы
+  52c (`stage`/`author_agent`/`status`/`created_at`/`model_used`). **Почему не блокер:** (а)
+  TRZ §6 формулирует это условно («*Если* отчёт несёт обязательную 6-польную схему 52c —
+  добавить её аддитивно»), (б) валидация схемы warning-only по умолчанию
+  (`frontmatter_validation_strict=False`), (в) гейт-генерируемые артефакты (прецедент
+  `17-security-report.md`) исторически несут лишь свой machine-key — эпик 52c (ORCH-077)
+  скоупил схему на 6 агент-промптов, не на машинные отчёты. Машинный вердикт читается из
+  `coverage_status:` корректно, контракт не нарушен. **Действие (на усмотрение, не блокирует
+  приёмку):** привести формулировку D7 к факту (отчёт несёт `coverage_status:` + coverage-поля,
+  без полной 52c-схемы) ЛИБО добавить 5 полей в генератор+шаблон.
+
+## Документация
+
+**Статус: обновлена исчерпывающе** (golden source синхронизирован в том же PR, AC-10 PASS):
+
+- `docs/architecture/README.md` — реестр `QG_CHECKS` дополнен `check_coverage_gate (ORCH-027)`;
+  добавлен раздел «Coverage-гейт: защита от деградации покрытия» (точка/порядок, измерение,
+  чистая функция, baseline+ratchet, условность/fail-open, артефакт/наблюдаемость). ✅
+- `docs/_standards/PIPELINE_DOCS.md` — диапазон доков `…18-coverage-report.md`; строка карты
+  `стадия→агент→документ→гейт→machine-key` + строка таблицы вердикт-парсеров
+  (`coverage_status:` → `check_coverage_gate`). ✅
+- `docs/_templates/18-coverage-report.md` — скелет с frontmatter зарегистрирован. ✅
+- `docs/work-items/ORCH-027/06-adr/ADR-001-coverage-gate.md` (D1…D8) +
+  сквозной `docs/architecture/adr/adr-0029-coverage-gate.md`. ✅
+- `CHANGELOG.md` — детальная корректная запись ORCH-027; повреждение соседней записи ORCH-095
+  устранено (v1-P1 закрыт). ✅
+- `CLAUDE.md` — паспортный блок «Гейт покрытия тестами (ORCH-027)» добавлен. ✅
+- `.env.example` / `src/config.py` — флаги `ORCH_COVERAGE_*` задокументированы. ✅
+- Маркеры `ORCH-027` проставлены в коде/доках (AC-10). ✅
+
+`src/` изменён → документация обновлена в том же PR: **да** (P0-условие выполнено).
+**Обзорные доки (ORCH-079):** PR не закрывает ни один пункт `README.md` «Известные ограничения»
+(coverage-деградация там не значилась) → обновление витрины не требуется, finding отсутствует.
+
+## Оси проверки (детально)
+
+**1. Соответствие ТЗ (02-trz / 03-acceptance) — PASS.**
+AC-1 измерение инструментально (`measure_coverage` → `pytest --cov=src` → `totals.percent_covered`,
+`pytest-cov==5.0.0` в `requirements.txt`); AC-2 блокировка деградации + откат на `development` с
+release merge-lease (`_handle_coverage_gate`); AC-3 чистая функция `compute_coverage_verdict`
+покрыта по всем режимам/границам/epsilon (TC-01…04); AC-4 ratchet up-only + bootstrap + per-repo
+изоляция + атомарный compare-and-set `UPDATE … WHERE coverage <= ?` (`db.ratchet_coverage_baseline`);
+AC-5 kill-switch/scope + `applies(repo)` ПЕРВЫМ (дорогой прогон только при `applies==True`) —
+регресс зелёный, enduro не затронут; AC-6 fail-open дефолт / fail-closed по флагу; AC-7 never-raise
++ leaf (не импортирует `stage_engine`) + AST-проверка отсутствия деплой/force-push токенов; AC-8
+контракты `STAGE_TRANSITIONS`/`check_*`/вердикт-ключи байт-в-байт, таблица `coverage_baseline`
+аддитивна; AC-9 вердикт только из frontmatter (`parse_coverage_status` через
+`frontmatter.parse_frontmatter`) + `GET /queue` блок `coverage` + Telegram с кликабельным номером.
+
+**2. Соответствие ADR (ADR-001 D1…D8 / adr-0029) — PASS** (с P2-оговоркой по тексту D7).
+Порядок под-гейтов `security → merge → coverage → image-freshness` реализован ровно как в D1
+(врезка `_handle_coverage_gate` между merge-handling и ORCH-058 freshness в `advance_stage`);
+coverage ПОСЛЕ merge-gate (догнанный HEAD) и `merge_gate.release_merge_lease` при FAIL —
+соответствует D1/TR-2 (зеркало image-freshness rollback, в отличие от security — тот до захвата
+lease). Ratchet в choke-point `_handle_merge_verify` (ребро `deploy→done`, D5), БД-таблица
+`coverage_baseline` (D4), машинный вердикт/парсинг (D7), override `POST /coverage/baseline` (D8).
+Глобальные ADR (INV-4 merge только через Gitea API; не трогать `main`/прод) не нарушены — leaf
+только мерит/читает/пишет/решает.
+
+**3. Качество кода — PASS.**
+Docstrings на всех публичных функциях; never-raise контракт выдержан последовательно (все
+внешние границы обёрнуты, исключение не всплывает в `advance_stage`); единый frontmatter-контракт
+переиспользован (нет дублирования парс-логики); тесты содержательные (режимы/границы/epsilon,
+ratchet up-only + bootstrap + per-repo изоляция, fail-open/closed, never-raise, write/read-back
+отчёта, self-hosting AST-инвариант, интеграция в `advance_stage` с откатом+release lease).
+Фикс `sys.executable` вместо bare `python` (коммит `8cd7c20`) корректен — pytest-cov живёт в
+интерпретаторе орка. Нет утечек/security-дыр; измерение offline. Замечание (не finding):
+синхронный `pytest --cov` в hot-path `advance_stage` (тайм-аут `coverage_run_timeout_s=900`)
+наследует established-паттерн merge-gate re-test/security-gate — нового класса риска не вводит.
+
+**4. Документация — см. раздел «Документация» выше (P0-условие выполнено; обзорные доки N/A).**
+
+**Трассировка маркеров (TRACEABILITY).** Правки рядом с маркерами `ORCH-022`/`ORCH-043`/`ORCH-058`
+в `advance_stage` — аддитивная врезка между merge-gate и image-freshness; инварианты соседних
+под-гейтов не сломаны (release-lease зеркалит image-freshness rollback, merge через Gitea API
+не тронут). Врезка в `_handle_merge_verify` (ORCH-071/073) — never-raise best-effort ratchet,
+SHA-in-main choke-point не изменён. Чужие артефакты не повреждены (восстановлена запись ORCH-095).

docs/work-items/ORCH-027/13-test-report.md

@@ -0,0 +1,76 @@
+---
+result: PASS   # PASS | FAIL — машинный вердикт, UPPERCASE
+work_item: ORCH-027
+stage: testing
+author_agent: tester
+status: pass
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+type: test-report
+work_item_id: ORCH-027
+---
+
+# Test Report — ORCH-027 — Code coverage как гейт
+
+Work Item: **ORCH-027** · Repo: **orchestrator** · Branch: **feature/ORCH-027-code-coverage** · Стадия: testing
+Предусловие: `12-review.md` → `verdict: APPROVED` ✅ (проверено).
+
+## Окружение
+- Python: 3.12.13
+- pytest: 8.3.3 (plugins: cov-5.0.0, anyio-4.13.0, asyncio-0.23.8)
+- Worktree: `/repos/_wt/orchestrator/feature_ORCH-027-code-coverage` (HEAD `619fd0c`)
+- Дата: 2026-06-10
+
+## Smoke API (read-only)
+| Endpoint | Результат |
+|----------|-----------|
+| `GET /health` | PASS — `{"status":"ok","service":"orchestrator"}` |
+| `GET /status` | PASS — активные задачи отдаются, ORCH-027 в `testing` |
+| `GET /queue` | PASS — блоки `serial_gate` (ORCH-088) **и** `auto_labels` присутствуют в payload; добавлен read-only блок `coverage`-наблюдаемости по ТЗ FR-7 (через общий снапшот) |
+
+`serial_gate.per_repo.orchestrator.active_task = ORCH-027 (testing)` — гейт сериализации виден, регресса смока нет.
+
+## Результаты — покрытие ТЗ (каждый TC из 04-test-plan.yaml ↔ AC из 03-acceptance-criteria.md)
+
+| TC ID | Тип | Описание | Тест-функция(и) | AC | Результат |
+|-------|-----|----------|-----------------|----|-----------|
+| TC-01 | unit | `compute_coverage_verdict` policy=absolute (порог/ниже/ровно) | `test_tc01_policy_absolute` | AC-3 | PASS |
+| TC-02 | unit | policy=baseline (no-regression / ratchet) | `test_tc02_policy_baseline` | AC-3/AC-4 | PASS |
+| TC-03 | unit | policy=both — оба условия | `test_tc03_policy_both` | AC-3 | PASS |
+| TC-04 | unit | epsilon-допуск (анти-флап, NFR-4) | `test_tc04_epsilon_tolerance` | AC-3 | PASS |
+| TC-05 | unit | Ratchet базовой линии up-only + per-repo изоляция | `test_tc05_ratchet_up_only`, `test_tc05_ratchet_per_repo_isolated` | AC-4 | PASS |
+| TC-06 | unit | Bootstrap baseline при отсутствии значения | `test_tc06_bootstrap` | AC-4 | PASS |
+| TC-07 | unit | `applies(repo)`: пустой CSV → self-hosting only; вне области → no-op без прогона | `test_tc07_applies_self_hosting_only`, `test_tc07_applies_csv_scope`, `test_tc07_out_of_scope_noop_no_measure` | AC-5 | PASS |
+| TC-08 | unit | Kill-switch `coverage_gate_enabled=False` → инертен (1:1 до ORCH-027) | `test_tc08_kill_switch_off` | AC-5 | PASS |
+| TC-09 | unit | Fail-open дефолт + fail-closed по флагу | `test_tc09_fail_open_default`, `test_tc09_fail_closed_when_configured` | AC-6 | PASS |
+| TC-10 | unit | never-raise: битый вывод/отсутствие worktree не всплывает | `test_tc10_verdict_never_raises_on_bad_inputs`, `test_tc10_parse_coverage_percent_tolerant`, `test_tc10_check_never_raises`, `test_tc10_ratchet_never_raises_on_missing_report` | AC-7 | PASS |
+| TC-11 | unit | write/read-back отчёта `coverage_status:` через `src/frontmatter.py` | `test_tc11_report_roundtrip`, `test_tc11_parse_missing_frontmatter`, `test_tc11_bootstrap_report_blank_baseline` | AC-9 | PASS |
+| TC-12 | unit | Self-hosting безопасность: leaf без engine-импорта; нет деплой/force-push | `test_tc12_leaf_no_engine_import`, `test_tc12_delta_signed` | AC-7 | PASS |
+| TC-13 | integration | Гейт в конвейере: FAIL → откат на development; PASS → штатное продвижение | `test_tc13_advance_rolls_back_on_fail`, `test_tc13_advance_passes_through_on_ok` | AC-2 | PASS |
+| TC-14 | integration | Реальное измерение pytest под coverage в worktree + тайм-аут | `test_tc14_real_measurement`, `test_tc14_measure_timeout_returns_none` | AC-1 | PASS |
+| TC-15 | integration | Наблюдаемость `GET /queue` блок coverage + контракты не изменены | `test_tc15_snapshot_shape`, `test_tc15_snapshot_never_raises`, `test_tc15_registry_and_transitions_unchanged` | AC-8/AC-9 | PASS |
+
+**Итог покрытия ТЗ:** все 15 TC выполнены и сопоставлены с AC-1…AC-10; ни одного непокрытого/пропущенного TC.
+
+## Вывод pytest
+
+### Целевой набор — `tests/test_coverage_gate.py`
+```
+collected 29 items
+tests/test_coverage_gate.py::test_tc01_policy_absolute PASSED
+... (29 тестов, TC-01…TC-15) ...
+tests/test_coverage_gate.py::test_tc15_registry_and_transitions_unchanged PASSED
+======================== 29 passed, 1 warning in 2.28s =========================
+```
+
+### Полный регресс — `pytest tests/ -q`
+```
+1466 passed, 1 warning in 48.89s
+```
+(Единственное предупреждение — PydanticDeprecatedSince20 в `src/config.py:8`, не связано с ORCH-027, регрессом не является.)
+
+## Итог
+**PASS** — целевой набор coverage-гейта зелёный (29/29), полный регресс зелёный (1466/1466,
+нулевая регрессия для enduro-trails), smoke API read-only OK (`serial_gate` + `auto_labels`
+присутствуют). Каждый TC из `04-test-plan.yaml` выполнен и сопоставлен с критериями приёмки.
+Задача готова к продвижению на `deploy-staging`.

docs/work-items/ORCH-027/14-deploy-log.md

@@ -0,0 +1,12 @@
+---
+deploy_status: SUCCESS
+work_item: ORCH-027
+hook_exit_code: 0
+deployed_by: deploy-finalizer
+---
+
+# Deploy log — ORCH-036 executable self-deploy
+
+Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
+
+Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.

docs/work-items/ORCH-027/15-staging-log.md

@@ -0,0 +1,32 @@
+---
+staging_status: SUCCESS
+work_item: ORCH-027
+stage: deploy-staging
+author_agent: deployer
+status: success
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+timestamp: 2026-06-09T22:25:00Z
+base_url: http://localhost:8501
+---
+
+# Staging Gate Log
+
+Staging test suite completed against the live `orchestrator-staging` stand (8501), run canonically
+inside the container (`docker exec orchestrator-staging python3 /repos/orchestrator/scripts/staging_check.py
+--base-url http://localhost:8501 --mode stub`). **Exit code 0 → SUCCESS.** All REAL pipeline checks
+passed; the only failures are the two known waived sandbox-infra checks (C9a/C9b), tolerated under
+ORCH-061 because every REAL check is green.
+
+INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
+VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
+
+## Results
+- **Block A (SMOKE)**: PASS — A1 `/health` 200 ok; A2 `/queue` 200 with counts/max_concurrency/resilience; A3 `ORCH_STAGING=true` (not prod).
+- **Block B (ACCESS)**: PASS — B4 Plane sandbox project accessible (sandbox=YES); B5 Gitea `orchestrator-sandbox` accessible push=true; B6 Registry isolation (sandbox present, prod ET/ORCH absent).
+- **Block C (E2E, mode=stub)**: C7 create issue in Plane SANDBOX PASS; C8 trigger pipeline via `/webhook/plane` PASS; C9a/C9b FAIL — **waived sandbox-infra** (SANDBOX bot-accounts not members of the sandbox Plane project; not a pipeline regression).
+
+REAL failed: none.
+SANDBOX_INFRA failed (waived): C9a Branch appears in orchestrator-sandbox; C9b Analyst job enqueued in staging queue.
+
+Result: 8/10 checks PASS, exit 0. Tolerance `staging_infra_tolerance_enabled=True`. Cleanup OK (Plane test issue deleted, HTTP 204; no branch created to delete).

docs/work-items/ORCH-057/15-staging-log.md

@@ -0,0 +1,33 @@
+---
+staging_status: SUCCESS
+work_item: ORCH-057
+stage: deploy-staging
+author_agent: deployer
+status: success
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+timestamp: 2026-06-10T00:02:11Z
+base_url: http://localhost:8501
+---
+
+# Staging Gate Log
+
+> Машинный вердикт читается ТОЛЬКО из `staging_status:` во frontmatter. `SUCCESS` → дальше; `FAILED` → откат.
+
+Staging test suite завершён против живого стенда `orchestrator-staging` (8501). Запуск канонический —
+`docker exec orchestrator-staging python3 /repos/orchestrator/scripts/staging_check.py --base-url http://localhost:8501 --mode stub`
+(ORCH-048, ADR-001). Скрипт завершился с **exit code 0** → `staging_status: SUCCESS`.
+
+Итог: **8/10 checks PASS**. Все REAL-проверки зелёные; два FAIL — известные sandbox-infra-проверки
+(C9a/C9b), waived согласно ORCH-061 (зависят от членства SANDBOX bot-аккаунтов в проекте, не от
+конвейера). Exit-code → вердикт не меняется: trust the exit code, REAL failed = none.
+
+INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
+VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
+
+## Results
+- **Block A (SMOKE)**: PASS — A1 `/health` → 200 `status=ok`; A2 `/queue` → 200 с counts/max_concurrency/resilience; A3 `ORCH_STAGING=true` (не прод).
+- **Block B (ACCESS)**: PASS — B4 Plane sandbox доступен (5 projects, sandbox=YES); B5 Gitea `orchestrator-sandbox` доступен, push=true; B6 Registry изолирован (sandbox present, prod ET/ORCH absent).
+- **Block C (E2E, mode=stub)**: C7 создать issue в Plane SANDBOX → PASS; C8 триггер конвейера `/webhook/plane` → PASS; C9a (branch в sandbox) и C9b (analyst job в очереди) → FAIL, **INFRA-WAIVED** (sandbox bot-accounts не члены проекта). Cleanup: Plane issue удалён (HTTP 204).
+
+REAL failed: none.

docs/work-items/ORCH-099/00-business-request.md

@@ -0,0 +1,7 @@
+# Business Request: FND/F1a: лёгкий /metrics в орке — отдать сырьё (стадии/очередь/agent-liveness/cost)
+
+Work Item ID: ORCH-099
+
+## Description
+
+TBD

docs/work-items/ORCH-099/01-brd.md

@@ -0,0 +1,141 @@
+---
+work_item: ORCH-099
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 01 — BRD (бизнес-требования): ORCH-099 — FND/F1a: лёгкий `/metrics` в орке (отдать сырьё)
+
+Work Item: **ORCH-099** · Repo: **orchestrator** · Стадия: analysis
+
+## 1. Бизнес-контекст и проблема
+
+Задача — фундаментный кирпич **F1a** домена 0 «Фундамент» эпика автономного саморазвития
+(`docs/epics/self-evolution.md`). Архитектурная рамка наблюдаемости **зафиксирована заказчиком
+(Слава, 09.06)** и для аналитика — установленный факт, не предмет переизобретения:
+
+- **C-1/C-1б:** наблюдатель ОТДЕЛЁН от наблюдаемого. Мониторинг живёт в **отдельном sidecar-контейнере**
+  (`watchdog/`, рантайм — свой Dockerfile + сервис в compose), а НЕ внутри орка. Если орк
+  упал/завис/съел память — sidecar жив и репортит это.
+- **C-2/C-3:** без внешнего плеча, тонкий стек (хост впритык: RAM 171Mi free, диск 92% — НЕ
+  Grafana/Prometheus).
+- **Разделение ответственности:** орк отдаёт **только сырьё** (лёгкий read-only `/metrics` — свои
+  внутренние данные, которые знает только он сам), БЕЗ логики мониторинга/порогов/алертов/хранения.
+  Мозг (пороги, алерты, свой Telegram-канал, история) — это **F1b (sidecar)**, отдельная задача.
+
+**Боль, которую закрывает задача.** Сегодня у орка нет машинного «сырья» о самом себе в одной
+точке. `/health` отдаёт лишь `{"status":"ok"}`, `/status` — список активных задач, `/queue` —
+богатый, но «человеческий» снимок очереди, перемешанный с конфигом демонов. Ни один из них не даёт
+sidecar'у структурированный, стабильный КОНТРАКТ для детекта: застрявшая стадия, зависший агент
+(liveness по pid/CPU), деградация очереди (breaker open, рост failed), всплеск стоимости токенов.
+Без этого источника весь домен наблюдаемости (F1b и далее) слеп и не может стартовать.
+
+**Self-hosting контекст.** Орк дорабатывает сам себя; прод-контейнер общий для всех проектов.
+`/metrics` обязан быть **строго read-only** и **never-raise** — он не должен ни при каких входных
+данных уронить или притормозить прод, обслуживающий enduro-trails.
+
+## 2. Объём (scope)
+
+### В объёме
+- Новый **read-only** HTTP-эндпоинт (`GET /metrics`), отдающий JSON-снимок сырья о самом орке.
+- Четыре раздела сырья: **активные стадии задач**, **очередь jobs**, **agent-liveness**,
+  **стоимость/токены** (`agent_runs`).
+- Новый leaf-модуль `src/metrics.py` — сборка снимка из БД (чистый, never-raise, без побочных
+  эффектов), по образцу `snapshot()`-функций (`serial_gate`/`task_deps`/`cancel`).
+- Документирование формата `/metrics` как **контракта для sidecar (F1b)** в
+  `docs/architecture/README.md` + запись в `CHANGELOG.md`.
+- Pytest-покрытие: структура ответа, never-raise, read-only-инвариант.
+
+### Вне объёма
+- ❌ Любая логика мониторинга: пороги, алерты, Telegram, оценка «застрял/завис», хранение истории
+  — это **F1b (sidecar)**.
+- ❌ Сам sidecar-контейнер (`watchdog/`, Dockerfile, compose-сервис) — отдельная задача F1b.
+- ❌ Хостовые/контейнерные/внешние метрики (диск/RAM/CPU хоста, docker.sock, пинг
+  Plane/Gitea/Anthropic) — их собирает sidecar, не орк.
+- ❌ Изменение `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / схемы БД / любых machine-verdict
+  ключей.
+- ❌ Дашборд/UI (упомянут в F1 эпика как отдельный последующий шаг).
+- ❌ Прометей-совместимый text-формат — отдаём JSON (контракт под конкретный sidecar; OpenMetrics
+  не требование заказчика).
+
+## 3. Заинтересованные стороны
+
+- **Заказчик:** Слава (рамки наблюдаемости F1, эпик саморазвития).
+- **Прямой потребитель контракта:** будущий sidecar **F1b** (`watchdog/`) — читает `/metrics` по
+  HTTP. Задача F1b **заблокирована** этой (ORCH-099 — источник контракта).
+- **Затрагивается:** прод-инстанс орка (общий с enduro-trails) — поэтому жёсткое требование
+  read-only/never-raise.
+- **Принимает результат:** reviewer/tester конвейера + Слава как владелец рамок.
+
+## 4. Бизнес-требования (BR)
+
+- **BR-1 — Эндпоинт сырья.** Орк предоставляет HTTP `GET /metrics`, отдающий JSON с четырьмя
+  разделами: (a) активные стадии задач, (b) очередь jobs, (c) agent-liveness, (d) стоимость/токены.
+  Состав полей каждого раздела — см. TRZ §3 (FR-1…FR-4).
+- **BR-2 — Стадии задач.** По каждой незавершённой задаче отдаётся `work_item`, текущая `stage` и
+  «как давно в стадии» (секунды) — сырьё для детекта застреваний sidecar'ом.
+- **BR-3 — Очередь jobs.** Отдаются счётчики по статусам (`queued`/`running`/`failed`/…), глубина
+  очереди, информация о ретраях и состояние circuit-breaker'а — сырьё для детекта деградации.
+- **BR-4 — Agent-liveness.** По каждому running-job отдаётся `agent`, `run_id`, `pid`, `runtime_s`
+  и сырьё для alive-детекта (CPU-тики pid либо данные, по которым sidecar посчитает CPU-дельту).
+  sidecar — арбитр «жив/завис»; орк лишь поставляет факты.
+- **BR-5 — Стоимость/токены.** Отдаётся текущая (по running-job) и агрегированная стоимость/токены
+  из `agent_runs` (`cost_usd`, `input/output/cache_*` токены) — сырьё для cost-наблюдаемости (D3).
+- **BR-6 — Аддитивность.** Существующие `/health`, `/status`, `/queue` остаются байт-в-байт прежними
+  по контракту; `/metrics` добавляется рядом, ничего не ломая.
+- **BR-7 — Документированный контракт.** Формат `/metrics` зафиксирован в
+  `docs/architecture/README.md` как стабильный контракт для sidecar (F1b) + `CHANGELOG.md`.
+
+## 5. Нефункциональные требования (NFR)
+
+- **NFR-1 — Read-only.** Эндпоинт НИЧЕГО не мутирует: не пишет в БД, не запускает/останавливает
+  процессы, не рестартит, не дёргает внешние API. Только SELECT'ы + чтение in-memory-снимков
+  демонов.
+- **NFR-2 — Never-raise (по полям).** Любая ошибка при сборе отдельного поля/раздела → это поле
+  получает `null` (или раздел — безопасный дефолт), но эндпоинт **возвращает 200 и валидный JSON**,
+  никогда не 500. Эталон — `serial_gate.snapshot()` с fallback в `except`.
+- **NFR-3 — Лёгкость.** Только быстрые запросы к локальной SQLite + чтение уже посчитанных
+  in-memory снапшотов; без тяжёлых вычислений, без сетевых вызовов, без сканирования файлов/git.
+  Цель — единичные мс на типовом объёме (десятки задач/jobs).
+- **NFR-4 — Self-hosting-безопасность.** Эндпоинт физически не способен повлиять на прод-конвейер
+  (следствие NFR-1) — безопасен на общем инстансе с enduro-trails.
+- **NFR-5 — Совместимость БД/гейтов.** `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` /
+  machine-verdict ключи / схема БД — НЕ трогаются. Задача читает существующие таблицы
+  (`tasks`/`jobs`/`agent_runs`) и существующие in-memory снапшоты.
+- **NFR-6 — Стабильность контракта.** Формат — аддитивный и версионируемый (поле `schema_version`),
+  чтобы будущие расширения не ломали уже написанный sidecar.
+
+## 6. Допущения и ограничения
+
+- **Данные уже есть в БД.** Все нужные поля присутствуют: `tasks(stage, work_item_id, updated_at,
+  created_at)`, `jobs(status, attempts, max_attempts, transient_attempts, available_at, pid,
+  run_id)`, `agent_runs(agent, started_at, finished_at, model, effort, cost_usd, input_tokens,
+  output_tokens, cache_read_tokens, cache_creation_tokens)`. **Новые колонки/таблицы не нужны.**
+- **Breaker-состояние — in-memory** (`queue_worker.worker.status()` / `CircuitBreaker.snapshot()`);
+  читается без БД.
+- **CPU-тики pid** читаются из `/proc/<pid>/stat` (Linux прод-контейнер). Допущение: контейнер
+  Linux; при отсутствии/гонке (процесс уже умер) — поле `null` (NFR-2), НЕ ошибка. Это согласуется
+  с рамкой C-1: «орк лёг → endpoint недоступен = сам сигнал тревоги» — детект делает sidecar.
+- **Арбитраж liveness — на стороне sidecar.** Орк не решает «завис/жив»; он лишь отдаёт `pid`,
+  `runtime_s` и (по возможности) CPU-тики; sidecar считает дельту между опросами.
+- **Формат — JSON**, не OpenMetrics/Prometheus (рамка C-3: тонкий кастомный sidecar, не Prometheus).
+
+## 7. Критерии успеха
+
+`GET /metrics` отдаёт лёгкий, read-only, never-raise JSON с четырьмя разделами сырья;
+`/health`/`/status`/`/queue` не сломаны; формат задокументирован как контракт sidecar; pytest
+зелёный. Детальные PASS/FAIL — `03-acceptance-criteria.md`.
+
+## 8. Риски
+
+- Гонка чтения `/proc/<pid>/stat` (процесс умер между выборкой job и чтением proc) → закрывается
+  NFR-2 (`null`, не ошибка).
+- Расхождение контракта `/metrics` и ожиданий sidecar (F1b) → закрывается BR-7 (контракт в одном
+  репо, документирован) + `schema_version` (NFR-6).
+- Соблазн «протащить» в `/metrics` логику алертинга → закрывается scope-границей (вне объёма) и
+  NFR-1.
+
+Детальная оценка технических рисков — `10-tech-risks.md` (заполняет архитектор).

docs/work-items/ORCH-099/02-trz.md

@@ -0,0 +1,173 @@
+---
+work_item: ORCH-099
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 02 — ТЗ (TRZ): ORCH-099 — FND/F1a: лёгкий `/metrics` в орке (отдать сырьё)
+
+Work Item: **ORCH-099** · Repo: **orchestrator** · Стадия: analysis
+
+> ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода.
+> Архитектурное обоснование/решения (формат полей liveness, способ чтения CPU, версионирование
+> контракта) — задача архитектора (`06-adr/`).
+
+## 1. Сводка изменения
+
+Добавить read-only HTTP-эндпоинт `GET /metrics`, отдающий JSON-снимок «сырья» о самом орке для
+будущего sidecar (F1b): активные стадии задач, очередь jobs, agent-liveness, стоимость/токены.
+Логика сборки выносится в **новый leaf-модуль** `src/metrics.py` (чистая функция-сборщик, never-raise,
+без побочных эффектов — по образцу `serial_gate.snapshot()`/`task_deps.snapshot()`/`cancel.snapshot()`).
+Эндпоинт в `src/main.py` — тонкая обёртка над сборщиком, в том же стиле, что `GET /queue`
+(`src/main.py`, дикт с разделами). Никаких изменений `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схемы
+БД/machine-verdict ключей. Только чтение существующих таблиц и существующих in-memory-снапшотов.
+
+## 2. Задействованные модули / пути
+
+| Путь | Действие |
+|------|----------|
+| `src/metrics.py` | **создать** — leaf-сборщик снимка из БД (`build_metrics() -> dict`, never-raise) |
+| `src/main.py` | изменить — добавить `@app.get("/metrics")` (тонкая обёртка над `metrics.build_metrics()`) |
+| `src/db.py` | изменить (при необходимости) — добавить read-only helper(ы) для агрегатов `agent_runs` (напр. `agent_cost_totals()`); существующие `job_status_counts`/`get_running_jobs`/`recent_jobs`/`get_active_tasks_for_reconcile` переиспользуются как есть |
+| `docs/architecture/README.md` | изменить — задокументировать контракт `/metrics` (формат для sidecar F1b) |
+| `CHANGELOG.md` | изменить — запись `## [Unreleased]` (ORCH-099) |
+| `tests/test_metrics.py` | **создать** — pytest на структуру/never-raise/read-only |
+
+**Существующие источники данных (переиспользуются, НЕ дублируются):**
+- `db.get_active_tasks_for_reconcile()` — задачи с `stage != 'done'` + вычисленный `age_s`
+  (секунды с `updated_at`). Базис для раздела стадий.
+- `db.job_status_counts()` — `{queued, running, done, failed}` из `jobs`.
+- `db.get_running_jobs()` — running-jobs с `running_age_s`, плюс джойн на `agent_runs` (`agent`,
+  `run_id`, `pid`, `started_at`, `model`, `effort`). Базис для liveness.
+- `queue_worker.worker.status()` / `worker.breaker.snapshot()` — breaker-состояние in-memory
+  (`state`/`consecutive_transient`/`pause_remaining_s`), `max_concurrency`, `poll_interval`.
+
+## 3. Функциональные требования
+
+### FR-1 — Раздел `stages` (активные стадии задач) — BR-2
+
+Список активных (незавершённых) задач. По каждой:
+- `work_item` — `tasks.work_item_id`.
+- `stage` — `tasks.stage` (значение слоя A, машина стадий).
+- `age_in_stage_s` — целое; секунды с `tasks.updated_at` (= момент последней смены стадии).
+  Источник вычисления — SQL `CAST(strftime('%s','now') - strftime('%s', updated_at) AS INTEGER)`,
+  как в `get_active_tasks_for_reconcile`.
+- `repo` — `tasks.repo` (sidecar мультипроектный; нужно отличать orchestrator от enduro-trails).
+- (опционально) `task_id`, `created_age_s` (общий возраст задачи).
+
+Инвариант: выборка только `stage NOT IN ('done', 'cancelled')` (терминальные исключены — см.
+ORCH-090: множество терминалов `{done, cancelled}`). Пустой список — валидный ответ.
+
+### FR-2 — Раздел `queue` (очередь jobs) — BR-3
+
+- `counts` — `db.job_status_counts()` (`queued`/`running`/`done`/`failed`); при наличии —
+  добавить `cancelled` (ORCH-090 терминал).
+- `depth` — глубина очереди = число `queued`-jobs, готовых к выдаче (можно вернуть как
+  `counts.queued`; при желании — отдельно «доступные сейчас» с учётом `available_at <= now`).
+- `retries` — сырьё по ретраям: сумма/список `attempts` vs `max_attempts` и `transient_attempts`
+  по незавершённым jobs; как минимум агрегат «сколько jobs в backoff» (`available_at > now`).
+- `breaker` — `worker.breaker.snapshot()`: `state` (`closed`/`open`/`half-open`),
+  `consecutive_transient`, `pause_remaining_s`.
+- `max_concurrency` — `worker.max_concurrency`.
+
+Инвариант: ни одно поле не обязано существовать ценой падения — недоступный breaker
+(например, worker не инициализирован в тесте) → `breaker: null`, не 500 (NFR-2).
+
+### FR-3 — Раздел `agents` (agent-liveness) — BR-4
+
+Список running-jobs (из `db.get_running_jobs()`), по каждому:
+- `agent` — `agent_runs.agent` (через джойн; роль: analyst/architect/developer/…).
+- `run_id` — `jobs.run_id` (= `agent_runs.id`).
+- `job_id` — `jobs.id`.
+- `pid` — `jobs.pid` (может быть `null`, если процесс ещё не застамплен / уже завершён).
+- `runtime_s` — `running_age_s` из `get_running_jobs` (секунды с `jobs.started_at`); как
+  альтернатива — секунды с `agent_runs.started_at`. Решение о базисе — за архитектором (ADR).
+- **Сырьё для alive-детекта** — одно из (выбор реализации — ADR архитектора, BR-4 допускает оба):
+  - вариант A: `cpu_ticks` — суммарные utime+stime из `/proc/<pid>/stat` (поля 14–15), плюс
+    `clk_tck` (`os.sysconf("SC_CLK_TCK")`), чтобы sidecar посчитал CPU-дельту между опросами;
+  - вариант B: орк сам не считает дельту (он опрашивается стейтлесс sidecar'ом) — отдаёт только
+    сырые тики + временную метку выборки.
+- `model`, `effort` — `agent_runs.model`/`effort` (контекст стоимости).
+
+Инвариант (NFR-2): `pid is None` ИЛИ `/proc/<pid>` отсутствует/гонка (процесс умер) →
+`cpu_ticks: null` для этого агента, остальные поля и весь эндпоинт целы. НЕ бросать, НЕ ждать.
+
+### FR-4 — Раздел `cost` (стоимость/токены) — BR-5
+
+- `running` — по каждому running-job текущие накопленные значения из `agent_runs`, если уже
+  застамплены (часто `null` до завершения — токены/cost парсятся из CLI-JSON в `_monitor_agent`
+  по окончании). Допустимо отдавать `null` для незавершённых — это честное сырьё.
+- `aggregate` — агрегаты по `agent_runs`: суммарные `cost_usd`, `input_tokens`, `output_tokens`,
+  `cache_read_tokens`, `cache_creation_tokens`. Желателен срез: всего + за последние N (или
+  по `repo`). Реализуется новым read-only helper'ом `db.agent_cost_totals()` (чистый SELECT
+  с `COALESCE(SUM(...),0)`).
+
+Инвариант: пустая `agent_runs` → нули, не ошибка.
+
+### FR-5 — Конверт ответа (envelope) — BR-1, BR-6, NFR-6
+
+`GET /metrics` возвращает JSON:
+```json
+{
+  "schema_version": 1,
+  "generated_at": "<ISO-8601 / datetime('now')>",
+  "stages": [ ... ],
+  "queue": { ... },
+  "agents": [ ... ],
+  "cost": { "running": [...], "aggregate": {...} }
+}
+```
+- `schema_version` — целое; точка стабильности контракта для sidecar (NFR-6). Стартовое значение
+  и политика инкремента — за архитектором.
+- `generated_at` — метка времени снимка (нужна sidecar'у для расчёта дельт).
+- Точные имена ключей разделов/полей фиксируются в `docs/architecture/README.md` (BR-7) и являются
+  контрактом; reviewer/tester сверяют ответ с документом.
+
+### FR-6 — Never-raise сборщик — NFR-2
+
+`metrics.build_metrics()` строит ответ по-раздельно; каждый раздел — в своём `try/except`, в
+`except` пишет `logger.warning(...)` и подставляет безопасный дефолт (`null`/`[]`/`{}`). Функция
+**никогда** не пробрасывает исключение. Эндпоинт `main` дополнительно не нуждается в обработке, но
+обязан вернуть результат сборщика как есть. Эталон — `serial_gate.snapshot()`.
+
+## 4. Изменения API
+
+**Новый эндпоинт:**
+- `GET /metrics` → `200 application/json`, тело — конверт FR-5. Без параметров. Без аутентификации
+  сверх существующей (тот же уровень, что `/queue`/`/status`). Read-only.
+
+**Изменённые эндпоинты:** Нет. `/health`, `/status`, `/queue`, `/webhook/*` — без изменений
+(BR-6). Регресс-проверка: существующие тесты эндпоинтов остаются зелёными.
+
+## 5. Изменения схемы БД
+
+**Нет.** Новые таблицы/колонки/индексы/миграции не вводятся. Используются существующие
+`tasks`/`jobs`/`agent_runs` и их колонки (перечислены в §2). Допускается добавление **read-only**
+helper-функций в `src/db.py` (например `agent_cost_totals()`) — это код, не схема; `CREATE`/`ALTER`
+не выполняются. `STAGE_TRANSITIONS`/`QG_CHECKS`/схема — байт-в-байт прежние (NFR-5).
+
+## 6. Требования к новым/изменённым QG checks
+
+**Нет.** `/metrics` — наблюдаемость, не гейт конвейера. `QG_CHECKS` / `check_*` / `_parse_*` /
+machine-verdict ключи (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`/
+`coverage_status:`) — НЕ трогаются. Новых артефактов pipeline (`NN-*.md`) задача не создаёт.
+
+## 7. Совместимость / регресс
+
+- **Аддитивность:** новый модуль (`src/metrics.py`) + новый эндпоинт + read-only helper(ы).
+  Существующий код путей конвейера не модифицируется.
+- **Read-only / never-raise:** по конструкции (NFR-1/NFR-2) эндпоинт не влияет на состояние и не
+  падает → нулевой риск для прод-конвейера, общего с enduro-trails (NFR-4).
+- **Kill-switch:** жёсткий флаг не обязателен (эндпоинт инертен и не подключён к конвейеру). Если
+  архитектор сочтёт нужным — допустим конфиг-флаг включения `/metrics` (по образцу snapshot-флагов),
+  но это НЕ требование BRD; дефолт — эндпоинт доступен.
+- **Обратимость:** удаление эндпоинта/модуля полностью откатывает изменение без следов в БД/схеме.
+- **Контракт sidecar:** `schema_version` + документ в README обеспечивают, что F1b не сломается при
+  будущих аддитивных расширениях (NFR-6).
+- **Артефакты pipeline, создаваемые/обновляемые задачей:** `01-brd.md`, `02-trz.md`,
+  `03-acceptance-criteria.md`, `04-test-plan.yaml` (analysis); далее — `06-adr/` (architect),
+  обновление `docs/architecture/README.md` и `CHANGELOG.md` (developer в том же PR — правило
+  «доки = golden source»).

docs/work-items/ORCH-099/03-acceptance-criteria.md

@@ -0,0 +1,127 @@
+---
+work_item: ORCH-099
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 03 — Критерии приёмки (Acceptance Criteria): ORCH-099 — FND/F1a: лёгкий `/metrics` в орке
+
+Work Item: **ORCH-099** · Repo: **orchestrator** · Стадия: analysis
+
+Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL**
+(что считается провалом). Reviewer/tester проверяет их буквально по файлам репозитория и по ответу
+эндпоинта.
+
+---
+
+## AC-1 — Эндпоинт `/metrics` отдаёт четыре раздела сырья
+
+**Условие:** `GET /metrics` возвращает `200` и JSON с разделами `stages`, `queue`, `agents`, `cost`
+(плюс конверт `schema_version` / `generated_at`), с полями из TRZ §3.
+- **PASS:** ответ — валидный JSON-объект; присутствуют ключи `schema_version`, `generated_at`,
+  `stages` (список; элемент содержит `work_item`, `stage`, `age_in_stage_s`, `repo`), `queue`
+  (содержит `counts`, `breaker`, `max_concurrency`, сырьё ретраев), `agents` (список; элемент
+  содержит `agent`, `run_id`, `pid`, `runtime_s` и поле сырья CPU-liveness), `cost` (содержит
+  `aggregate` с суммами `cost_usd`/`input_tokens`/`output_tokens`/`cache_read_tokens`/
+  `cache_creation_tokens`).
+- **FAIL:** отсутствует любой из четырёх разделов; в `agents` нет `pid`/`runtime_s`; в `stages` нет
+  «как давно в стадии»; в `cost` нет агрегата токенов/стоимости; ответ не JSON или статус ≠ 200.
+
+---
+
+## AC-2 — Аддитивность: `/health`, `/status`, `/queue` не сломаны
+
+**Условие:** существующие эндпоинты сохраняют прежний контракт.
+- **PASS:** `GET /health` → `{"status":"ok", ...}`; `GET /status` → `{"active_tasks":[...]}`;
+  `GET /queue` отдаёт прежний набор ключей; существующие тесты эндпоинтов (`tests/test_queue_endpoint.py`
+  и пр.) зелёные без модификации их ожиданий.
+- **FAIL:** изменён/удалён любой существующий ключ ответа `/health`/`/status`/`/queue`; пришлось
+  править существующие тесты под новый контракт; регресс в этих эндпоинтах.
+
+---
+
+## AC-3 — Лёгкость и быстрая выборка
+
+**Условие:** эндпоинт лёгкий — только быстрые локальные SQL + чтение in-memory снапшотов, без
+тяжёлых вычислений и сетевых вызовов.
+- **PASS:** в коде `src/metrics.py` нет сетевых вызовов (HTTP/Plane/Gitea/Anthropic), нет запуска
+  подпроцессов кроме безопасного чтения `/proc/<pid>/stat`, нет сканирования git/файлового дерева;
+  данные берутся из существующих helper'ов БД и `worker`-снапшота; на типовом объёме ответ
+  формируется без заметной задержки.
+- **FAIL:** эндпоинт делает сетевой запрос, запускает агента/тяжёлый процесс, сканирует worktree/git
+  или выполняет дорогие агрегаты, заметно тормозящие ответ.
+
+---
+
+## AC-4 — Never-raise (ошибка поля → `null`, эндпоинт не падает)
+
+**Условие:** любая ошибка сбора отдельного поля/раздела не роняет эндпоинт.
+- **PASS:** при недоступном источнике (например, `worker` не инициализирован, `pid` уже мёртв,
+  `/proc/<pid>` отсутствует, пустые таблицы) соответствующее поле получает `null`/безопасный дефолт,
+  а `GET /metrics` всё равно возвращает `200` и валидный JSON; есть тест, симулирующий сбой раздела
+  и проверяющий 200 + `null` в этом поле.
+- **FAIL:** при любом из перечисленных условий эндпоинт возвращает `500` / бросает исключение /
+  возвращает невалидный JSON.
+
+---
+
+## AC-5 — Read-only (ничего не меняет; гейты/схема не тронуты)
+
+**Условие:** эндпоинт и модуль строго read-only; конвейерные инварианты целы.
+- **PASS:** `src/metrics.py` и обработчик `/metrics` не выполняют `INSERT`/`UPDATE`/`DELETE`/`CREATE`/
+  `ALTER`, не запускают/останавливают процессы, не рестартят, не мутируют состояние демонов;
+  `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, machine-verdict ключи и схема БД (`tasks`/`jobs`/
+  `agent_runs` и пр.) — без изменений в диффе; повторный вызов `/metrics` не меняет состояние БД
+  (тест: снимок БД до/после идентичен).
+- **FAIL:** дифф трогает `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схему/machine-verdict; модуль
+  выполняет любую запись/мутацию; вызов эндпоинта меняет состояние.
+
+---
+
+## AC-6 — agent-liveness содержит сырьё для alive-детекта
+
+**Условие:** по каждому running-job отдаётся идентификация процесса и сырьё для CPU-детекта
+sidecar'ом.
+- **PASS:** для running-job ответ содержит `agent`, `run_id`, `pid`, `runtime_s` и поле сырья
+  CPU-liveness (например `cpu_ticks` из `/proc/<pid>/stat` + базис тиков `clk_tck`, либо
+  эквивалент по решению ADR), позволяющее внешнему наблюдателю посчитать CPU-дельту между опросами;
+  при `pid is None`/мёртвом процессе CPU-поле = `null` (см. AC-4), прочие поля целы.
+- **FAIL:** liveness-раздел не позволяет sidecar'у отличить «жив» от «завис» (нет ни CPU-сырья, ни
+  pid+runtime); отсутствуют `run_id`/`pid`; обращение к мёртвому pid роняет эндпоинт.
+
+---
+
+## AC-7 — Контракт задокументирован (для sidecar F1b) + CHANGELOG
+
+**Условие:** формат `/metrics` зафиксирован как контракт и отражён в журнале изменений.
+- **PASS:** в `docs/architecture/README.md` описан формат ответа `/metrics` (разделы, поля,
+  `schema_version`) как стабильный контракт для sidecar (F1b); в `CHANGELOG.md` есть запись
+  `## [Unreleased]` с пометкой `ORCH-099`.
+- **FAIL:** формат не задокументирован или описан только в коде; нет записи в `CHANGELOG.md`;
+  документация противоречит фактическому ответу эндпоинта.
+
+---
+
+## AC-8 — pytest зелёный
+
+**Условие:** новый тест-набор и полный регресс проходят.
+- **PASS:** `pytest tests/ -q` зелёный; присутствует `tests/test_metrics.py`, покрывающий структуру
+  ответа (AC-1), never-raise (AC-4), read-only (AC-5), liveness-сырьё (AC-6) и аддитивность (AC-2).
+- **FAIL:** любой тест красный; новые тесты отсутствуют или не покрывают перечисленные критерии.
+
+---
+
+## Сводная матрица AC ↔ FR/BR
+| AC | Покрывает |
+|----|-----------|
+| AC-1 | BR-1/BR-2/BR-3/BR-5 / FR-1…FR-5 |
+| AC-2 | BR-6 / FR-4 |
+| AC-3 | NFR-3 / FR-6 |
+| AC-4 | NFR-2 / FR-6 |
+| AC-5 | NFR-1/NFR-4/NFR-5 / FR-5 |
+| AC-6 | BR-4 / FR-3 |
+| AC-7 | BR-7 / FR-5 |
+| AC-8 | NFR-3 (валидация) / все FR |

docs/work-items/ORCH-099/04-test-plan.yaml

@@ -0,0 +1,86 @@
+work_item: ORCH-099
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+title: "FND/F1a — лёгкий read-only /metrics: стадии/очередь/agent-liveness/cost"
+framework: pytest
+scope: >
+  Покрывается: структура ответа GET /metrics (4 раздела + конверт), never-raise по полям,
+  read-only инвариант, agent-liveness сырьё (pid/runtime/cpu-тики), агрегаты cost/токенов,
+  аддитивность (не сломаны /health//status//queue). Вне покрытия: сам sidecar (F1b),
+  хостовые/контейнерные метрики, пороги/алерты/Telegram. Полный регресс tests/ остаётся зелёным.
+notes: >
+  Тесты идут в новый tests/test_metrics.py. Используется существующий паттерн conftest.py
+  (autouse fresh_db на tmp_path + init_db, monkeypatch send_telegram). Эндпоинт зовётся как
+  корутина через asyncio.run(main.metrics()) по образцу tests/test_queue_endpoint.py
+  (asyncio.run(main.queue())). Read-only проверяется сравнением снимка БД до/после вызова.
+  Never-raise — monkeypatch источника (worker / helper БД / чтения /proc) на бросающий стаб.
+
+tests:
+  - id: TC-01
+    type: unit
+    description: "build_metrics() возвращает dict с ключами schema_version, generated_at, stages, queue, agents, cost (конверт FR-5)."
+    module: tests/test_metrics.py
+    expected: PASS
+
+  - id: TC-02
+    type: unit
+    description: "Раздел stages: для задачи со stage!=done/cancelled элемент содержит work_item, stage, age_in_stage_s (int), repo; терминальные задачи (done/cancelled) исключены."
+    module: tests/test_metrics.py
+    expected: PASS
+
+  - id: TC-03
+    type: unit
+    description: "Раздел queue: counts (queued/running/failed), max_concurrency, сырьё ретраев и breaker-снимок (state/consecutive_transient/pause_remaining_s) присутствуют."
+    module: tests/test_metrics.py
+    expected: PASS
+
+  - id: TC-04
+    type: unit
+    description: "Раздел agents: по running-job отдаются agent, run_id, job_id, pid, runtime_s и поле CPU-liveness сырья (cpu_ticks или эквивалент)."
+    module: tests/test_metrics.py
+    expected: PASS
+
+  - id: TC-05
+    type: unit
+    description: "agent-liveness never-raise: при pid=None или отсутствующем /proc/<pid> CPU-поле = null, остальные поля агента и весь ответ целы (без исключения)."
+    module: tests/test_metrics.py
+    expected: PASS
+
+  - id: TC-06
+    type: unit
+    description: "Раздел cost.aggregate: суммы cost_usd/input_tokens/output_tokens/cache_read_tokens/cache_creation_tokens из agent_runs; пустая таблица -> нули, не ошибка."
+    module: tests/test_metrics.py
+    expected: PASS
+
+  - id: TC-07
+    type: unit
+    description: "Never-raise по разделу: если источник раздела (напр. job_status_counts/worker.status) бросает, раздел получает null/дефолт, build_metrics() не пробрасывает исключение."
+    module: tests/test_metrics.py
+    expected: PASS
+
+  - id: TC-08
+    type: integration
+    description: "GET /metrics через ASGI/обработчик возвращает 200 и валидный JSON со всеми разделами на засеянной БД (задача + running-job + agent_run)."
+    module: tests/test_metrics.py
+    expected: PASS
+
+  - id: TC-09
+    type: integration
+    description: "Read-only: снимок всех таблиц БД (tasks/jobs/agent_runs) до и после вызова /metrics идентичен; повторный вызов не меняет состояние."
+    module: tests/test_metrics.py
+    expected: PASS
+
+  - id: TC-10
+    type: integration
+    description: "Аддитивность: GET /health, /status, /queue сохраняют прежний контракт (ключи на месте) при наличии /metrics; существующие тесты эндпоинтов зелёные."
+    module: tests/test_metrics.py
+    expected: PASS
+
+  - id: TC-11
+    type: unit
+    description: "Пустое состояние: при отсутствии активных задач/running-jobs/agent_runs ответ валиден — stages=[], agents=[], cost.aggregate=нули, queue.counts с нулями; 200/без исключений."
+    module: tests/test_metrics.py
+    expected: PASS

docs/work-items/ORCH-099/06-adr/ADR-001-metrics-endpoint.md

@@ -0,0 +1,249 @@
+---
+work_item: ORCH-099
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# ADR-001: Лёгкий read-only `/metrics` — сырьё о самом орке для sidecar (F1b)
+
+Work Item: **ORCH-099** — FND/F1a: лёгкий `/metrics` в орке (отдать сырьё)
+Стадия: **architecture**
+Сквозная регистрация: **`docs/architecture/adr/adr-0030-metrics-endpoint.md`** (решение
+кросс-каттинговое — новый компонент наблюдаемости + новый публичный HTTP-контракт для будущего
+sidecar F1b).
+
+## Статус
+Proposed
+
+## Контекст
+
+F1a — фундаментный кирпич домена 0 «Фундамент» эпика автономного саморазвития. Рамка наблюдаемости
+зафиксирована заказчиком (BRD §1): **наблюдатель отделён от наблюдаемого** — мониторинг (пороги,
+алерты, история, свой Telegram) живёт в отдельном sidecar-контейнере **F1b** (`watchdog/`), а орк
+отдаёт **только сырьё**, которое знает лишь он сам. F1a поставляет источник этого сырья и **ничего
+больше**.
+
+Факты, сверенные с кодом:
+- `GET /health` (`src/main.py:147`) → `{"status":"ok", ...}`; `GET /status` (`:152`) → список
+  активных задач; `GET /queue` (`:163`) — богатый, но «человеческий» снимок, перемешанный с
+  конфигом демонов (reconciler/reaper/post_deploy/disk_monitor/…). Ни один не даёт **стабильного
+  машинного контракта** для детекта: застрявшая стадия, зависший агент, деградация очереди, всплеск
+  стоимости.
+- Все нужные данные уже в БД и in-memory: `db.get_active_tasks_for_reconcile()` (`src/db.py:388` —
+  `stage != 'done'` + `age_s` в SQL), `db.get_running_jobs()` (`:1103` — `SELECT j.*` + `running_age_s`,
+  LEFT JOIN `agent_runs` на `run_id`), `db.job_status_counts()` (`:1187`),
+  `queue_worker.worker.status()`/`CircuitBreaker.snapshot()` (`src/queue_worker.py:242`/`:113` — breaker
+  in-memory). `pid`/`run_id`/`job_id` — колонки `jobs` (ORCH-065, `:83`); `model`/`effort`/`cost_usd`/
+  `*_tokens` — колонки `agent_runs` (`:97`–`:106`). Терминальное множество — `{done, cancelled}`
+  (ORCH-090, adr-0026).
+- Self-hosting: прод-контейнер общий с enduro-trails. Эндпоинт обязан быть строго **read-only** и
+  **never-raise** — не ронять и не тормозить прод ни при каких входных данных.
+
+«Как есть» не годится: добавлять поля в `/queue` сломало бы его контракт (BR-6) и смешало бы сырьё с
+человеческим снимком; в коде sidecar'а нет ни одной стабильной точки опроса. Нужен отдельный,
+версионируемый, машинный контракт.
+
+## Решение
+
+### Сводка
+
+Новый **leaf-модуль** `src/metrics.py` с чистой never-raise функцией-сборщиком
+`build_metrics() -> dict` (по образцу `serial_gate.snapshot()`/`task_deps.snapshot()`/
+`cancel.snapshot()`) + тонкий эндпоинт `@app.get("/metrics")` в `src/main.py` (обёртка над
+сборщиком, в стиле `GET /queue`). Сборщик собирает четыре раздела (`stages`/`queue`/`agents`/`cost`)
+в версионируемом конверте, **каждый раздел — в своём `try/except`** с безопасным дефолтом. Только
+чтение существующих таблиц (`tasks`/`jobs`/`agent_runs`) и существующих in-memory-снапшотов + два
+read-only helper'а в `src/db.py`. `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict-ключи/
+схема БД — **не трогаются**.
+
+### D1 — Новый leaf-модуль + тонкий эндпоинт (изоляция, never-raise по разделам)
+
+Логика сборки — в `src/metrics.py`, не в `main.py` (тестируемость без ASGI, паттерн `*.snapshot()`).
+`build_metrics()` строит конверт по-раздельно; каждый раздел обёрнут в `try/except Exception`, в
+`except` → `logger.warning(...)` + безопасный дефолт (`null` для скаляра/объекта, `[]` для списка).
+Функция **никогда** не пробрасывает исключение (FR-6, NFR-2, AC-4). Эндпоинт `/metrics` —
+тонкая обёртка: возвращает `build_metrics()` как есть; собственной обработки ошибок не требует
+(сборщик уже never-raise). Уровень доступа — тот же, что `/queue`/`/status` (без доп. аутентификации,
+FR-4).
+
+Привязка: FR-6, NFR-1, NFR-2, AC-4, AC-5.
+
+### D2 — Конверт ответа + контракт `schema_version` (BR-1, BR-6, NFR-6)
+
+```json
+{
+  "schema_version": 1,
+  "generated_at": "2026-06-10T12:34:56Z",
+  "clk_tck": 100,
+  "stages":  [ ... ],
+  "queue":   { ... },
+  "agents":  [ ... ],
+  "cost":    { "running": [ ... ], "aggregate": { ... } }
+}
+```
+
+- **`schema_version` стартует с `1`.** Политика инкремента (контракт для F1b, документируется в
+  README, BR-7): **аддитивные** изменения (новое поле/раздел) **НЕ бампят версию** — sidecar
+  **обязан игнорировать незнакомые ключи и толерировать отсутствие опциональных**. Версия бампится
+  **только при ломающем** изменении (переименование/удаление/смена типа существующего поля). Это
+  делает контракт forward-compatible: будущие расширения F1a не ломают уже написанный F1b (NFR-6,
+  TR-4). Формат-чек версии — по духу `is_valid_model` (ORCH-74): структурный, не статичный allowlist.
+- **`generated_at`** — `datetime('now')` UTC, ISO-8601 (тот же часовой домен, что timestamp'ы БД и
+  выборка CPU-тиков). Это момент снимка: sidecar считает дельты между двумя опросами по
+  `(cpu_ticks, generated_at)` из ответов — **всё в часах самого орка**, поэтому расчёт иммунен к
+  расхождению часов орк↔sidecar (TR-3).
+- **`clk_tck`** — `os.sysconf("SC_CLK_TCK")` на уровне конверта (а не на каждом агенте — значение
+  процесс-глобальное): базис для перевода CPU-тиков в секунды на стороне sidecar.
+
+Привязка: BR-1, BR-6, NFR-6, FR-5, AC-1, AC-7.
+
+### D3 — Раздел `stages` (BR-2, FR-1)
+
+Список активных задач из `db.get_active_tasks_for_reconcile()`, **с дополнительной фильтрацией
+`stage NOT IN ('done','cancelled')`** на слое metrics. Обоснование: helper намеренно возвращает
+`cancelled`-задачи (для skip-счётчика реконсилятора ORCH-086, см. `src/db.py:396`) — но для сырья
+наблюдаемости терминальные задачи не нужны (терминальное множество `{done, cancelled}`, ORCH-090).
+Не меняем helper (его инвариант принадлежит ORCH-053/086) — фильтруем на потребителе. По каждой
+задаче: `work_item` (`work_item_id`), `stage`, `age_in_stage_s` (= `age_s`, целое, SQL
+`strftime` против UTC-now — момент последней смены стадии), `repo` (sidecar мультипроектный),
+опц. `task_id`/`created_age_s`. Пустой список — валидный ответ (AC, TC-11).
+
+Привязка: BR-2, FR-1, AC-1, TC-02, TC-11.
+
+### D4 — Раздел `queue` (BR-3, FR-2)
+
+- `counts` — `db.job_status_counts()` (`queued`/`running`/`done`/`failed`); добавить `cancelled`
+  (ORCH-090 терминал) — helper уже агрегирует `GROUP BY status`, нужно лишь не терять ключ.
+- `depth` — глубина очереди = число `queued`-jobs (можно `counts.queued`); опц. «доступные сейчас»
+  с учётом `available_at <= now`.
+- `retries` — агрегат по незавершённым jobs: `attempts` vs `max_attempts`, `transient_attempts`, и
+  как минимум «сколько jobs в backoff» (`available_at > now`). Источник — read-only SELECT-агрегат
+  (новый helper или агрегация по `recent_jobs`/прямой SELECT; решение реализации за developer'ом в
+  рамках read-only).
+- `breaker` — `worker.breaker.snapshot()` (`state`/`consecutive_transient`/`pause_remaining_s`).
+- `max_concurrency` — `worker.max_concurrency`; опц. `poll_interval`.
+
+Инвариант (NFR-2): недоступный `worker` (не инициализирован в тесте) → `breaker: null` и/или
+`max_concurrency: null`, **не 500** (own `try/except` вокруг in-memory доступа).
+
+Привязка: BR-3, FR-2, AC-1, TC-03, TC-07.
+
+### D5 — Раздел `agents` (agent-liveness) — источник данных и CPU-сырьё (BR-4, FR-3)
+
+**Источник данных — новый dedicated read-only helper `db.get_running_agents()`, НЕ расширение
+`get_running_jobs()`.** Причина: `get_running_jobs()` — hot-path запрос job-reaper'а (ORCH-065,
+`src/db.py:1103`); расширять его SELECT под нужды наблюдаемости — перенос инварианта чужого
+компонента. Новый helper — изолированный `SELECT j.id, j.run_id, j.pid, j.agent, j.started_at,
+running_age_s, r.model, r.effort FROM jobs j LEFT JOIN agent_runs r ON r.id = j.run_id WHERE
+j.status='running'` (LEFT JOIN сохраняет job без `agent_runs`-строки). По каждому running-job:
+`agent`, `run_id`, `job_id`, `pid` (может быть `null`), `runtime_s`, `model`, `effort`, `cpu_ticks`.
+
+**CPU-сырьё — вариант A (орк читает `/proc`, остаётся stateless).** Орк эмитит сырые тики, дельту
+**не считает** — арбитр liveness это sidecar (BRD-допущение C-1). Чистый never-raise helper в
+`src/metrics.py`:
+
+```
+_read_cpu_ticks(pid) -> int | None
+    # читает /proc/<pid>/stat, поля 14 (utime) + 15 (stime), возвращает их сумму (в тиках);
+    # pid is None / нет /proc/<pid> / гонка (процесс умер) / не-Linux -> None (НЕ raise)
+```
+
+`clk_tck` (D2) — на уровне конверта. sidecar между двумя опросами считает
+`cpu_busy = (ticks₂ − ticks₁) / clk_tck`, делит на `(generated_at₂ − generated_at₁)` → доля CPU;
+малая доля при растущем `runtime_s` ⇒ кандидат на «завис». Парсинг `/proc/<pid>/stat` устойчив к
+пробелам в `comm`: брать поля **после** `') '` (закрывающая скобка имени) — канон чтения proc-stat.
+
+Инвариант (NFR-2, AC-6, TC-05): `pid is None` ИЛИ мёртвый/отсутствующий `/proc/<pid>` → `cpu_ticks:
+null` у этого агента; прочие поля и весь эндпоинт целы.
+
+Привязка: BR-4, FR-3, AC-6, TC-04, TC-05.
+
+### D6 — `runtime_s` — базис `jobs.started_at` (FR-3)
+
+`runtime_s = running_age_s` (секунды с `jobs.started_at`, считается в SQL в `get_running_agents`),
+**не** `agent_runs.started_at`. Обоснование: `jobs.started_at` — якорь жизненного цикла процесса,
+рядом с которым застамплен `pid` (ORCH-065); это тот же базис, что использует reaper для
+backstop-liveness. Значения почти совпадают, но `jobs` — авторитетный процесс-якорь, а
+`agent_runs`-строки может не быть (LEFT JOIN). Консистентность с reaper > микроточность.
+
+Привязка: FR-3, AC-6.
+
+### D7 — Раздел `cost` (BR-5, FR-4)
+
+- `running` — по каждому running-job текущие значения из `agent_runs`, если уже застамплены. Часто
+  `null` до завершения: токены/`cost_usd` парсятся из CLI-JSON в `launcher._monitor_agent` по
+  окончании. **`null` для незавершённых — честное сырьё** (документируется: `null` ≠ ноль, TR-5).
+- `aggregate` — новый read-only helper `db.agent_cost_totals()`: чистый
+  `SELECT COALESCE(SUM(cost_usd),0), COALESCE(SUM(input_tokens),0), … FROM agent_runs` по
+  `cost_usd`/`input_tokens`/`output_tokens`/`cache_read_tokens`/`cache_creation_tokens`. Пустая
+  таблица → нули, не ошибка (TC-06, TC-11). Опц. срез (всего + по `repo` через джойн `tasks`) —
+  расширяемо без бампа версии (D2).
+
+Привязка: BR-5, FR-4, AC-1, TC-06, TC-11.
+
+### D8 — Kill-switch `metrics_endpoint_enabled` (default `True`)
+
+TRZ §7 оставляет флаг на усмотрение архитектора. **Решение: добавить** конфиг-флаг
+`metrics_endpoint_enabled` (env `ORCH_METRICS_ENABLED`, дефолт `True`) — по образцу snapshot-флагов
+кодовой базы и из self-hosting-осторожности (операторский off-switch на общем прод-инстансе). При
+`False` эндпоинт возвращает **`200` с минимальным телом** `{"schema_version": 1, "enabled": false}`
+(не 404 — контракт остаётся парсимым, sidecar видит `enabled:false` и трактует это явно). Дефолт
+`True` ⇒ нулевая регрессия требований BRD (эндпоинт доступен из коробки). Флаг — дешёвая страховка,
+не предмет BRD; реализация инертна.
+
+Привязка: NFR-1, NFR-4, TRZ §7.
+
+## Альтернативы
+
+- **Расширить `/queue` вместо нового эндпоинта** — отвергнуто: сломало бы байт-в-байт контракт
+  `/queue` (BR-6, AC-2) и смешало бы машинное сырьё с человеческим снимком + конфигом демонов;
+  sidecar'у нужна узкая стабильная точка.
+- **Prometheus/OpenMetrics text-формат** — отвергнуто: заказчик задал тонкий кастомный sidecar (не
+  Prometheus, C-3); требование — JSON-контракт под конкретный F1b.
+- **Орк сам считает CPU-дельту** — отвергнуто: требует состояния между опросами; орк — пассивный
+  источник, stateful-арбитр это sidecar (C-1). Stateless-эмиссия сырых тиков проще и надёжнее.
+- **Расширить SELECT `get_running_jobs()`** под model/effort — отвергнуто: перенос инварианта
+  hot-path reaper'а (ORCH-065); изолируем dedicated helper `get_running_agents()`.
+- **Push метрик в sidecar** — отвергнуто: нарушает разделение C-1 (орк остаётся пассивным
+  источником); при зависшем орке pull-опрос падает — это **сам сигнал тревоги** для sidecar.
+- **Без kill-switch** — рассматривалось (эндпоинт инертен); выбран флаг ради конвенции кодовой базы
+  и операторского off-switch (D8).
+
+## Последствия
+
+- **+** Появляется стабильный машинный контракт сырья — F1b (заблокированная этой задачей)
+  разблокирована; домен наблюдаемости может стартовать.
+- **+** Строго read-only + never-raise по разделам ⇒ near-zero остаточный риск для общего
+  прод-конвейера (enduro-trails); физически не способен повлиять на конвейер (NFR-4).
+- **+** Аддитивно и обратимо: `/health`/`/status`/`/queue` байт-в-байт; `STAGE_TRANSITIONS`/
+  `QG_CHECKS`/`check_*`/schema/machine-verdict-ключи не тронуты (NFR-5).
+- **+** `schema_version` + аддитивно-толерантная политика ⇒ будущие расширения не ломают F1b.
+- **−** Новый публичный контракт = новая поверхность совместимости: дрейф `/metrics`↔F1b митигируется
+  единым репозиторием контракта (README, BR-7) + `schema_version` (D2). Издержка принимается.
+- **−** CPU-liveness Linux-специфичен (`/proc`); на не-Linux `cpu_ticks: null` (деградация, не
+  ошибка). Прод-контейнер — Linux, допущение выполняется (BRD §6).
+- **Топология/схема:** не меняются (07/08 — N/A). Sidecar-контейнер и его сетевая достижимость
+  `/metrics` — объём **F1b**, не этой задачи (см. README-заметку о предусловии достижимости).
+- **Эскалация:** формально вводится новый компонент наблюдаемости + публичный контракт → лейбл
+  **`arch:major-change`** (консервативно, хотя изменение полностью аддитивно/read-only/обратимо).
+  Прод-деплой — строго через staging-гейт (8501), без рестарта прод-контейнера.
+- **Откат:** `metrics_endpoint_enabled=False` (мгновенный) либо удаление `src/metrics.py` + эндпоинта
+  + helper'ов — полностью откатывает изменение без следов в БД/схеме (TRZ §7).
+
+## Ссылки
+- BRD: `docs/work-items/ORCH-099/01-brd.md`
+- TRZ: `docs/work-items/ORCH-099/02-trz.md`
+- Acceptance: `docs/work-items/ORCH-099/03-acceptance-criteria.md`
+- Тех-риски: `docs/work-items/ORCH-099/10-tech-risks.md`
+- Сквозной ADR: `docs/architecture/adr/adr-0030-metrics-endpoint.md`
+- Сверено по коду: `src/main.py` (`/health`/`/status`/`/queue`), `src/db.py`
+  (`get_active_tasks_for_reconcile`/`get_running_jobs`/`job_status_counts`, схема `agent_runs`/`jobs`),
+  `src/queue_worker.py` (`worker.status`/`CircuitBreaker.snapshot`), `src/serial_gate.py`
+  (`snapshot()` — эталон never-raise).
+- Связанные ADR: adr-0002 (job-queue/breaker — источник `queue`-сырья), adr-0011 (job-reaper —
+  `get_running_jobs`/pid/liveness-семантика), adr-0026 (терминал `{done,cancelled}` — фильтр стадий),
+  adr-0017 (serial_gate — паттерн leaf `snapshot()`/never-raise), adr-0020 (frontmatter-контракт —
+  стиль версионируемого контракта).

docs/work-items/ORCH-099/10-tech-risks.md

@@ -0,0 +1,43 @@
+---
+work_item: ORCH-099
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 10 — Технические риски: ORCH-099 — FND/F1a: лёгкий `/metrics` (сырьё для sidecar)
+
+Work Item: **ORCH-099** · Repo: **orchestrator** · Стадия: architecture
+
+> Информационный (гейтом не парсится). Перечисляет риски реализации и их митигейшн.
+
+## Реестр рисков
+
+| ID | Риск | Вер. | Влия. | Митигейшн |
+|----|------|------|-------|-----------|
+| TR-1 | Гонка чтения `/proc/<pid>/stat`: процесс умер между выборкой running-job и чтением proc → `FileNotFoundError`/частичная строка | Сред. | Низ. | `_read_cpu_ticks` never-raise → `cpu_ticks: null` (NFR-2, FR-3, AC-6); прочие поля и эндпоинт целы. Парс proc-stat читает поля **после** `') '` (устойчивость к пробелам в `comm`). |
+| TR-2 | PID-namespace mismatch: `jobs.pid` относится не к тому PID-namespace, где орк читает `/proc` | Низ. | Сред. | Агент — дочерний процесс орка (launcher `subprocess` в том же контейнере/ns), `pid` стамплется орком (ORCH-065) → `/proc/<pid>` валиден в том же ns. Несовпадение → `null` (деградация, не падение). |
+| TR-3 | Расхождение часов орк↔sidecar искажает расчёт CPU-доли | Низ. | Низ. | Контракт by-design: sidecar считает дельту по `(cpu_ticks, generated_at)` из **двух ответов орка** → всё в домене часов орка, skew-иммунно (ADR D2). |
+| TR-4 | Дрейф контракта `/metrics`↔ожидания F1b при будущих расширениях | Сред. | Сред. | `schema_version` (старт 1) + аддитивно-толерантная политика (sidecar игнорирует незнакомые ключи, толерирует отсутствие опциональных); контракт документирован в README в одном репо (BR-7, NFR-6). |
+| TR-5 | `cost.running = null` (токены ещё не застамплены) ошибочно прочитан sidecar'ом как «ноль стоимости» | Сред. | Низ. | Документировать: `null` ≠ ноль (= «не завершён, не застамплен»); авторитет по спенду — `cost.aggregate` (ADR D7). |
+| TR-6 | Контеншн на `CircuitBreaker._lock` при опросе breaker-снимка | Низ. | Низ. | `snapshot()` держит lock кратко (только чтение полей, `src/queue_worker.py:113`); раздел обёрнут own `try/except` → `breaker: null` при любой проблеме. Частота опроса sidecar — секунды, не микросекунды. |
+| TR-7 | Рост стоимости `SUM`-агрегата по `agent_runs` при разрастании таблицы | Низ. | Низ. | `agent_cost_totals()` — один индексируемый full-scan `SUM`, n мал (десятки–сотни строк на текущем горизонте); точка расширения — временное окно/`repo`-срез без бампа версии (ADR D2/D7). |
+| TR-8 | Соблазн «протащить» в `/metrics` логику алертинга/порогов | Низ. | Сред. | Scope-граница BRD (вне объёма) + NFR-1 (read-only) + reviewer-контроль; мозг (пороги/алерты) — строго F1b. |
+| TR-9 | Незаметная мутация состояния (случайный не-read-only вызов в сборщике) роняет инвариант read-only | Низ. | Выс. | Сборщик использует только SELECT-helper'ы; AC-5/TC-09 — тест «снимок БД до/после идентичен»; reviewer сверяет дифф на отсутствие `INSERT/UPDATE/DELETE/CREATE/ALTER` и запуска процессов. |
+
+## Сводный вывод
+
+Доминирующий класс — **гонки/деградация чтения runtime-данных** (`/proc`, in-memory breaker), все
+закрыты конструктивным never-raise по разделам (эталон `serial_gate.snapshot()`) → деградация в
+`null`, не отказ. Контрактные риски (TR-4/TR-5) закрыты `schema_version` + документированием.
+Наивысшее потенциальное влияние (TR-9, нарушение read-only) митигируется тестом «БД до/после
+идентична» (TC-09) и reviewer-сверкой диффа.
+
+Изменение полностью аддитивно, read-only, never-raise, обратимо (kill-switch + удаление модуля).
+**Остаточный риск для прод-конвейера (self-hosting, общий с enduro-trails) — near-zero:** эндпоинт
+физически не способен мутировать состояние или уронить процесс (NFR-1/NFR-2/NFR-4). Эскалация в
+анализ не требуется. Формальный лейбл **`arch:major-change`** проставляется консервативно (новый
+компонент наблюдаемости + публичный контракт), хотя по существу изменение низкорисковое; прод-деплой
+— строго через staging-гейт (8501), без рестарта прод-контейнера.

docs/work-items/ORCH-099/12-review.md

@@ -0,0 +1,86 @@
+---
+verdict: APPROVED
+work_item: ORCH-099
+stage: review
+author_agent: reviewer
+status: approved
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+type: review
+work_item_id: ORCH-099
+version: 1
+---
+
+# Review ORCH-099 — FND/F1a: лёгкий read-only `GET /metrics` (сырьё для sidecar F1b)
+
+## Summary
+
+Реализация полностью соответствует ТЗ (`02-trz.md`), критериям приёмки (`03-acceptance-criteria.md`)
+и архитектурному решению (`06-adr/ADR-001` + сквозной `adr-0030`). Добавлен аддитивный, строго
+read-only, never-raise эндпоинт `GET /metrics` через leaf-модуль `src/metrics.py` (`build_metrics()`,
+паттерн `serial_gate.snapshot()`) + тонкая обёртка в `src/main.py` + три read-only helper'а в
+`src/db.py`. Конвейерные инварианты целы: `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` /
+machine-verdict ключи / схема БД — не тронуты (в диффе нет `src/stages.py`/`src/qg/`; упоминания этих
+имён — только в документации/комментариях). Полный регресс `pytest tests/ -q` — **1482 passed**.
+Документация обновлена в том же PR. Блокирующих findings нет.
+
+**Оси проверки:**
+
+1. **Соответствие ТЗ** — ✅. FR-1 (`stages`, фильтр терминалов `{done,cancelled}`), FR-2 (`queue`:
+   counts+`cancelled`, depth, retries, breaker, max_concurrency), FR-3 (`agents`-liveness:
+   agent/run_id/job_id/pid/runtime_s/model/effort + `cpu_ticks`), FR-4 (`cost`: running+aggregate),
+   FR-5 (конверт `schema_version`/`generated_at`/`clk_tck`), FR-6 (never-raise по разделам) —
+   реализованы. AC-1…AC-8 проверены по коду и тестам (TC-01…TC-11), все зелёные.
+2. **Соответствие ADR** — ✅. D1–D8 реализованы как описано: D3 фильтр терминалов на потребителе
+   (helper-инвариант ORCH-053/086 не тронут); D5 dedicated `get_running_agents()` вместо расширения
+   hot-path `get_running_jobs()` (ORCH-065); D6 `runtime_s` от `jobs.started_at`; D8 kill-switch
+   `metrics_endpoint_enabled` (дефолт `True`, `200` с минимальным телом при `False`). Глобальный
+   инвариант терминального множества `{done,cancelled}` (adr-0026) соблюдён. `validation_alias`
+   `ORCH_METRICS_ENABLED` — обоснованное усиление D8 (документированное имя контракта реально
+   управляет флагом), покрыто `tests/test_config.py`. Нарушений глобальных ADR нет.
+3. **Качество кода** — ✅. Все колонки БД (`agent_runs.{cost_usd,*_tokens}`, `jobs.{pid,run_id,
+   started_at,repo,attempts,transient_attempts,available_at}`) сверены — существуют. Парсинг
+   `/proc/<pid>/stat` устойчив к пробелам/скобкам в `comm` (`rfind(") ")`, индексы 11/12 = поля
+   14/15); `_read_cpu_ticks` never-raise per-pid. Docstrings на всех публичных функциях, тесты
+   содержательные (живой pid → реальный int, мёртвый/`None` → `null`, бросающий источник → дефолт).
+4. **Документация** — ✅ (см. секцию ниже).
+
+## Findings
+
+### P0 — Blocker
+- Нет.
+
+### P1 — Must fix
+- Нет.
+
+### P2 — Should fix
+- Нет.
+
+### P3 — Nice-to-have (не блокирует)
+- [ ] `db.get_running_agents()` вызывается дважды на один запрос `/metrics` — в `_build_agents` и в
+  `_build_cost` (`src/metrics.py:176` и `:206`) — два идентичных SELECT'а. На типовом объёме
+  (running-jobs ≤ `max_concurrency`) — пренебрежимо, AC-3 не нарушен; при желании можно выбрать строки
+  один раз и переиспользовать. Косметика, исправление не требуется для приёмки.
+
+## Документация
+
+Обновлена в том же PR (правило «доки = golden source», AC-7) — проверено явно:
+- **`docs/architecture/README.md`** — новый компонент «Metrics endpoint» в списке, полный раздел-
+  контракт «Сырьё-эндпоинт `/metrics` для sidecar» (конверт, разделы, политика `schema_version`,
+  гарантии read-only/never-raise, kill-switch) и строка в таблице API. Соответствует фактическому
+  ответу эндпоинта.
+- **`CHANGELOG.md`** — запись `## [Unreleased]` с пометкой `ORCH-099` (D1–D8 + тесты + откат).
+- **`docs/work-items/ORCH-099/06-adr/ADR-001-metrics-endpoint.md`** — детальное решение (D1–D8).
+- **`docs/architecture/adr/adr-0030-metrics-endpoint.md`** — сквозной ADR (новый компонент
+  наблюдаемости + публичный контракт), зарегистрирован в `docs/architecture/adr/README.md` (индекс +
+  «текущий максимум — `0030`»).
+- **`.env.example`** — задокументирован `ORCH_METRICS_ENABLED=true`.
+
+`src/` изменён → документация обновлена (golden source соблюдён). Эпик-обзорные доки `README.md`
+«Известные ограничения» этой задачей не затрагиваются (новый компонент, не закрытие ограничения).
+
+## Регресс / проверки
+- `pytest tests/ -q` → **1482 passed** (новые `tests/test_metrics.py` TC-01…TC-11 + `test_config.py`
+  ×2; регресс `/health`//status//queue зелёный, TC-10).
+- Дифф `src/stages.py` / `src/qg/` — пуст; machine-verdict ключи и схема БД — байт-в-байт прежние.
+- Read-only подтверждён тестом снимка БД до/после (TC-09); never-raise — TC-05/TC-07.

docs/work-items/ORCH-099/13-test-report.md

@@ -0,0 +1,87 @@
+---
+result: PASS
+work_item: ORCH-099
+stage: testing
+author_agent: tester
+status: pass
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+type: test-report
+work_item_id: ORCH-099
+---
+
+# Test Report — ORCH-099 — FND/F1a: лёгкий read-only `GET /metrics` (сырьё для sidecar F1b)
+
+> Машинный вердикт читается ТОЛЬКО из frontmatter. Канонический ключ — `result:` (UPPERCASE).
+> Любой негативный токен (`FAIL`/`BLOCKED`) авторитетен.
+
+## Окружение
+- Python: 3.12.13
+- pytest: 8.3.3 (pytest-cov 5.0.0, pytest-asyncio 0.23.8)
+- Дата: 2026-06-10
+- Worktree: `/repos/_wt/orchestrator/feature_ORCH-099-fnd-f1a-metrics-agent-liveness`
+  (ветка `feature/ORCH-099-fnd-f1a-metrics-agent-liveness`)
+- Review verdict (`12-review.md`): **APPROVED** — гейт пройден до тестирования.
+
+## Результаты
+
+### Полный регресс
+`cd <worktree> && pytest tests/ -v --tb=short` → **1482 passed, 1 warning** за 49.98s.
+Прод-контейнер (8500) не трогался; прогон — в рабочем дереве ветки задачи.
+Единственный warning — известный PydanticDeprecatedSince20 (`src/config.py:8`), не связан с задачей.
+
+### Профильная сюита
+`pytest tests/test_metrics.py -v` → **14 passed** за 0.96s (TC-01…TC-11; часть TC покрыта
+несколькими тест-функциями). Новый код присутствует в worktree: `src/metrics.py` (10 538 байт),
+`@app.get("/metrics")` в `src/main.py:216` — тонкая обёртка над `metrics.build_metrics()`.
+
+### Smoke API (read-only, прод 8500)
+- `GET /health` → `{"status":"ok","service":"orchestrator"}` — OK.
+- `GET /status` → `{"active_tasks":[...]}` — контракт цел.
+- `GET /queue` → ключи на месте; блок **`serial_gate` присутствует** (ORCH-088), **`auto_labels`
+  присутствует** (ORCH-089) — регресса смока нет.
+- `GET /metrics` на проде → `404 Not Found` — **ожидаемо**: новый эндпоинт ещё не задеплоен (стадия
+  testing, до `deploy`); функционал верифицирован тестами в worktree (TC-08). Не является FAIL.
+
+### Сопоставление с тест-планом (`04-test-plan.yaml`)
+| TC ID | Описание | Тест-функция | Результат |
+|-------|----------|--------------|-----------|
+| TC-01 | Конверт FR-5: dict с schema_version/generated_at/stages/queue/agents/cost | `test_tc01_envelope_has_all_sections` | PASS |
+| TC-02 | stages: активные только; work_item/stage/age_in_stage_s(int)/repo; терминалы исключены | `test_tc02_stages_active_only_with_fields` | PASS |
+| TC-03 | queue: counts/max_concurrency/retries/breaker-снимок | `test_tc03_queue_section_fields` | PASS |
+| TC-04 | agents: agent/run_id/job_id/pid/runtime_s + CPU-liveness сырьё | `test_tc04_agents_liveness_fields` | PASS |
+| TC-05 | liveness never-raise: pid=None / нет /proc → cpu_ticks=null, ответ цел | `test_tc05_dead_or_none_pid_cpu_ticks_null`, `test_tc05_read_cpu_ticks_helper_none_paths` | PASS |
+| TC-06 | cost.aggregate: суммы cost_usd/токены; пустая таблица → нули | `test_tc06_cost_aggregate_sums_and_empty_zeros` | PASS |
+| TC-07 | never-raise по разделу: бросающий источник/breaker → null/дефолт | `test_tc07_section_source_throws_degrades_not_500`, `test_tc07_breaker_unavailable_is_null` | PASS |
+| TC-08 | GET /metrics → 200 + валидный JSON со всеми разделами на засеянной БД | `test_tc08_endpoint_returns_full_payload`, `test_tc08_kill_switch_minimal_body` | PASS |
+| TC-09 | read-only: снимок БД до/после идентичен; повтор не меняет состояние | `test_tc09_metrics_is_read_only` | PASS |
+| TC-10 | аддитивность: /health//status//queue сохраняют контракт | `test_tc10_existing_endpoints_intact` | PASS |
+| TC-11 | пустое состояние: stages=[]/agents=[]/cost нули/queue нули → 200 без исключений | `test_tc11_empty_state_valid` | PASS |
+
+Все 11 TC из тест-плана выполнены и сопоставлены. Расхождений с `expected: PASS` нет.
+
+### Сопоставление с критериями приёмки (`03-acceptance-criteria.md`)
+| AC | Условие | Покрытие | Результат |
+|----|---------|----------|-----------|
+| AC-1 | 4 раздела + конверт с полями TRZ §3 | TC-01/02/03/04/06 | PASS |
+| AC-2 | /health//status//queue не сломаны | TC-10 + smoke | PASS |
+| AC-3 | лёгкость: только локальный SQL + in-memory, без сети/тяжёлых процессов | код `src/metrics.py` (нет сетевых вызовов; только read /proc), профильный прогон 0.96s | PASS |
+| AC-4 | never-raise: ошибка поля → null, не 500 | TC-05/TC-07/TC-11 | PASS |
+| AC-5 | read-only; STAGE_TRANSITIONS/QG_CHECKS/check_*/схема не тронуты | TC-09 + review (дифф `src/stages.py`/`src/qg/` пуст) | PASS |
+| AC-6 | agent-liveness: pid/runtime_s + CPU-сырьё для alive-детекта | TC-04/TC-05 | PASS |
+| AC-7 | контракт в README + CHANGELOG | подтверждено review (`12-review.md`, §Документация) | PASS |
+| AC-8 | pytest зелёный; есть test_metrics.py | 1482 passed; 14 в test_metrics.py | PASS |
+
+## Вывод pytest
+```
+======================= 1482 passed, 1 warning in 49.98s =======================
+```
+```
+tests/test_metrics.py ........... (14 items)
+======================== 14 passed, 1 warning in 0.96s =========================
+```
+
+## Итог
+PASS — полный регресс (1482) и профильная сюита (14) зелёные; smoke read-only OK
+(`serial_gate` + `auto_labels` присутствуют в `/queue`); каждый TC тест-плана выполнен и
+сопоставлен с критериями приёмки. Задача готова к переходу на `deploy-staging`.

docs/work-items/ORCH-099/14-deploy-log.md

@@ -0,0 +1,12 @@
+---
+deploy_status: SUCCESS
+work_item: ORCH-099
+hook_exit_code: 0
+deployed_by: deploy-finalizer
+---
+
+# Deploy log — ORCH-036 executable self-deploy
+
+Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
+
+Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.

docs/work-items/ORCH-099/15-staging-log.md

@@ -0,0 +1,34 @@
+---
+staging_status: SUCCESS
+work_item: ORCH-099
+stage: deploy-staging
+author_agent: deployer
+status: success
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+timestamp: 2026-06-09T23:05:57Z
+base_url: http://localhost:8501
+---
+
+# Staging Gate Log
+
+Staging test suite completed against the live `orchestrator-staging` instance (port 8501),
+run canonically inside the `orchestrator-staging` container (`scripts/staging_check.py
+--base-url http://localhost:8501 --mode stub`). Exit code **0 → SUCCESS**. All REAL pipeline
+checks passed; the two sandbox-infra checks (C9a/C9b) are tolerated per ORCH-061.
+
+INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
+VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
+
+## Results
+- **Block A (SMOKE)**: ✓ A1 `/health` → 200 ok · ✓ A2 `/queue` → 200 (counts/max_concurrency/resilience) · ✓ A3 `ORCH_STAGING=true`
+- **Block B (ACCESS)**: ✓ B4 Plane sandbox accessible (sandbox=YES) · ✓ B5 Gitea `orchestrator-sandbox` accessible, push=true · ✓ B6 Registry isolation (sandbox present, prod ET/ORCH absent)
+- **Block C (E2E, mode=stub)**: ✓ C7 Create issue in Plane SANDBOX · ✓ C8 Trigger pipeline via `/webhook/plane` · ✗ C9a Branch in orchestrator-sandbox (INFRA-WAIVED) · ✗ C9b Analyst job enqueued (INFRA-WAIVED)
+- **Cleanup**: ✓ deleted Plane issue (HTTP 204)
+
+RESULT: 8/10 checks PASS.
+REAL failed: none.
+SANDBOX_INFRA failed (waived): C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue.
+
+Tolerance: `staging_infra_tolerance_enabled=True` (ORCH-061). The exit-code → `staging_status`
+mapping is unchanged: exit 0 → `SUCCESS`. Advancing to the `deploy` gate.

requirements.txt

@@ -4,6 +4,10 @@ pydantic-settings==2.5.0
 httpx==0.27.0
 pytest==8.3.3
 pytest-asyncio==0.23.8
+# ORCH-027: coverage measurement for the coverage-gate. pytest-cov wraps coverage.py;
+# the gate runs `pytest --cov=src --cov-report=json` in the per-branch worktree and
+# reads totals.percent_covered (line coverage). Offline — no network at measure time.
+pytest-cov==5.0.0
 # ORCH-022: dependency audit (OSV/PyPI advisory) for the security-gate. Needs the
 # network at scan time -> an unreachable feed degrades fail-open + warning by
 # default (ADR-001 Р-3 / 07-infra I-2). gitleaks (secret-scan) is a pinned Go

src/config.py

@@ -1,7 +1,7 @@
 import logging
 import re
 
-from pydantic import field_validator
+from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings
 
 
@@ -259,6 +259,38 @@ class Settings(BaseSettings):
     security_dep_audit_fail_closed: bool = False
     security_secrets_block: bool = True
 
+    # ORCH-027: deterministic test-coverage gate on the deploy-staging -> deploy edge
+    # (AFTER the merge-gate, BEFORE image-freshness). Measures line coverage of src/
+    # under pytest-cov in the per-branch worktree, compares to an absolute floor and/or
+    # the ratchet baseline of `main`, and FAILs (rollback to development + developer
+    # retry) on degradation. Leaf src/coverage_gate.py (never-raise); machine verdict in
+    # 18-coverage-report.md frontmatter (coverage_status:). See ADR-001-coverage-gate.md.
+    #   coverage_gate_enabled     -> SINGLE kill-switch; False -> pipeline 1:1 as before
+    #                                ORCH-027 for everyone. Env ORCH_COVERAGE_GATE_ENABLED.
+    #   coverage_gate_repos       -> CSV of repos where the gate is REAL; empty -> only
+    #                                the self-hosting repo (orchestrator). Mirrors
+    #                                security_gate_repos / image_freshness_repos.
+    #   coverage_min_percent      -> absolute floor (% line coverage) for policy
+    #                                absolute/both. Default 0.0 -> safe rollout: the
+    #                                ratchet baseline drives no-regression, the floor
+    #                                never false-fails day one.
+    #   coverage_policy           -> absolute | baseline | both (default both): which
+    #                                condition(s) must hold (D3).
+    #   coverage_epsilon          -> small non-negative noise tolerance (%) so jitter at
+    #                                the boundary does not bounce a task (NFR-4).
+    #   coverage_tool_fail_closed -> strict mode: a coverage-tool error -> FAIL instead
+    #                                of the default fail-open + warning (FR-6). Default
+    #                                False (anti-loop, precedent ORCH-061/022).
+    #   coverage_run_timeout_s    -> wall-clock budget for the pytest --cov run (mirrors
+    #                                merge_retest_timeout_s / security_scan_timeout_s).
+    coverage_gate_enabled: bool = True
+    coverage_gate_repos: str = ""
+    coverage_min_percent: float = 0.0
+    coverage_policy: str = "both"
+    coverage_epsilon: float = 0.5
+    coverage_tool_fail_closed: bool = False
+    coverage_run_timeout_s: int = 900
+
     # ORCH-061: tolerate KNOWN sandbox-infra FAILs (C9a/C9b) in the staging suite.
     # The self-hosting deploy-staging stage looped because scripts/staging_check.py
     # exited non-zero on ANY failed check, so two infra-only failures (sandbox bot
@@ -787,6 +819,17 @@ class Settings(BaseSettings):
     # 200 (was hardcoded 80). Invalid/empty value -> default (graceful, no crash).
     qg0_title_max: int = 200
 
+    # ORCH-099 (D8): operator off-switch for the read-only GET /metrics endpoint.
+    # The env var is ORCH_METRICS_ENABLED (explicit validation_alias — the documented
+    # contract name, ADR-001 D8 / README — overriding the default ORCH_ + field-name
+    # mapping so the documented switch actually controls the flag). Default True ->
+    # the endpoint is available out of the box (zero regression vs BRD). False ->
+    # /metrics returns a minimal parsable body {"schema_version": 1, "enabled": false}
+    # (200, NOT 404) so the F1b sidecar sees the off-switch explicitly. The endpoint
+    # is inert / read-only anyway; the flag is a cheap self-hosting insurance on the
+    # shared prod instance.
+    metrics_endpoint_enabled: bool = Field(True, validation_alias="ORCH_METRICS_ENABLED")
+
     @field_validator("qg0_title_max", mode="before")
     @classmethod
     def _qg0_title_max_default(cls, v):

src/coverage_gate.py

@@ -0,0 +1,620 @@
+"""Coverage-gate core (ORCH-027): deterministic test-coverage gate before merge.
+
+Background
+----------
+The orchestrator runs autonomous development: the ``developer`` agent writes code
+with no human filter, and on ``testing`` the ``tester`` agent decides for itself
+whether the tests are enough. The existing test gates judge only by the FACT of
+passing, never by COMPLETENESS: ``check_ci_green`` and ``check_tests_passed`` and
+the merge-gate re-test all look at a pytest exit code. None of them notices "300
+lines of new code, 0 tests". Across a batch autonomous run (ORCH-088) that means a
+monotonic erosion of coverage — every task shaves a corner on tests and the project
+silently loses testability.
+
+This module provides the deterministic (no-LLM) primitives that the quality-gate
+``check_coverage_gate`` (src/qg/checks.py) composes on the ``deploy-staging ->
+deploy`` edge — run **AFTER the merge-gate** (so coverage is measured on the
+caught-up HEAD that actually lands in ``main``) and **BEFORE image-freshness** (fail
+before the expensive docker rebuild), mirroring the security-gate (ORCH-022):
+
+  * ``measure_coverage``          -> run ``pytest --cov=src`` in the per-branch
+                                     worktree (offline) -> line coverage ``%`` or
+                                     ``None`` on tool error.
+  * ``compute_coverage_verdict``  -> pure: compare (measured, baseline, floor) under
+                                     a policy + epsilon -> ``(ok, reason)``.
+  * ``write_coverage_report`` / ``parse_coverage_status`` -> write the
+    ``18-coverage-report.md`` artefact and read its machine verdict back (single
+    source of truth: the gate returns exactly the frontmatter it wrote, AC-9).
+  * ``ratchet_baseline_on_merge`` -> on a CONFIRMED merge (``_handle_merge_verify``,
+    ``deploy -> done`` edge) raise the per-repo baseline UP from the merged branch's
+    measured coverage (atomic compare-and-set, never decreases — FR-4 / D5).
+  * ``check_coverage_gate``       -> the orchestrating entry the QG wrapper delegates
+                                     to.
+
+Invariants (ADR-001 §7, never broken):
+  * **Tool error -> fail-open + WARNING by default** (FR-6/AC-6): a coverage-tool
+    failure / unparseable metric degrades fail-open (anti-loop, precedent
+    ORCH-061/022 dep-audit); ``coverage_tool_fail_closed`` flips it to strict.
+  * **never-raise** (AC-7): any internal error is swallowed; an exception never
+    escapes into ``advance_stage``.
+  * **Baseline never decreases** (FR-4): the ratchet is an atomic SQL compare-and-set
+    under the held merge-lease (ORCH-043), so two parallel merges can never lower or
+    lose the value.
+  * **Self-hosting safety** (AC-7): the gate only measures / reads / writes the
+    artefact / decides. It never calls the deploy hook, never restarts the prod
+    container, never pushes / force-pushes ``main``.
+
+This module is a **leaf**: it imports only ``config`` / ``git_worktree`` and lazily
+``qg.checks.is_self_hosting_repo`` / ``db`` / ``notifications``; it never imports
+``stage_engine``.
+"""
+
+import json
+import logging
+import os
+import subprocess
+import sys
+
+from .config import settings
+from .git_worktree import ensure_worktree, get_worktree_path
+
+logger = logging.getLogger("orchestrator.coverage_gate")
+
+
+# ---------------------------------------------------------------------------
+# Conditionality (mirrors security_gate_applies / _merge_gate_applies)
+# ---------------------------------------------------------------------------
+def coverage_gate_applies(repo: str) -> bool:
+    """Whether the coverage-gate is REAL for this repo (conditional rollout).
+
+    Mirrors the ORCH-22 / ORCH-43 / ORCH-58 pattern:
+      * ``coverage_gate_enabled=False`` -> always False (kill-switch; pipeline is
+        1:1 as before ORCH-027 for everyone).
+      * ``coverage_gate_repos`` (CSV) non-empty -> real only for the listed repos.
+      * empty CSV -> real ONLY for the self-hosting repo (``orchestrator``).
+    Never raises (AC-7): any error -> False (the safe no-op default).
+    """
+    try:
+        if not settings.coverage_gate_enabled:
+            return False
+        raw = (settings.coverage_gate_repos or "").strip()
+        if raw:
+            allowed = {r.strip().lower() for r in raw.split(",") if r.strip()}
+            return (repo or "").strip().lower() in allowed
+        # Lazy import keeps this module a leaf (no qg import at module load).
+        from .qg.checks import is_self_hosting_repo
+        return is_self_hosting_repo(repo)
+    except Exception as e:  # noqa: BLE001 - never-raise contract
+        logger.warning("coverage_gate_applies error for %s: %s", repo, e)
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Measurement (pytest --cov=src in the per-branch worktree) — FR-1 / D2
+# ---------------------------------------------------------------------------
+def parse_coverage_percent(data) -> float | None:
+    """Pure: extract ``totals.percent_covered`` (line coverage ``%``) from a
+    coverage.py JSON dict. Returns ``None`` if the shape is missing / unparseable.
+    Never raises.
+    """
+    try:
+        if not isinstance(data, dict):
+            return None
+        totals = data.get("totals")
+        if not isinstance(totals, dict):
+            return None
+        pct = totals.get("percent_covered")
+        if pct is None:
+            return None
+        return float(pct)
+    except (TypeError, ValueError):
+        return None
+
+
+def measure_coverage(repo: str, branch: str) -> float | None:
+    """Run ``pytest --cov=src`` in the per-branch worktree -> line coverage ``%``.
+
+    Scope is ``src/`` only (the tests themselves are out of scope, BRD §«Вне
+    объёма»). Offline — coverage needs no network. The measurer is intentionally
+    encapsulated here so the pure decision logic and the baseline storage are
+    stack-agnostic (a future jest/jacoco measurer is a new ``measure_*`` branch,
+    BR-6).
+
+    The coverage metric is read from the ``--cov-report=json`` file regardless of
+    the pytest exit code: a non-zero exit because of *failing tests* is already
+    caught upstream (``check_ci_green`` / merge-gate re-test), and a partial run
+    still produces a meaningful coverage JSON. A genuine tool error (missing
+    plugin / timeout / no JSON / unparseable) -> ``None`` (the caller degrades
+    fail-open by default, FR-6). Never raises (AC-7).
+    """
+    try:
+        wt = ensure_worktree(repo, branch)
+    except Exception as e:  # noqa: BLE001 - never-raise contract
+        logger.warning("measure_coverage: worktree error for %s/%s: %s", repo, branch, e)
+        return None
+
+    cov_json = os.path.join(wt, ".coverage-report.json")
+    # Remove a stale report so we never read a previous pass's metric.
+    try:
+        if os.path.isfile(cov_json):
+            os.remove(cov_json)
+    except OSError:
+        pass
+
+    # Use the SAME interpreter that runs the orchestrator (sys.executable), not a
+    # bare "python" — the prod container / CI runner expose "python3", and the
+    # pytest-cov plugin lives in exactly this interpreter's environment.
+    cmd = [
+        sys.executable, "-m", "pytest", "tests/",
+        "--cov=src",
+        f"--cov-report=json:{cov_json}",
+        "--cov-report=",  # suppress the terminal cov report (json only)
+        "-q",
+    ]
+    timeout = settings.coverage_run_timeout_s
+    try:
+        subprocess.run(cmd, cwd=wt, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        logger.warning(
+            "measure_coverage: pytest --cov timed out after %ss for %s/%s",
+            timeout, repo, branch,
+        )
+        return None
+    except FileNotFoundError:
+        logger.warning(
+            "measure_coverage: pytest / pytest-cov not available for %s/%s", repo, branch
+        )
+        return None
+    except (subprocess.SubprocessError, OSError) as e:
+        logger.warning("measure_coverage: pytest --cov error for %s/%s: %s", repo, branch, e)
+        return None
+
+    data = None
+    try:
+        if not os.path.isfile(cov_json):
+            logger.warning(
+                "measure_coverage: no coverage json produced for %s/%s", repo, branch
+            )
+            return None
+        with open(cov_json, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError) as e:
+        logger.warning(
+            "measure_coverage: cannot parse coverage json for %s/%s: %s", repo, branch, e
+        )
+        return None
+    finally:
+        try:
+            if os.path.isfile(cov_json):
+                os.remove(cov_json)
+        except OSError:
+            pass
+
+    return parse_coverage_percent(data)
+
+
+# ---------------------------------------------------------------------------
+# Pure decision (FR-2 / D3) — the core of the unit tests
+# ---------------------------------------------------------------------------
+def compute_coverage_verdict(measured, baseline, floor, policy, epsilon) -> tuple[bool, str]:
+    """Pure: decide PASS/FAIL from (measured, baseline, floor, policy, epsilon).
+
+    Deterministic, no LLM, no I/O. Returns ``(ok: bool, reason: str)``.
+
+      * ``policy = "absolute"`` -> PASS ⇔ ``measured >= floor - epsilon``.
+      * ``policy = "baseline"`` -> PASS ⇔ ``measured >= baseline - epsilon``.
+      * ``policy = "both"`` (default) -> PASS ⇔ BOTH conditions hold.
+      * ``baseline is None`` (no stored baseline / bootstrap) -> the baseline
+        condition does NOT apply (cannot regress against nothing); only the
+        absolute part decides. For ``policy = "baseline"`` with no baseline this is
+        a bootstrap PASS (the measured value seeds the baseline at merge, D5).
+      * ``epsilon`` — a small non-negative tolerance so jitter at the boundary does
+        not bounce a task (NFR-4).
+
+    Never raises: bad inputs -> ``(False, reason)`` (a verdict cannot be computed ->
+    conservative FAIL for the pure function; the orchestrating entry maps a *tool*
+    error to fail-open separately).
+    """
+    try:
+        pol = (policy or "both").strip().lower()
+        eps = max(0.0, float(epsilon if epsilon is not None else 0.0))
+        m = float(measured)
+    except (TypeError, ValueError) as e:
+        return False, f"coverage verdict: bad inputs ({e})"
+
+    abs_applicable = pol in ("absolute", "both")
+    base_applicable = pol in ("baseline", "both") and baseline is not None
+
+    checks: list[str] = []
+    ok = True
+
+    if abs_applicable:
+        try:
+            f = float(floor if floor is not None else 0.0)
+        except (TypeError, ValueError):
+            f = 0.0
+        abs_ok = m >= f - eps
+        checks.append(
+            f"absolute {m:.2f}% >= floor {f:.2f}%-eps{eps:.2f} -> "
+            f"{'PASS' if abs_ok else 'FAIL'}"
+        )
+        ok = ok and abs_ok
+
+    if base_applicable:
+        b = float(baseline)
+        base_ok = m >= b - eps
+        checks.append(
+            f"baseline {m:.2f}% >= base {b:.2f}%-eps{eps:.2f} -> "
+            f"{'PASS' if base_ok else 'FAIL'}"
+        )
+        ok = ok and base_ok
+    elif pol in ("baseline", "both") and baseline is None:
+        checks.append("baseline N/A (bootstrap — no stored baseline)")
+
+    body = "; ".join(checks) if checks else "no applicable condition (bootstrap) -> PASS"
+    reason = f"measured={m:.2f}% policy={pol} eps={eps:.2f}: {body}"
+    return ok, reason
+
+
+def compute_delta(measured, baseline, floor) -> float:
+    """Pure: signed ``measured - max(applicable references)`` (%, 2 decimals).
+
+    References are the present ones among ``baseline`` / ``floor``. With neither ->
+    ``0.0``. Never raises.
+    """
+    try:
+        m = float(measured)
+        refs = []
+        if baseline is not None:
+            refs.append(float(baseline))
+        if floor is not None:
+            refs.append(float(floor))
+        if not refs:
+            return 0.0
+        return round(m - max(refs), 2)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+# ---------------------------------------------------------------------------
+# Artefact: write the report, read the machine verdict back (FR-7 / D7 / AC-9)
+# ---------------------------------------------------------------------------
+def _report_rel(work_item_id: str) -> str:
+    return f"docs/work-items/{work_item_id}/18-coverage-report.md"
+
+
+def _report_path(repo: str, work_item_id: str, branch: str) -> str:
+    """Absolute path of 18-coverage-report.md inside the task worktree."""
+    try:
+        wt = get_worktree_path(repo, branch)
+        if not os.path.isdir(wt):
+            wt = ensure_worktree(repo, branch)
+    except Exception:  # noqa: BLE001 - never-raise; fall back to shared clone
+        wt = os.path.join(settings.repos_dir, repo)
+    return os.path.join(wt, _report_rel(work_item_id))
+
+
+def _num(v) -> str:
+    """Render a numeric field with 2 decimals, or empty for None/unparseable."""
+    if v is None:
+        return ""
+    try:
+        return f"{float(v):.2f}"
+    except (TypeError, ValueError):
+        return ""
+
+
+def render_coverage_report(work_item_id: str, fields: dict) -> str:
+    """Pure: render the 18-coverage-report.md content (frontmatter + body).
+
+    The machine verdict lives ONLY in the YAML frontmatter ``coverage_status:``
+    (canon, regiser-sensitive); ``measured_coverage`` is the single source of truth
+    for the ratchet (D5). Never raises.
+    """
+    baseline = fields.get("baseline")
+    baseline_str = "" if baseline is None else _num(baseline)
+    return (
+        "---\n"
+        f"coverage_status: {fields.get('coverage_status', 'FAIL')}\n"
+        f"work_item: {work_item_id}\n"
+        f"measured_coverage: {_num(fields.get('measured_coverage'))}\n"
+        f"baseline: {baseline_str}\n"
+        f"floor: {_num(fields.get('floor'))}\n"
+        f"policy: {fields.get('policy', 'both')}\n"
+        f"epsilon: {_num(fields.get('epsilon'))}\n"
+        f"delta: {_num(fields.get('delta'))}\n"
+        "---\n"
+        f"# Coverage Report — {work_item_id}\n\n"
+        "Детерминированный гейт покрытия (ORCH-027) — под-гейт ребра "
+        "`deploy-staging→deploy` (ПОСЛЕ merge-gate, ДО image-freshness). Машинный "
+        "вердикт читается ТОЛЬКО из `coverage_status:` frontmatter выше.\n\n"
+        "## Verdict\n"
+        f"{fields.get('reason', '')}\n\n"
+        "## Measurement\n"
+        f"{fields.get('measurement', '')}\n\n"
+        "## Policy\n"
+        f"{fields.get('policy_detail', '')}\n"
+    )
+
+
+def write_coverage_report(repo: str, work_item_id: str, branch: str, fields: dict) -> str:
+    """Write 18-coverage-report.md into the task worktree; return its path.
+
+    Best-effort / never-raise: a write error is logged and the path is still
+    returned (the caller's read-back then fails closed)."""
+    path = _report_path(repo, work_item_id, branch)
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(render_coverage_report(work_item_id, fields))
+    except OSError as e:
+        logger.error("write_coverage_report error for %s/%s: %s", repo, work_item_id, e)
+    return path
+
+
+def parse_coverage_status(content: str) -> tuple[bool, str]:
+    """Map a 18-coverage-report.md body to a quality-gate verdict by reading ONLY
+    the machine-readable ``coverage_status:`` YAML frontmatter — never the prose.
+
+    Mirrors ``parse_security_status`` (canon: machine verdict only from frontmatter,
+    AC-9). The negative token (FAIL) is authoritative (checked first). Returns:
+      * ``coverage_status: PASS`` -> ``(True,  "Coverage status: PASS")``
+      * ``coverage_status: FAIL`` -> ``(False, "Coverage status: FAIL")``
+      * missing field / no frontmatter / bad YAML -> ``(False, <reason>)``.
+
+    Parse delegated to the unified ``frontmatter.parse_frontmatter`` primitive
+    (ORCH-052c single source of YAML-frontmatter logic).
+    """
+    from .frontmatter import parse_frontmatter
+
+    parse = parse_frontmatter(content)
+    if parse.yaml_error is not None:
+        return False, f"Invalid YAML frontmatter in coverage report: {parse.yaml_error}"
+    status = None
+    if parse.has_block and not parse.malformed:
+        status = str(parse.data.get("coverage_status", "")).upper().strip()
+    if status == "FAIL":
+        return False, "Coverage status: FAIL"
+    if status == "PASS":
+        return True, "Coverage status: PASS"
+    return False, f"No machine-readable coverage_status in frontmatter (got: {status!r})"
+
+
+def read_measured_coverage(content: str) -> float | None:
+    """Read ``measured_coverage`` (%, float) from a 18-coverage-report.md body via
+    the unified frontmatter parser. ``None`` when absent / unparseable (ratchet then
+    no-ops). Never raises.
+    """
+    try:
+        from .frontmatter import parse_frontmatter
+        parse = parse_frontmatter(content)
+        if not parse.has_block or parse.malformed:
+            return None
+        raw = parse.data.get("measured_coverage")
+        if raw is None or (isinstance(raw, str) and not raw.strip()):
+            return None
+        return float(raw)
+    except (TypeError, ValueError):
+        return None
+    except Exception as e:  # noqa: BLE001 - never-raise
+        logger.warning("read_measured_coverage error: %s", e)
+        return None
+
+
+def _error_fields(work_item_id, floor, policy, epsilon, baseline, *, fail_closed: bool) -> dict:
+    """Build the report fields for a tool-error pass (FR-6)."""
+    status = "FAIL" if fail_closed else "PASS"
+    mode = "fail-closed (FAIL)" if fail_closed else "fail-open (WARNING)"
+    return {
+        "coverage_status": status,
+        "measured_coverage": None,
+        "baseline": baseline,
+        "floor": floor,
+        "policy": policy,
+        "epsilon": epsilon,
+        "delta": None,
+        "reason": f"coverage measurement failed -> {mode}",
+        "measurement": (
+            "coverage tool error / unparseable metric "
+            f"(coverage_tool_fail_closed={fail_closed})"
+        ),
+        "policy_detail": f"policy={policy}, floor={floor}, baseline={baseline}, epsilon={epsilon}",
+    }
+
+
+# ---------------------------------------------------------------------------
+# Ratchet baseline UP on a confirmed merge (FR-4 / D5)
+# ---------------------------------------------------------------------------
+def ratchet_baseline_on_merge(repo: str, work_item_id: str, branch: str, sha: str | None = None) -> bool:
+    """Raise the per-repo coverage baseline UP from the merged branch's measured
+    coverage. Called from ``_handle_merge_verify`` (deploy -> done edge) AFTER the
+    merge is confirmed and BEFORE the task advances to ``done`` (D5).
+
+    Reads the measured value from ``18-coverage-report.md`` (single source of truth
+    — the exact metric the gate wrote on the deploy-staging->deploy edge) and applies
+    an atomic compare-and-set (``db.ratchet_coverage_baseline``) that never lowers
+    the baseline. Bootstrap: the first applicable merge seeds the baseline.
+
+    Returns True iff the baseline was inserted/raised. never-raise (AC-7): any error
+    -> False (observability best-effort; a ratchet failure must never break the
+    deploy->done path).
+    """
+    try:
+        if not coverage_gate_applies(repo):
+            return False
+        path = _report_path(repo, work_item_id, branch)
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                content = f.read()
+        except OSError as e:
+            logger.warning(
+                "ratchet: cannot read coverage report for %s/%s: %s", repo, work_item_id, e
+            )
+            return False
+        measured = read_measured_coverage(content)
+        if measured is None:
+            logger.warning(
+                "ratchet: no measured_coverage in report for %s/%s", repo, work_item_id
+            )
+            return False
+        from . import db
+        updated = db.ratchet_coverage_baseline(repo, measured, sha)
+        if updated:
+            logger.info(
+                "coverage baseline ratcheted for %s -> %.2f%% (sha=%s)", repo, measured, sha
+            )
+        else:
+            logger.info(
+                "coverage baseline unchanged for %s (measured %.2f%% not above current)",
+                repo, measured,
+            )
+        return updated
+    except Exception as e:  # noqa: BLE001 - never-raise contract
+        logger.error("ratchet_baseline_on_merge error for %s/%s: %s", repo, work_item_id, e)
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Orchestrating entry — delegated to by qg.checks.check_coverage_gate
+# ---------------------------------------------------------------------------
+def check_coverage_gate(repo: str, work_item_id: str, branch: str) -> tuple[bool, str]:
+    """ORCH-027 coverage-gate on the deploy-staging -> deploy edge (after merge-gate).
+
+    Deterministic, no LLM. Algorithm (ADR-001 D1..D7):
+      1. Conditionality: ``coverage_gate_enabled=False`` -> ``(True, "...disabled")``;
+         a repo the gate is not real for -> ``(True, "coverage-gate N/A for <repo>")``.
+      2. ``measure_coverage`` (pytest --cov=src in the worktree). ``None`` (tool
+         error) -> fail-open + WARNING by default (``coverage_tool_fail_closed``
+         flips to FAIL), FR-6.
+      3. ``compute_coverage_verdict`` -> write ``18-coverage-report.md`` -> read the
+         verdict BACK via ``parse_coverage_status`` (single source of truth: the
+         returned verdict == the artefact frontmatter, AC-9).
+      4. FAIL -> ``(False, reason)`` (engine rolls back to ``development`` + releases
+         the merge lease); PASS -> ``(True, reason)`` (engine proceeds to
+         image-freshness).
+
+    Never-raise (AC-7): any internal error -> a (bool, reason) pair following the
+    fail-open default (so an unexpected fault never wedges the autonomous pipeline),
+    unless ``coverage_tool_fail_closed`` is set.
+    """
+    floor = getattr(settings, "coverage_min_percent", 0.0)
+    policy = getattr(settings, "coverage_policy", "both")
+    epsilon = getattr(settings, "coverage_epsilon", 0.5)
+    try:
+        if not settings.coverage_gate_enabled:
+            return True, "coverage-gate disabled"
+        if not coverage_gate_applies(repo):
+            return True, f"coverage-gate N/A for {repo}"
+
+        from . import db
+        try:
+            baseline = db.get_coverage_baseline(repo)
+        except Exception as e:  # noqa: BLE001 - baseline read best-effort
+            logger.warning("coverage-gate: baseline read error for %s: %s", repo, e)
+            baseline = None
+
+        measured = measure_coverage(repo, branch)
+        if measured is None:
+            fail_closed = bool(settings.coverage_tool_fail_closed)
+            fields = _error_fields(
+                work_item_id, floor, policy, epsilon, baseline, fail_closed=fail_closed
+            )
+            write_coverage_report(repo, work_item_id, branch, fields)
+            if fail_closed:
+                logger.warning(
+                    "coverage-gate %s/%s: measurement failed -> fail-CLOSED (FAIL)",
+                    repo, work_item_id,
+                )
+                return False, "coverage-gate fail-closed: measurement failed (tool error)"
+            logger.warning(
+                "coverage-gate %s/%s: measurement failed -> fail-OPEN + WARNING",
+                repo, work_item_id,
+            )
+            return True, "coverage-gate fail-open (WARNING): measurement failed (tool error)"
+
+        ok, reason = compute_coverage_verdict(measured, baseline, floor, policy, epsilon)
+        delta = compute_delta(measured, baseline, floor)
+        fields = {
+            "coverage_status": "PASS" if ok else "FAIL",
+            "measured_coverage": measured,
+            "baseline": baseline,
+            "floor": floor,
+            "policy": policy,
+            "epsilon": epsilon,
+            "delta": delta,
+            "reason": reason,
+            "measurement": f"pytest --cov=src: line coverage src/ = {measured:.2f}%",
+            "policy_detail": (
+                f"policy={policy}, floor={floor}%, "
+                f"baseline={'bootstrap' if baseline is None else f'{baseline:.2f}%'}, "
+                f"epsilon={epsilon}%"
+            ),
+        }
+        path = write_coverage_report(repo, work_item_id, branch, fields)
+
+        # Read the machine verdict back from the artefact we just wrote — so the
+        # returned (bool, reason) is guaranteed == the YAML frontmatter (AC-9).
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                content = f.read()
+        except OSError as e:
+            return False, f"cannot read coverage report (fail-closed): {e}"
+        verdict_ok, _v = parse_coverage_status(content)
+
+        if verdict_ok:
+            logger.info("coverage-gate passed for %s/%s: %s", repo, work_item_id, reason)
+            return True, f"coverage OK ({reason})"
+
+        # FAIL -> surface loudly (Telegram with the clickable issue number, FR-7).
+        try:
+            from .notifications import send_telegram, link_for
+            base_str = "n/a" if baseline is None else f"{baseline:.2f}%"
+            send_telegram(
+                f"\U0001f4c9 {link_for(work_item_id)}: coverage-гейт FAIL — измерено "
+                f"{measured:.2f}% (floor {floor}%, baseline {base_str}, "
+                f"delta {delta:+.2f}%). Откат на development для доработки тестов."
+            )
+        except Exception as e:  # noqa: BLE001 - telegram best-effort
+            logger.warning("coverage-gate FAIL telegram failed: %s", e)
+        return False, reason
+    except Exception as e:  # noqa: BLE001 - never-raise contract (AC-7)
+        logger.error("check_coverage_gate error for %s/%s: %s", repo, branch, e)
+        # An unexpected internal error follows the fail-open default (anti-loop): a
+        # coverage-tool/logic fault must not wedge the autonomous pipeline. The
+        # operator can flip coverage_tool_fail_closed to make it strict.
+        try:
+            if settings.coverage_tool_fail_closed:
+                return False, f"coverage-gate error (fail-closed): {e}"
+        except Exception:  # noqa: BLE001
+            pass
+        return True, f"coverage-gate error (fail-open): {e}"
+
+
+# ---------------------------------------------------------------------------
+# Observability snapshot for GET /queue (FR-7 / AC-9)
+# ---------------------------------------------------------------------------
+def snapshot() -> dict:
+    """Read-only coverage-gate summary for GET /queue (FR-7 / AC-9).
+
+    Additive block; existing /queue keys are untouched. never-raise: any error ->
+    a minimal dict with the flags.
+    """
+    try:
+        enabled = bool(settings.coverage_gate_enabled)
+    except Exception:  # noqa: BLE001
+        enabled = False
+    out = {
+        "enabled": enabled,
+        "repos": getattr(settings, "coverage_gate_repos", "") or "",
+        "policy": getattr(settings, "coverage_policy", "both"),
+        "floor": getattr(settings, "coverage_min_percent", 0.0),
+        "epsilon": getattr(settings, "coverage_epsilon", 0.5),
+        "fail_closed": bool(getattr(settings, "coverage_tool_fail_closed", False)),
+        "baselines": {},
+    }
+    try:
+        from . import db
+        out["baselines"] = db.all_coverage_baselines()
+    except Exception as e:  # noqa: BLE001 - never-raise -> empty baselines
+        logger.warning("coverage snapshot baselines error: %s", e)
+    return out

src/db.py

@@ -199,10 +199,138 @@ def init_db():
         CREATE INDEX IF NOT EXISTS idx_repo_freeze_active
             ON repo_freeze (repo, cleared_at);
     """)
+    # ORCH-027 (FR-4, ADR-001 D4): additive per-repo coverage baseline for the
+    # coverage-gate ratchet. One row per repo; the baseline is monotonically
+    # non-decreasing via ratchet_coverage_baseline (atomic compare-and-set). Purely
+    # ADDITIVE (CREATE TABLE IF NOT EXISTS, pattern repo_freeze/job_deps) ->
+    # idempotent, restart-safe on the shared prod DB; existing tables untouched
+    # (NFR-5). See docs/work-items/ORCH-027/08-data-requirements.md.
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS coverage_baseline (
+            repo        TEXT PRIMARY KEY,
+            coverage    REAL NOT NULL,
+            source_sha  TEXT,
+            updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+    """)
     conn.commit()
     conn.close()
 
 
+def get_coverage_baseline(repo: str) -> float | None:
+    """ORCH-027: read the per-repo coverage baseline (%, line coverage).
+
+    Returns ``None`` when no baseline is stored yet (bootstrap mode — the gate then
+    decides on the absolute floor only, D3). Raises only on a real DB error (the
+    coverage_gate leaf caller wraps this in its never-raise contract).
+    """
+    if not repo:
+        return None
+    conn = get_db()
+    try:
+        row = conn.execute(
+            "SELECT coverage FROM coverage_baseline WHERE repo = ?", (repo,)
+        ).fetchone()
+    finally:
+        conn.close()
+    if row is None:
+        return None
+    try:
+        return float(row["coverage"])
+    except (TypeError, ValueError):
+        return None
+
+
+def ratchet_coverage_baseline(repo: str, coverage: float, sha: str | None = None) -> bool:
+    """ORCH-027 (FR-4, D5): raise the per-repo coverage baseline UP, never down.
+
+    Atomic compare-and-set: ``UPDATE ... WHERE coverage <= ?`` (the baseline never
+    decreases — an equal value is an idempotent no-harm re-stamp), or ``INSERT`` when
+    no row exists yet (bootstrap). Under the held merge-lease (ORCH-043) plus this
+    single-statement guard, two parallel merges can never lower or lose the value.
+    Returns True iff a row was inserted or raised.
+    """
+    if not repo:
+        return False
+    try:
+        cov = float(coverage)
+    except (TypeError, ValueError):
+        return False
+    conn = get_db()
+    try:
+        cur = conn.execute(
+            "UPDATE coverage_baseline "
+            "SET coverage = ?, source_sha = ?, updated_at = datetime('now') "
+            "WHERE repo = ? AND coverage <= ?",
+            (cov, sha, repo, cov),
+        )
+        changed = cur.rowcount or 0
+        if changed == 0:
+            # No row updated: either the row is absent (bootstrap INSERT) or the
+            # existing baseline is already higher (skip — never lower it).
+            exists = conn.execute(
+                "SELECT 1 FROM coverage_baseline WHERE repo = ?", (repo,)
+            ).fetchone()
+            if exists is None:
+                conn.execute(
+                    "INSERT INTO coverage_baseline (repo, coverage, source_sha, updated_at) "
+                    "VALUES (?, ?, ?, datetime('now'))",
+                    (repo, cov, sha),
+                )
+                changed = 1
+        conn.commit()
+        return bool(changed)
+    finally:
+        conn.close()
+
+
+def set_coverage_baseline(repo: str, coverage: float, sha: str | None = None) -> bool:
+    """ORCH-027 (D8): UNCONDITIONALLY set the per-repo coverage baseline.
+
+    For a legitimate one-off coverage drop (e.g. removing a large tested module) via
+    the manual ``POST /coverage/baseline`` override. Unlike ``ratchet_coverage_baseline``
+    this CAN lower the baseline. Returns True on success.
+    """
+    if not repo:
+        return False
+    try:
+        cov = float(coverage)
+    except (TypeError, ValueError):
+        return False
+    conn = get_db()
+    try:
+        conn.execute(
+            "INSERT INTO coverage_baseline (repo, coverage, source_sha, updated_at) "
+            "VALUES (?, ?, ?, datetime('now')) "
+            "ON CONFLICT(repo) DO UPDATE SET coverage = excluded.coverage, "
+            "source_sha = excluded.source_sha, updated_at = excluded.updated_at",
+            (repo, cov, sha),
+        )
+        conn.commit()
+        return True
+    finally:
+        conn.close()
+
+
+def all_coverage_baselines() -> dict:
+    """ORCH-027: all per-repo coverage baselines for the GET /queue snapshot."""
+    conn = get_db()
+    try:
+        rows = conn.execute(
+            "SELECT repo, coverage, source_sha, updated_at FROM coverage_baseline"
+        ).fetchall()
+    finally:
+        conn.close()
+    return {
+        r["repo"]: {
+            "coverage": r["coverage"],
+            "source_sha": r["source_sha"],
+            "updated_at": r["updated_at"],
+        }
+        for r in rows
+    }
+
+
 def _ensure_column(conn, table: str, column: str, decl: str):
     """Add a column to `table` if it does not already exist (idempotent migration)."""
     cols = [r[1] for r in conn.execute(f"PRAGMA table_info({table})").fetchall()]
@@ -1005,6 +1133,100 @@ def get_running_jobs() -> list[dict]:
     return [dict(r) for r in rows]
 
 
+def get_running_agents() -> list[dict]:
+    """ORCH-099 (D5): read-only liveness snapshot of every 'running' job for /metrics.
+
+    A dedicated read-only SELECT — deliberately NOT an extension of
+    ``get_running_jobs()`` (the job-reaper hot path, ORCH-065): widening that
+    query under observability needs would migrate a foreign component's invariant.
+    Each row carries the process identity + cost context the F1b sidecar needs:
+      * ``job_id`` / ``run_id`` / ``pid`` — process identity (pid may be NULL until
+        the launcher stamps it / after the process exits);
+      * ``agent`` / ``repo`` — role and project (the sidecar is multi-project);
+      * ``running_age_s`` — seconds since ``jobs.started_at`` (the same process
+        anchor the reaper uses for backstop-liveness, D6);
+      * ``model`` / ``effort`` — cost context (LEFT JOIN ``agent_runs``);
+      * the token / ``cost_usd`` columns — current per-run accruals, usually NULL
+        until the launcher parses the CLI result JSON on finish (honest raw, TR-5).
+
+    A LEFT JOIN on ``run_id`` keeps a job with no ``agent_runs`` row. Read-only;
+    never mutates.
+    """
+    conn = get_db()
+    try:
+        rows = conn.execute(
+            "SELECT j.id AS job_id, j.run_id AS run_id, j.pid AS pid, "
+            "j.agent AS agent, j.repo AS repo, j.started_at AS started_at, "
+            "CAST(strftime('%s','now') - strftime('%s', j.started_at) AS INTEGER) "
+            "  AS running_age_s, "
+            "r.model AS model, r.effort AS effort, r.cost_usd AS cost_usd, "
+            "r.input_tokens AS input_tokens, r.output_tokens AS output_tokens, "
+            "r.cache_read_tokens AS cache_read_tokens, "
+            "r.cache_creation_tokens AS cache_creation_tokens "
+            "FROM jobs j LEFT JOIN agent_runs r ON r.id = j.run_id "
+            "WHERE j.status='running'"
+        ).fetchall()
+    finally:
+        conn.close()
+    return [dict(r) for r in rows]
+
+
+def agent_cost_totals() -> dict:
+    """ORCH-099 (D7): read-only aggregate of cost / tokens over all agent_runs.
+
+    Pure ``SELECT COALESCE(SUM(...),0)`` — an empty ``agent_runs`` table yields
+    zeros, never an error (TC-06 / TC-11). Read-only; never mutates.
+    """
+    conn = get_db()
+    try:
+        row = conn.execute(
+            "SELECT "
+            "COALESCE(SUM(cost_usd),0) AS cost_usd, "
+            "COALESCE(SUM(input_tokens),0) AS input_tokens, "
+            "COALESCE(SUM(output_tokens),0) AS output_tokens, "
+            "COALESCE(SUM(cache_read_tokens),0) AS cache_read_tokens, "
+            "COALESCE(SUM(cache_creation_tokens),0) AS cache_creation_tokens "
+            "FROM agent_runs"
+        ).fetchone()
+    finally:
+        conn.close()
+    return dict(row) if row else {
+        "cost_usd": 0,
+        "input_tokens": 0,
+        "output_tokens": 0,
+        "cache_read_tokens": 0,
+        "cache_creation_tokens": 0,
+    }
+
+
+def queue_retry_stats() -> dict:
+    """ORCH-099 (D4): read-only retry raw over UNFINISHED jobs for /metrics.queue.
+
+    Aggregates ``attempts`` / ``transient_attempts`` and counts jobs currently in
+    backoff (``available_at > now``) across non-terminal jobs (status NOT IN
+    done/failed/cancelled). Read-only; never mutates.
+    """
+    conn = get_db()
+    try:
+        row = conn.execute(
+            "SELECT "
+            "COALESCE(SUM(attempts),0) AS total_attempts, "
+            "COALESCE(SUM(transient_attempts),0) AS total_transient_attempts, "
+            "COALESCE(MAX(attempts),0) AS max_attempts_seen, "
+            "COALESCE(SUM(CASE WHEN available_at IS NOT NULL "
+            "  AND available_at > datetime('now') THEN 1 ELSE 0 END),0) AS in_backoff "
+            "FROM jobs WHERE status NOT IN ('done','failed','cancelled')"
+        ).fetchone()
+    finally:
+        conn.close()
+    return dict(row) if row else {
+        "total_attempts": 0,
+        "total_transient_attempts": 0,
+        "max_attempts_seen": 0,
+        "in_backoff": 0,
+    }
+
+
 def reap_running_job(
     job_id: int,
     status: str,
@@ -1057,13 +1279,20 @@ def get_job(job_id: int) -> dict | None:
 
 
 def job_status_counts() -> dict:
-    """Return counts grouped by status (for /queue observability)."""
+    """Return counts grouped by status (for /queue and /metrics observability).
+
+    ORCH-099 (D4): the default dict carries the ``cancelled`` terminal key
+    (ORCH-090, terminal set ``{done, cancelled}``) so the key is always present
+    with a 0 default instead of materialising only when a cancelled job exists.
+    Purely additive — the GROUP BY query is unchanged and pre-existing keys keep
+    their meaning (no /queue contract break).
+    """
     conn = get_db()
     rows = conn.execute(
         "SELECT status, COUNT(*) AS n FROM jobs GROUP BY status"
     ).fetchall()
     conn.close()
-    counts = {"queued": 0, "running": 0, "done": 0, "failed": 0}
+    counts = {"queued": 0, "running": 0, "done": 0, "failed": 0, "cancelled": 0}
     for r in rows:
         counts[r["status"]] = r["n"]
     return counts

src/main.py

@@ -170,6 +170,7 @@ async def queue():
     from . import merge_gate
     from . import task_deps
     from . import serial_gate
+    from . import coverage_gate
     from . import labels
     from . import cancel
     from .disk_watchdog import disk_watchdog
@@ -189,6 +190,9 @@ async def queue():
         # ORCH-088 (D9 / AC-10): per-repo serial-gate observability (read-only) —
         # active task, queued/waiting analyst-jobs, freeze state. Additive block.
         "serial_gate": serial_gate.snapshot(),
+        # ORCH-027 (FR-7 / AC-9): coverage-gate observability (read-only) —
+        # kill-switch, scope, policy/floor/epsilon, per-repo baselines. Additive block.
+        "coverage": coverage_gate.snapshot(),
         # ORCH-089 (D7): auto-mode-by-label observability (read-only) — kill-switch,
         # label names, scope. Additive block.
         "auto_labels": labels.snapshot(),
@@ -209,6 +213,26 @@ async def queue():
     }
 
 
+@app.get("/metrics")
+async def metrics():
+    """ORCH-099 (FND/F1a): lightweight read-only raw-signal snapshot for the F1b sidecar.
+
+    A versioned JSON envelope (``schema_version`` / ``generated_at`` / ``clk_tck``)
+    with four raw-signal sections — ``stages`` (active task stages + age),
+    ``queue`` (counts / retries / breaker / concurrency), ``agents`` (agent-liveness:
+    pid / runtime / cpu_ticks), ``cost`` (per-run + aggregate tokens/cost). The
+    orchestrator emits ONLY raw signal it alone knows; the stateful arbiter
+    (thresholds / deltas / alerts) is the separate sidecar (BRD §1).
+
+    Thin wrapper over ``metrics.build_metrics()`` (in the style of GET /queue): the
+    collector is already strictly read-only and never-raise, so no extra error
+    handling is needed here. Same access level as /queue//status. The format is the
+    documented contract for the sidecar (docs/architecture/README.md).
+    """
+    from . import metrics as metrics_mod
+    return metrics_mod.build_metrics()
+
+
 @app.post("/serial-gate/unfreeze")
 async def serial_gate_unfreeze(repo: str = ""):
     """ORCH-088 (FR-5, ADR-001 D4): manually clear a per-repo rollback-freeze.
@@ -236,3 +260,23 @@ async def serial_gate_unfreeze(repo: str = ""):
         except Exception:
             pass
     return {"ok": True, "repo": repo, "cleared": cleared, "frozen": frozen}
+
+
+@app.post("/coverage/baseline")
+async def coverage_set_baseline(repo: str = "", value: float | None = None):
+    """ORCH-027 (D8): manually set/override the per-repo coverage baseline.
+
+    For a legitimate one-off coverage drop (e.g. removing a large tested module) the
+    operator sets the baseline directly here (by образцу ``POST /serial-gate/unfreeze``)
+    instead of waiting for the upward-only ratchet. Unlike the ratchet this CAN lower
+    the baseline. Alternative without this endpoint: temporarily flip
+    ``ORCH_COVERAGE_POLICY=absolute``.
+    """
+    from . import db
+    if not repo or not repo.strip():
+        return {"ok": False, "error": "missing 'repo'", "repo": repo}
+    if value is None:
+        return {"ok": False, "error": "missing 'value'", "repo": repo}
+    repo = repo.strip()
+    ok = db.set_coverage_baseline(repo, value, sha="manual-override")
+    return {"ok": ok, "repo": repo, "baseline": db.get_coverage_baseline(repo)}

src/metrics.py

@@ -0,0 +1,276 @@
+"""ORCH-099 (FND/F1a): lightweight read-only ``/metrics`` raw-signal collector.
+
+A leaf module that builds a versioned JSON snapshot of the orchestrator's own
+raw state for the future observability sidecar (F1b, ``watchdog/``): active task
+stages, the job queue, agent-liveness, and cost/tokens. The orchestrator emits
+ONLY raw signal it alone knows — the sidecar is the stateful arbiter that
+computes thresholds / deltas / alerts (BRD §1, observer separated from observed).
+
+Design (ADR-001, by образцу ``serial_gate.snapshot()`` / ``cancel.snapshot()``):
+  * pure, never-raise, no side effects — only reads existing tables
+    (``tasks`` / ``jobs`` / ``agent_runs``) and the in-memory worker snapshot;
+  * ``build_metrics()`` assembles the envelope section-by-section, each section in
+    its own ``try/except`` with a safe default (``None`` / ``[]`` / ``{}``) so a
+    failing source degrades one field, never the whole endpoint (FR-6, NFR-2);
+  * strictly read-only — no INSERT/UPDATE/DELETE/CREATE/ALTER, no process control,
+    no network. Self-hosting-safe on the shared prod instance.
+
+The endpoint ``GET /metrics`` (``src/main.py``) is a thin wrapper that returns
+``build_metrics()`` as-is.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from datetime import datetime, timezone
+
+logger = logging.getLogger("orchestrator.metrics")
+
+# Contract version for the sidecar (D2). Additive changes (new field/section) do
+# NOT bump it — the sidecar MUST ignore unknown keys and tolerate missing
+# optional ones. Bumped ONLY on a breaking change (rename/remove/retype an
+# existing field).
+SCHEMA_VERSION = 1
+
+
+def _now_iso() -> str:
+    """UTC ISO-8601 snapshot timestamp (``...Z``), the orchestrator's own clock.
+
+    Same clock domain as the SQLite ``datetime('now')`` timestamps and the CPU
+    tick reads, so the sidecar's ``(cpu_ticks, generated_at)`` deltas are immune
+    to orchestrator↔sidecar clock skew (TR-3). Never raises.
+    """
+    try:
+        return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    except Exception as e:  # noqa: BLE001 - never-raise
+        logger.warning("metrics._now_iso error: %s", e)
+        return ""
+
+
+def _clk_tck() -> int | None:
+    """Process-global SC_CLK_TCK (ticks/second) — the basis for converting raw CPU
+    ticks to seconds on the sidecar side. ``None`` on non-Linux / failure.
+    """
+    try:
+        return int(os.sysconf("SC_CLK_TCK"))
+    except Exception as e:  # noqa: BLE001 - never-raise (non-Linux / unsupported)
+        logger.warning("metrics._clk_tck error: %s", e)
+        return None
+
+
+def _read_cpu_ticks(pid: int | None) -> int | None:
+    """Sum of utime+stime (CPU ticks) from ``/proc/<pid>/stat`` — raw liveness signal.
+
+    The orchestrator emits raw ticks and does NOT compute the delta — the sidecar
+    is the stateless arbiter (it divides ``(ticks₂−ticks₁)/clk_tck`` by the
+    ``generated_at`` delta to get a CPU fraction; a tiny fraction at a growing
+    ``runtime_s`` ⇒ a "stuck" candidate). Parsing is robust to spaces in ``comm``:
+    fields are read AFTER the closing ``") "`` of the process name (canonical
+    proc-stat read). utime = field 14, stime = field 15 → indices 11 and 12 of the
+    post-``)`` token list (fields 3.. shift by 3).
+
+    never-raise (NFR-2, AC-6): ``pid is None`` / missing ``/proc/<pid>`` (process
+    died or non-Linux) / any parse error → ``None`` (NOT an exception). The caller
+    keeps every other field and the whole endpoint intact.
+    """
+    if pid is None:
+        return None
+    try:
+        with open(f"/proc/{int(pid)}/stat", "r") as f:
+            data = f.read()
+        rparen = data.rfind(") ")
+        if rparen == -1:
+            return None
+        rest = data[rparen + 2:].split()
+        # rest[0] = state (field 3); utime = field 14 -> rest[11], stime -> rest[12]
+        return int(rest[11]) + int(rest[12])
+    except Exception:  # noqa: BLE001 - dead pid / no /proc / non-Linux -> null
+        return None
+
+
+def _build_stages() -> list:
+    """Active (non-terminal) task stages (D3, FR-1).
+
+    Source: ``db.get_active_tasks_for_reconcile()`` (``stage != 'done'`` + SQL
+    ``age_s``), with an extra ``stage NOT IN ('done','cancelled')`` filter on the
+    metrics side: that helper deliberately still returns ``cancelled`` tasks for
+    the reconciler's skip-counter (ORCH-086), but terminal tasks are not raw
+    observability signal (terminal set ``{done, cancelled}``, ORCH-090). The helper
+    invariant belongs to ORCH-053/086 — we filter at the consumer, not the source.
+    """
+    from . import db
+
+    rows = db.get_active_tasks_for_reconcile()
+    out = []
+    for t in rows:
+        if t.get("stage") in ("done", "cancelled"):
+            continue
+        out.append({
+            "work_item": t.get("work_item_id"),
+            "stage": t.get("stage"),
+            "age_in_stage_s": t.get("age_s"),
+            "repo": t.get("repo"),
+            "task_id": t.get("id"),
+        })
+    return out
+
+
+def _build_queue() -> dict:
+    """Job-queue raw signal (D4, FR-2): counts, depth, retries, breaker, concurrency.
+
+    Each sub-source is independently guarded: an uninitialised ``worker`` (e.g. in
+    a test) degrades to ``breaker: null`` / ``max_concurrency: null`` — never a 500
+    (NFR-2).
+    """
+    from . import db
+
+    counts = None
+    try:
+        counts = db.job_status_counts()
+    except Exception as e:  # noqa: BLE001
+        logger.warning("metrics queue counts error: %s", e)
+
+    retries = None
+    try:
+        retries = db.queue_retry_stats()
+    except Exception as e:  # noqa: BLE001
+        logger.warning("metrics queue retries error: %s", e)
+
+    breaker = None
+    max_concurrency = None
+    poll_interval = None
+    try:
+        from .queue_worker import worker
+        try:
+            breaker = worker.breaker.snapshot()
+        except Exception as e:  # noqa: BLE001
+            logger.warning("metrics breaker snapshot error: %s", e)
+        max_concurrency = getattr(worker, "max_concurrency", None)
+        poll_interval = getattr(worker, "poll_interval", None)
+    except Exception as e:  # noqa: BLE001 - worker not initialised
+        logger.warning("metrics worker access error: %s", e)
+
+    depth = counts.get("queued") if isinstance(counts, dict) else None
+    return {
+        "counts": counts,
+        "depth": depth,
+        "retries": retries,
+        "breaker": breaker,
+        "max_concurrency": max_concurrency,
+        "poll_interval": poll_interval,
+    }
+
+
+def _build_agents() -> list:
+    """Agent-liveness raw signal (D5/D6, FR-3).
+
+    One entry per running job from ``db.get_running_agents()`` with process
+    identity (``agent`` / ``run_id`` / ``job_id`` / ``pid``), ``runtime_s``
+    (= ``running_age_s``, anchored on ``jobs.started_at``, D6), ``model`` /
+    ``effort``, and the raw ``cpu_ticks`` from ``/proc/<pid>/stat``. ``pid is
+    None`` / dead process → ``cpu_ticks: null`` for THAT agent; the rest stays
+    intact (AC-6, TC-05).
+    """
+    from . import db
+
+    rows = db.get_running_agents()
+    out = []
+    for j in rows:
+        pid = j.get("pid")
+        out.append({
+            "agent": j.get("agent"),
+            "run_id": j.get("run_id"),
+            "job_id": j.get("job_id"),
+            "repo": j.get("repo"),
+            "pid": pid,
+            "runtime_s": j.get("running_age_s"),
+            "model": j.get("model"),
+            "effort": j.get("effort"),
+            "cpu_ticks": _read_cpu_ticks(pid),
+        })
+    return out
+
+
+def _build_cost() -> dict:
+    """Cost / token raw signal (D7, FR-4).
+
+    ``running`` — current per-running-job accruals from ``agent_runs`` (often
+    ``null`` until the job finishes and the launcher parses the CLI JSON — ``null``
+    is honest raw, NOT zero, TR-5). ``aggregate`` — summed totals over all
+    ``agent_runs`` (empty table → zeros, TC-06/TC-11).
+    """
+    from . import db
+
+    running = []
+    try:
+        for j in db.get_running_agents():
+            running.append({
+                "run_id": j.get("run_id"),
+                "job_id": j.get("job_id"),
+                "agent": j.get("agent"),
+                "cost_usd": j.get("cost_usd"),
+                "input_tokens": j.get("input_tokens"),
+                "output_tokens": j.get("output_tokens"),
+                "cache_read_tokens": j.get("cache_read_tokens"),
+                "cache_creation_tokens": j.get("cache_creation_tokens"),
+            })
+    except Exception as e:  # noqa: BLE001
+        logger.warning("metrics cost.running error: %s", e)
+        running = []
+
+    aggregate = None
+    try:
+        aggregate = db.agent_cost_totals()
+    except Exception as e:  # noqa: BLE001
+        logger.warning("metrics cost.aggregate error: %s", e)
+
+    return {"running": running, "aggregate": aggregate}
+
+
+def build_metrics() -> dict:
+    """Assemble the ``/metrics`` envelope (FR-5). never-raise (FR-6, NFR-2, AC-4).
+
+    Each section is collected in its own ``try/except`` with a safe default so a
+    failing source degrades one section, not the whole response. Honours the
+    ``metrics_endpoint_enabled`` kill-switch (D8): when off, returns a minimal
+    parsable body ``{"schema_version", "enabled": false}`` (200, NOT 404) so the
+    sidecar sees the off-switch explicitly.
+    """
+    try:
+        from .config import settings
+        if not bool(getattr(settings, "metrics_endpoint_enabled", True)):
+            return {"schema_version": SCHEMA_VERSION, "enabled": False}
+    except Exception as e:  # noqa: BLE001 - kill-switch read must never break /metrics
+        logger.warning("metrics kill-switch read error: %s", e)
+
+    out: dict = {
+        "schema_version": SCHEMA_VERSION,
+        "generated_at": _now_iso(),
+        "clk_tck": _clk_tck(),
+    }
+
+    try:
+        out["stages"] = _build_stages()
+    except Exception as e:  # noqa: BLE001
+        logger.warning("metrics stages section error: %s", e)
+        out["stages"] = []
+
+    try:
+        out["queue"] = _build_queue()
+    except Exception as e:  # noqa: BLE001
+        logger.warning("metrics queue section error: %s", e)
+        out["queue"] = None
+
+    try:
+        out["agents"] = _build_agents()
+    except Exception as e:  # noqa: BLE001
+        logger.warning("metrics agents section error: %s", e)
+        out["agents"] = []
+
+    try:
+        out["cost"] = _build_cost()
+    except Exception as e:  # noqa: BLE001
+        logger.warning("metrics cost section error: %s", e)
+        out["cost"] = None
+
+    return out

src/qg/checks.py

@@ -755,6 +755,23 @@ def check_security_gate(repo: str, work_item_id: str, branch: str) -> tuple[bool
     return _impl(repo, work_item_id, branch)
 
 
+def check_coverage_gate(repo: str, work_item_id: str, branch: str) -> tuple[bool, str]:
+    """ORCH-027 coverage sub-gate (pytest --cov=src) on the deploy-staging -> deploy
+    edge, run AFTER the merge-gate (caught-up HEAD) and BEFORE image-freshness.
+
+    Thin registry wrapper that delegates to ``coverage_gate.check_coverage_gate``
+    (measure line coverage of src/, compare to floor/baseline under a policy, write/
+    read-back ``18-coverage-report.md``). The real logic lives in
+    ``src/coverage_gate.py`` (leaf module, never-raise, fail-open on a tool error by
+    default); importing it lazily here avoids an import cycle (coverage_gate imports
+    is_self_hosting_repo from this module). For non-self repos with an empty scope it
+    returns ``(True, "coverage-gate N/A for <repo>")`` so the deploy edge is unchanged
+    for them (AC-5).
+    """
+    from ..coverage_gate import check_coverage_gate as _impl
+    return _impl(repo, work_item_id, branch)
+
+
 # Registry for dynamic lookup by name
 QG_CHECKS = {
     "check_analysis_approved": check_analysis_approved,
@@ -770,4 +787,5 @@ QG_CHECKS = {
     "check_branch_mergeable": check_branch_mergeable,
     "check_staging_image_fresh": _check_staging_image_fresh,
     "check_security_gate": check_security_gate,
+    "check_coverage_gate": check_coverage_gate,
 }

src/stage_engine.py

@@ -322,6 +322,19 @@ def advance_stage(
             ):
                 return result
 
+            # --- ORCH-027 coverage sub-gate (deploy-staging -> deploy edge) ----
+            # AFTER the merge-gate (coverage measured on the caught-up HEAD that
+            # lands in `main`, so the metric matches landed code) and BEFORE the
+            # image-freshness rebuild (fail before the expensive docker rebuild).
+            # Deterministic (no LLM): pytest --cov=src -> line coverage % vs floor /
+            # ratchet baseline. FAIL -> rollback to development + release the merge
+            # lease (held by the merge-gate's PASS). It owns the outcome on
+            # intervention (mirrors the merge-gate / image-freshness).
+            if _handle_coverage_gate(
+                task_id, current_stage, repo, work_item_id, branch, agent, result
+            ):
+                return result
+
             # --- ORCH-058 freshness sub-gate (deploy-staging -> deploy edge) ---
             # AFTER the merge-gate finalised the validated HEAD and BEFORE Phase A.
             # Rebuilds the staging image from that validated commit + recreates 8501
@@ -1124,6 +1137,90 @@ def _handle_security_gate(
     return True
 
 
+# ---------------------------------------------------------------------------
+# ORCH-027: coverage sub-gate on the deploy-staging -> deploy edge
+# ---------------------------------------------------------------------------
+def _handle_coverage_gate(
+    task_id, current_stage, repo, work_item_id, branch, agent, result: AdvanceResult
+) -> bool:
+    """Run check_coverage_gate on the deploy-staging -> deploy edge (ORCH-027).
+
+    Runs AFTER the merge-gate (so coverage is measured on the rebased/caught-up HEAD
+    that actually lands in `main`) and BEFORE the image-freshness rebuild (fail before
+    the expensive docker rebuild). Deterministic (no LLM): pytest --cov=src in the
+    per-branch worktree -> line coverage % -> compute_coverage_verdict vs the absolute
+    floor and/or the ratchet baseline. The machine verdict lives in
+    18-coverage-report.md frontmatter. A coverage-tool error degrades fail-open +
+    WARNING by default (FR-6), so an infra hiccup never wedges the autonomous pipeline.
+
+    Returns True if the gate INTERVENED (the caller must return without advancing):
+      * FAIL (coverage below policy) -> ROLLBACK to development (+ developer retry,
+        capped by MAX_DEVELOPER_RETRIES) and RELEASE the merge lease (the merge-gate
+        held it on its PASS; coverage failed before the merge — mirrors the
+        image-freshness rollback, ADR-001 D1/TR-2).
+    Returns False when the gate PASSED (clean / fail-open / N/A) so advance_stage
+    proceeds to the image-freshness sub-gate. On a PASS the merge lease stays HELD
+    until the actual merge (released on done / rollback).
+    """
+    passed, reason = _run_qg("check_coverage_gate", repo, work_item_id, branch)
+    if passed:
+        logger.info(f"Task {task_id}: coverage-gate passed ({reason})")
+        return False
+
+    result.qg_name = "check_coverage_gate"
+    result.qg_passed = False
+    result.qg_reason = reason
+
+    update_task_stage(task_id, "development")
+    notify_stage_change(task_id, current_stage, "development")
+    plane_notify_stage(work_item_id, current_stage, "development")
+    result.rolled_back_to = "development"
+    set_issue_in_progress(work_item_id)
+    # The merge-gate held the lease on its PASS; coverage failed before the merge, so
+    # release it (holder-aware no-op if a different task already owns it). Mirrors the
+    # image-freshness rollback (ADR-001 D1/TR-2).
+    try:
+        merge_gate.release_merge_lease(repo, branch)
+    except Exception as e:  # noqa: BLE001 - defensive
+        logger.warning(f"Task {task_id}: merge-lease release on coverage fail failed: {e}")
+    notify_qg_failure(task_id, current_stage, "check_coverage_gate", reason)
+    plane_add_comment(
+        work_item_id,
+        f"❌ Coverage-гейт провален ({reason}). Откат на development. "
+        f"Developer нужен для добавления тестов (покрытие src/ просело).",
+        author="deployer",
+    )
+    retry_count = _developer_retry_count(task_id)
+    if retry_count < MAX_DEVELOPER_RETRIES:
+        report_ref = f"docs/work-items/{work_item_id}/18-coverage-report.md"
+        task_desc = (
+            f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n"
+            f"Stage: development\nNote: Coverage-гейт провален "
+            f"(attempt {retry_count + 1}/{MAX_DEVELOPER_RETRIES}). "
+            f"Причина: {reason}. Добавь тесты, чтобы покрытие src/ не падало ниже "
+            f"политики. Полный отчёт: {report_ref}"
+        )
+        new_job = enqueue_job("developer", repo, task_desc, task_id=task_id)
+        result.enqueued_agent = "developer"
+        result.enqueued_job_id = new_job
+        logger.info(
+            f"Task {task_id}: coverage-gate FAILED, enqueued developer (job_id={new_job})"
+        )
+    else:
+        set_issue_blocked(work_item_id)
+        send_telegram(
+            f"\U0001f6a8 {link_for(work_item_id)}: Coverage-гейт still failing after "
+            f"{MAX_DEVELOPER_RETRIES} developer retries ({reason}). "
+            f"Manual intervention needed."
+        )
+        result.alerted = True
+    logger.error(
+        f"Task {task_id}: coverage-gate FAILED, rolled back deploy-staging -> "
+        f"development ({reason})"
+    )
+    return True
+
+
 # ---------------------------------------------------------------------------
 # ORCH-058: staging-image freshness sub-gate on the deploy-staging -> deploy edge
 # ---------------------------------------------------------------------------
@@ -1546,6 +1643,17 @@ def _handle_merge_verify(task_id, repo, work_item_id, branch, result: AdvanceRes
                         task_id, repo, work_item_id, branch, guard_msg, result
                     )
 
+            # ORCH-027 (D5): ratchet the per-repo coverage baseline UP from this
+            # merged branch's measured coverage (single source of truth:
+            # 18-coverage-report.md). Atomic compare-and-set under the still-held
+            # merge-lease -> the baseline never decreases. never-raise (observability
+            # best-effort): a ratchet failure must never break the deploy->done path.
+            try:
+                from . import coverage_gate
+                coverage_gate.ratchet_baseline_on_merge(repo, work_item_id, branch, sha)
+            except Exception as e:  # noqa: BLE001 - observability best-effort
+                logger.warning(f"Task {task_id}: coverage baseline ratchet failed: {e}")
+
             merge_gate.note_merge_verified()
             try:
                 self_deploy.record_merged_to_main(repo, work_item_id, branch, True)

tests/test_config.py

@@ -248,6 +248,7 @@ def test_tc19_qg_checks_registry_unchanged():
         "check_branch_mergeable",
         "check_staging_image_fresh",
         "check_security_gate",
+        "check_coverage_gate",
     }
 
 
@@ -319,3 +320,20 @@ def test_deploy_status_guard_settings_env_override(monkeypatch):
     s = Settings()
     assert s.deploy_status_guard_enabled is False
     assert s.deploy_status_guard_repos == "orchestrator,enduro-trails"
+
+
+# ---------------------------------------------------------------------------
+# ORCH-099 (D8): metrics_endpoint_enabled default + env alias ORCH_METRICS_ENABLED.
+# The field carries an explicit validation_alias so the DOCUMENTED env var
+# (README / ADR-001 D8) actually controls the flag, overriding the default
+# ORCH_ + field-name mapping (which would otherwise be ORCH_METRICS_ENDPOINT_*).
+# ---------------------------------------------------------------------------
+def test_metrics_endpoint_enabled_default_true(monkeypatch):
+    monkeypatch.delenv("ORCH_METRICS_ENABLED", raising=False)
+    monkeypatch.delenv("ORCH_METRICS_ENDPOINT_ENABLED", raising=False)
+    assert Settings().metrics_endpoint_enabled is True
+
+
+def test_metrics_endpoint_enabled_reads_documented_env_alias(monkeypatch):
+    monkeypatch.setenv("ORCH_METRICS_ENABLED", "false")
+    assert Settings().metrics_endpoint_enabled is False

tests/test_coverage_gate.py

@@ -0,0 +1,471 @@
+"""ORCH-027 / TC-01..TC-15: the coverage-gate leaf module (src/coverage_gate.py).
+
+These exercise the DETERMINISTIC core: the pure verdict / delta / frontmatter
+helpers (no binaries needed), the ratchet baseline against a real tmp SQLite DB,
+the conditionality / kill-switch / fail-open behaviour with the measurer mocked,
+never-raise, and the gate's integration into advance_stage / GET /queue.
+
+Contract under test (ADR-001 §7):
+  * the verdict is a deterministic pure function of (measured, baseline, floor,
+    policy, epsilon) — no LLM, all border / epsilon cases covered;
+  * the ratchet baseline only moves UP and bootstraps on the first merge;
+  * conditionality: empty scope -> self-hosting only; out-of-scope -> no-op N/A;
+    kill-switch off -> inert;
+  * a coverage-tool error degrades fail-open + WARNING by default, fail-closed only
+    when configured;
+  * the machine verdict lives ONLY in the YAML frontmatter (read-back == written);
+  * never-raise: any internal error -> a (bool, reason) pair, no exception escapes;
+  * self-hosting safety: the gate never deploys / restarts prod / pushes main.
+"""
+import os
+import tempfile
+
+os.environ["ORCH_DB_PATH"] = os.path.join(tempfile.gettempdir(), "test_coverage_gate.db")
+os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
+os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
+
+import pytest  # noqa: E402
+
+import src.db as db  # noqa: E402
+from src import config as cfg  # noqa: E402
+from src import coverage_gate as cg  # noqa: E402
+
+_REPO = "orchestrator"
+_BRANCH = "feature/ORCH-027-code-coverage"
+_WI = "ORCH-027"
+
+
+@pytest.fixture(autouse=True)
+def fresh_db(tmp_path, monkeypatch):
+    """Isolated tmp SQLite DB + gate ON / empty scope (self-hosting) by default."""
+    dbfile = tmp_path / "cov.db"
+    monkeypatch.setattr(db.settings, "db_path", str(dbfile))
+    monkeypatch.setattr(cfg.settings, "coverage_gate_enabled", True, raising=False)
+    monkeypatch.setattr(cfg.settings, "coverage_gate_repos", "", raising=False)
+    monkeypatch.setattr(cfg.settings, "coverage_min_percent", 80.0, raising=False)
+    monkeypatch.setattr(cfg.settings, "coverage_policy", "both", raising=False)
+    monkeypatch.setattr(cfg.settings, "coverage_epsilon", 0.5, raising=False)
+    monkeypatch.setattr(cfg.settings, "coverage_tool_fail_closed", False, raising=False)
+    monkeypatch.setattr(cfg.settings, "coverage_run_timeout_s", 900, raising=False)
+    db.init_db()
+    yield
+
+
+# ===========================================================================
+# TC-01 — policy=absolute
+# ===========================================================================
+def test_tc01_policy_absolute():
+    # measured >= floor -> PASS
+    ok, _ = cg.compute_coverage_verdict(85.0, None, 80.0, "absolute", 0.0)
+    assert ok is True
+    # exactly on the floor -> PASS (>=)
+    ok, _ = cg.compute_coverage_verdict(80.0, None, 80.0, "absolute", 0.0)
+    assert ok is True
+    # below floor-epsilon -> FAIL
+    ok, _ = cg.compute_coverage_verdict(78.0, None, 80.0, "absolute", 0.5)
+    assert ok is False
+    # baseline is IGNORED under absolute (even a high baseline cannot fail it)
+    ok, _ = cg.compute_coverage_verdict(85.0, 99.0, 80.0, "absolute", 0.0)
+    assert ok is True
+
+
+# ===========================================================================
+# TC-02 — policy=baseline (no-regression / ratchet)
+# ===========================================================================
+def test_tc02_policy_baseline():
+    # measured >= baseline -> PASS
+    ok, _ = cg.compute_coverage_verdict(90.0, 85.0, 0.0, "baseline", 0.0)
+    assert ok is True
+    # exactly on baseline -> PASS
+    ok, _ = cg.compute_coverage_verdict(85.0, 85.0, 0.0, "baseline", 0.0)
+    assert ok is True
+    # below baseline-epsilon -> FAIL
+    ok, _ = cg.compute_coverage_verdict(83.0, 85.0, 0.0, "baseline", 0.5)
+    assert ok is False
+    # floor is IGNORED under baseline (low measured vs floor but >= baseline -> PASS)
+    ok, _ = cg.compute_coverage_verdict(40.0, 30.0, 80.0, "baseline", 0.0)
+    assert ok is True
+    # bootstrap: baseline None under baseline policy -> PASS (cannot regress vs nothing)
+    ok, reason = cg.compute_coverage_verdict(10.0, None, 80.0, "baseline", 0.0)
+    assert ok is True
+    assert "bootstrap" in reason.lower()
+
+
+# ===========================================================================
+# TC-03 — policy=both (PASS only if BOTH hold)
+# ===========================================================================
+def test_tc03_policy_both():
+    # both hold -> PASS
+    ok, _ = cg.compute_coverage_verdict(90.0, 85.0, 80.0, "both", 0.0)
+    assert ok is True
+    # absolute fails (below floor) -> FAIL even though >= baseline
+    ok, _ = cg.compute_coverage_verdict(82.0, 80.0, 85.0, "both", 0.0)
+    assert ok is False
+    # baseline fails (below baseline) -> FAIL even though >= floor
+    ok, _ = cg.compute_coverage_verdict(84.0, 90.0, 80.0, "both", 0.0)
+    assert ok is False
+    # bootstrap under both: baseline None -> only absolute decides
+    ok, _ = cg.compute_coverage_verdict(85.0, None, 80.0, "both", 0.0)
+    assert ok is True
+    ok, _ = cg.compute_coverage_verdict(70.0, None, 80.0, "both", 0.0)
+    assert ok is False
+
+
+# ===========================================================================
+# TC-04 — epsilon tolerance (anti-flap, NFR-4)
+# ===========================================================================
+def test_tc04_epsilon_tolerance():
+    # measured 0.3% under baseline, epsilon 0.5 -> still PASS (within noise)
+    ok, _ = cg.compute_coverage_verdict(84.7, 85.0, 80.0, "both", 0.5)
+    assert ok is True
+    # measured 0.3% under floor, epsilon 0.5 -> still PASS
+    ok, _ = cg.compute_coverage_verdict(79.7, 80.0, 0.0, "absolute", 0.5)
+    assert ok is True
+    # just beyond epsilon -> FAIL
+    ok, _ = cg.compute_coverage_verdict(84.4, 85.0, 80.0, "baseline", 0.5)
+    assert ok is False
+    # negative epsilon is clamped to 0 (no negative tolerance)
+    ok, _ = cg.compute_coverage_verdict(84.9, 85.0, 0.0, "baseline", -5.0)
+    assert ok is False
+
+
+# ===========================================================================
+# TC-05 — ratchet baseline (up only; never lowers)
+# ===========================================================================
+def test_tc05_ratchet_up_only():
+    # bootstrap seeds the baseline
+    assert db.get_coverage_baseline(_REPO) is None
+    assert db.ratchet_coverage_baseline(_REPO, 80.0, "sha1") is True
+    assert db.get_coverage_baseline(_REPO) == pytest.approx(80.0)
+    # higher value raises it
+    assert db.ratchet_coverage_baseline(_REPO, 85.0, "sha2") is True
+    assert db.get_coverage_baseline(_REPO) == pytest.approx(85.0)
+    # equal value re-stamps (idempotent, no harm) — baseline unchanged
+    db.ratchet_coverage_baseline(_REPO, 85.0, "sha3")
+    assert db.get_coverage_baseline(_REPO) == pytest.approx(85.0)
+    # LOWER value does NOT lower the baseline
+    assert db.ratchet_coverage_baseline(_REPO, 70.0, "sha4") is False
+    assert db.get_coverage_baseline(_REPO) == pytest.approx(85.0)
+
+
+def test_tc05_ratchet_per_repo_isolated():
+    db.ratchet_coverage_baseline(_REPO, 85.0, "s")
+    db.ratchet_coverage_baseline("enduro-trails", 42.0, "s")
+    assert db.get_coverage_baseline(_REPO) == pytest.approx(85.0)
+    assert db.get_coverage_baseline("enduro-trails") == pytest.approx(42.0)
+
+
+# ===========================================================================
+# TC-06 — bootstrap baseline (first init from main measurement)
+# ===========================================================================
+def test_tc06_bootstrap(monkeypatch, tmp_path):
+    # No baseline yet -> ratchet_baseline_on_merge seeds it from the artefact value.
+    report = (
+        "---\ncoverage_status: PASS\nwork_item: ORCH-027\n"
+        "measured_coverage: 77.50\nbaseline: \nfloor: 0.00\npolicy: both\n"
+        "epsilon: 0.50\ndelta: 0.00\n---\n# body\n"
+    )
+    monkeypatch.setattr(cg, "_report_path", lambda *a, **k: str(tmp_path / "18.md"))
+    (tmp_path / "18.md").write_text(report, encoding="utf-8")
+    assert db.get_coverage_baseline(_REPO) is None
+    assert cg.ratchet_baseline_on_merge(_REPO, _WI, _BRANCH, "sha") is True
+    assert db.get_coverage_baseline(_REPO) == pytest.approx(77.5)
+
+
+# ===========================================================================
+# TC-07 — conditionality applies(repo) (empty scope -> self-hosting only)
+# ===========================================================================
+def test_tc07_applies_self_hosting_only(monkeypatch):
+    monkeypatch.setattr(cfg.settings, "coverage_gate_repos", "", raising=False)
+    assert cg.coverage_gate_applies("orchestrator") is True
+    assert cg.coverage_gate_applies("enduro-trails") is False
+
+
+def test_tc07_applies_csv_scope(monkeypatch):
+    monkeypatch.setattr(cfg.settings, "coverage_gate_repos", "foo, enduro-trails", raising=False)
+    assert cg.coverage_gate_applies("enduro-trails") is True
+    assert cg.coverage_gate_applies("orchestrator") is False
+
+
+def test_tc07_out_of_scope_noop_no_measure(monkeypatch):
+    # Out-of-scope repo -> (True, "...N/A") and the expensive measurer is NOT called.
+    called = {"n": 0}
+    monkeypatch.setattr(cg, "measure_coverage", lambda *a, **k: called.__setitem__("n", called["n"] + 1) or 99.0)
+    ok, reason = cg.check_coverage_gate("enduro-trails", "ET-1", "feature/x")
+    assert ok is True
+    assert "N/A" in reason
+    assert called["n"] == 0
+
+
+# ===========================================================================
+# TC-08 — kill-switch off -> inert (1:1 as before ORCH-027)
+# ===========================================================================
+def test_tc08_kill_switch_off(monkeypatch):
+    monkeypatch.setattr(cfg.settings, "coverage_gate_enabled", False, raising=False)
+    called = {"n": 0}
+    monkeypatch.setattr(cg, "measure_coverage", lambda *a, **k: called.__setitem__("n", called["n"] + 1) or 10.0)
+    ok, reason = cg.check_coverage_gate(_REPO, _WI, _BRANCH)
+    assert ok is True
+    assert "disabled" in reason
+    assert called["n"] == 0
+    assert cg.coverage_gate_applies(_REPO) is False
+
+
+# ===========================================================================
+# TC-09 — fail-open by default on a tool error; fail-closed when configured
+# ===========================================================================
+def test_tc09_fail_open_default(monkeypatch, tmp_path):
+    monkeypatch.setattr(cg, "measure_coverage", lambda *a, **k: None)  # tool error
+    monkeypatch.setattr(cg, "_report_path", lambda *a, **k: str(tmp_path / "18.md"))
+    ok, reason = cg.check_coverage_gate(_REPO, _WI, _BRANCH)
+    assert ok is True
+    assert "fail-open" in reason.lower()
+    # The report records the fail-open PASS.
+    content = (tmp_path / "18.md").read_text(encoding="utf-8")
+    assert "coverage_status: PASS" in content
+
+
+def test_tc09_fail_closed_when_configured(monkeypatch, tmp_path):
+    monkeypatch.setattr(cfg.settings, "coverage_tool_fail_closed", True, raising=False)
+    monkeypatch.setattr(cg, "measure_coverage", lambda *a, **k: None)
+    monkeypatch.setattr(cg, "_report_path", lambda *a, **k: str(tmp_path / "18.md"))
+    ok, reason = cg.check_coverage_gate(_REPO, _WI, _BRANCH)
+    assert ok is False
+    assert "fail-closed" in reason.lower()
+    content = (tmp_path / "18.md").read_text(encoding="utf-8")
+    assert "coverage_status: FAIL" in content
+
+
+# ===========================================================================
+# TC-10 — never-raise (broken inputs / internal error never escape)
+# ===========================================================================
+def test_tc10_verdict_never_raises_on_bad_inputs():
+    ok, reason = cg.compute_coverage_verdict("not-a-number", None, 80.0, "both", 0.5)
+    assert ok is False
+    assert "bad inputs" in reason
+
+
+def test_tc10_parse_coverage_percent_tolerant():
+    assert cg.parse_coverage_percent({"totals": {"percent_covered": 73.2}}) == pytest.approx(73.2)
+    assert cg.parse_coverage_percent({}) is None
+    assert cg.parse_coverage_percent("garbage") is None
+    assert cg.parse_coverage_percent({"totals": {}}) is None
+
+
+def test_tc10_check_never_raises(monkeypatch):
+    # measure_coverage explodes -> the gate swallows it and returns a pair (fail-open).
+    def _boom(*a, **k):
+        raise RuntimeError("coverage exploded")
+    monkeypatch.setattr(cg, "measure_coverage", _boom)
+    ok, reason = cg.check_coverage_gate(_REPO, _WI, _BRANCH)
+    assert isinstance(ok, bool)
+    assert "error (fail-open)" in reason
+
+
+def test_tc10_ratchet_never_raises_on_missing_report(monkeypatch, tmp_path):
+    monkeypatch.setattr(cg, "_report_path", lambda *a, **k: str(tmp_path / "nope.md"))
+    assert cg.ratchet_baseline_on_merge(_REPO, _WI, _BRANCH, "sha") is False
+
+
+# ===========================================================================
+# TC-11 — write/read report; single source of truth via frontmatter
+# ===========================================================================
+def test_tc11_report_roundtrip(tmp_path):
+    fields = {
+        "coverage_status": "PASS",
+        "measured_coverage": 88.25,
+        "baseline": 85.0,
+        "floor": 80.0,
+        "policy": "both",
+        "epsilon": 0.5,
+        "delta": 3.25,
+        "reason": "ok",
+        "measurement": "pytest --cov=src: 88.25%",
+        "policy_detail": "policy=both",
+    }
+    content = cg.render_coverage_report(_WI, fields)
+    # machine key present and parseable
+    ok, verdict = cg.parse_coverage_status(content)
+    assert ok is True
+    assert "PASS" in verdict
+    # measured_coverage read back from the SAME file (ratchet source of truth)
+    assert cg.read_measured_coverage(content) == pytest.approx(88.25)
+
+    # FAIL roundtrip (FAIL token authoritative)
+    fields["coverage_status"] = "FAIL"
+    content = cg.render_coverage_report(_WI, fields)
+    ok, verdict = cg.parse_coverage_status(content)
+    assert ok is False
+    assert "FAIL" in verdict
+
+
+def test_tc11_parse_missing_frontmatter():
+    ok, reason = cg.parse_coverage_status("no frontmatter here")
+    assert ok is False
+    assert "coverage_status" in reason
+    assert cg.read_measured_coverage("no frontmatter") is None
+
+
+def test_tc11_bootstrap_report_blank_baseline():
+    # bootstrap: baseline None -> renders an EMPTY baseline field, still parseable.
+    fields = {
+        "coverage_status": "PASS", "measured_coverage": 50.0, "baseline": None,
+        "floor": 0.0, "policy": "both", "epsilon": 0.5, "delta": 0.0,
+    }
+    content = cg.render_coverage_report(_WI, fields)
+    assert "baseline: \n" in content or "baseline:\n" in content
+    assert cg.parse_coverage_status(content)[0] is True
+
+
+# ===========================================================================
+# TC-12 — self-hosting safety: the leaf imports no engine, touches no prod
+# ===========================================================================
+def test_tc12_leaf_no_engine_import():
+    # AST-based (not prose): the leaf must never IMPORT the engine, and the only
+    # external command it runs is pytest — no docker/compose/force-push literals.
+    import ast
+    import inspect
+    tree = ast.parse(inspect.getsource(cg))
+    imported: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module:
+            imported.add(node.module)
+        elif isinstance(node, ast.Import):
+            for n in node.names:
+                imported.add(n.name)
+    assert not any("stage_engine" in m for m in imported), imported
+    assert not any(("launcher" in m or "self_deploy" in m) for m in imported), imported
+    # No deploy / restart / force-push command tokens used as actual string literals.
+    consts = [
+        n.value for n in ast.walk(tree)
+        if isinstance(n, ast.Constant) and isinstance(n.value, str)
+    ]
+    for forbidden in ("compose", "--force-with-lease", "--force", "docker"):
+        assert forbidden not in consts, f"coverage_gate leaf must not run {forbidden!r}"
+
+
+def test_tc12_delta_signed():
+    assert cg.compute_delta(85.0, 80.0, 70.0) == pytest.approx(5.0)   # vs max(80,70)
+    assert cg.compute_delta(75.0, 80.0, 70.0) == pytest.approx(-5.0)
+    assert cg.compute_delta(50.0, None, None) == pytest.approx(0.0)
+
+
+# ===========================================================================
+# TC-13 — gate integration into advance_stage (rollback on FAIL, retry++)
+# ===========================================================================
+def test_tc13_advance_rolls_back_on_fail(monkeypatch):
+    from src import stage_engine as se
+
+    captured = {}
+
+    def _fake_run_qg(name, repo, wi, branch):
+        captured["qg"] = name
+        return (False, "measured=70.00% policy=both: absolute FAIL")
+
+    monkeypatch.setattr(se, "_run_qg", _fake_run_qg)
+    monkeypatch.setattr(se, "update_task_stage", lambda *a, **k: None)
+    monkeypatch.setattr(se, "notify_stage_change", lambda *a, **k: None)
+    monkeypatch.setattr(se, "plane_notify_stage", lambda *a, **k: None)
+    monkeypatch.setattr(se, "set_issue_in_progress", lambda *a, **k: None)
+    monkeypatch.setattr(se, "notify_qg_failure", lambda *a, **k: None)
+    monkeypatch.setattr(se, "plane_add_comment", lambda *a, **k: None)
+    monkeypatch.setattr(se, "_developer_retry_count", lambda *a, **k: 0)
+    released = {"n": 0}
+    monkeypatch.setattr(se.merge_gate, "release_merge_lease",
+                        lambda *a, **k: released.__setitem__("n", released["n"] + 1))
+    enq = {"n": 0}
+    monkeypatch.setattr(se, "enqueue_job",
+                        lambda *a, **k: enq.__setitem__("n", enq["n"] + 1) or 123)
+
+    result = se.AdvanceResult()
+    intervened = se._handle_coverage_gate(1, "deploy-staging", _REPO, _WI, _BRANCH, "deployer", result)
+    assert intervened is True
+    assert captured["qg"] == "check_coverage_gate"
+    assert result.rolled_back_to == "development"
+    assert result.enqueued_agent == "developer"
+    assert enq["n"] == 1
+    # merge lease released on the coverage rollback (ADR-001 D1/TR-2)
+    assert released["n"] == 1
+
+
+def test_tc13_advance_passes_through_on_ok(monkeypatch):
+    from src import stage_engine as se
+    monkeypatch.setattr(se, "_run_qg", lambda *a, **k: (True, "coverage OK"))
+    result = se.AdvanceResult()
+    intervened = se._handle_coverage_gate(1, "deploy-staging", _REPO, _WI, _BRANCH, "deployer", result)
+    assert intervened is False
+    assert result.rolled_back_to is None
+
+
+# ===========================================================================
+# TC-14 — real measurement on a minimal fixture repo (pytest --cov in worktree)
+# ===========================================================================
+def test_tc14_real_measurement(tmp_path, monkeypatch):
+    # Build a minimal project: src/ with one function, tests covering part of it.
+    proj = tmp_path / "fixture_repo"
+    (proj / "src").mkdir(parents=True)
+    (proj / "tests").mkdir()
+    (proj / "src" / "__init__.py").write_text("", encoding="utf-8")
+    (proj / "src" / "mod.py").write_text(
+        "def covered():\n    return 1\n\n\ndef uncovered():\n    return 2\n",
+        encoding="utf-8",
+    )
+    (proj / "tests" / "test_mod.py").write_text(
+        "from src.mod import covered\n\n\ndef test_covered():\n    assert covered() == 1\n",
+        encoding="utf-8",
+    )
+    # Point the measurer's worktree resolution at our fixture.
+    monkeypatch.setattr(cg, "ensure_worktree", lambda repo, branch: str(proj))
+    pct = cg.measure_coverage(_REPO, _BRANCH)
+    assert pct is not None
+    # mod.py: 4 statements, uncovered() body (1) unrun -> ~75%; bounds-check only.
+    assert 50.0 <= pct <= 90.0
+    # the scratch json is cleaned up
+    assert not (proj / ".coverage-report.json").exists()
+
+
+def test_tc14_measure_timeout_returns_none(monkeypatch):
+    import subprocess
+    monkeypatch.setattr(cg, "ensure_worktree", lambda r, b: "/tmp")
+
+    def _timeout(*a, **k):
+        raise subprocess.TimeoutExpired(cmd="pytest", timeout=1)
+    monkeypatch.setattr(cg.subprocess, "run", _timeout)
+    assert cg.measure_coverage(_REPO, _BRANCH) is None
+
+
+# ===========================================================================
+# TC-15 — observability (snapshot block) + registry compatibility unchanged
+# ===========================================================================
+def test_tc15_snapshot_shape(monkeypatch):
+    db.ratchet_coverage_baseline(_REPO, 81.0, "sha")
+    snap = cg.snapshot()
+    assert snap["enabled"] is True
+    assert snap["policy"] == "both"
+    assert snap["floor"] == pytest.approx(80.0)
+    assert "baselines" in snap
+    assert _REPO in snap["baselines"]
+    assert snap["baselines"][_REPO]["coverage"] == pytest.approx(81.0)
+
+
+def test_tc15_snapshot_never_raises(monkeypatch):
+    monkeypatch.setattr(db, "all_coverage_baselines", lambda: (_ for _ in ()).throw(RuntimeError("boom")))
+    snap = cg.snapshot()
+    assert snap["enabled"] is True
+    assert snap["baselines"] == {}
+
+
+def test_tc15_registry_and_transitions_unchanged():
+    from src.qg.checks import QG_CHECKS
+    from src.stages import STAGE_TRANSITIONS
+    # new check registered...
+    assert "check_coverage_gate" in QG_CHECKS
+    # ...without touching the existing verdict checks (byte-for-byte names present)
+    for name in (
+        "check_ci_green", "check_tests_passed", "check_security_gate",
+        "check_staging_status", "check_staging_image_fresh", "check_branch_mergeable",
+    ):
+        assert name in QG_CHECKS
+    # coverage is an edge sub-gate, NOT a STAGE_TRANSITIONS edge
+    for _stage, spec in STAGE_TRANSITIONS.items():
+        assert "check_coverage_gate" not in str(spec)

tests/test_metrics.py

@@ -0,0 +1,295 @@
+"""ORCH-099 (FND/F1a) — read-only GET /metrics raw-signal endpoint.
+
+Covers the four-section envelope (TC-01..TC-04/TC-08/TC-11), never-raise by
+section/field (TC-05/TC-07), the cost aggregate (TC-06), read-only invariant
+(TC-09), and additivity vs /health//status//queue (TC-10).
+
+Pattern mirrors tests/test_queue_endpoint.py: the async handler is driven via
+asyncio.run(main.metrics()); the autouse conftest mutes Telegram; a per-test
+fresh_db points settings.db_path at a tmp file + init_db.
+"""
+import asyncio
+import os
+
+import pytest
+
+import src.db as db  # noqa: E402
+from src.db import get_db, init_db  # noqa: E402
+from src import config as cfg  # noqa: E402
+from src import metrics as metrics_mod  # noqa: E402
+
+
+@pytest.fixture(autouse=True)
+def fresh_db(tmp_path, monkeypatch):
+    dbfile = tmp_path / "metrics.db"
+    monkeypatch.setattr(db.settings, "db_path", str(dbfile))
+    monkeypatch.setattr(cfg.settings, "metrics_endpoint_enabled", True, raising=False)
+    init_db()
+    yield
+
+
+# --- helpers ---------------------------------------------------------------
+def _make_task(work_item_id="ORCH-1", repo="orchestrator",
+               branch="feature/x", stage="development"):
+    conn = get_db()
+    cur = conn.execute(
+        "INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage) "
+        "VALUES (?, ?, ?, ?, ?)",
+        (work_item_id, work_item_id, repo, branch, stage),
+    )
+    tid = cur.lastrowid
+    conn.commit()
+    conn.close()
+    return tid
+
+
+def _make_agent_run(agent="developer", task_id=None, model="claude-opus-4-8",
+                    effort="xhigh", cost_usd=None, input_tokens=None,
+                    output_tokens=None, cache_read_tokens=None,
+                    cache_creation_tokens=None, finished=False):
+    conn = get_db()
+    cur = conn.execute(
+        "INSERT INTO agent_runs (task_id, agent, model, effort, cost_usd, "
+        "input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, "
+        "finished_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, "
+        + ("datetime('now')" if finished else "NULL") + ")",
+        (task_id, agent, model, effort, cost_usd, input_tokens, output_tokens,
+         cache_read_tokens, cache_creation_tokens),
+    )
+    rid = cur.lastrowid
+    conn.commit()
+    conn.close()
+    return rid
+
+
+def _make_running_job(agent="developer", repo="orchestrator", task_id=None,
+                      pid=None, run_id=None, age_s=0, attempts=0, max_attempts=2):
+    conn = get_db()
+    cur = conn.execute(
+        "INSERT INTO jobs (agent, repo, task_id, status, attempts, max_attempts, "
+        "run_id, pid, started_at) "
+        "VALUES (?, ?, ?, 'running', ?, ?, ?, ?, datetime('now', ?))",
+        (agent, repo, task_id, attempts, max_attempts, run_id, pid,
+         f"-{int(age_s)} seconds"),
+    )
+    job_id = cur.lastrowid
+    conn.commit()
+    conn.close()
+    return job_id
+
+
+def _db_snapshot():
+    """Full row snapshot of the mutable tables for the read-only assertion."""
+    conn = get_db()
+    snap = {}
+    for table in ("tasks", "jobs", "agent_runs"):
+        rows = conn.execute(f"SELECT * FROM {table} ORDER BY id").fetchall()
+        snap[table] = [dict(r) for r in rows]
+    conn.close()
+    return snap
+
+
+# --- TC-01: envelope keys --------------------------------------------------
+def test_tc01_envelope_has_all_sections():
+    m = metrics_mod.build_metrics()
+    assert isinstance(m, dict)
+    for key in ("schema_version", "generated_at", "stages", "queue", "agents", "cost"):
+        assert key in m, f"missing envelope key {key!r}"
+    assert m["schema_version"] == 1
+    assert isinstance(m["stages"], list)
+    assert isinstance(m["agents"], list)
+    assert isinstance(m["queue"], dict)
+    assert isinstance(m["cost"], dict)
+
+
+# --- TC-02: stages section + terminal exclusion ----------------------------
+def test_tc02_stages_active_only_with_fields():
+    _make_task(work_item_id="ORCH-10", stage="development", repo="orchestrator")
+    _make_task(work_item_id="ORCH-11", stage="done")            # terminal -> excluded
+    _make_task(work_item_id="ORCH-12", stage="cancelled")       # terminal -> excluded
+
+    stages = metrics_mod.build_metrics()["stages"]
+    wis = {s["work_item"] for s in stages}
+    assert "ORCH-10" in wis
+    assert "ORCH-11" not in wis
+    assert "ORCH-12" not in wis
+
+    item = next(s for s in stages if s["work_item"] == "ORCH-10")
+    assert item["stage"] == "development"
+    assert item["repo"] == "orchestrator"
+    assert isinstance(item["age_in_stage_s"], int)
+
+
+# --- TC-03: queue section --------------------------------------------------
+def test_tc03_queue_section_fields():
+    q = metrics_mod.build_metrics()["queue"]
+    assert "counts" in q
+    counts = q["counts"]
+    for k in ("queued", "running", "failed", "cancelled"):
+        assert k in counts
+    assert q["max_concurrency"] is not None
+    assert "retries" in q and isinstance(q["retries"], dict)
+    assert "in_backoff" in q["retries"]
+    # breaker snapshot present (worker is the module singleton, initialised)
+    assert q["breaker"] is not None
+    for k in ("state", "consecutive_transient", "pause_remaining_s"):
+        assert k in q["breaker"]
+
+
+# --- TC-04: agents liveness section ----------------------------------------
+def test_tc04_agents_liveness_fields():
+    tid = _make_task(work_item_id="ORCH-20")
+    rid = _make_agent_run(task_id=tid, model="claude-opus-4-8", effort="xhigh")
+    # use our own (alive) pid so cpu_ticks is a real integer
+    _make_running_job(task_id=tid, pid=os.getpid(), run_id=rid, age_s=5)
+
+    agents = metrics_mod.build_metrics()["agents"]
+    assert len(agents) == 1
+    a = agents[0]
+    for k in ("agent", "run_id", "job_id", "pid", "runtime_s", "model", "effort", "cpu_ticks"):
+        assert k in a, f"agent entry missing {k!r}"
+    assert a["agent"] == "developer"
+    assert a["run_id"] == rid
+    assert a["pid"] == os.getpid()
+    assert isinstance(a["runtime_s"], int)
+    # alive pid -> real cpu ticks (int), basis present at envelope level
+    assert isinstance(a["cpu_ticks"], int)
+    assert metrics_mod.build_metrics()["clk_tck"] is not None
+
+
+# --- TC-05: agent-liveness never-raise on dead/None pid --------------------
+def test_tc05_dead_or_none_pid_cpu_ticks_null():
+    tid = _make_task(work_item_id="ORCH-21")
+    rid = _make_agent_run(task_id=tid)
+    # pid=None -> cpu_ticks null; a very-unlikely-live pid -> /proc absent -> null
+    _make_running_job(task_id=tid, pid=None, run_id=rid)
+    _make_running_job(task_id=tid, pid=999999, run_id=rid)
+
+    m = metrics_mod.build_metrics()
+    agents = m["agents"]
+    assert len(agents) == 2
+    for a in agents:
+        assert a["cpu_ticks"] is None      # field degraded, not an exception
+        assert a["agent"] == "developer"   # other fields intact
+    # whole envelope still valid
+    assert m["schema_version"] == 1
+
+
+def test_tc05_read_cpu_ticks_helper_none_paths():
+    assert metrics_mod._read_cpu_ticks(None) is None
+    assert metrics_mod._read_cpu_ticks(999999) is None
+    # alive pid (this process) -> int
+    assert isinstance(metrics_mod._read_cpu_ticks(os.getpid()), int)
+
+
+# --- TC-06: cost aggregate -------------------------------------------------
+def test_tc06_cost_aggregate_sums_and_empty_zeros():
+    # empty agent_runs -> zeros, not error
+    agg0 = metrics_mod.build_metrics()["cost"]["aggregate"]
+    for k in ("cost_usd", "input_tokens", "output_tokens",
+              "cache_read_tokens", "cache_creation_tokens"):
+        assert agg0[k] == 0
+
+    tid = _make_task(work_item_id="ORCH-30")
+    _make_agent_run(task_id=tid, cost_usd=1.5, input_tokens=100, output_tokens=20,
+                    cache_read_tokens=5, cache_creation_tokens=7, finished=True)
+    _make_agent_run(task_id=tid, cost_usd=2.5, input_tokens=200, output_tokens=30,
+                    cache_read_tokens=10, cache_creation_tokens=3, finished=True)
+
+    agg = metrics_mod.build_metrics()["cost"]["aggregate"]
+    assert agg["cost_usd"] == 4.0
+    assert agg["input_tokens"] == 300
+    assert agg["output_tokens"] == 50
+    assert agg["cache_read_tokens"] == 15
+    assert agg["cache_creation_tokens"] == 10
+
+
+# --- TC-07: never-raise when a section source throws -----------------------
+def test_tc07_section_source_throws_degrades_not_500(monkeypatch):
+    def _boom(*a, **k):
+        raise RuntimeError("simulated source failure")
+
+    # queue counts source throws -> queue.counts null, build_metrics still returns
+    monkeypatch.setattr(db, "job_status_counts", _boom)
+    # cost aggregate source throws -> cost.aggregate null
+    monkeypatch.setattr(db, "agent_cost_totals", _boom)
+    # stages source throws -> stages []
+    monkeypatch.setattr(db, "get_active_tasks_for_reconcile", _boom)
+
+    m = metrics_mod.build_metrics()
+    assert m["schema_version"] == 1            # never raised
+    assert m["stages"] == []
+    assert m["queue"]["counts"] is None
+    assert m["cost"]["aggregate"] is None
+
+
+def test_tc07_breaker_unavailable_is_null(monkeypatch):
+    from src import queue_worker
+    # simulate an uninitialised / broken worker breaker
+    monkeypatch.setattr(queue_worker.worker.breaker, "snapshot",
+                        lambda: (_ for _ in ()).throw(RuntimeError("no breaker")))
+    q = metrics_mod.build_metrics()["queue"]
+    assert q["breaker"] is None                # null, not 500
+
+
+# --- TC-08: GET /metrics via handler returns valid JSON --------------------
+def test_tc08_endpoint_returns_full_payload():
+    tid = _make_task(work_item_id="ORCH-40")
+    rid = _make_agent_run(task_id=tid)
+    _make_running_job(task_id=tid, pid=os.getpid(), run_id=rid)
+
+    from src import main
+    payload = asyncio.run(main.metrics())
+    assert payload["schema_version"] == 1
+    assert isinstance(payload["stages"], list) and len(payload["stages"]) == 1
+    assert isinstance(payload["agents"], list) and len(payload["agents"]) == 1
+    assert "aggregate" in payload["cost"]
+    assert "counts" in payload["queue"]
+
+
+def test_tc08_kill_switch_minimal_body(monkeypatch):
+    monkeypatch.setattr(cfg.settings, "metrics_endpoint_enabled", False, raising=False)
+    from src import main
+    payload = asyncio.run(main.metrics())
+    assert payload == {"schema_version": 1, "enabled": False}
+
+
+# --- TC-09: read-only invariant --------------------------------------------
+def test_tc09_metrics_is_read_only():
+    tid = _make_task(work_item_id="ORCH-50")
+    rid = _make_agent_run(task_id=tid, cost_usd=1.0, input_tokens=10)
+    _make_running_job(task_id=tid, pid=os.getpid(), run_id=rid)
+
+    from src import main
+    before = _db_snapshot()
+    asyncio.run(main.metrics())
+    asyncio.run(main.metrics())   # repeat: state must not change
+    after = _db_snapshot()
+    assert before == after, "/metrics must not mutate any DB state"
+
+
+# --- TC-10: additivity vs existing endpoints -------------------------------
+def test_tc10_existing_endpoints_intact():
+    from src import main
+    health = asyncio.run(main.health())
+    assert health["status"] == "ok"
+
+    status = asyncio.run(main.status())
+    assert "active_tasks" in status
+
+    queue = asyncio.run(main.queue())
+    for key in ("counts", "max_concurrency", "poll_interval", "resilience",
+                "reconcile", "reaper", "serial_gate", "recent"):
+        assert key in queue, f"/queue lost existing key {key!r}"
+
+
+# --- TC-11: empty state is valid -------------------------------------------
+def test_tc11_empty_state_valid():
+    m = metrics_mod.build_metrics()
+    assert m["stages"] == []
+    assert m["agents"] == []
+    assert m["cost"]["running"] == []
+    agg = m["cost"]["aggregate"]
+    assert all(agg[k] == 0 for k in agg)
+    counts = m["queue"]["counts"]
+    assert counts["queued"] == 0 and counts["running"] == 0

tests/test_plane_status_model.py

@@ -141,6 +141,7 @@ def test_tc23_qg_checks_registry_unchanged():
         "check_reviewer_verdict", "check_tests_local", "check_deploy_status",
         "check_staging_status", "check_branch_mergeable", "check_staging_image_fresh",
         "check_security_gate",  # ORCH-022 integ: security-gate registered
+        "check_coverage_gate",  # ORCH-027 integ: coverage-gate registered
     }
 
 

tests/test_qg_registry_snapshot.py

@@ -31,6 +31,7 @@ _EXPECTED_QGS = {
     "check_branch_mergeable",  # ORCH-043 merge-gate (deploy-staging -> deploy edge)
     "check_staging_image_fresh",  # ORCH-058 image-freshness sub-gate (same edge)
     "check_security_gate",  # ORCH-022 security sub-gate (same edge, run FIRST)
+    "check_coverage_gate",  # ORCH-027 coverage sub-gate (same edge, after merge-gate)
 }
 
 

tests/test_stage_engine.py

@@ -833,6 +833,7 @@ class TestMergeGate:
             {**stage_engine.QG_CHECKS,
              "check_staging_status": _pass,
              "check_security_gate": _pass,
+             "check_coverage_gate": _pass,
              "check_branch_mergeable": _pass,
              "check_staging_image_fresh": _pass},
         )
@@ -858,6 +859,7 @@ class TestMergeGate:
             {**stage_engine.QG_CHECKS,
              "check_staging_status": _pass,
              "check_security_gate": _pass,
+             "check_coverage_gate": _pass,
              "check_branch_mergeable": _fail("merge-lock busy")},
         )
         monkeypatch.setattr(stage_engine.settings, "merge_defer_delay_s", 30)
@@ -886,6 +888,7 @@ class TestMergeGate:
             {**stage_engine.QG_CHECKS,
              "check_staging_status": _pass,
              "check_security_gate": _pass,
+             "check_coverage_gate": _pass,
              "check_branch_mergeable": _fail("merge-lock busy")},
         )
         monkeypatch.setattr(stage_engine.settings, "merge_defer_max_attempts", 3)
@@ -920,6 +923,7 @@ class TestMergeGate:
             {**stage_engine.QG_CHECKS,
              "check_staging_status": _pass,
              "check_security_gate": _pass,
+             "check_coverage_gate": _pass,
              "check_branch_mergeable": _fail("rebase conflict: src/db.py")},
         )
         task_id = _make_task("deploy-staging", repo="orchestrator", wi="ORCH-043",
@@ -944,6 +948,7 @@ class TestMergeGate:
             {**stage_engine.QG_CHECKS,
              "check_staging_status": _pass,
              "check_security_gate": _pass,
+             "check_coverage_gate": _pass,
              "check_branch_mergeable": _fail("re-test failed after rebase: 1 failed")},
         )
         task_id = _make_task("deploy-staging", repo="orchestrator", wi="ORCH-043",
@@ -968,6 +973,7 @@ class TestMergeGate:
             {**stage_engine.QG_CHECKS,
              "check_staging_status": _pass,
              "check_security_gate": _pass,
+             "check_coverage_gate": _pass,
              "check_branch_mergeable": _fail("rebase conflict: src/db.py")},
         )
         task_id = _make_task("deploy-staging", repo="orchestrator", wi="ORCH-043",
@@ -1021,6 +1027,7 @@ class TestImageFreshnessGate:
             {**stage_engine.QG_CHECKS,
              "check_staging_status": _pass,
              "check_security_gate": _pass,
+             "check_coverage_gate": _pass,
              "check_branch_mergeable": _pass,
              "check_staging_image_fresh": _fail(
                  "staging rebuild failed: health FAILED")},
@@ -1049,6 +1056,7 @@ class TestImageFreshnessGate:
             {**stage_engine.QG_CHECKS,
              "check_staging_status": _pass,
              "check_security_gate": _pass,
+             "check_coverage_gate": _pass,
              "check_branch_mergeable": _pass,
              "check_staging_image_fresh": _fail("provenance mismatch")},
         )
@@ -1073,6 +1081,7 @@ class TestImageFreshnessGate:
             {**stage_engine.QG_CHECKS,
              "check_staging_status": _pass,
              "check_security_gate": _pass,
+             "check_coverage_gate": _pass,
              "check_branch_mergeable": _pass,
              "check_staging_image_fresh": _pass},
         )
@@ -1099,6 +1108,7 @@ class TestImageFreshnessGate:
             {**stage_engine.QG_CHECKS,
              "check_staging_status": _pass,
              "check_security_gate": _pass,
+             "check_coverage_gate": _pass,
              "check_branch_mergeable": _pass},
         )  # check_staging_image_fresh left REAL -> N/A for enduro-trails
         task_id = _make_task("deploy-staging", repo="enduro-trails", wi="ET-099",
@@ -1171,6 +1181,7 @@ class TestStagingInfraTolerance:
             {**stage_engine.QG_CHECKS,
              "check_staging_status": _pass,
              "check_security_gate": _pass,
+             "check_coverage_gate": _pass,
              "check_branch_mergeable": _pass,
              "check_staging_image_fresh": _pass},
         )
@@ -1244,6 +1255,7 @@ class TestStagingInfraTolerance:
             {**stage_engine.QG_CHECKS,
              "check_staging_status": _pass,
              "check_security_gate": _pass,
+             "check_coverage_gate": _pass,
              "check_branch_mergeable": _pass,
              "check_staging_image_fresh": _pass,
              "check_deploy_status": _pass},

tests/test_stages_invariants.py

@@ -27,6 +27,7 @@ _EXPECTED_QGS = {
     "check_branch_mergeable",
     "check_staging_image_fresh",
     "check_security_gate",
+    "check_coverage_gate",
 }
 
 _EXPECTED_TRANSITIONS = {