architect(ET): auto-commit from architect run_id=542

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-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/`, отдельная задача).