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

docs/architecture/README.md

@@ -35,7 +35,7 @@ created → analysis → architecture → development → review → testing →
 | deploy | — | `check_deploy_status` | 14-deploy-log.md (`deploy_status:`) |
 | done | — | — | — |
 
-**Реестр QG** (`QG_CHECKS`): check_analysis_approved, check_analysis_complete, check_architecture_done, check_ci_green, check_review_approved, check_tests_passed, check_reviewer_verdict, check_tests_local, check_deploy_status, check_staging_status, check_branch_mergeable (ORCH-043).
+**Реестр QG** (`QG_CHECKS`): check_analysis_approved, check_analysis_complete, check_architecture_done, check_ci_green, check_review_approved, check_tests_passed, check_reviewer_verdict, check_tests_local, check_deploy_status, check_staging_status, check_branch_mergeable (ORCH-043), check_staging_image_fresh (ORCH-058).
 
 **Канон гейтов:** машинные вердикты читаются ТОЛЬКО из YAML-frontmatter, никогда из прозы. Лог-файлы мержатся в `origin/main` отдельным PR; гейт читает из `origin/main`.
 
@@ -80,6 +80,34 @@ terminal-sync, merge-gate, exit-code-контракт хука. Restart-safe с
 sentinel-файлы (`<repos_dir>/.deploy-state-<repo>/<wi>/`), без миграции БД.
 Подробнее: [adr-0007](adr/adr-0007-executable-self-deploy.md), детально —
 `docs/work-items/ORCH-036/06-adr/ADR-001-executable-self-deploy.md`.
+
+### Свежесть артефакта BUILD-ONCE: провенанс staging-образа (ORCH-058 — design)
+BUILD-ONCE retag (ORCH-36) промоутит `SOURCE_IMAGE=orchestrator-orchestrator-staging` в прод
+**без rebuild**, полагаясь на «staging-образ свеж и провалидирован». Этой гарантии нет:
+конвейер нигде не пересобирает staging-образ из провалидированного коммита → retag мог тихо
+промоутнуть УСТАРЕВШИЙ образ (инцидент LESSONS_ORCH-036 п.4 — зелёный деплой молча
+откатывал прод). ORCH-058 обеспечивает инвариант `INV-FRESH` **двумя слоями** (defense in
+depth), только для self-hosting:
+- **A — пересборка (liveness):** детерминированный QG-под-чек `check_staging_image_fresh` на
+  ребре `deploy-staging → deploy` ПОСЛЕ merge-gate и ДО Phase A пересобирает
+  `orchestrator-orchestrator-staging` из worktree валидированного коммита
+  (`--build-arg GIT_SHA=<sha>`, OCI-лейбл `org.opencontainers.image.revision`), пересоздаёт
+  8501 и прогоняет `staging_check` против свежего образа → валидируем и промоутим один
+  артефакт. FAIL → откат на `development` (как merge-gate). Сборки/recreate — ТОЛЬКО staging.
+- **B — fail-closed guard (safety):** хук шагом 2b ПЕРЕД `docker tag` сверяет лейбл `revision`
+  у `SOURCE_IMAGE` с `EXPECTED_REVISION` (пробрасывает `build_deploy_command`). Несовпадение
+  / пустой лейбл / пустой ожидаемый SHA / ошибка inspect → `exit 1` → FAILED (БАГ-8 откат),
+  прод не трогается. Делает тихий промоут устаревшего образа структурно невозможным даже при
+  отключённой/проигравшей гонку A.
+
+Якорь «провалидированного коммита» — `git rev-parse HEAD` worktree ПОСЛЕ merge-gate (один
+helper `validated_revision` питает и штамп A, и `EXPECTED_REVISION` B). Единый kill-switch
+`image_freshness_enabled` включает A+B **как целое** (нет «B без A» = вечного fail-fast);
+`image_freshness_repos` (пусто → self-hosting). `STAGE_TRANSITIONS`, exit-code хука (0/1/2),
+`check_deploy_status`, БАГ-8, merge-gate, схема БД — НЕ меняются (под-гейт ребра + лейбл
+образа, без миграций). Подробнее: [adr-0008](adr/adr-0008-staging-image-provenance.md),
+детально — `docs/work-items/ORCH-058/06-adr/ADR-001-staging-image-provenance.md`.
+
 ### Reconciler: реконсиляция потерянных webhook (ORCH-053 — реализовано)
 Конвейер продвигается только входящими webhook; потерянное событие (502 на ребилде,
 нет ретраев у Plane/Gitea, неразрезолвленный `sha→branch`) → задача застревает молча
@@ -168,3 +196,4 @@ never-raise на единицу работы; тишина при синхрон
 ---
 *Актуально на 2026-06-06. Обновлять при изменении src/stages.py, src/qg/checks.py, src/main.py. ORCH-043: merge-gate — design (см. adr-0006), реализация в ветке feature/ORCH-043. ORCH-036: исполняемый самодеплой стадии `deploy` — design (см. adr-0007), реализация в ветке feature/ORCH-036.*
 *Актуально на 2026-06-06. Обновлять при изменении src/stages.py, src/qg/checks.py, src/main.py. ORCH-043: merge-gate — design (см. adr-0006), реализация в ветке feature/ORCH-043. ORCH-053: reconciler — реализовано (см. adr-0007, src/reconciler.py).*
+*ORCH-058: провенанс staging-образа перед BUILD-ONCE retag (check_staging_image_fresh + хук-guard) — design (см. adr-0008), реализация в ветке feature/ORCH-058. Обновлять также при изменении src/self_deploy.py, scripts/orchestrator-deploy-hook.sh, Dockerfile.*

docs/architecture/adr/adr-0008-staging-image-provenance.md

@@ -0,0 +1,77 @@
+# ADR-0008: Провенанс staging-образа перед BUILD-ONCE retag в прод (ORCH-058)
+
+## Статус
+Accepted (design) — реализация в ветке `feature/ORCH-058-self-deploy-retag-staging`.
+Метка: `arch:major-change`.
+
+> Примечание о нумерации: в `adr/` исторически два файла `adr-0007-*`
+> (`executable-self-deploy`, `reconciler`) — пред-существующая коллизия. Этот ADR берёт
+> следующий свободный номер **0008**; коллизию 0007 не трогаем (вне объёма ORCH-058).
+
+## Контекст
+
+ORCH-36 (`adr-0007-executable-self-deploy`) сделал стадию `deploy` исполняемой для
+self-hosting: Phase B запускает host-хук, который шагом **2b** (BUILD-ONCE) делает
+`docker tag $SOURCE_IMAGE → $TARGET_IMAGE` **без rebuild** — «прод = ровно тот артефакт,
+что прошёл staging». Предпосылка: staging-образ свеж и собран из провалидированного кода.
+
+**Этой гарантии нет.** Конвейер нигде не пересобирает `orchestrator-orchestrator-staging`
+из провалидированного коммита; `deploy-staging` лишь гоняет `staging_check.py` против уже
+работающего 8501. Инцидент (LESSONS_ORCH-036 п.4): staging-образ не пересобрали → проверка
+прошла против старого кода → retag промоутнул СТАРЫЙ образ → прод **молча** откатился на
+2-дневный код. Зелёный гейт = ложный позитив. Самый опасный из 4 багов: не падает, а тихо
+откатывает инструмент, обслуживающий все проекты.
+
+## Решение
+
+Гарантировать `INV-FRESH`: в прод промоутится только образ, собранный из коммита,
+провалидированного `deploy-staging` для данной задачи; иначе fail-fast (`FAILED` → откат на
+`development`, БАГ-8), прод не трогается. Достигается **двумя взаимодополняющими слоями**
+(defense in depth), только для self-hosting (условность как ORCH-35/36/43):
+
+- **A — пересборка (liveness).** На ребре `deploy-staging → deploy`, ПОСЛЕ merge-gate и ДО
+  Phase A, детерминированный QG-под-чек `check_staging_image_fresh` пересобирает
+  `orchestrator-orchestrator-staging` из worktree валидированного коммита
+  (`--build-arg GIT_SHA=<sha>`, лейбл `org.opencontainers.image.revision`), пересоздаёт 8501
+  и прогоняет `staging_check`. FAIL → откат на `development`. Так валидируемый и промоутимый
+  артефакт — один и тот же; гарантирует наличие зелёного пути (нет вечного fail-fast).
+- **B — fail-closed guard (safety).** Хук шагом 2b ПЕРЕД `docker tag` сверяет лейбл
+  `revision` образа `SOURCE_IMAGE` с `EXPECTED_REVISION` (пробрасывает `build_deploy_command`).
+  Несовпадение / пустой лейбл / пустой ожидаемый SHA / ошибка inspect → `exit 1` → FAILED.
+  Делает тихий промоут устаревшего образа структурно невозможным даже при отключённой/
+  проигравшей гонку A.
+
+**Якорь провалидированного коммита** — `git rev-parse HEAD` в worktree ПОСЛЕ merge-gate
+(post-rebase tree, который ре-тестирован и сольётся в `main`). Один helper
+`validated_revision(repo, branch)` питает и штамп сборки (A), и `EXPECTED_REVISION` (B).
+
+**Условность и kill-switch:** единый `image_freshness_enabled` (вкл/выкл A+B как целое,
+чтобы не было «B без A» = вечный fail-fast), `image_freshness_repos` (CSV; пусто →
+self-hosting). Все настройки с префиксом `ORCH_`.
+
+### Что НЕ меняется
+`STAGE_TRANSITIONS` (набор стадий — под-гейт ребра, не стадия), exit-code хука (0/1/2),
+`map_exit_code_to_status`, `check_deploy_status`/`_parse_deploy_status`, БАГ-8, terminal-sync,
+merge-gate, Phase A/B/C. Схема БД — без миграций (провенанс в лейбле образа, не в БД).
+
+### Что добавляется (сквозное)
+- QG `check_staging_image_fresh` в реестре `QG_CHECKS` (+ snapshot-тест), wired через
+  `_handle_image_freshness` в `stage_engine` (рядом с merge-gate).
+- Режим хука `--build-staging` (build из worktree + recreate 8501; STAGING-safe дефолты).
+- OCI-лейбл `org.opencontainers.image.revision` в `Dockerfile` (`ARG GIT_SHA`).
+- Helpers `validated_revision` / `rebuild_staging_image` в `self_deploy.py` (never-raise).
+
+## Последствия
+
+- Класс «тихого регресса прод» закрыт структурно (B); валидный деплой всегда доходит до
+  зелёного (A) — устранён ручной bootstrap-разрыв пересборки staging.
+- Латентность ребра растёт (build + recreate + повторный staging_check); `staging_check`
+  гоняется дважды (soft pre-check агента + авторитетный код) — плата за «валидируем =
+  промоутим».
+- Все сборки/recreate — ТОЛЬКО staging (8501); прод (8500) не трогается; `main` не пушится.
+  Новая под-компонента → `arch:major-change`.
+
+## Связанные ADR
+`adr-0007-executable-self-deploy` (BUILD-ONCE, Phase A/B/C), `adr-0006-merge-gate` (образец
+edge-под-гейта), `adr-0003-staging-gate` (условность self-hosting), `adr-0005`
+(run-as-host-uid). Детальный per-work-item: `docs/work-items/ORCH-058/06-adr/ADR-001-staging-image-provenance.md`.