Compare commits

...

53 Commits

Author SHA1 Message Date
753eea37fc deployer(ET): auto-commit from deployer run_id=172
All checks were successful
CI / test (push) Successful in 13s
CI / test (pull_request) Successful in 12s
2026-06-06 10:20:02 +00:00
6ef28efccd tester(ET): auto-commit from tester run_id=171
All checks were successful
CI / test (push) Successful in 14s
CI / test (pull_request) Successful in 12s
2026-06-06 10:17:45 +00:00
52cfe51bd8 reviewer(ET): auto-commit from reviewer run_id=170
All checks were successful
CI / test (push) Successful in 12s
CI / test (pull_request) Successful in 12s
2026-06-06 10:16:31 +00:00
05c17135c1 feat(notifications): add bump mode + russify Telegram live-tracker
All checks were successful
CI / test (push) Successful in 13s
CI / test (pull_request) Successful in 13s
ORCH-042: new ORCH_TRACKER_MODE (Settings.tracker_mode, default edit) selects
the live-tracker card behaviour. bump mode re-creates the card at the bottom of
the chat on every update (delete_telegram + send silently + repoint message_id),
keeping the "one card per task" invariant: <=1 new message per call, repoint
only on successful send, delete result never gates the send. New never-raising
delete_telegram helper. Anything != "bump" resolves to edit (zero regression).

Also russify/cosmetic-fix the card text (both modes): "Подтверждение BRD" label,
 after approve-gate, Russian stage labels, "📦 Внедрено". Docs updated in the
same PR (CHANGELOG, internals.md, .env.example).

Refs: ORCH-042

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-06 10:13:49 +00:00
0ac50b8c73 architect(ET): auto-commit from architect run_id=168
All checks were successful
CI / test (push) Successful in 12s
2026-06-06 10:05:26 +00:00
66100855f6 analyst(ET): auto-commit from analyst run_id=167
All checks were successful
CI / test (push) Successful in 15s
2026-06-06 09:49:58 +00:00
3f23897327 docs: init ORCH-042 business request
All checks were successful
CI / test (push) Successful in 13s
2026-06-06 12:27:13 +03:00
ed10f28879 docs(ORCH-044): add deploy log (deploy_status: SUCCESS)
Some checks failed
CI / test (push) Has been cancelled
Artifact-only production deploy verdict for ORCH-044. All gates green
(review APPROVED, tests PASS, staging SUCCESS 10/10). src/ runtime
changed → real rebuild+restart of prod orchestrator (8500) delegated to
Owner-run deploy hook (ORCH-36); prod container not touched by agent.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-06 08:45:08 +00:00
45480966c1 Merge pull request '#51' staging-log/ORCH-044 into main 2026-06-06 11:42:58 +03:00
a662eeb2a1 docs(ORCH-044): staging gate log — SUCCESS (10/10, B6 registry isolation PASS)
All checks were successful
CI / test (pull_request) Successful in 15s
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-06 08:42:47 +00:00
507c225175 Merge pull request 'docs(history): LESSONS_ORCH-048' (#49) from docs/lessons-orch-048 into main
Some checks failed
CI / test (push) Has been cancelled
2026-06-06 10:30:51 +03:00
a8221f01c8 docs(history): LESSONS_ORCH-048 — staging B6 isolation, variant (v), chicken-egg lesson
All checks were successful
CI / test (pull_request) Successful in 12s
2026-06-06 10:30:50 +03:00
2a36ed80b9 fix(staging_check): ORCH-048 B6 reads registry inside staging container (variant v)
ADR-001 in-container run; removes host-path hack; _evaluate_b6 pure fn; deployer.md+STAGING_CHECK.md updated. Staging 10/10 PASS incl B6.
2026-06-06 10:24:10 +03:00
3f1f3fc73b Merge pull request 'docs(ORCH-048): prod deploy log — SUCCESS (bind-mount-only, prod untouched)' (#48) from deploy-log/ORCH-048-20260606T071157 into main 2026-06-06 10:12:28 +03:00
8a70398496 docs(ORCH-048): prod deploy log — SUCCESS (bind-mount-only, prod untouched, staging gate green)
All checks were successful
CI / test (pull_request) Successful in 14s
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-06 07:11:57 +00:00
9c1c028dc1 Merge pull request 'docs(ORCH-048): staging gate log — SUCCESS (10/10, B6 registry isolation PASS)' (#47) from staging-log/ORCH-048-20260606T071003 into main 2026-06-06 10:10:18 +03:00
81e6ec5a20 docs(ORCH-048): staging gate log — SUCCESS (10/10, B6 registry isolation PASS)
All checks were successful
CI / test (pull_request) Successful in 13s
Staging suite run inside orchestrator-staging via docker exec (canonical,
ADR-001). All 10/10 checks pass, exit 0. B6 now reads registry from the
running staging instance's own process-env -> sandbox present, prod ET/ORCH
absent, no false FAIL / spurious rollback.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-06 07:10:03 +00:00
913c185232 tester(ET): auto-commit from tester run_id=154
All checks were successful
CI / test (push) Successful in 13s
CI / test (pull_request) Successful in 13s
2026-06-06 07:07:53 +00:00
2424f9aaad reviewer(ET): auto-commit from reviewer run_id=153
All checks were successful
CI / test (push) Successful in 13s
CI / test (pull_request) Successful in 14s
2026-06-06 07:05:47 +00:00
28d019a1e2 fix(staging_check): B6 reads registry from running staging instance env
All checks were successful
CI / test (push) Successful in 12s
CI / test (pull_request) Successful in 16s
B6 false-FAILed because it built the project registry from the
launcher process-env via a host-path hack (sys.path.insert +
importlib.reload), not from the running staging instance. Run from the
host, ORCH_PROJECTS_JSON is unset -> default ET+ORCH registry -> false
FAIL -> spurious deploy-staging -> development rollback.

Variant (v) per ADR-001: remove the host-path hack; canonically run the
suite INSIDE orchestrator-staging via docker exec so src.projects
resolves from /app (PYTHONPATH) with .env.staging. Verdict logic
extracted into pure _evaluate_b6(known) -> (passed, detail) +
_known_project_ids_from_registry() / _run_b6() with deterministic FAIL on
source unavailability. deployer.md and STAGING_CHECK.md updated to the
docker exec command. src/projects.py, .env* and checks A/B4/B5/C
untouched.

Refs: ORCH-048

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-06 07:03:31 +00:00
d6744c3c05 architect(ET): auto-commit from architect run_id=151
All checks were successful
CI / test (push) Successful in 15s
CI / test (pull_request) Successful in 14s
2026-06-06 06:59:56 +00:00
stream
7a6c7a0151 docs(ORCH-048): owner decision — pin variant (v), reject (a) HTTP-endpoint (chicken-egg)
All checks were successful
CI / test (push) Successful in 13s
CI / test (pull_request) Successful in 13s
2026-06-06 06:56:09 +00:00
04e88b833f Merge pull request 'docs(ORCH-048): staging gate log — FAILED (9/10, B6 /projects 404 on stale staging)' (#46) from staging-log/ORCH-048-20260606T053413 into main 2026-06-06 08:34:44 +03:00
7203812b17 docs(ORCH-048): staging gate log — FAILED (9/10, B6 /projects 404 on stale staging)
All checks were successful
CI / test (pull_request) Successful in 12s
Staging instance (8501) still runs a pre-ORCH-048 image without GET /projects,
so B6 deterministically FAILs (endpoint unavailable → no false PASS). Branch
code is correct; remediation is a host-side `--profile staging up -d --build`
of orchestrator-staging before re-running the gate.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-06 05:34:14 +00:00
8b5b1f0056 analyst(ET): auto-commit from analyst run_id=145
All checks were successful
CI / test (push) Successful in 13s
CI / test (pull_request) Successful in 13s
2026-06-06 05:06:33 +00:00
9538103eff docs: init ORCH-048 business request
All checks were successful
CI / test (push) Successful in 13s
2026-06-06 08:03:16 +03:00
0bc2398462 feat(stage_engine): ORCH-046 embed reviewer/tester findings in task_desc (#43)
Some checks failed
CI / test (push) Has been cancelled
Manual merge (Slava trust, variant A). Findings text embedded into developer task_desc (not just link). New src/review_parse.py, graceful fallback. 50 tests pass. Reviewer APPROVED, CI green. Staging FAIL = B6/ORCH-48 (infra, unrelated).
2026-06-06 07:54:03 +03:00
13b7df06b1 deployer(ET): auto-commit from deployer run_id=144
All checks were successful
CI / test (push) Successful in 12s
CI / test (pull_request) Successful in 12s
2026-06-06 04:49:37 +00:00
b5f4eb6f2f Merge pull request 'docs(ORCH-046): staging gate log — FAILED (9/10, B6 registry isolation)' (#44) from staging-log/ORCH-046-20260606T044841 into main 2026-06-06 07:49:22 +03:00
75c2b814d8 docs(ORCH-046): staging gate log — FAILED (9/10, B6 registry isolation)
All checks were successful
CI / test (pull_request) Successful in 12s
Staging suite ran end-to-end against staging (8501, stub mode): 9/10 PASS,
exit 1. Failure is B6 — staging project registry not isolated (sees prod
ET/ORCH, sandbox absent), violating the INFRA isolation invariant. Gate is
authoritative and red → staging_status: FAILED (rollback to development).
Note: this is a staging .env/ORCH_PROJECTS_JSON misconfig, not an ORCH-046
code regression (same B6 as ORCH-047).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-06 04:48:47 +00:00
be10becae2 tester(ET): auto-commit from tester run_id=143
All checks were successful
CI / test (push) Successful in 16s
CI / test (pull_request) Successful in 12s
2026-06-06 04:46:28 +00:00
4cd55063b4 reviewer(ET): auto-commit from reviewer run_id=142
All checks were successful
CI / test (push) Successful in 12s
CI / test (pull_request) Successful in 11s
2026-06-06 04:44:57 +00:00
03c3d77cac feat(stage-engine): embed verbatim reviewer/tester findings in rollback task_desc
All checks were successful
CI / test (push) Successful in 12s
CI / test (pull_request) Successful in 11s
При заворотах на development task_desc теперь несёт дословный must-fix текст
(P0/P1 ревьюера, причина FAIL тестера) вместо одной ссылки на файл — developer-
агент видит суть претензий сразу и не повторяет ту же ошибку, экономя retry-
бюджет и токены общего инстанса.

- Новый defensive-модуль src/review_parse.py (never-raise): extract_review_findings
  (P0/P1 из 12-review.md ## Findings), extract_test_failures (фрагмент тела
  13-test-report.md: pytest output / FAIL-строки / Итог), усечение по лимиту.
- Две rollback-ветки stage_engine: встраивают текст + сохраняют ссылку на полный
  файл; graceful-фоллбэк на ссылку-строку при битом/пустом артефакте.
- Последовательность отката, retry-счётчик, поля AdvanceResult, реестр QG_CHECKS
  не менялись.
- Доки: README (Stage Engine / Откаты), CHANGELOG.
- Тесты: tests/test_review_parse.py, test_stage_engine.py::TestRollbackTaskDescEmbedding.

Refs: ORCH-046

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-06 04:42:11 +00:00
29e83341b5 architect(ET): auto-commit from architect run_id=140
All checks were successful
CI / test (push) Successful in 11s
2026-06-06 04:36:40 +00:00
c7bca51d4b analyst(ET): auto-commit from analyst run_id=139
All checks were successful
CI / test (push) Successful in 12s
2026-06-06 04:09:41 +00:00
50a3c60b0e docs: init ORCH-046 business request
All checks were successful
CI / test (push) Successful in 13s
2026-06-06 07:06:44 +03:00
615a778d20 docs: lessons 2026-06-05 (#42)
Some checks failed
CI / test (push) Has been cancelled
2026-06-06 00:42:14 +03:00
stream
58116f93bd docs(history): сводные уроки вечера 05.06 — ORCH-17/45/47, деплой прода, грабли auth/git/Gitea
All checks were successful
CI / test (pull_request) Successful in 11s
2026-06-05 21:41:52 +00:00
941eec248e Merge pull request 'docs(ORCH-047): staging gate log — FAILED' (#41) from staging-log/ORCH-047-20260605213215 into main 2026-06-06 00:32:38 +03:00
b061354a8f docs(ORCH-047): staging gate log — FAILED (9/10, B6 registry isolation)
All checks were successful
CI / test (pull_request) Successful in 11s
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-05 21:32:15 +00:00
5d04de9eb6 fix(qg): ORCH-047 read result in tests gate (#40)
Manual merge by Owner. check_tests_passed reads result as equal-rank field. APPROVED reviewer v3, 68 tests pass.
2026-06-06 00:25:40 +03:00
edff0484c9 reviewer(ET): auto-commit from reviewer run_id=134
All checks were successful
CI / test (push) Successful in 12s
CI / test (pull_request) Successful in 11s
2026-06-05 21:18:33 +00:00
2f396452e8 tester(ET): auto-commit from tester run_id=132
All checks were successful
CI / test (push) Successful in 15s
CI / test (pull_request) Successful in 12s
2026-06-05 21:14:05 +00:00
185eb3f6cf reviewer(ET): auto-commit from reviewer run_id=131
All checks were successful
CI / test (push) Successful in 12s
CI / test (pull_request) Successful in 12s
2026-06-05 21:12:23 +00:00
58fc0a8b94 tester(ET): auto-commit from tester run_id=129
All checks were successful
CI / test (push) Successful in 12s
CI / test (pull_request) Successful in 12s
2026-06-05 21:07:30 +00:00
c1abfb7436 reviewer(ET): auto-commit from reviewer run_id=128
All checks were successful
CI / test (push) Successful in 12s
CI / test (pull_request) Successful in 12s
2026-06-05 21:06:01 +00:00
51a76e8169 fix(qg): read result: alongside verdict:/status: in tests gate
All checks were successful
CI / test (push) Successful in 12s
CI / test (pull_request) Successful in 11s
_parse_tests_verdict now accepts three equal-rank machine-readable
frontmatter fields in 13-test-report.md — result: (canonical tester
output), verdict: and status: (legacy/enduro-trails). Any one non-empty
field suffices; a negative token in any field stays authoritative.

Fixes the producer/consumer contract mismatch where the tester emits
`result: PASS` (per .openclaw/agents/tester.md) but the gate only read
verdict:/status:, causing a testing->development rollback loop until
MAX_DEVELOPER_RETRIES (observed on ORCH-17). Token sets frozen and gate
signature/QG_CHECKS unchanged for full backward compatibility.

Refs: ORCH-047
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-05 21:03:32 +00:00
75fb4069a4 architect(ET): auto-commit from architect run_id=126
All checks were successful
CI / test (push) Successful in 11s
2026-06-05 21:00:57 +00:00
c3879f2b80 analyst(ET): auto-commit from analyst run_id=125
All checks were successful
CI / test (push) Successful in 12s
2026-06-05 20:44:58 +00:00
974d4f94db docs: init ORCH-047 business request
All checks were successful
CI / test (push) Successful in 13s
2026-06-05 23:42:29 +03:00
982698c4e3 feat(qg): ORCH-045 CI poll-retry (#39)
Some checks failed
CI / test (push) Has been cancelled
Manual merge by Owner (Slava). check_ci_green polling with retry to fix CI race.
2026-06-05 23:08:15 +03:00
stream
0eff781d13 feat(qg): ORCH-045 — poll check_ci_green with retry to fix CI race (pending->success)
All checks were successful
CI / test (push) Successful in 12s
CI / test (pull_request) Successful in 12s
2026-06-05 19:59:06 +00:00
b9c61fc1f1 Merge pull request 'docs: uroki ORCH-017 (deadlock shared-gate, isporchennyy telefon, otkat)' (#38) from docs/lessons-orch-017 into main 2026-06-05 22:50:17 +03:00
65 changed files with 5118 additions and 121 deletions

View File

@@ -12,3 +12,8 @@ ORCH_GITEA_WEBHOOK_SECRET=
ORCH_CLAUDE_BIN=/usr/bin/claude
ORCH_REPOS_DIR=/home/slin/repos
ORCH_DB_PATH=/app/data/orchestrator.db
# ORCH-042: live-tracker mode. edit (DEFAULT) -> the task card is edited in place
# (editMessageText). bump -> on every update the old card is deleted and a fresh
# one is sent silently to the BOTTOM of the chat (deleteMessage + sendMessage +
# repoint). One card per task in both modes. Any value other than "bump" -> edit.
ORCH_TRACKER_MODE=edit

View File

@@ -21,10 +21,20 @@ On stage `deploy-staging` your job is to run the staging test suite and write a
### Steps:
1. Run the staging test suite against the live staging environment:
1. Run the staging test suite against the live staging environment.
**CANONICAL: run INSIDE the `orchestrator-staging` container via `docker exec`**
(ORCH-048, ADR-001) — NOT from the host:
```bash
python3 scripts/staging_check.py --base-url http://localhost:8501 --mode stub
docker exec orchestrator-staging \
python3 /repos/orchestrator/scripts/staging_check.py \
--base-url http://localhost:8501 --mode stub
```
Why: the B6 registry-isolation check reads the registry from the running
instance's own process-env (`.env.staging`). Running from the host leaves
`ORCH_PROJECTS_JSON` unset → B6 falls back to the default (ET+ORCH) registry
→ false FAIL → spurious rollback. The script path is `/repos/orchestrator/scripts/…`
(bind-mount); `scripts/` is NOT copied into the image, so `/app/scripts` does
not exist. Details: `docs/operations/STAGING_CHECK.md`.
2. Check the exit code:
- Exit code **0** = all tests PASS → `staging_status: SUCCESS`

View File

@@ -5,6 +5,9 @@
## [Unreleased]
### Added
- **Режим `bump` live-трекера Telegram** (ORCH-042): новый `ORCH_TRACKER_MODE` (`Settings.tracker_mode`, дефолт `edit`) выбирает поведение карточки задачи. `edit` (как было) — карточка редактируется на месте (`editMessageText`). `bump` — на каждом обновлении старое сообщение удаляется и карточка отправляется заново вниз чата (best-effort `delete_telegram(старый_id)``send_telegram(text, disable_notification=True)``set_tracker_message_id(new_id)`), чтобы актуальный статус всегда был последним в чате при активной переписке. Инвариант «одна карточка на задачу» сохранён в обоих режимах: за один вызов `update_task_tracker` шлётся ≤1 нового сообщения; `set_tracker_message_id` вызывается ТОЛЬКО при успешном send (транзиентный `None` не затирает указатель); результат delete НЕ блокирует отправку новой карточки (delete-fail у сообщения >48ч → всё равно шлём новое). Резолюция режима в `notifications` (case-insensitive, trim): всё, что ≠ `"bump"` (включая пустое/мусор) → `edit` → нулевая регрессия и оркестратор не падает на любом значении флага. Новый low-level helper `delete_telegram(message_id) -> bool` (контракт «never raises», маркеры `_DELETE_GONE_MARKERS`): `ok:true` или «уже нет / нельзя удалить» → `True`; неизвестный `ok:false`/5xx/исключение → `False`; нет кредов → `False` без HTTP. Сигнатуры `send_telegram`/`edit_telegram`/`update_task_tracker` и схема БД (`tasks.tracker_message_id`) не менялись. ADR `docs/work-items/ORCH-042/06-adr/ADR-001-tracker-bump-mode.md`. Тесты: `tests/test_tracker_bump.py`, `tests/test_config.py`.
- **Дословный текст findings reviewer/tester встраивается в `task_desc` заворота** (ORCH-046): при откате на `development` строка `task_desc` (попадает в `.task-dev.md` developer-агента) теперь несёт суть претензий, а не только ссылку на файл — устраняет «испорченный телефон», из-за которого агент шёл «читать файл», терял ключевые P0/P1 / причину FAIL и заворачивался снова, выжигая `MAX_DEVELOPER_RETRIES` и токены. Новый defensive-модуль `src/review_parse.py` (контракт «never raise», как `src/frontmatter.py`): `extract_review_findings(path)` — дословные пункты P0/P1 из секции `## Findings` файла `12-review.md`; `extract_test_failures(path)` — релевантный фрагмент тела `13-test-report.md` (приоритет `## Вывод pytest` → FAIL-строки `## Результаты``## Итог`). Обе функции усекают результат до `MAX_FINDINGS_CHARS`/`MAX_FAILURES_CHARS` (≈2000) с маркером `…(truncated)`. Две rollback-ветки `src/stage_engine.py` (reviewer REQUEST_CHANGES, tester `check_tests_passed` FAIL) встраивают извлечённый текст и **сохраняют ссылку** на полный файл («Полный контекст»); при пустом/битом артефакте — graceful-фоллбэк на прежнюю ссылку-строку (никаких исключений в `advance_stage`). Tester-ветка дополнительно всегда включает `reason` гейта. Последовательность отката, `_developer_retry_count`, поля `AdvanceResult` и реестр `QG_CHECKS` не менялись. ADR `docs/work-items/ORCH-046/06-adr/ADR-001-embed-findings-in-task-desc.md`. Тесты: `tests/test_review_parse.py`, `tests/test_stage_engine.py::TestRollbackTaskDescEmbedding`.
- **Поллинг с ретраем в quality-gate `check_ci_green`** (ORCH-045): гейт CI превращён из single-shot в polling, чтобы устранить race condition — раньше один опрос combined commit-status сразу после пуша developer-а ловил транзиентный `pending` (типично 1-3с, реальный кейс ORCH-017: опрос 17:58:54 → pending, CI дозеленел 17:58:55) и задача застревала насмерть без повторного опроса. Теперь: `success` → пропуск сразу; `failure`/`error` → провал сразу (терминально, ретрай бессмыслен); `pending`/unknown → `time.sleep` и повторный опрос до `ci_poll_max_attempts` раз; истечение попыток → явный `(False, "CI still pending after <T>s")` (тупик больше не молчаливый); 404 → как раньше; транзиентная `httpx.HTTPError` на попытке логируется и ретраится в рамках бюджета. Параметры — новые настройки `ORCH_CI_POLL_MAX_ATTEMPTS` (12) и `ORCH_CI_POLL_INTERVAL_S` (10) в `src/config.py` (~2 мин ожидания pending). Сигнатура `check_ci_green(repo, branch)` и реестр `QG_CHECKS` не менялись; `check_tests_passed` не затронут. ADR `docs/architecture/adr/adr-0004-ci-poll-retry.md`. Тесты: `tests/test_qg.py::TestCheckCIGreen`.
- **Прямые ссылки на BRD и Plane-таску в Telegram-уведомлении об апруве** (ORCH-017): пингующее сообщение `notify_approve_requested` теперь встраивает две HTML-`<a>`-ссылки — на `docs/work-items/<WI>/01-brd.md` (Gitea branch-view: `gitea_public_url``gitea_url`) и на issue в Plane (`{web_base}/{workspace}/projects/{project_id}/issues/{plane_issue_id}/`). Новая настройка `ORCH_PLANE_WEB_URL` (внешний браузерный web-URL Plane; фолбэк на `plane_api_url`). **Loopback-guard:** если итоговый Plane web-base указывает на localhost/127.0.0.1/0.0.0.0/::1 или пуст — Plane-ссылка опускается (не выпускаем битый localhost-URL). Graceful degradation: каждая ссылка строится независимо и опускается при нехватке данных, сообщение и призыв «Переведите задачу в статус Approved …» сохраняются всегда; ровно одно пингующее сообщение, разделяемая `send_telegram` не тронута. Динамические подписи экранируются `html.escape`, `parse_mode=HTML` сохранён. ADR `docs/work-items/ORCH-017/06-adr/ADR-001-telegram-approve-links.md`. Тесты: `test_notify_approve_links.py`, `test_analysis_approve_flow_links.py`.
- **Конфигурируемые модель LLM и режим работы (`--effort`) агентов** (ORCH-41): модель/effort каждого агента вынесены из хардкода `launcher.py` в конфиг — глобально per-agent (`ORCH_AGENT_MODEL_<AGENT>` / `ORCH_AGENT_EFFORT_<AGENT>`, дефолты `ORCH_AGENT_MODEL_DEFAULT=claude-opus-4-8`, `ORCH_AGENT_EFFORT_DEFAULT=high`) и per-project (`agent_models` / `agent_efforts` в `ORCH_PROJECTS_JSON`). Резолверы `resolve_agent_model` / `resolve_agent_effort` (приоритет project > per-agent env > default > пусто), валидация effort `{low,medium,high,xhigh,max}`, опц. `ORCH_AGENT_FALLBACK_MODEL` (`--fallback-model`). Хардкод `"model":"opus"` (architect/reviewer) удалён. Тесты: `test_resolve_agent_model.py`, `test_resolve_agent_effort.py`.
- **Единый status-коммент агентов в Plane** (ORCH-016): `usage.build_status_comment(...)` — один хелпер для ВСЕХ ролей (analyst..deployer). HTML-формат: header `{icon} {Role} — {описание}`, опциональная строка `Verdict/Status: …` из YAML-frontmatter артефакта, **строка `Длительность: 4m 12s`** (явный `duration_s` от launcher, fallback из `agent_runs` для аналитика), `<b>Документы:</b><ul><li><a>…</a></li></ul>`, тех-хвост `<sub>tokens · cost</sub>`. Утилитки: `usage.fmt_duration`, `usage.get_agent_duration`, новый модуль `src/frontmatter.py` (defensive YAML reader). ADR `docs/work-items/ORCH-016/06-adr/ADR-001-unified-status-comment.md`.
@@ -17,10 +20,13 @@
- **Реестр проектов** (ORCH-6): `src/projects.py`, фильтрация вебхуков по проекту.
### Changed
- **Русификация и косметика карточки live-трекера Telegram** (ORCH-042, оба режима): метка `Подтверждение BRD` вместо «Ревью БРД» (`_BRD_LABEL`); после прохождения approve-gate строка подтверждения BRD начинается с ✅ вместо ⏸️ (ветка ожидания человека сохраняет ⏸️/⏳); русские display-labels стадий в `_TRACKER_STAGES` (`Анализ / Архитектура / Разработка / Код ревью / Тестирование / Внедрение`) — применяются и в «✅ …», и в «🔄 … идёт»; финальная строка готовой задачи `📦 Внедрено` вместо `deployed` (`_done_link`). Меняются только отображаемые строки — ключи стадий и имена агентов не трогаются. Существующие ассерты `tests/test_telegram_tracker.py` обновлены под русские метки.
- **Status-коммент агентов теперь HTML и единообразен** (ORCH-016): `src/usage.usage_comment(...)` помечен deprecated и стал тонкой обёрткой над `build_status_comment`; `src/usage.artifact_links(...)` теперь возвращает `<li><a>…</a></li>` HTML-фрагменты (раньше — markdown `[label](url)`); `stage_engine._build_analyst_ready_comment(...)` — тонкая обёртка, аналитик идёт через ту же ветку `build_status_comment(agent="analyst", ...)`. Реестр `QG_CHECKS` и `STAGE_TRANSITIONS` НЕ изменялись.
- Цепочка стадий: `... testing → deploy-staging → deploy → done` (была без `deploy-staging`).
### Fixed
- **Staging-чек B6 читает реестр из окружения работающего staging-инстанса** (ORCH-048): блок B6 «Registry: sandbox present, prod ET/ORCH absent» в `scripts/staging_check.py` давал **ложный FAIL** (`prod-ET=YES(BAD!)`, `prod-ORCH=YES(BAD!)`) при фактически исправной изоляции — единственный чек suite, который не ходил к инстансу по HTTP, а импортировал `src.projects` локально через host-path хак `sys.path.insert(0, "/repos/orchestrator")` + `importlib.reload`, строя реестр из `ORCH_PROJECTS_JSON` **process-env запускающего процесса**. При фактическом запуске деплоером с хоста переменная не задана → дефолт `_DEFAULT_PROJECTS` (ET+ORCH) → ложный FAIL → лишний откат `deploy-staging → development`. Решение (вариант «в», ADR-001): host-path хак удалён; suite канонически запускается ВНУТРИ контейнера `orchestrator-staging` через `docker exec … python3 /repos/orchestrator/scripts/staging_check.py` (`scripts/` доступен только через bind-mount, `import src.projects` резолвится через `PYTHONPATH=/app` из кода контейнера, env — `.env.staging`) → B6 читает реестр именно работающего инстанса, без HTTP-bootstrap и «курицы-яйца». Логика вердикта вынесена в чистую `_evaluate_b6(known) -> (passed, detail)` (инвариант `passed ⟺ SANDBOX ∈ known ∧ PROD_ET ∉ known ∧ PROD_ORCH ∉ known`, формат detail сохранён) + `_known_project_ids_from_registry()` / `_run_b6()` с детерминированным FAIL при недоступности источника (не ложный PASS, не необработанное исключение). Синхронно обновлены `.openclaw/agents/deployer.md` (команда стадии через `docker exec`) и `docs/operations/STAGING_CHECK.md`. `src/projects.py`, `.env*` и прочие чеки A/B4/B5/C не тронуты; реестр `QG_CHECKS` и `check_staging_status` (ADR-0003) не менялись. ADR `docs/work-items/ORCH-048/06-adr/ADR-001-b6-registry-via-in-container-run.md`. Тесты: `tests/test_staging_check_b6.py`.
- **Testing-гейт `check_tests_passed` читает `result:` наравне с `verdict:`/`status:`** (ORCH-047): парсер `_parse_tests_verdict` (`src/qg/checks.py`) теперь принимает три равноправных машиночитаемых поля frontmatter `13-test-report.md``result:` (канон промпта тестера `.openclaw/agents/tester.md`, `result: PASS|FAIL`), плюс легаси `verdict:` и `status:` (enduro-trails ET-001..ET-014); достаточно любого одного непустого. Устраняет рассинхрон контракта: тестер честно эмитил `result: PASS` без `verdict:`/`status:`, парсер попадал в ветку «нет машинного вердикта» → откат `testing → development` в петлю до исчерпания `MAX_DEVELOPER_RETRIES` (наблюдалось на ORCH-17; ORCH-016 прошёл лишь из-за избыточного дублирования полей). Семантика приоритетов сохранена и распространена на все три поля через объединённую строку: negative-токен в любом поле авторитетен (перебивает positive), наборы токенов заморожены (обратная совместимость). Сигнатура гейта, имя и реестр `QG_CHECKS` не менялись. ADR `docs/work-items/ORCH-047/06-adr/ADR-001-result-field-in-tests-gate.md`. Тесты: `tests/test_qg.py::TestCheckTestsPassed`.
- БАГ-8: провал deploy/deploy-staging → корректный откат на `development`.
- Изоляция тестов от живого Plane API (PR #27): autouse-фикстура сброса settings.

View File

@@ -7,6 +7,7 @@
- **Webhook Receivers** (`src/webhooks/plane.py`, `gitea.py`) — приём событий, HMAC-проверка, дедупликация (`_dedup.py`). Роуты: `POST /webhook/plane`, `POST /webhook/gitea`.
- **State Machine** (`src/stages.py`) — `STAGE_TRANSITIONS`: переходы, агент и QG каждой стадии. Хелперы: `get_next_stage`, `get_agent_for_stage`, `get_qg_for_stage`, `get_previous_stage`.
- **Stage Engine** (`src/stage_engine.py`) — исполнение переходов, диспетчеризация QG (`_run_qg`), откаты, синхронизация с Plane.
- **Review/Test Parsers** (`src/review_parse.py`, ORCH-046) — defensive-извлечение дословного must-fix текста из артефактов для встраивания в `task_desc` заворота: `extract_review_findings` (P0/P1 из `12-review.md`), `extract_test_failures` (фрагмент тела `13-test-report.md`). Контракт «never raise»: любая ошибка → `""`.
- **Quality Gates** (`src/qg/checks.py`) — проверки выхода со стадии, реестр `QG_CHECKS`.
- **Agent Launcher** (`src/agents/launcher.py`) — запуск Claude CLI агентов в изолированном git worktree, мониторинг, auto-advance.
- **Queue** (`src/queue_worker.py`, ORCH-1) — персистентная очередь задач (SQLite `jobs`), atomic claim, max_concurrency, ретраи, restart-safe.
@@ -46,6 +47,13 @@ created → analysis → architecture → development → review → testing →
- Deploy / deploy-staging FAILED → откат на `development`.
- `get_previous_stage` использует порядок ключей `STAGE_TRANSITIONS`.
### Обогащение `task_desc` при заворотах (ORCH-046)
При откате на `development` `task_desc` (попадает в `.task-dev.md` developer-агента) несёт **дословный must-fix текст**, а не только ссылку — чтобы агент видел суть претензий сразу и не повторял ту же ошибку:
- **reviewer REQUEST_CHANGES** → дословные пункты P0/P1 из секции `## Findings` файла `12-review.md` (`extract_review_findings`);
- **tester `check_tests_passed` FAIL** → `reason` гейта + фрагмент тела `13-test-report.md` (приоритет: `## Вывод pytest` → FAIL-строки `## Результаты``## Итог`; `extract_test_failures`).
Ссылка на полный файл-артефакт сохраняется всегда («Полный контекст»). Парсеры `src/review_parse.py` — defensive (never-raise); при отсутствующем/битом артефакте `task_desc` graceful-фоллбэк на прежнюю ссылку-строку, последовательность отката и retry-счётчик не меняются (ADR `docs/work-items/ORCH-046/06-adr/ADR-001-embed-findings-in-task-desc.md`).
### Plane Sync: единый status-коммент агентов (ORCH-016)
Все агенты (analyst / architect / developer / reviewer / tester / deployer) пишут финальный коммент через **один хелпер** `usage.build_status_comment(...)` (ADR `docs/work-items/ORCH-016/06-adr/ADR-001-unified-status-comment.md`). Формат HTML, разделители `<br>`:
@@ -58,7 +66,7 @@ created → analysis → architecture → development → review → testing →
```
- **Длительность** считается launcher'ом (`_monitor_agent`) и пробрасывается в `_post_usage_comments`; для analyst (коммент строится в `stage_engine`) используется DB-фоллбэк `usage.get_agent_duration(task_id, agent)`.
- **Vердикт-парсер** — `src/frontmatter.read_frontmatter_value(...)` (defensive, никогда не raise). Машинные ключи: `verdict:` (reviewer/tester), `deploy_status:` (14-deploy-log.md), `staging_status:` (15-staging-log.md).
- **Vердикт-парсер** — `src/frontmatter.read_frontmatter_value(...)` (defensive, никогда не raise). Машинные ключи: reviewer → `verdict:` (12-review.md); **testing-гейт `check_tests_passed` (13-test-report.md) → любое из трёх равноправных: `result:` (канон промпта тестера), `verdict:`, `status:`** (ORCH-047, ADR-001); deployer → `deploy_status:` (14-deploy-log.md), `staging_status:` (15-staging-log.md). Negative-токен в любом поле авторитетен (перебивает positive).
- Формат коммента **не** меняет реестр гейтов и стадий; коммент — отображение, не управление.
## База данных (SQLite)

View File

@@ -8,6 +8,7 @@ Per-work-item решения живут в `docs/work-items/<id>/06-adr/ADR-NNN-
| adr-0001 | Реестр проектов (multi-repo) | accepted | 2026-06-02 | ORCH-6 |
| adr-0002 | Очередь задач вместо in-process потоков | accepted | 2026-06-03 | ORCH-1 |
| adr-0003 | Условный staging-гейт перед прод-деплоем | accepted | 2026-06-05 | ORCH-35 |
| adr-0004 | Поллинг с ретраем в check_ci_green (фикс CI-race) | accepted | 2026-06-05 | ORCH-045 |
## Формат
**Контекст → Решение → Альтернативы → Последствия → Связи.** Статус: proposed / accepted / superseded.

View File

@@ -0,0 +1,45 @@
# adr-0004: Поллинг с ретраем в quality-gate check_ci_green (фикс CI-race)
- **Статус:** accepted
- **Дата:** 2026-06-05
- **Задача:** ORCH-045
## Контекст
Quality-gate `check_ci_green(repo, branch)` (`src/qg/checks.py`) проверяет combined commit-status ветки через Gitea API сразу после того, как developer-агент запушил код. Реализация была **single-shot**: один `GET /repos/{owner}/{repo}/commits/{branch}/status`, чтение `data["state"]``success` → пропуск, иначе → сразу `False`.
Это создавало race condition. Gitea-CI после пуша 13 секунды держит combined state `pending`, пока не отработают чек-раннеры. Если гейт опрашивал статус в этом окне, он получал `pending` и возвращал `False` **ровно один раз** — повторного опроса не было. Combined state затем дозеленевал до `success`, но гейт уже промахнулся, и задача застревала насмерть без видимой причины.
Реальный инцидент **ORCH-017**: гейт опросил статус в 17:58:54 → `pending`; CI дозеленел в 17:58:55. Задача встала в тупик (см. `docs/history` / lessons ORCH-017).
## Решение
`check_ci_green` превращён из single-shot в **polling с ретраем**:
- `state == "success"``(True, "CI green")` немедленно.
- `state in ("failure", "error")``(False, "CI state: <state>")` немедленно — CI красный, ретрай бессмыслен (терминальное состояние).
- `state == "pending"` (или `unknown` / иное не-терминальное) → `time.sleep(interval)` и опрос снова, до `N` попыток.
- После исчерпания всех попыток при всё ещё `pending``(False, "CI still pending after <T>s")`**явный** провал с причиной, чтобы оператор видел тупик, а не молчаливый стол.
- `404``(False, "Branch ... not found or no status")` — как раньше.
- Транзиентная `httpx.HTTPError` на отдельной попытке — **не падаем сразу**: логируем и пробуем ещё в рамках лимита попыток; если все попытки — сетевая ошибка → `(False, "API error: <e>")`.
Параметры вынесены в `src/config.py` (pydantic-settings, env-prefix `ORCH_`, единый стиль с остальными настройками):
- `ci_poll_max_attempts` (env `ORCH_CI_POLL_MAX_ATTEMPTS`, дефолт **12**)
- `ci_poll_interval_s` (env `ORCH_CI_POLL_INTERVAL_S`, дефолт **10**)
Итого по умолчанию гейт ждёт `pending` до ~2 минут (12 × 10s) перед тем как явно провалиться. Каждая не-финальная попытка логируется через существующий `logger` (`check_ci_green: attempt i/N, state=..., retrying in Ns`). `timeout=10` на каждый отдельный запрос сохранён.
Сигнатура `check_ci_green(repo, branch) -> tuple[bool, str]` **не менялась** — её зовёт stage_engine и реестр гейтов `QG_CHECKS`.
## Альтернативы
- **Оставить single-shot, опрашивать гейт повторно снаружи (на уровне stage_engine/воркера).** Отклонено: размазывает логику CI-ожидания по слоям, дублирует таймауты; гейт — естественное место знания о combined-status.
- **Webhook от Gitea на завершение CI вместо поллинга.** Отложено: требует надёжной доставки/дедупликации вебхуков именно по CI-статусу и переписывания триггера стадии; поллинг — минимальный, локализованный фикс race-а здесь и сейчас.
- **Бесконечный ретрай до зелёного.** Отклонено: задача могла бы висеть вечно при реально зависшем CI; ограниченный бюджет + явный `False` с причиной даёт оператору сигнал.
## Последствия
- CI-race ORCH-017 закрыт: транзиентный `pending` переживается ретраем, гейт не промахивается.
- `check_ci_green` теперь **блокирующий** до ~`max_attempts × interval` секунд при затяжном `pending` (по умолчанию ~2 мин). Это осознанный trade-off; для красного CI и success — выход немедленный, без задержки.
- Тупик больше не молчаливый: истечение попыток → `(False, "CI still pending after <T>s")`, причина видна.
- Бюджет/интервал настраиваемы через env без правки кода.
- `check_tests_passed` / `_parse_tests_verdict` (ORCH-47) **не затронуты**.
## Связи
ORCH-017 (инцидент-первоисточник: deadlock shared-gate из-за CI-race), реестр гейтов `QG_CHECKS` (`check_ci_green`), стадия `development`. Тесты: `tests/test_qg.py::TestCheckCIGreen`.

View File

@@ -107,6 +107,27 @@ claude.exe --print --system-prompt --allowedTools Read,Write,Edit,Bash
2. Если < MAX_DEV_RETRIES (3) — откатывает в development, перезапускает developer
3. Если >= MAX_DEV_RETRIES — эскалация (логирование + уведомление)
### 7. Live Telegram tracker (`src/notifications.py`)
Вместо ~15 отдельных сообщений на задачу оркестратор держит **ОДНУ** live-карточку на задачу (`update_task_tracker`), которая обновляется на каждом переходе стадии. Текст рендерится статически из БД (`render_task_tracker`: стадии, токены, стоимость, BRD-подтверждение, итоги). Карточка всегда тихая (`disable_notification=True`); отдельные пинги шлют только `notify_approve_requested` / `notify_error`. `message_id` хранится в `tasks.tracker_message_id`; helpers `get_tracker_message_id` / `set_tracker_message_id`. Контракт всего компонента — **never raises**.
**Режимы (ORCH-042, `ORCH_TRACKER_MODE` → `Settings.tracker_mode`).** Резолвится в `update_task_tracker` (case-insensitive, trim); всё, что ≠ `"bump"` (включая пустое/мусор/None), трактуется как `edit` → нулевая регрессия и безопасный фолбэк. Инвариант «одна карточка на задачу» сохраняется в обоих режимах.
| Режим | Поведение при обновлении |
|-------|--------------------------|
| `edit` (дефолт) | первый вызов → `send_telegram` (тихо) + сохранение `message_id`; далее → `edit_telegram` на сохранённый id. Новое сообщение шлётся ТОЛЬКО при `EDIT_GONE` (удалено/старше 48ч/невалидный id). `EDIT_NOT_MODIFIED` / `EDIT_FAILED` → нового сообщения нет (анти-дубль). |
| `bump` | карточка пересоздаётся внизу чата: best-effort `delete_telegram(старый_id)``send_telegram(text, disable_notification=True)``set_tracker_message_id(new_id)` **только** при успешном send (`new_mid is not None`). За один вызов — не более одного нового сообщения. |
**`delete_telegram(message_id) -> bool`** (low-level, never raises). Семантика возврата — «исчезло ли старое сообщение»:
- `ok:true``True`;
- `ok:false` с маркерами `_DELETE_GONE_MARKERS` (`message to delete not found`, `message can't be deleted`, `message_id_invalid`) → `True` (старше 48ч / уже удалено — не транзиент);
- прочий `ok:false` / 5xx / исключение (сеть/таймаут) → `False` + `logger.warning`;
- нет токена/chat_id → `False`, HTTP не выполняется.
Результат `delete_telegram` **не** блокирует отправку новой карточки (BR-6: delete-fail у сообщения >48ч → всё равно шлём новое); `False` означает лишь «старое, возможно, ещё живо» — будет вычищено повторной попыткой на следующем переходе. При транзиентном сбое send (`None`) указатель `tracker_message_id` **не** затирается (анти-затирание, симметрично edit-fallback).
**Текст карточки (оба режима, ORCH-042):** метка `Подтверждение BRD` (была «Ревью БРД»); после прохождения approve-gate строка BRD начинается с ✅ (ветка ожидания сохраняет ⏸️/⏳); русские display-labels стадий (`Анализ / Архитектура / Разработка / Код ревью / Тестирование / Внедрение`); финальная строка `📦 Внедрено` (было `deployed`). Меняются только отображаемые строки — ключи стадий и имена агентов (завязаны на `_STAGE_ACTIVE_AGENT`, `last_done`, БД) не трогаются.
## Database Schema
```sql

View File

@@ -0,0 +1,128 @@
# Lessons Learned — 2026-06-05 (вечер): ORCH-17/45/47 + деплой прода
## Итог дня
Закрыты три задачи (ORCH-17, ORCH-45, ORCH-47), два прод-гейта стали умнее, заведено
4 системных задачи в бэклог (ORCH-44/46/48 + B6). Главный сквозной урок: **конвейер не мог
провести эти задачи автономно из-за дыр в самом конвейере** — потребовались ручные merge и
ребилды прода. Корни задокументированы, чинятся отдельными задачами.
---
## 1. ORCH-17 — approve-ping links (закрыта вручную)
Подробный разбор: `docs/history/LESSONS_ORCH-017.md`. Кратко: косметика (2 ссылки)
застряла 5 раз, объективный дедлок shared-гейта, ручной merge PR #37 (`26c6f267`).
---
## 2. ORCH-45 — CI-гонка в `check_ci_green` (исправлена, в проде)
### Проблема
`check_ci_green` делал **один** запрос статуса CI сразу после developer. Если CI ещё
`pending` 1-3 секунды (реальный кейс: опрос 17:58:54 → pending, CI позеленел 17:58:55) —
гейт возвращал False **один раз** и задача застревала насмерть с зелёным CI.
### Решение (PR #39, merge `982698c4`)
Поллинг с ретраем: `success`/`failure` — терминальны (сразу), `pending` → ждать
`CI_POLL_INTERVAL_S`(10с) до `CI_POLL_MAX_ATTEMPTS`(12) раз, истёк лимит → явный
`False` с причиной "CI still pending after Ns" (не виснет молча). Параметры в `config.py`
как env `ORCH_CI_POLL_*`. ADR-0004. +5 тестов (мок httpx + time.sleep).
---
## 3. ORCH-47 — тестер-гейт игнорил `result:` (исправлен, в проде)
### Проблема (уловка-22)
`check_tests_passed`/`_parse_tests_verdict` читал только `verdict:`/`status:` из frontmatter
`13-test-report.md`, но промпт tester-агента велит писать `result: PASS|FAIL`. Честный тестер
(`result: PASS`, без `verdict:`) → гейт «No machine-readable verdict» → ложный FAIL → петля
dev↔review↔tester → Blocked. **И сама ORCH-47 (которая это чинит) попала в тот же капкан:**
в проде крутился старый гейт → не понимал её собственный `result: PASS` → 3 круга петли.
Змея кусает хвост: чтобы пройти гейт автономно, фикс уже должен быть в проде.
### Решение (PR #40, merge `5d04de9e`)
`result:` добавлен как равноправное поле наряду с `verdict:`/`status:`. Любое одно непустое
поле достаточно. Negative-токен (BLOCKED/FAILED) в ЛЮБОМ поле авторитетен (ET-013 кейс
сохранён). Token sets заморожены для обратной совместимости. ADR-001. +6 тестов (68 passed).
После деплоя ручной `advance_stage` пнул застрявшую task → гейт принял `result: PASS`
прошёл testing. Петля исчезла навсегда.
### Остаточная находка → B6 / ORCH-48
На staging деплоер дал 9/10 PASS, завалил **B6 Registry isolation**: staging-реестр видит
боевые ET+ORCH вместо одного sandbox (нарушает «staging — только sandbox»). Деплоер честно
поставил FAILED и НЕ стал натягивать зелёнку (вне мандата) → откат by design. К фиксу гейта
отношения не имеет (E2E против sandbox прошёл). Заведена ORCH-48.
---
## 4. ДЕПЛОЙ ПРОДА — как правильно (важная операционная памятка)
### `/app` запечён в образ, НЕ volume
`docker-compose.yml`: `build: .` + `COPY src/ ./src/`. Поэтому `git pull` + рестарт с
`--no-build` **НЕ довозит код** — нужен `docker compose build orchestrator`. Деплой-хук
(`scripts/orchestrator-deploy-hook.sh`) по дефолту целит в **staging** (by design) — для
прода нужны env `TARGET_SERVICE=orchestrator TARGET_PORT=8500 COMPOSE_PROFILE=''`.
### Порты/профили
- prod orchestrator = порт **8500** (`/health``{"status":"ok"}`), `network_mode: host`,
профиль prod = пустой (стартует обычным `docker compose up -d orchestrator`).
- staging = порт **8501**, профиль `staging` (стартует только `--profile staging`).
### Рабочая последовательность деплоя (проверена дважды 05.06)
1. `sudo chown -R slin:slin /home/slin/repos/orchestrator` (см. грабля ниже).
2. `git checkout main && git reset --hard origin/main && git clean -fd -e '*.bak*' -e '.deploy-prev-image-prod'`.
3. `docker compose build orchestrator`.
4. `docker compose up -d orchestrator` + health-loop на :8500.
5. **Проверка claude-auth** (ребилд её ломает — см. ниже).
6. Проверка что новый код активен в `/app` (grep маркера правки).
### ⚠️ ГРАБЛЯ: хост-репо рассинхронизирован с git (агенты пишут под root)
Хост-репо `/home/slin/repos/orchestrator` оказывался на feature-ветке (не main), а рабочая
копия засеяна untracked+modified файлами, созданными агентами **под uid=0 (root-owned)** прямо
в репо. → `git pull --ff-only` падал `Permission denied` / `would be overwritten`, обычный
`rm` под slin не мог снести root-файлы. **Лечение:** `sudo chown -R slin:slin <repo>`
проверить что modified=совпадает-с-main и untracked=уже-в-main (дубликаты, не теряем) →
`git reset --hard origin/main` + `git clean`. **Хук это НЕ разруливает** — сверять состояние
хост-репо перед каждым деплоем.
### ⚠️ ГРАБЛЯ: ребилд ломает claude-auth (проверять ВСЕГДА)
Пересоздание контейнера может root-овнить `/home/slin/.claude/.credentials.json` и сделать
`/root/.claude` пустышкой → агенты падают `Not logged in`. Защита — монтирование creds в
compose (`/home/slin/.claude` + `.claude.json`), launcher форсит `HOME=/home/slin`.
**После каждого ребилда боевая проверка:**
`docker exec orchestrator bash -c 'cd /tmp && HOME=/home/slin /opt/claude-code/bin/claude.exe --print "ОК"'`
(timeout 90с). 05.06 auth пережил оба ребилда — защита держит.
---
## 5. ЗАПУСК конвейера и Gitea API
### Старт конвейера = Plane Backlog → In Progress
Конвейер стартует штатно переводом задачи в Plane из Backlog в **In Progress** (код:
`webhooks/plane.py handle_status_start` — «pipeline is started when Slava moves the issue
into In Progress»). Webhook создаёт task-row, заводит ветку, запускает analyst. Никаких
ручных вставок в БД.
### QG-0: лимит заголовка 80 символов
При старте задача с заголовком >80 символов заворачивается на QG-0 («Title слишком длинный»)
и уходит в Blocked. Чинить — укоротить `name` (суть в заголовок, детали в description),
вернуть в Backlog, снова In Progress.
### Gitea API грабли
- **merge/create PR** требуют заголовок `Authorization: token <ORCH_GITEA_TOKEN>` (форма
с префиксом `token `), иначе 401 "token is required".
- **heredoc через ssh+docker exec глотает вывод** python-скрипта. Надёжный путь: написать
`.py` локально → `base64 -w0``ssh "echo <b64> | base64 -d > /tmp/x.py"``docker cp`
`docker exec python3 /tmp/x.py`. Это же обходит экранирование кириллицы/скобок.
---
## Состояние прод-гейтов после 05.06
-`check_ci_green` — поллинг с ретраем (ORCH-45)
-`check_tests_passed` — читает `result:`/`verdict:`/`status:` (ORCH-47)
## Бэклог (high) после дня
- **ORCH-44** — надёжность запуска агента (preflight слеп к auth; `--effort` гасит вывод;
пустой run-лог → должен быть failed).
- **ORCH-46** — «испорченный телефон»: орк не передаёт деву ТЕКСТ замечаний reviewer/tester
(только ссылку на файл), противоречивые сигналы tester↔reviewer, нет памяти между кругами.
- **ORCH-48 / B6** — staging registry isolation (staging видит прод-проекты вместо sandbox).

View File

@@ -0,0 +1,119 @@
# LESSONS — ORCH-048 (B6 staging registry isolation, вариант «в»)
**Дата:** 2026-06-06
**Work item:** ORCH-048 — «staging B6 check reads registry from host worktree, not staging container»
**Статус:** ✅ Done. Merge PR #45 (`2a36ed80`), Plane → Done, task 38 → done. Прод не тронут.
---
## TL;DR
B6-чек staging-suite давал **ложный FAIL** (`prod-ET=YES, prod-ORCH=YES`), блокируя `deploy-staging` у **всех** ORCH-задач, хотя изоляция реестра в staging работала корректно. Починили, выбрав архитектурный вариант, который **не порождает новых ловушек автономности**. По дороге словили три урока, которые стоят дороже самой фичи.
---
## 1. Root cause (для истории)
`scripts/staging_check.py` блок **B6** был единственным чеком suite, который не ходил по HTTP к живому инстансу, а **импортировал Python-код локально**:
```python
sys.path.insert(0, "/repos/orchestrator") # host-worktree
importlib.reload(sys.modules["src.projects"]) # подхватывает env ТЕКУЩЕГО процесса
known = known_plane_project_ids()
```
Деплоер запускал suite **с хоста**, где `ORCH_PROJECTS_JSON` не задан → `src.projects` грузил встроенный `_DEFAULT_PROJECTS` (ET+ORCH) → `known_plane_project_ids()` возвращал боевые id → **ложный FAIL**. То есть B6 проверял реестр НЕ того окружения, реестр которого реально использует staging-инстанс.
Изоляция при этом была исправна: внутри `orchestrator-staging` `known_plane_project_ids()` корректно отдавал только sandbox (`.env.staging`).
---
## 2. ГЛАВНЫЙ УРОК: «курица-яйцо» в staging-гейте
Архитектор на первом прогоне выбрал **вариант (а): новый HTTP-эндпоинт `GET /projects`**, и B6 стал ходить на него. Решение красивое (единый HTTP-стиль с остальными чеками), **но оно само себя заблокировало**:
- B6 проверяет **работающий** staging-инстанс (порт 8501).
- Эндпоинт `/projects` **запечён в Docker-образ** (`src/main.py`).
- В текущем (ещё не пересобранном) образе эндпоинта НЕТ`GET /projects`**404** → B6 FAIL → откат на development.
- Чтобы чек прошёл, нужен **ручной bootstrap-деплой** образа. А деплой не происходит, потому что чек красный. **Тупик by design.**
Подтверждено на проде: `GET /projects` на 8501 и 8500 → 404 → `deploy-staging FAILED`.
**Вывод-правило:**
> Staging-чек НЕ должен проверять то, что появляется в работающем инстансе только ПОСЛЕ деплоя проверяемой ветки. Иначе первый прогон всегда падает и требует ручного bootstrap — это прямая поломка автономности.
**Решение — вариант (в):** запускать suite **ВНУТРИ** staging-контейнера (`docker exec orchestrator-staging`), читать реестр из собственного process-env контейнера, убрать host-path хак. Преимущество принципиальное:
- B6 не зависит от того, что отдаёт инстанс по HTTP.
- `staging_check.py` берётся из bind-mount → свежий код подхватывается **без ребилда образа**.
- **Курицы-яйца нет ни на первом прогоне, ни в будущем.**
Вариант (б) (`docker exec ... python3 -c "..."` + парсинг stdout) отклонён: хрупкое экранирование (см. `LESSONS_2026-06-05.md`).
**Как это попало в реализацию:** после FAIL под (а) — откатили ветку к analyst-артефактам (`git reset --hard <analyst-commit>`), стёрли ADR(а)+код(а), зашили в `02-trz.md §4` блок «РЕШЕНИЕ ПРИНЯТО ВЛАДЕЛЬЦЕМ: вариант (в)» с обоснованием и чек-листом, откатили задачу на `architecture` + поставили job архитектору заново. Второй прогон: arch→dev→review→tester→deploy-staging — без петель, **B6 ✓ PASS, 10/10**.
---
## 3. УРОК: орк мержит в main ТОЛЬКО логи, а не фикс-код
После прохождения staging орк сам:
- закрыл задачу в `done`,
- смержил в `main` PR с **логами** (`15-staging-log.md`, `14-deploy-log.md`),
- но **сам фикс-код остался в feature-ветке**`main` всё ещё содержал старый сломанный B6.
Это by design: фичу в main вливает **владелец**. Поймали проверкой:
```bash
git fetch origin -q
git log --oneline origin/main..origin/feature/<branch> # покажет невлитые коммиты фикса
git show origin/main:scripts/staging_check.py | grep -c '_evaluate_b6' # 0 = фикс НЕ в main
```
**Правило:**
> Прежде чем считать задачу реально доставленной — проверить `git log origin/main..feature` и наличие ключевой функции/строки фикса в `origin/main`. `done` в Plane + смерженные логи ≠ код в main.
Финальный шаг: смерджить feature-PR в main (Gitea API, `Do: merge`), затем синхронизировать host-репо.
---
## 4. УРОК: rollout bind-mount-фикса = host `git pull`, без ребилда/рестарта прода
ORCH-048 менял только **bind-mounted / non-runtime** артефакты:
| Файл | Как доходит до прода |
|------|----------------------|
| `scripts/staging_check.py` | bind-mount (`/home/slin/repos``/repos`); **не** в образе (`scripts/` нет в `/app`) → host `git pull` → live сразу |
| `.openclaw/agents/deployer.md` | bind-mounted промпт, читается при запуске агента → live на следующем запуске |
| `tests/`, `docs/` | не деплоятся |
`src/` и `Dockerfile` НЕ менялись → **рестарт/ребилд прод-контейнера 8500 не нужен и не делался** (zero group-risk для ET).
**Грабли host-репо:** `git pull` в `/home/slin/repos/orchestrator` сначала упёрся в `sudo: a password is required` — ложная тревога. Репо принадлежит `slin`, sudo не нужен; прямой `git pull --ff-only origin main` прошёл. **Сначала проверь `ls -ld` / `stat -c %U` репо — не лезь в sudo вслепую.**
**Верификация rollout в живом bind-mount (обязательна):**
```bash
grep -c '_evaluate_b6' scripts/staging_check.py # >=1
grep -c 'sys.path.insert(0, "/repos/orchestrator")' scripts/staging_check.py # 0
grep -c 'docker exec orchestrator-staging' .openclaw/agents/deployer.md # >=1
curl -s -o /dev/null -w '%{http_code}' http://localhost:8500/health # 200
```
---
## 5. Технические заметки (gotchas)
- **В контейнере orchestrator НЕТ `curl`** — для Gitea/Plane API использовать `urllib` через python (script-file → base64 → `docker cp``docker exec`).
- **Plane state-id зависят от проекта.** Approved для проекта orchestrator = `63f2c8fe-dcda-4ace-952f-dd88bd0118ff` (НЕ дефолтный `a519a341...` из кода — тот для sandbox/ET). Брать реальные state-id через `GET .../states/`.
- **BRD-апрув = перевод Plane-issue в статус Approved** → webhook ловит смену статуса → путь `agent=None``approved-via-status` → гейт пропускает, БЕЗ повторного запуска `check_analysis_approved`.
- **Dockerfile НЕ копирует `scripts/`** в образ — `staging_check.py` доступен в контейнере только через mount. Путь запуска внутри контейнера учитывать (не `/app/scripts`).
- **Перезапуск стадии вручную:** `update_task_stage(task_id, "<stage>")` + `enqueue_job(agent, repo, task_content, task_id)`. Guard перед этим: `agent_running IS NULL` И нет jobs со `status IN ('queued','running')` для task_id.
---
## 6. Итог по гейтам/ядру после серии ORCH-45/46/47/48
-`check_ci_green` — поллинг (ORCH-45)
-`check_tests_passed` — читает `result:` (ORCH-47)
-`stage_engine` — передаёт деву **текст** findings, не только ссылку (ORCH-46)
- ✅ B6 staging — читает реестр ВНУТРИ staging-контейнера, больше не ложный FAIL (ORCH-48) → **deploy-staging разблокирован для всех ORCH-задач**
Конвейер стал по-настоящему автономным: задача проходит analyst→deploy без ручного пинания стадий.

View File

@@ -36,34 +36,53 @@ Exit code: **0** = все PASS, **non-zero** = есть FAIL.
## Способы запуска
### 1. Внутри контейнера (рекомендуемый)
```bash
docker exec orchestrator-staging \
python3 /repos/orchestrator/scripts/staging_check.py --mode stub
```
### 2. С хоста (если есть токены в env)
```bash
export ORCH_STAGING=true
export ORCH_PLANE_API_TOKEN=...
# ... остальные переменные ...
python3 scripts/staging_check.py \
--base-url http://localhost:8501 \
--mode stub
```
### 3. Из docker exec с передачей URL
### 1. Внутри контейнера (КАНОНИЧЕСКИЙ — обязателен для деплоера)
```bash
docker exec orchestrator-staging \
python3 /repos/orchestrator/scripts/staging_check.py \
--base-url http://localhost:8501 \
--mode stub
--base-url http://localhost:8501 --mode stub
```
Это единственный канонический способ для стадии `deploy-staging` (ORCH-048, ADR-001).
Внутри контейнера env уже staging (`.env.staging`), а чек **B6** строит реестр проектов из
собственного process-env инстанса (см. ниже). Путь к скрипту — `/repos/orchestrator/scripts/…`
(bind-mount); `scripts/` **не** копируется в образ, поэтому `/app/scripts` не существует.
### 2. С хоста — НЕ рекомендуется
```bash
# ⚠️ Воспроизводит баг ORCH-048: на хосте ORCH_PROJECTS_JSON не задан →
# B6 строит реестр из дефолта (ET+ORCH) → ложный FAIL.
# Допустимо ТОЛЬКО если env хоста полностью повторяет staging (включая ORCH_PROJECTS_JSON).
export ORCH_STAGING=true
export ORCH_PROJECTS_JSON=... # обязателен, иначе B6 даст ложный FAIL
export ORCH_PLANE_API_TOKEN=...
# ... остальные переменные ...
python3 scripts/staging_check.py --base-url http://localhost:8501 --mode stub
```
---
## Механика чека B6 (ORCH-048, ADR-001)
B6 «Registry: sandbox present, prod ET/ORCH absent» подтверждает изоляцию: в реестре
работающего staging-инстанса есть только sandbox-проект и НЕТ боевых (ET/ORCH).
- B6 импортирует `known_plane_project_ids()` из `src.projects` **кода контейнера**
(`/app/src` через `PYTHONPATH=/app`), env которого — `.env.staging`. Реестр отражает
именно работающий staging-инстанс.
- Прежний host-path хак (`sys.path.insert(0, "/repos/orchestrator")` + `importlib.reload`)
удалён: он подхватывал env процесса-запускателя и при запуске с хоста давал ложный FAIL.
- Логика вердикта вынесена в чистую функцию `_evaluate_b6(known) -> (passed, detail)`:
`passed ⟺ SANDBOX ∈ known ∧ PROD_ET ∉ known ∧ PROD_ORCH ∉ known`. Покрыта юнит-тестами
(`tests/test_staging_check_b6.py`) на оба исхода без поднятия инстанса/docker.
- При недоступности источника реестра B6 даёт детерминированный FAIL (не ложный PASS,
не необработанное исключение).
**Поэтому B6 достоверен только при каноническом запуске (способ 1).**
---
## Режимы (`--mode`)

View File

@@ -0,0 +1,7 @@
# Business Request: Telegram live-tracker: режим bump (карточка падает вниз при обновлении)
Work Item ID: ORCH-042
## Description
TBD

View File

@@ -0,0 +1,65 @@
# 01 — BRD: Telegram live-tracker, режим bump + русификация карточки
**Work Item:** ORCH-042
**Тип:** UX-улучшение (notifications)
**Приоритет:** средний
**Запрос:** Слава, 05.06. Связь: `feat/telegram-live-tracker` (Variant B+).
**Self-hosting:** да — правка самого оркестратора, проходит через его же конвейер (общая БД/очередь с enduro-trails). См. `docs/operations/INFRA.md`.
## 1. Контекст и проблема
Live-tracker задачи (`src/notifications.py`) — это ОДНА карточка на задачу в Telegram, которая обновляется на каждом переходе стадии через `editMessageText` (Variant B+). Так сделано СПЕЦИАЛЬНО, чтобы убить старую проблему «~15 отдельных карточек/дублей на задачу».
Побочный эффект текущего решения: карточка редактируется **на месте в истории чата**. При активной переписке в чате карточка «тонет» вверху и её неудобно искать — приходится скроллить вверх к старому сообщению, чтобы увидеть актуальный статус задачи.
Дополнительно накопились косметические претензии к тексту карточки: смесь англоязычных меток стадий с русским текстом, неудачная формулировка «Ревью БРД», и финальный технический хвост `deployed` вместо человекочитаемого «Внедрено».
## 2. Цель
1. Дать Славе альтернативный режим отображения трекера — **bump**: при каждом обновлении карточка «падает вниз» свежим сообщением (всегда последняя в чате), но БЕЗ возврата к проблеме дублей (по-прежнему ОДНА карточка на задачу) и БЕЗ спама звуками/пингами.
2. Привести текст карточки к единому русскому виду и поправить формулировки.
## 3. Заинтересованные лица
- **Слава (Owner)** — единственный получатель Telegram-уведомлений; принимает UX.
- **Агенты конвейера** — косвенно: трекер обновляется из `notify_*`-хелперов на каждой стадии.
## 4. Требования (бизнес-уровень)
### 4.1. Режим работы трекера (флаг)
- **BR-1.** Новый конфиг-флаг `ORCH_TRACKER_MODE` с двумя значениями:
- `edit` — текущее поведение (редактирование на месте). **Это ДЕФОЛТ** (обратная совместимость, никакой регрессии без явного включения).
- `bump` — новый режим «карточка падает вниз».
- **BR-2.** Неизвестное/пустое значение флага трактуется как `edit` (безопасный фолбэк, оркестратор не падает).
### 4.2. Поведение режима bump
- **BR-3.** При обновлении карточки в режиме `bump`: старое сообщение удаляется (`deleteMessage`), отправляется новое (`sendMessage`), указатель `tracker_message_id` перенаправляется на новое сообщение. Итог: в чате всегда ровно ОДНА карточка задачи, и она всегда внизу.
- **BR-4.** Bump тихий: новое сообщение отправляется с `disable_notification=true` — карточка всплывает внизу, но БЕЗ звука/пинга на каждой стадии (как и сейчас в edit-режиме).
- **BR-5.** Первое обновление (карточки ещё нет) в режиме `bump` — просто тихо отправить новое и запомнить id (удалять нечего).
### 4.3. Устойчивость (критично — не сломать защиту от дублей)
- **BR-6.** Fallback: если `deleteMessage` не удался (сообщение старше 48 ч / уже удалено / недоступно) — карточка всё равно отправляется заново, оркестратор НЕ падает.
- **BR-7.** Любой сбой нотификации (сеть/таймаут/5xx/Telegram-ошибка) НЕ роняет оркестратор (контракт «never raises» сохраняется) и НЕ плодит дубли карточек в пределах одного обновления.
- **BR-8.** Режим `edit` после изменений работает строго как раньше — без регрессий (защита от ~15 дублей сохранена).
### 4.4. Текстовые правки карточки (применяются в ОБОИХ режимах)
- **BR-9.** Метку «Ревью БРД» заменить на «Подтверждение BRD».
- **BR-10.** После того как задача переведена в Approved (человеческий gate пройден, время ревью зафиксировано), эмодзи в строке подтверждения BRD заменить на галочку (✅) вместо текущей паузы (⏸️). Пока ждём человека — оставить прежний индикатор ожидания.
- **BR-11.** Русифицировать метки стадий карточки: `Analysis → Анализ`, `Architecture → Архитектура`, `Development → Разработка`, `Review → Код ревью`, `Testing → Тестирование`, `Deploy → Внедрение`.
- **BR-12.** В итоговой (последней) строке готовой задачи заменить технический `deployed` на «Внедрено».
## 5. Вне scope
- Изменение состава событий, которые шлются ОТДЕЛЬНЫМИ пингами (approve-gate / deploy-fail / agent-fail / error) — остаётся как есть.
- Изменение формата метрик (токены/стоимость/длительность), макета строк, логики «попытка N».
- Любые изменения в Plane-комментариях агентов (`usage.build_status_comment`).
- Хранение истории карточек / несколько карточек на задачу.
## 6. Влияние на документацию (golden source)
- `CHANGELOG.md` — запись в `[Unreleased]`.
- `docs/architecture/internals.md` (или соответствующая секция про live-tracker) — описать режимы `edit`/`bump` и `ORCH_TRACKER_MODE`.
- `.env.example` — добавить `ORCH_TRACKER_MODE` с пояснением.
## 7. Критерии успеха (резюме)
Слава может выставить `ORCH_TRACKER_MODE=bump` и видеть актуальную карточку всегда внизу чата, одну на задачу, без звона; при откате на `edit` (дефолт) поведение неотличимо от текущего; текст карточки полностью русифицирован по BR-9..BR-12. Полные условия PASS/FAIL — `03-acceptance-criteria.md`.
</content>
</invoke>

View File

@@ -0,0 +1,118 @@
# 02 — ТЗ: Telegram live-tracker, режим bump + русификация
**Work Item:** ORCH-042 · См. `01-brd.md`, `03-acceptance-criteria.md`.
## 1. Задействованные модули `src/`
| Файл | Что меняется |
|------|--------------|
| `src/config.py` | Новое поле `Settings.tracker_mode` (env `ORCH_TRACKER_MODE`). |
| `src/notifications.py` | Новый helper `delete_telegram(message_id)`; ветвление `update_task_tracker` по режиму; текстовые правки в `_BRD_LABEL`, `_TRACKER_STAGES`, BRD-строке `render_task_tracker`, `_done_link`. |
БД — **без изменений** (используется существующая колонка `tasks.tracker_message_id` и хелперы `get_tracker_message_id` / `set_tracker_message_id` в `src/db.py`). API HTTP-эндпоинты оркестратора — **без изменений**. Новые QG checks — **не требуются**.
## 2. Изменения конфигурации (`src/config.py`)
Добавить в класс `Settings` (рядом с блоком «Telegram notifications»):
```python
# ORCH-042: режим live-трекера задачи.
# edit -> карточка редактируется на месте (editMessageText), ДЕФОЛТ (как было).
# bump -> при обновлении старое сообщение удаляется и карточка отправляется
# заново вниз чата (deleteMessage + sendMessage + repoint message_id),
# тихо (disable_notification). Одна карточка на задачу в обоих режимах.
# Неизвестное/пустое значение трактуется как edit (см. notifications).
tracker_mode: str = "edit"
```
- `env_prefix = "ORCH_"` уже задан → переменная окружения `ORCH_TRACKER_MODE`.
- Резолюция режима — в `notifications`: всё, что не равно (case-insensitive, trimmed) `"bump"`, считается `edit`. Не падать на любом значении.
## 3. Изменения нотификаций (`src/notifications.py`)
### 3.1. Новый low-level helper `delete_telegram`
Рядом с `send_telegram` / `edit_telegram`. Контракт «never raises».
```python
def delete_telegram(message_id: int) -> bool:
"""Delete a Telegram message. Never raises.
Returns True if the message is gone after the call (deleted now, OR Telegram
says it's already not there / can't be deleted -> treat as "no longer our
problem", caller proceeds to send a fresh card). Returns False only on a
transient failure (network / timeout / 5xx / unknown error) where the old
message may still be alive.
"""
```
Требования к реализации:
- Эндпоинт `https://api.telegram.org/bot{token}/deleteMessage`, тело `{chat_id, message_id}`, `timeout=5`.
- Нет токена/chat_id → вернуть `False` (как и прочие helpers при отсутствии кредов — ничего не отправлено, ничего не удалено).
- `ok:true``True`.
- `ok:false` с описанием «уже нет / нельзя удалить» (маркеры: `"message to delete not found"`, `"message can't be deleted"`, `"message_id_invalid"`) → `True` (сообщение и так недоступно; не транзиент).
- Прочие `ok:false` (неизвестный 400 / 5xx) и исключения (сеть/таймаут) → `False` + `logger.warning`.
- Вынести маркеры в модульную константу (по аналогии с `_GONE_MARKERS`), например `_DELETE_GONE_MARKERS`.
### 3.2. Ветвление `update_task_tracker` по режиму
Сохранить существующий путь `edit` без изменений поведения. Добавить путь `bump`.
Псевдокод целевой логики:
```python
def update_task_tracker(task_id: int):
try:
from .db import get_tracker_message_id, set_tracker_message_id
text = render_task_tracker(task_id)
mode = (_get_settings().tracker_mode or "edit").strip().lower()
mid = get_tracker_message_id(task_id)
if mode == "bump":
# bump: одна карточка, но всегда внизу.
if mid is not None:
delete_telegram(mid) # best-effort; fallback -> всё равно шлём новое
new_mid = send_telegram(text, disable_notification=True)
if new_mid is not None:
set_tracker_message_id(task_id, new_mid)
# send вернул None (нет кредов / транзиент) -> mid не трогаем,
# дубля в пределах вызова нет; перерисуется на следующем переходе.
return
# mode == "edit" (ДЕФОЛТ): существующая логика без изменений.
... # текущий код edit/EDIT_GONE-fallback as is
except Exception as e:
logger.warning(f"update_task_tracker({task_id}) failed: {e}")
```
Инварианты bump-ветки:
- В пределах ОДНОГО вызова отправляется максимум одно новое сообщение → дублей нет (BR-7).
- `set_tracker_message_id` вызывается ТОЛЬКО при успешном `send` (`new_mid is not None`). При сбое send id остаётся прежним; на следующем переходе старый будет удалён (или уже мёртв) и отправлен новый — без накопления карточек.
- `delete_telegram` — best-effort: его результат НЕ блокирует отправку новой карточки (BR-6: delete-fail → всё равно шлём новое).
- Bump всегда тихий: `disable_notification=True` (BR-4).
### 3.3. Текстовые правки (общие для обоих режимов)
| BR | Где | Было | Стало |
|----|-----|------|-------|
| BR-9 | `_BRD_LABEL` (модульная константа) | `"Ревью БРД"` | `"Подтверждение BRD"` |
| BR-10 | `render_task_tracker`, ветка BRD-строки при `review_seconds is not None` | префикс `⏸️` (`⏸️`) | `✅` (`✅`). Ветка ожидания (`review_seconds is None`, с ⏳) — НЕ менять. |
| BR-11 | `_TRACKER_STAGES` (метки) | `Analysis / Architecture / Development / Review / Testing / Deploy` | `Анализ / Архитектура / Разработка / Код ревью / Тестирование / Внедрение` |
| BR-12 | `_done_link` | `"\U0001f4e6 deployed"` | `"\U0001f4e6 Внедрено"` |
Примечания:
- В `_TRACKER_STAGES` меняется ТОЛЬКО display-label (2-й элемент кортежа). Ключи стадий (`analysis`,…) и имена агентов (`analyst`,…) НЕ трогать — они завязаны на `_STAGE_ACTIVE_AGENT`, `last_done`, БД.
- Выравнивание `{label:<13}` и `{_BRD_LABEL:<13}` оставить как есть (все новые русские метки ≤13 символов; «Подтверждение BRD» длиннее — формат просто не паддит, косметика, поведение не ломает).
- Метки используются и в «✅ …»-строках завершённых стадий, и в «🔄 … идёт»-строке активной стадии — обе автоматически станут русскими (правка в одном месте).
## 4. Совместимость и риски
- Дефолт `edit` гарантирует нулевую регрессию без явного включения bump (BR-8). Подробно — `10-tech-risks.md` (заводит архитектор/девелопер при необходимости).
- Самохостинг: изменения только в коде нотификаций, миграций БД нет, перезапуск self — по стандартной страховке `deploy-staging` (8501) перед prod (см. `CLAUDE.md`).
## 5. Артефакты pipeline, которые ДОЛЖНЫ быть обновлены в этом же PR
- `CHANGELOG.md` → запись в `[Unreleased] / Added` (режим bump) + `Changed` (русификация текста).
- `docs/architecture/internals.md` — секция про live-tracker: режимы `edit`/`bump`, `ORCH_TRACKER_MODE`, контракт `delete_telegram`.
- `.env.example``ORCH_TRACKER_MODE=edit` с комментарием.
- Тесты — см. `04-test-plan.yaml`. **Существующие тесты в `tests/test_telegram_tracker.py`, проверяющие англоязычные метки (`"✅ Analysis"`, `"🔄 Deploy"`, `"Review"`) и метку `"Ревью БРД"`, ОБЯЗАТЕЛЬНО обновить под новые русские строки** — иначе регрессия в CI. Это правка существующих ассертов, не изменение контракта.
## 6. Замечания по реализации (без расширения scope)
- Не вводить новых зависимостей; `httpx` уже используется.
- Не менять сигнатуры `send_telegram` / `edit_telegram` / `update_task_tracker` (внешние вызовы из `launcher`/`stage_engine` не трогаются).
- Не менять состав отдельных пингов (approve-gate / error / deploy-fail / agent-fail).
</content>

View File

@@ -0,0 +1,55 @@
# 03 — Критерии приёмки: ORCH-042
Каждый критерий — однозначное условие PASS/FAIL. Покрытие тестами — `04-test-plan.yaml`.
## Конфигурация
- **AC-1.** `Settings.tracker_mode` существует, дефолт `"edit"`, читается из env `ORCH_TRACKER_MODE`.
- PASS: `Settings().tracker_mode == "edit"` без env; `ORCH_TRACKER_MODE=bump``"bump"`.
- FAIL: поле отсутствует / другой дефолт / не читает env.
- **AC-2.** Неизвестное/пустое значение режима трактуется как `edit` (оркестратор не падает).
- PASS: `ORCH_TRACKER_MODE=garbage` (или пусто) → `update_task_tracker` идёт по edit-ветке, исключений нет.
- FAIL: исключение / выбор bump-ветки на мусоре.
## Режим edit (регрессия — поведение как было)
- **AC-3.** Первый вызов (нет `tracker_message_id`): `sendMessage` тихо (`disable_notification=True`), id сохраняется; `editMessageText` НЕ вызывается.
- **AC-4.** Повторный вызов при живом сообщении: `editMessageText` на сохранённый id; новое сообщение НЕ шлётся.
- **AC-5.** `edit` вернул `EDIT_GONE` → шлётся НОВОЕ сообщение, id обновляется (fallback как раньше).
- **AC-6.** `edit` вернул `EDIT_NOT_MODIFIED` или `EDIT_FAILED` → новое сообщение НЕ шлётся, id не меняется (защита от дублей сохранена).
- Все AC-3..AC-6 проверяются при `tracker_mode="edit"` (дефолт). FAIL — любое расхождение с текущим поведением.
## Режим bump
- **AC-7.** Первый вызов в `bump` (нет id): `deleteMessage` НЕ вызывается; `sendMessage` тихо (`disable_notification=True`); возвращённый id сохраняется.
- PASS: ровно один `send_telegram(..., disable_notification=True)`, `delete_telegram` не вызван, `get_tracker_message_id == new_id`.
- FAIL: вызван delete / громкое сообщение / id не сохранён.
- **AC-8.** Повторный вызов в `bump` при существующем id: вызывается `delete_telegram(старый_id)`, затем `send_telegram(..., disable_notification=True)`, затем `tracker_message_id` перенаправляется на новый id.
- PASS: порядок delete→send соблюдён, id == новый.
- FAIL: нет delete / нет send / id остался старым.
- **AC-9.** Bump тихий: новое сообщение всегда с `disable_notification=True`.
- FAIL: `disable_notification` False/отсутствует.
- **AC-10.** Одна карточка на задачу: за один вызов `update_task_tracker` в bump шлётся НЕ более одного нового сообщения.
- FAIL: более одного `send_telegram` за вызов.
## Устойчивость
- **AC-11.** Fallback при delete-fail: если `delete_telegram` вернул False (старое >48ч / транзиент) — новое сообщение всё равно отправляется, id обновляется, исключений нет.
- PASS: `delete_telegram→False` → ровно один send → id == новый.
- FAIL: send пропущен / исключение всплыло.
- **AC-12.** `delete_telegram` классификация (httpx замокан, never raises):
- `ok:true``True`;
- `ok:false` с `"message to delete not found"` / `"message can't be deleted"` / `"message_id_invalid"``True`;
- неизвестный `ok:false` / 5xx → `False`;
- исключение (таймаут/сеть) → `False`;
- нет токена/chat_id → `False`, HTTP-вызов не выполняется.
- **AC-13.** Транзиентный сбой send в bump (send вернул None): `tracker_message_id` НЕ затирается на None; исключений нет; дублей нет (≤1 попытка send за вызов).
- **AC-14.** `update_task_tracker` никогда не выбрасывает исключение ни в одном режиме (контракт «never raises») при любых сбоях БД/сети/Telegram.
## Текстовые правки (оба режима)
- **AC-15.** Метка «Подтверждение BRD» присутствует в карточке там, где раньше была «Ревью БРД»; строки «Ревью БРД» в выводе нет.
- **AC-16.** После прохождения approve-gate (зафиксированы `brd_review_started_at` и `brd_review_ended_at`) строка подтверждения BRD начинается с ✅ (не ⏸️). Пока ждём человека (`brd_review_ended_at` пуст) — индикатор ожидания/⏳ сохраняется (не ✅).
- **AC-17.** Метки стадий в карточке русские: `Анализ`, `Архитектура`, `Разработка`, `Код ревью`, `Тестирование`, `Внедрение`. Английских меток (`Analysis`/`Architecture`/`Development`/`Review`/`Testing`/`Deploy`) в выводе нет — ни в «✅ …»-строках, ни в «🔄 … идёт».
- **AC-18.** Итоговая строка готовой задачи содержит «📦 Внедрено» (не «deployed»).
## Регрессия и качество
- **AC-19.** Состав отдельных пингов не изменён: `notify_approve_requested` шлёт ровно один НЕтихий пинг и стартует BRD-часы; `notify_error` — один НЕтихий пинг; `notify_stage_change` / `notify_agent_started` / `notify_qg_failure`НЕ шлют отдельных сообщений (только refresh трекера).
- **AC-20.** Вся существующая и новая pytest-сюита зелёная (`pytest tests/ -q`). Существующие ассерты в `tests/test_telegram_tracker.py` обновлены под русские метки и «Подтверждение BRD».
- **AC-21.** Документация обновлена в ТОМ ЖЕ PR: `CHANGELOG.md`, `docs/architecture/internals.md` (режимы + `ORCH_TRACKER_MODE` + `delete_telegram`), `.env.example` (`ORCH_TRACKER_MODE`). Отсутствие — REQUEST_CHANGES на ревью.
</content>

View File

@@ -0,0 +1,160 @@
work_item: ORCH-042
description: >
Режим bump live-трекера (delete+send+repoint, тихо, fallback, never-raises),
сохранение режима edit без регрессий, и текстовые правки карточки
(Подтверждение BRD, ✅ после approve, русские метки стадий, «Внедрено»).
Сеть не трогаем: httpx / низкоуровневые helpers мокаются; изолированная temp-БД.
tests:
# --- config ---
- id: TC-01
type: unit
description: "Settings.tracker_mode по умолчанию 'edit' и читается из ORCH_TRACKER_MODE (AC-1)"
module: tests/test_config.py
expected: PASS
- id: TC-02
type: unit
description: "Неизвестное/пустое значение режима -> update_task_tracker идёт по edit-ветке, без исключений (AC-2)"
module: tests/test_telegram_tracker.py
expected: PASS
# --- edit mode regression ---
- id: TC-03
type: unit
description: "edit: первый вызов -> sendMessage тихо, id сохранён, editMessageText не вызван (AC-3)"
module: tests/test_telegram_tracker.py
expected: PASS
- id: TC-04
type: unit
description: "edit: повторный вызов -> editMessageText на сохранённый id, нового send нет (AC-4)"
module: tests/test_telegram_tracker.py
expected: PASS
- id: TC-05
type: unit
description: "edit: EDIT_GONE -> отправка нового, id обновлён (AC-5)"
module: tests/test_telegram_tracker.py
expected: PASS
- id: TC-06
type: unit
description: "edit: EDIT_NOT_MODIFIED и EDIT_FAILED -> нового сообщения нет, id не меняется (AC-6)"
module: tests/test_telegram_tracker.py
expected: PASS
# --- bump mode ---
- id: TC-07
type: unit
description: "bump: первый вызов (нет id) -> delete не вызван, send тихий, id сохранён (AC-7, AC-9)"
module: tests/test_tracker_bump.py
expected: PASS
- id: TC-08
type: unit
description: "bump: повторный вызов -> delete(старый) затем send(тихо), id перенаправлен на новый, порядок delete->send (AC-8, AC-9, AC-10)"
module: tests/test_tracker_bump.py
expected: PASS
- id: TC-09
type: unit
description: "bump fallback: delete_telegram->False -> новое всё равно отправлено, id обновлён, без исключений (AC-11)"
module: tests/test_tracker_bump.py
expected: PASS
- id: TC-10
type: unit
description: "bump: send вернул None (транзиент) -> id не затёрт на None, ровно одна попытка send, без исключений (AC-13)"
module: tests/test_tracker_bump.py
expected: PASS
- id: TC-11
type: unit
description: "bump: одна карточка за вызов -> send_telegram вызван <=1 раза (AC-10)"
module: tests/test_tracker_bump.py
expected: PASS
# --- delete_telegram classification ---
- id: TC-12
type: unit
description: "delete_telegram: ok:true -> True (httpx замокан)"
module: tests/test_tracker_bump.py
expected: PASS
- id: TC-13
type: unit
description: "delete_telegram: ok:false 'message to delete not found' / 'message can't be deleted' / 'message_id_invalid' -> True (AC-12)"
module: tests/test_tracker_bump.py
expected: PASS
- id: TC-14
type: unit
description: "delete_telegram: неизвестный ok:false / 5xx -> False (AC-12)"
module: tests/test_tracker_bump.py
expected: PASS
- id: TC-15
type: unit
description: "delete_telegram: исключение (таймаут/сеть) -> False, never raises (AC-12, AC-14)"
module: tests/test_tracker_bump.py
expected: PASS
- id: TC-16
type: unit
description: "delete_telegram: нет токена/chat_id -> False, HTTP не вызывается (AC-12)"
module: tests/test_tracker_bump.py
expected: PASS
# --- never raises ---
- id: TC-17
type: unit
description: "update_task_tracker никогда не бросает (DB/сеть сбой) в обоих режимах (AC-14)"
module: tests/test_tracker_bump.py
expected: PASS
# --- text changes ---
- id: TC-18
type: unit
description: "render: метка 'Подтверждение BRD' присутствует, 'Ревью БРД' отсутствует (AC-15)"
module: tests/test_telegram_tracker.py
expected: PASS
- id: TC-19
type: unit
description: "render: approve-gate пройден (brd_review_ended_at задан) -> строка BRD с ✅, не ⏸️ (AC-16)"
module: tests/test_telegram_tracker.py
expected: PASS
- id: TC-20
type: unit
description: "render: ожидание человека (brd_review_ended_at пуст) -> индикатор ожидания/⏳, не ✅ (AC-16)"
module: tests/test_telegram_tracker.py
expected: PASS
- id: TC-21
type: unit
description: "render: русские метки стадий (Анализ/Архитектура/Разработка/Код ревью/Тестирование/Внедрение), английских нет — в ✅- и 🔄-строках (AC-17)"
module: tests/test_telegram_tracker.py
expected: PASS
- id: TC-22
type: unit
description: "render done: итоговая строка содержит '📦 Внедрено', не 'deployed' (AC-18)"
module: tests/test_telegram_tracker.py
expected: PASS
# --- separate alerts regression ---
- id: TC-23
type: unit
description: "Состав отдельных пингов не изменён: approve-gate/error шлют 1 нетихий пинг; stage_change/agent_started/qg_failure не шлют (AC-19)"
module: tests/test_telegram_tracker.py
expected: PASS
# --- full suite ---
- id: TC-24
type: integration
description: "Вся pytest-сюита зелёная; обновлённые ассерты под русские метки проходят (AC-20)"
module: tests/
expected: PASS
</content>

View File

@@ -0,0 +1,85 @@
# ADR-001: Режим bump live-трекера через delete+send+repoint, edit как дефолт
**Work Item:** ORCH-042 · См. `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `10-tech-risks.md`.
## Статус
Accepted
## Контекст
Live-tracker (`src/notifications.py`, ветка `feat/telegram-live-tracker`, Variant B+) держит **ОДНУ** карточку на задачу и редактирует её на месте (`editMessageText`) на каждом переходе стадии. Это сознательно убило прежнюю боль — «~15 отдельных карточек/дублей на задачу». Защита от дублей — главный инвариант компонента и не должна регрессировать.
Побочный эффект edit-режима: при активной переписке в чате карточка «тонет» вверху истории — актуальный статус задачи приходится искать скроллом. Слава просит альтернативу: карточка должна всегда быть последней в чате, но без возврата дублей и без звона на каждой стадии.
Дополнительно — косметика текста карточки (смесь EN-меток стадий с RU-текстом, «Ревью БРД», технический хвост `deployed`). Текстовые правки тривиальны и сами по себе архитектурного решения не требуют; ключевое решение — как реализовать новый режим, не сломав инвариант «одна карточка».
Ограничения окружения (см. `CLAUDE.md`, `docs/operations/INFRA.md`):
- Контракт компонента: `update_task_tracker` и low-level helpers **никогда не бросают** (сбой нотификации не должен валить конвейер).
- Self-hosting: правка инструмента, который сейчас в проде и обслуживает другие проекты из общей БД/очереди. Прод-рестарт self — только через `deploy-staging` (8501).
- Telegram Bot API: `deleteMessage` не работает для сообщений старше 48 ч и для уже удалённых/недоступных — это нормальный ожидаемый исход, а не ошибка.
## Решение
### Р-1. Поведение задаётся конфиг-флагом, дефолт `edit` (нулевая регрессия)
Новое поле `Settings.tracker_mode` (env `ORCH_TRACKER_MODE`), значения `edit` | `bump`, **дефолт `edit`**. Резолюция режима — в `notifications`, case-insensitive + trim; всё, что не равно `"bump"` (включая пустое/мусор/None), трактуется как `edit`. Без явного включения bump поведение неотличимо от текущего → нулевая регрессия и безопасный фолбэк (оркестратор не падает на любом значении флага).
### Р-2. Режим bump = delete + send + repoint, инвариант «одна карточка» сохраняется иначе
edit-режим держит одну карточку, *редактируя* её. bump держит одну карточку, *пересоздавая* её внизу:
1. если сохранён `tracker_message_id` — best-effort `delete_telegram(старый_id)`;
2. `send_telegram(text, disable_notification=True)` — новая карточка внизу, тихо;
3. при успехе (`new_mid is not None`) — `set_tracker_message_id` перенаправляется на новый id.
Итог: в чате всегда ровно одна карточка задачи, и она всегда последняя. За **один** вызов `update_task_tracker` отправляется **не более одного** нового сообщения → дублей в пределах вызова нет.
### Р-3. delete — best-effort, никогда не блокирует отправку новой карточки
Новый low-level helper `delete_telegram(message_id) -> bool` с контрактом «never raises». Семантика возврата — «исчезло ли старое сообщение»:
- `ok:true``True`;
- `ok:false` с маркерами «уже нет / нельзя удалить» (`message to delete not found`, `message can't be deleted`, `message_id_invalid`, вынести в константу `_DELETE_GONE_MARKERS`) → `True` (не транзиент, сообщение и так недоступно);
- прочий `ok:false` / 5xx / исключение (сеть/таймаут) → `False` + `logger.warning`;
- нет токена/chat_id → `False`, HTTP не выполняется.
**Результат `delete_telegram` НЕ влияет на решение отправлять новую карточку** — её шлём всегда (BR-6: delete-fail у сообщения >48 ч → всё равно новое). `False` означает лишь «старое, возможно, ещё живо»; на следующем переходе оно будет удалено повторно (или уже мёртво). Накопления карточек это не даёт, т.к. указатель всегда хранит ровно один id.
### Р-4. repoint только при успешном send (анти-затирание указателя)
`set_tracker_message_id` вызывается **только** при `new_mid is not None`. Если send вернул None (нет кредов / транзиент 5xx/таймаут) — id **не трогаем** (не затираем на None): карточка перерисуется на следующем переходе, дубля нет (≤1 попытка send за вызов). Это симметрично существующему edit-fallback, который тоже не плодит сообщения при транзиенте.
### Р-5. bump всегда тихий
Новая карточка отправляется с `disable_notification=True` — всплывает внизу, но без звука/пинга, как и edit сейчас. Состав отдельных НЕтихих пингов (approve-gate / error / deploy-fail / agent-fail) не меняется (вне scope).
### Р-6. Текстовые правки — в одной точке, общие для обоих режимов
Правки (`_BRD_LABEL` → «Подтверждение BRD»; ✅ вместо ⏸️ после approve-gate; русские display-labels в `_TRACKER_STAGES`; `_done_link` → «Внедрено») затрагивают только **отображаемые** строки. Ключи стадий (`analysis`, …) и имена агентов (`analyst`, …) НЕ меняются — они завязаны на `_STAGE_ACTIVE_AGENT`, `last_done`, БД. Правка `_TRACKER_STAGES` в одном месте автоматически русифицирует и «✅ …», и «🔄 … идёт».
### Что НЕ меняется (границы решения)
- БД: миграций нет, используется существующая колонка `tasks.tracker_message_id` и хелперы `get_tracker_message_id` / `set_tracker_message_id`. → `08-data-requirements.md` не требуется.
- Инфраструктура / топология / порты / контейнеры — без изменений. → `07-infra-requirements.md` не требуется.
- State machine (`src/stages.py`), реестр QG (`src/qg/checks.py`), стадии, компоненты — без изменений. → глобальный (cross-cutting) ADR не требуется, решение локально для компонента notifications.
- Сигнатуры `send_telegram` / `edit_telegram` / `update_task_tracker` — без изменений (внешние вызовы из `launcher`/`stage_engine` не трогаются).
- Новых зависимостей нет (`httpx` уже используется).
## Альтернативы
- **A1. Только bump, без флага.** Отклонено: ломает обратную совместимость и единственного пользователя (Слава может предпочесть edit); рост риска регрессии защиты от дублей. Флаг с дефолтом `edit` даёт мгновенный откат.
- **A2. Pin-сообщение (закрепить карточку).** Отклонено: pin не решает «карточка внизу при переписке», шлёт системное уведомление о закреплении (звон), и усложняет API-контракт. Вне духа «тихого» трекера.
- **A3. send-then-delete (сначала новое, потом удалить старое).** Отклонено как дефолтный порядок: в окне между send и delete в чате видны ДВЕ карточки; при падении на delete остаётся осиротевшая старая → визуальный дубль. delete-then-send гарантирует ≤1 карточку в любой момент при нормальном пути и ≤1 *новую* отправку за вызов в любом случае.
- **A4. Хранить историю/несколько карточек.** Вне scope и противоречит исходному инварианту «одна карточка».
## Последствия
**Плюсы**
- Слава получает актуальную карточку всегда внизу чата, одну на задачу, без звона.
- Нулевая регрессия по умолчанию (edit), мгновенный откат флагом.
- Контракт «never raises» и инвариант «одна карточка» сохранены в обоих режимах.
- Изменения локальны (`config.py` + `notifications.py`), без миграций и без рестарта-критичных зависимостей.
**Минусы / ограничения**
- bump расходует Telegram API на 2 запроса вместо 1 (delete + send) на переход — для одного получателя несущественно (rate-limit Telegram не угрожает).
- При транзиентном delete-fail возможна кратко осиротевшая старая карточка до следующего перехода (она будет вычищена попыткой delete на следующем апдейте) — приемлемо, дублей всё равно не плодит.
- bump теряет визуальную «эволюцию на месте» edit-режима (история чата получает по карточке-замене) — но в чате всегда одна актуальная, что и требуется.
**Риски** — см. `10-tech-risks.md`.
## Связи
- BRD/ТЗ/AC: `docs/work-items/ORCH-042/01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`; тест-план `04-test-plan.yaml`.
- Компонент: live-tracker (`src/notifications.py`), `feat/telegram-live-tracker` (Variant B+).
- Контекст self-hosting / staging-страховка: `CLAUDE.md`, `docs/operations/INFRA.md`, `docs/architecture/adr/adr-0003-staging-gate.md`.
- Обновляемая дока (в том же PR, стадия development): `CHANGELOG.md`, `docs/architecture/internals.md` (секция live-tracker: режимы + `ORCH_TRACKER_MODE` + `delete_telegram`), `.env.example`.

View File

@@ -0,0 +1,21 @@
# 10 — Технические риски: ORCH-042
См. `02-trz.md`, `06-adr/ADR-001-tracker-bump-mode.md`, `03-acceptance-criteria.md`.
Шкала: Вероятность × Влияние ∈ {низк., сред., выс.}.
| # | Риск | Вер. | Влияние | Митигация | Контроль (AC/TC) |
|---|------|------|---------|-----------|-------------------|
| R-1 | **Регрессия защиты от дублей** — рефактор `update_task_tracker` ломает edit-ветку, возвращается боль «~15 карточек». | низк. | выс. | edit — дефолт и неизменяемая ветка; bump добавляется отдельной веткой `if mode == "bump"`, edit-код не трогается. Полное покрытие edit-регрессии тестами. | AC-3..AC-6, AC-8; TC-03..TC-06, TC-24 |
| R-2 | **Двойная отправка / накопление карточек в bump** — delete и send рассинхронизированы, в чате >1 карточки. | низк. | сред. | Инвариант: ≤1 `send_telegram` за вызов; `set_tracker_message_id` только при успешном send; delete best-effort и не блокирует. | AC-8, AC-10, AC-11; TC-08, TC-09, TC-11 |
| R-3 | **Затирание `tracker_message_id` на None** при транзиентном send-fail → потеря указателя, следующий апдейт не найдёт старое. | низк. | сред. | repoint только при `new_mid is not None`; при None id сохраняется как есть. | AC-13; TC-10 |
| R-4 | **Нарушение контракта «never raises»** — исключение из `delete_telegram`/новой ветки валит конвейер (групповой риск из-за общей очереди). | низк. | выс. | `delete_telegram` обёрнут try/except → bool; внешний try/except в `update_task_tracker` сохранён; сеть/httpx мокаются в тестах. | AC-12, AC-14; TC-12..TC-17 |
| R-5 | **Ложная классифик. delete-ответа** — неизвестный `ok:false` принят за «исчезло» (или наоборот), вечные ретраи/тишина. | низк. | низк. | Явные `_DELETE_GONE_MARKERS` → True; всё прочее (включая 5xx) → False; повтор delete на следующем апдейте безопасен (идемпотентно). | AC-12; TC-13, TC-14 |
| R-6 | **Падение CI на старых ассертах** — тесты `tests/test_telegram_tracker.py` проверяют EN-метки/«Ревью БРД». | сред. | сред. | ТЗ §5 явно требует обновить существующие ассерты под русские метки и «Подтверждение BRD» в том же PR. | AC-20; TC-18, TC-21, TC-24 |
| R-7 | **Сломанная human-gate индикация** — ✅ показан до прохождения approve-gate (ввод в заблуждение). | низк. | низк. | ✅ только при заданном `brd_review_ended_at`; ветка ожидания (`review_seconds is None`, ⏳) не меняется. | AC-16; TC-19, TC-20 |
| R-8 | **Скрытая зависимость от display-label** — русификация `_TRACKER_STAGES` ломает логику, завязанную на текст метки. | низк. | сред. | Меняется только 2-й элемент кортежа (label); ключи стадий и имена агентов (`_STAGE_ACTIVE_AGENT`, `last_done`, БД) не трогаются. | AC-17; TC-21 |
| R-9 | **Self-hosting: прод-сбой при выкатке self** — общая БД/очередь, рестарт орка останавливает все проекты. | низк. | выс. | Изменения только в коде нотификаций, миграций БД нет; обязательная страховка `deploy-staging` (8501) перед prod (CLAUDE.md, INFRA.md, adr-0003). Дефолт edit → даже при выкатке поведение не меняется без явного флага. | стадия deploy-staging; `check_staging_status` |
| R-10 | **Документация не обновлена** в том же PR (internals.md / .env.example / CHANGELOG) → REQUEST_CHANGES. | сред. | низк. | ТЗ §5 и AC-21 фиксируют список; reviewer проверяет наличие. | AC-21 |
## Сводный вывод
Все риски — **низкие по вероятности** при соблюдении инвариантов из ADR-001 (edit-дефолт, ≤1 send/вызов, repoint-only-on-success, never-raises, правка только display-label). Остаточный групповой self-hosting-риск (R-9) полностью покрывается обязательным `deploy-staging`-гейтом и тем, что дефолтное поведение не меняется. Блокеров для перехода на стадию development нет.

View File

@@ -0,0 +1,56 @@
---
type: review
work_item_id: ORCH-042
verdict: APPROVED
version: 1
---
# Review ORCH-042
## Summary
Telegram live-tracker: добавлен режим `bump` (`ORCH_TRACKER_MODE` / `Settings.tracker_mode`, дефолт `edit`) + русификация и косметика карточки. Реализация точно соответствует `02-trz.md` и `06-adr/ADR-001-tracker-bump-mode.md`. Все 21 критерий приёмки покрыты; `pytest tests/ -q`**494 passed**. Документация обновлена в том же PR. Замечаний уровня P0/P1/P2 нет.
## Проверка по осям
### 1. Соответствие ТЗ
- `Settings.tracker_mode = "edit"` + env `ORCH_TRACKER_MODE` — есть (config.py).
- `delete_telegram(message_id) -> bool` — контракт «never raises», `_DELETE_GONE_MARKERS` вынесены в константу, классификация ok/gone/transient/no-creds реализована дословно по ТЗ §3.1.
- Ветвление `update_task_tracker`: bump = delete(best-effort) → send(silent) → repoint только при `new_mid is not None`; edit-ветка сохранена без изменений (§3.2). Инварианты bump (≤1 send/вызов, анти-затирание указателя, delete не блокирует send, всегда тихо) соблюдены.
- Текстовые правки BR-9..BR-12 (`_BRD_LABEL`→«Подтверждение BRD», ✅ вместо ⏸️ после approve-gate, русские display-labels `_TRACKER_STAGES`, `_done_link`→«Внедрено») — на месте; ключи стадий и имена агентов не тронуты.
- БД, API, сигнатуры helpers, зависимости — без изменений (как и требовалось).
### 2. Соответствие ADR (ADR-001)
Реализация соответствует решениям Р-1..Р-6: флаг с дефолтом edit (нулевая регрессия), delete+send+repoint, best-effort delete, repoint только при успешном send, всегда тихий bump, текст в одной точке. Выбран порядок delete-then-send (A3 отклонён обоснованно). Глобальные ADR не нарушены; решение локально для компонента notifications, что зафиксировано в ADR.
### 3. Качество кода
- Defensive-контракты «never raises» соблюдены и в helper, и в `update_task_tracker`.
- Docstrings содержательные; логирование (`debug`/`warning`) корректно разнесено по случаям.
- Security/утечек нет; новых зависимостей нет.
### 4. Качество тестов
- `tests/test_config.py` (AC-1), `tests/test_tracker_bump.py` (AC-7..AC-14: ордеринг delete→send, delete-fail, send=None, ≤1 send, классификация delete_telegram, never-raises), `tests/test_telegram_tracker.py` (AC-2 garbage→edit, AC-15..AC-18 русификация, регрессия edit).
- Существующие англоязычные ассерты обновлены под русские метки и «Подтверждение BRD» (AC-20).
- Тесты содержательные, не тривиальные. `pytest tests/ -q` → 494 passed.
## Findings
### P0 — Blocker
- нет
### P1 — Must fix
- нет
### P2 — Should fix
- нет
### P3 — Nice to have
- [ ] В `_TRACKER_STAGES` строчные комментарии-дубли (`# Анализ` и т.п.) после уже русских меток избыточны — косметика, на поведение не влияет.
## Документация
Обновлена в том же PR, полностью соответствует AC-21:
- `CHANGELOG.md` — записи в `[Unreleased] / Added` (bump-режим + `delete_telegram`) и `Changed` (русификация). ✅
- `docs/architecture/internals.md` — новая секция «Live Telegram tracker»: режимы edit/bump (таблица), `ORCH_TRACKER_MODE`, контракт `delete_telegram`, текстовые правки. ✅
- `.env.example``ORCH_TRACKER_MODE=edit` с комментарием. ✅
- ADR заведён: `06-adr/ADR-001-tracker-bump-mode.md`. ✅
Изменения `src/` (config.py, notifications.py) полностью отражены в документации — правило «документация = golden source» выполнено.

View File

@@ -0,0 +1,78 @@
---
type: test-report
work_item_id: ORCH-042
result: PASS
---
# Test Report — ORCH-042
Telegram live-tracker: режим `bump` (delete+send+repoint, тихо, fallback, never-raises),
сохранение режима `edit` без регрессий, русификация карточки.
## Окружение
- Python: 3.12.13
- pytest: 8.3.3
- Ветка: feature/ORCH-042-telegram-live-tracker-bump
- Дата: 2026-06-06
- Prod orchestrator (8500): `/health``{"status":"ok"}`, активна задача #40 (ORCH-042, stage=testing)
## Smoke test API
| Endpoint | Результат |
|----------|-----------|
| GET /health | PASS — `{"status":"ok","service":"orchestrator"}` |
| GET /status | PASS — активная задача ORCH-042 (stage=testing) |
| GET /queue | PASS — queued:0 running:1 done:99 failed:0, breaker=closed |
(`curl` в окружении недоступен — smoke выполнен через `urllib`.)
## Результаты по тест-плану (04-test-plan.yaml)
| TC ID | Описание | AC | Результат |
|-------|----------|----|-----------|
| TC-01 | Settings.tracker_mode дефолт 'edit', читается из ORCH_TRACKER_MODE | AC-1 | PASS |
| TC-02 | Мусорное/пустое значение → edit-ветка, без исключений | AC-2 | PASS |
| TC-03 | edit: первый вызов → send тихо, id сохранён, edit не вызван | AC-3 | PASS |
| TC-04 | edit: повтор → editMessageText на сохранённый id, нового send нет | AC-4 | PASS |
| TC-05 | edit: EDIT_GONE → отправка нового, id обновлён | AC-5 | PASS |
| TC-06 | edit: EDIT_NOT_MODIFIED/EDIT_FAILED → нового нет, id не меняется | AC-6 | PASS |
| TC-07 | bump: первый вызов → delete не вызван, send тихий, id сохранён | AC-7,9 | PASS |
| TC-08 | bump: повтор → delete(старый)→send(тихо)→repoint, порядок соблюдён | AC-8,9,10 | PASS |
| TC-09 | bump fallback: delete→False → новое всё равно отправлено | AC-11 | PASS |
| TC-10 | bump: send=None → id не затёрт, ≤1 send | AC-13 | PASS |
| TC-11 | bump: одна карточка за вызов (send ≤1) | AC-10 | PASS |
| TC-12 | delete_telegram: ok:true → True | AC-12 | PASS |
| TC-13 | delete_telegram: gone-маркеры → True | AC-12 | PASS |
| TC-14 | delete_telegram: неизвестный ok:false / 5xx → False | AC-12 | PASS |
| TC-15 | delete_telegram: исключение → False, never raises | AC-12,14 | PASS |
| TC-16 | delete_telegram: нет кредов → False, HTTP не вызван | AC-12 | PASS |
| TC-17 | update_task_tracker never raises (оба режима) | AC-14 | PASS |
| TC-18 | render: «Подтверждение BRD» есть, «Ревью БРД» нет | AC-15 | PASS |
| TC-19 | render: approve-gate пройден → строка BRD с ✅ | AC-16 | PASS |
| TC-20 | render: ожидание человека → ⏳, не ✅ | AC-16 | PASS |
| TC-21 | render: русские метки стадий, английских нет | AC-17 | PASS |
| TC-22 | render done: «📦 Внедрено», не «deployed» | AC-18 | PASS |
| TC-23 | состав отдельных пингов не изменён | AC-19 | PASS |
| TC-24 | вся pytest-сюита зелёная | AC-20 | PASS |
Все 24 тест-кейса плана покрыты и пройдены. Критерии AC-1..AC-20 подтверждены
тестами; AC-21 (документация) подтверждён на ревью (12-review.md, verdict APPROVED).
## Вывод pytest
Целевые модули ORCH-042:
```
tests/test_config.py tests/test_telegram_tracker.py tests/test_tracker_bump.py
52 passed, 1 warning in 1.38s
```
Полный регресс:
```
======================== 494 passed, 1 warning in 8.57s ========================
```
(Единственный warning — PydanticDeprecatedSince20 в `src/config.py:4`, не связан с
ORCH-042, существовал ранее, на результат не влияет.)
## Итог
**PASS** — полный регресс 494/494 зелёный, целевые модули 52/52 PASS, smoke API OK.
Задача готова к стадии deploy-staging.

View File

@@ -0,0 +1,58 @@
---
staging_status: SUCCESS
timestamp: 2026-06-06T10:19:10+00:00
base_url: http://localhost:8501
work_item: ORCH-042
mode: stub
checks: 10/10 PASS
---
# Staging Gate Log — ORCH-042
Staging test suite completed against the live staging environment
(`orchestrator-staging`, port 8501). All checks passed.
## Execution
Canonical procedure (ORCH-048, ADR-001): run **inside** the
`orchestrator-staging` container so the B6 registry-isolation check reads the
registry from the running instance's own process-env (`.env.staging`).
```
docker exec orchestrator-staging \
python3 /repos/orchestrator/scripts/staging_check.py \
--base-url http://localhost:8501 --mode stub
```
(Executed via the Docker Engine API over the mounted unix socket, since no
docker CLI is present in the agent environment; equivalent to the canonical
`docker exec`.)
**Exit code: 0 → staging_status: SUCCESS**
## Results — 10/10 PASS
### Block A — SMOKE
- ✓ A1 GET /health → 200 status=ok
- ✓ A2 GET /queue → 200 with counts/max_concurrency/resilience
- ✓ A3 ORCH_STAGING=true (not prod)
### Block B — ACCESS
- ✓ B4 Plane: sandbox project accessible (5 projects, sandbox=YES)
- ✓ B5 Gitea: orchestrator-sandbox accessible, push=true
- ✓ B6 Registry: sandbox present, prod ET/ORCH absent (isolation confirmed)
### Block C — E2E (mode=stub)
- ✓ C7 Create issue in Plane SANDBOX (HTTP 201)
- ✓ C8 Trigger pipeline via /webhook/plane (HTTP 200, HMAC)
- ✓ C9a Branch appears in orchestrator-sandbox
- ✓ C9b Analyst job enqueued in staging queue
### Cleanup
- ✓ Branch deleted, Plane issue deleted, staging DB job/task rows removed.
```
============================================================
RESULT: 10/10 checks PASS
============================================================
```

View File

@@ -0,0 +1,90 @@
---
deploy_status: SUCCESS
timestamp: 2026-06-06T08:44:04Z
work_item: ORCH-044
branch: feature/ORCH-044-preflight-auth-effort
commit: 08ace892bbf1809a65c1dc504459d052bfd71f79
target_service: orchestrator
target_port: 8500
deploy_mode: artifact-only
staging_gate: SUCCESS
prod_container_restarted: false
rebuild_required: true
---
# Deploy Log — ORCH-044
## Verdict
**`deploy_status: SUCCESS`** — артефактный (artifact-only) деплой-вердикт.
Реальный `git pull` + `docker compose ... --build` + рестарт прод-контейнера
`orchestrator` (8500) в рамках этой стадии **НЕ выполняется**. Он делегирован
хуку `scripts/orchestrator-deploy-hook.sh` (ORCH-36), который запускается
Владельцем **после** мерджа ветки `feature/ORCH-044-preflight-auth-effort` в
`main`. Guardrail: агент никогда не перезапускает общий прод-инстанс внутри
ORCH-задачи (CLAUDE.md / INFRA.md §Self-hosting).
## Pre-conditions (все ✓)
| Артефакт | Поле | Значение |
|----------|------|----------|
| `12-review.md` | `verdict` | `APPROVED` |
| `13-test-report.md` | `result` | `PASS` |
| `15-staging-log.md` (origin/main) | `staging_status` | `SUCCESS` (10/10 staging-checks, прогон внутри `orchestrator-staging` :8501) |
| `04-test-plan.yaml` | — | покрывает AC (P2/`--effort` исключён владельцем → ORCH-50, N/A) |
| ADR | `06-adr/ADR-001-preflight-auth-and-empty-result-failure.md` | заведён |
| `CHANGELOG.md` | — | обновлён |
Стадия `deploy` достижима только потому, что условный staging-гейт
(`check_staging_status`, реальный для self-hosting repo=orchestrator) — зелёный.
## Change scope — почему нужен rebuild+restart (но не сейчас)
В отличие от чисто bind-mount изменений (ср. ORCH-048), ORCH-044 меняет
**рантайм-код `src/`**, который копируется в образ (`/app/src`) и исполняется
прод-процессом:
| Файл | Тип | Как доезжает до прода |
|------|-----|------------------------|
| `src/preflight.py` | runtime (в образе) | требует **rebuild + restart** контейнера |
| `src/agents/launcher.py` | runtime (в образе) | требует **rebuild + restart** контейнера |
| `src/config.py` | runtime (в образе) | требует **rebuild + restart** контейнера |
| `docs/**`, `CHANGELOG.md` | docs | мерж в `main` |
| `tests/**` | тесты, не деплоятся | n/a |
`rebuild_required: true`. Чтобы новый token-free auth-гейт preflight и
«пустой лог ⇒ провал» вступили в силу на проде, прод-инстанс `orchestrator`
(8500) должен быть пересобран и перезапущен. **Это делает Владелец через
деплой-хук после мерджа**, не данный агент.
## Self-hosting policy
> ORCH-044 правит слой запуска агента (preflight/launcher/config) того самого
> инструмента, который СЕЙЧАС обслуживает все прод-проекты (orchestrator +
> enduro-trails) из одного инстанса `orchestrator:8500` с общей БД и общей
> очередью.
Поэтому в рамках этой стадии:
- **Прод-контейнер `orchestrator` (8500) НЕ трогался** — ни рестарта, ни
пересборки (групповой риск для всех проектов).
- **Деплой-хук** `scripts/orchestrator-deploy-hook.sh` (реальный docker/SSH)
**не запускался** этим агентом (не было явной инструкции Owner; зарезервирован
за ним, ORCH-36). У хука есть health-цикл (10×6с) + авто-rollback —
страховка на момент боевого rebuild+restart.
- **Страховка пройдена:** staging (8501, изолированная БД/реестр) — зелёный
перед прод-деплоем (ORCH-35).
## Deploy action
- **Prod rebuild/restart:** требуется (`src/` изменён), **не выполнен** этим
агентом (guardrail self-hosting). Выполняется Владельцем через деплой-хук
после мерджа в `main`.
- **Эффективный rollout:** мерж ветки в `main` → Owner запускает
`scripts/orchestrator-deploy-hook.sh` (прод-режим: `TARGET_SERVICE=orchestrator
TARGET_PORT=8500 COMPOSE_PROFILE=""`) с health-check + авто-rollback.
## Verdict
`deploy_status: SUCCESS` — все гейты зелёные, артефакт-вердикт зафиксирован,
боевой rebuild+restart делегирован Owner-хуку. Прод-инстанс не затронут.

View File

@@ -0,0 +1,49 @@
---
staging_status: SUCCESS
timestamp: 2026-06-06T08:41:49Z
base_url: http://localhost:8501
---
# Staging Gate Log
Staging test suite completed. All checks passed (10/10).
- Work item: ORCH-044
- Repo: orchestrator (self-hosting → staging gate is real, not a no-op)
- Container: `orchestrator-staging` (port 8501)
- Command (canonical, ran INSIDE the container so B6 reads the instance's own `.env.staging` process-env):
`python3 /repos/orchestrator/scripts/staging_check.py --base-url http://localhost:8501 --mode stub`
- Exit code: 0
## Results
```
[Block A] SMOKE
✓ PASS A1 GET /health → 200 status=ok
✓ PASS A2 GET /queue → 200 with counts/max_concurrency/resilience
✓ PASS A3 ORCH_STAGING=true (not prod)
[Block B] ACCESS
✓ PASS B4 Plane: sandbox project accessible
✓ PASS B5 Gitea: orchestrator-sandbox accessible, push=true
✓ PASS B6 Registry: sandbox present, prod ET/ORCH absent
[Block C] E2E (mode=stub)
✓ PASS C7 Create issue in Plane SANDBOX
✓ PASS C8 Trigger pipeline via /webhook/plane
✓ PASS C9a Branch appears in orchestrator-sandbox
✓ PASS C9b Analyst job enqueued in staging queue
[CLEANUP]
✓ PASS CLEANUP: deleted branch in orchestrator-sandbox
✓ PASS CLEANUP: deleted Plane issue
✓ PASS CLEANUP DB: deleted job + task rows
RESULT: 10/10 checks PASS
```
> Note: the host in this environment lacks the `docker` CLI, so the canonical
> `docker exec orchestrator-staging ...` was performed via the Docker Engine API
> over `/var/run/docker.sock` (Python stdlib, no host-env leakage). Semantics are
> identical to `docker exec`: the script ran inside `orchestrator-staging` with
> its own `.env.staging` process-env, keeping the B6 registry-isolation check valid.

View File

@@ -0,0 +1,7 @@
# Business Request: stage_engine: pass reviewer/tester findings text to developer (not just link)
Work Item ID: ORCH-046
## Description
TBD

View File

@@ -0,0 +1,86 @@
# BRD — ORCH-046: pass reviewer/tester findings text to developer (not just link)
Work Item ID: ORCH-046
Stage: analysis
Author: analyst
Date: 2026-06-06
## 1. Контекст и проблема
Оркестратор при заворотах задачи деву (откат на `development`) формирует
описание задачи (`task_desc`), которое попадает в `.task-dev.md` запускаемого
агента-разработчика. Сейчас в двух ветках отката этот текст содержит **только
ссылку на файл-артефакт**, без сути замечаний:
- **Reviewer → REQUEST_CHANGES** (`src/stage_engine.py`, ветка
`_handle_qg_failure_rollbacks`, ~стр. 419): `task_desc` =
`"…Fix findings in docs/work-items/<id>/12-review.md"`.
- **Tester → FAIL** (`check_tests_passed`, ~стр. 455): `task_desc` =
`"…Fix failures described in docs/work-items/<id>/13-test-report.md"`.
В результате developer-агент получает инструкцию «иди читай файл». Ключевые
претензии (P0/P1 у ревьюера, причина падения у тестера) часто проскакивают —
агент не открывает файл целиком или теряет фокус, повторяет ту же ошибку, и
задача снова заворачивается. Это «испорченный телефон»: расход циклов retry
(`MAX_DEVELOPER_RETRIES = 3`), деньги на токены, простой конвейера.
## 2. Бизнес-цель
Убрать «испорченный телефон» между reviewer/tester и developer при заворотах:
встраивать **дословный текст ключевых замечаний** прямо в `task_desc`, чтобы
developer-агент видел суть претензий сразу, а не только ссылку.
Это снижает число повторных заворотов и расход retry-бюджета на одну задачу.
## 3. Объём (вариант A — выбран Славой 06.06)
Минимальное, низкорисковое изменение **ядра** (`stage_engine`), которое:
1. Извлекает из `12-review.md` блок findings и выносит **must-fix (P0/P1)
дословно** в `task_desc` при reviewer REQUEST_CHANGES.
2. Извлекает из `13-test-report.md` причину FAIL (reason из гейта + релевантный
фрагмент тела отчёта) в `task_desc` при tester FAIL.
3. Во всех случаях **сохраняет ссылку на полный файл** как дополнительный
контекст («полный контекст — см. файл»).
4. Извлечение выполняется новым отдельным хелпером-парсером
(`src/review_parse.py`), который **никогда не бросает исключение**: при
отсутствующем/битом файле возвращает пустой результат, и вызывающий код
делает graceful fallback на прежнюю ссылку-строку.
## 4. Что НЕ входит в объём (out of scope)
- НЕ трогать гейты `check_*` (в т. ч. ORCH-45 `check_ci_green`,
ORCH-47 `_parse_tests_verdict`) — они в проде, поведение неизменно.
- НЕ трогать реестр `QG_CHECKS`.
- НЕ менять сигнатуры публичных функций (`advance_stage`, `_run_qg`,
`check_*`).
- НЕ менять webhook-пути.
- НЕ менять retry-счётчик (`_developer_retry_count`, `MAX_DEVELOPER_RETRIES`)
и rollback-логику (последовательность `update_task_stage`
`notify_stage_change``plane_notify_stage` → enqueue) — поведение
идентично.
- НЕ менять формат Plane-комментариев (`build_status_comment`).
## 5. Заинтересованные стороны
- **Owner (Слава)** — заказчик, выбрал вариант A.
- **Developer-агенты** — потребители `task_desc`: получают суть замечаний.
- **Конвейер всех проектов** (self-hosting) — выигрывает за счёт меньшего
числа заворотов.
## 6. Ограничения и риски (self-hosting)
- Правка ядра `stage_engine` — компонент крутится в продакшене и обслуживает
все проекты из общего инстанса/БД/очереди. Любая регрессия в формировании
`task_desc` или (тем более) исключение в `advance_stage` останавливает
конвейер всех проектов → **парсер обязан быть полностью graceful**.
- Обязателен прогон `deploy-staging` (8501) перед прод-деплоем.
- Это правка ядра → требуется ADR (per-work-item).
## 7. Критерий успеха (бизнес)
- При заворотах в `.task-dev.md` есть дословный текст ключевых замечаний
(P0/P1 ревьюера; reason+фрагмент тестера) плюс ссылка на полный файл.
- Парсер устойчив к битым/отсутствующим артефактам (graceful fallback на
старую ссылку-строку).
- Существующие тесты зелёные; поведение retry/rollback не изменилось.

View File

@@ -0,0 +1,209 @@
# ТЗ — ORCH-046: встраивание текста findings reviewer/tester в task_desc
Work Item ID: ORCH-046
Stage: analysis
Author: analyst
Date: 2026-06-06
> Вариант A (минимальный, низкий риск). Это правка ЯДРА — обязателен ADR
> (per-work-item, `docs/work-items/ORCH-046/06-adr/`).
## 1. Задействованные модули `src/`
| Модуль | Изменение |
|--------|-----------|
| `src/review_parse.py` | **НОВЫЙ** хелпер-парсер: `extract_review_findings(path) -> str`, `extract_test_failures(path) -> str`. |
| `src/stage_engine.py` | Две ветки в `_handle_qg_failure_rollbacks`: reviewer REQUEST_CHANGES (~стр. 419) и tester `check_tests_passed` FAIL (~стр. 455) — встраивают извлечённый текст в `task_desc`. |
Источники-образцы (не менять, использовать как референс паттерна «never raise» и
формата артефактов):
- `src/qg/checks.py::_parse_tests_verdict` — образец «never raise», split по `---`, `yaml.safe_load`.
- `src/frontmatter.py::read_frontmatter_value` — образец defensive-парсера.
- `.openclaw/agents/reviewer.md` — канонический формат `12-review.md`.
- `.openclaw/agents/tester.md` — канонический формат `13-test-report.md`.
## 2. Новый модуль `src/review_parse.py`
### 2.1. `extract_review_findings(path: str) -> str`
Назначение: вернуть **дословный** текст must-fix findings (P0 + P1) из
`12-review.md` для встраивания в `task_desc`.
Формат входного файла (канон reviewer.md, секция `## Findings`):
```markdown
## Findings
### P0 — Blocker
- [ ] <описание>
### P1 — Must fix
- [ ] <описание>
### P2 — Should fix
- [ ] <описание>
```
Требования к реализации:
1. **Никогда не бросает исключение.** Любая ошибка (нет файла, IOError, кривой
markdown, нет секции `## Findings`) → возврат `""` (пустая строка).
2. Парсит **только** подсекции P0 и P1 (must-fix). P2/P3 игнорируются.
3. Заголовки подсекций распознаются устойчиво к регистру и к тире/дефису:
соответствие по наличию токена `P0` / `P1` в строке-заголовке уровня `###`.
4. Из распознанных подсекций берётся текст до следующего заголовка `###`/`##`
(т. е. тело подсекции дословно: пункты списка `- [ ] …` / `- …`).
5. Пустые подсекции (нет содержательных пунктов, только `(если есть)`-плейсхолдер
или ничего) — пропускаются. Если ни одного содержательного P0/P1 пункта нет
→ возврат `""`.
6. Результат — компактный многострочный текст, пригодный для вставки в
`task_desc` (например, заголовок подсекции + её пункты). Длина результата
ограничивается разумным лимитом (`MAX_FINDINGS_CHARS`, напр. 2000) с
усечением и маркером `…(truncated)`; полный контекст всё равно остаётся в
файле.
7. Frontmatter (верхний `--- … ---`) при необходимости отбрасывается, чтобы не
попасть в тело; парсинг секции делается по телу markdown.
Сигнатура и контракт (стабильны):
```python
def extract_review_findings(path: str) -> str:
"""Дословный текст P0/P1 findings из 12-review.md. Never raises; '' при ошибке/пусто."""
```
### 2.2. `extract_test_failures(path: str) -> str`
Назначение: вернуть текст причины падения тестов из `13-test-report.md` для
встраивания в `task_desc`.
Формат входного файла (канон tester.md): frontmatter `result: PASS|FAIL`, далее
тело с секциями `## Результаты` (таблица TC), `## Вывод pytest`, `## Итог`.
Требования к реализации:
1. **Никогда не бросает исключение.** Любая ошибка → возврат `""`.
2. Извлекает релевантный фрагмент тела, помогающий понять причину FAIL.
Приоритет источников (берём первый непустой):
- секция `## Вывод pytest` (вывод прогона — где видно упавшие тесты), и/или
- строки таблицы `## Результаты`, содержащие `FAIL`, и/или
- секция `## Итог`.
3. Результат усекается до `MAX_FAILURES_CHARS` (напр. 2000) с маркером
`…(truncated)`.
4. Если ничего извлечь не удалось → возврат `""` (вызывающий код делает
fallback на ссылку).
> Примечание: «reason» из самого гейта (`check_tests_passed` → второй элемент
> кортежа) у вызывающего кода уже есть (`reason`) — он добавляется в `task_desc`
> вызывающим кодом (как и сейчас в комментарии тестера). `extract_test_failures`
> добавляет **фрагмент тела отчёта** поверх этого reason.
Сигнатура и контракт (стабильны):
```python
def extract_test_failures(path: str) -> str:
"""Релевантный фрагмент тела 13-test-report.md (причина FAIL). Never raises; '' при ошибке/пусто."""
```
### 2.3. Общие требования модуля
- Модуль логирует диагностические сообщения на уровне `logger.debug`
(`logging.getLogger("orchestrator.review_parse")`), как `frontmatter.py`.
- Никаких сетевых вызовов, только чтение файла с диска.
- Константы лимитов вынесены модульными (`MAX_FINDINGS_CHARS`,
`MAX_FAILURES_CHARS`).
## 3. Изменения `src/stage_engine.py`
### 3.1. Ветка reviewer REQUEST_CHANGES (внутри `_handle_qg_failure_rollbacks`)
Текущее (~стр. 418424):
```python
task_desc = (
f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n"
f"Stage: development\nNote: REQUEST_CHANGES from reviewer "
f"(attempt {retry_count+1}/3). Fix findings in "
f"docs/work-items/{work_item_id}/12-review.md"
)
```
Целевое поведение:
- Сформировать путь к `12-review.md` через `get_worktree_path(repo, branch)` +
`docs/work-items/{work_item_id}/12-review.md` (как в `_check_review_approved_by_branch`).
- Вызвать `extract_review_findings(path)`.
- Если результат непустой — встроить findings **дословно** в `task_desc`
(под подзаголовком, напр. `Findings (P0/P1):\n<text>`), а ссылку на файл
оставить как «полный контекст» (`Полный контекст: docs/work-items/<id>/12-review.md`).
- Если результат пустой (graceful fallback) — `task_desc` остаётся **как
сейчас** (ссылка-строка). Никаких исключений.
- Префиксная часть (`Work item / Repo / Branch / Stage / Note: REQUEST_CHANGES …
(attempt N/3)`) сохраняется без изменений.
### 3.2. Ветка tester FAIL (`check_tests_passed`, внутри `_handle_qg_failure_rollbacks`)
Текущее (~стр. 454459):
```python
task_desc = (
f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n"
f"Stage: development\nNote: Tests FAILED. "
f"Fix failures described in docs/work-items/{work_item_id}/13-test-report.md"
)
```
Целевое поведение:
- Сформировать путь к `13-test-report.md` аналогично.
- Вызвать `extract_test_failures(path)`.
- В `task_desc` всегда включить `reason` (он уже доступен в этой ветке —
передаётся в `_handle_qg_failure_rollbacks`).
- Если фрагмент тела непустой — встроить его дословно
(`Причина: {reason}\nДетали:\n<fragment>`), плюс ссылку на файл как полный
контекст.
- Если фрагмент пустой — `task_desc` содержит `reason` + ссылку (graceful
fallback, не хуже текущего поведения). Никаких исключений.
- Префиксная часть и существующий Plane-комментарий тестера
(`❌ Тесты не прошли: {reason}…`) НЕ меняются.
### 3.3. Инварианты (НЕ менять поведение)
- Последовательность rollback в обеих ветках: `update_task_stage(task_id,
"development")` → `notify_stage_change` → `plane_notify_stage` →
(`set_issue_in_progress` для тестера) → проверка `_developer_retry_count` <
`MAX_DEVELOPER_RETRIES` → `enqueue_job("developer", …)` либо
`send_telegram` alert. Порядок и условия идентичны.
- `result.rolled_back_to`, `result.enqueued_agent`, `result.enqueued_job_id`,
`result.alerted` выставляются как сейчас.
- Меняется **только содержимое строки `task_desc`**, передаваемой в
`enqueue_job`.
- Импорт нового модуля — `from .review_parse import extract_review_findings,
extract_test_failures` в шапке `stage_engine.py`.
## 4. Изменения API
Нет. Публичные HTTP-эндпоинты (`/health`, `/status`, `/queue`,
`/webhook/plane`, `/webhook/gitea`) не затрагиваются.
## 5. Изменения схемы БД
Нет. Таблицы `tasks`, `agent_runs`, `jobs`, `events` не меняются.
`enqueue_job` вызывается с прежней сигнатурой.
## 6. Требования к новым QG checks
Нет. Реестр `QG_CHECKS` и все `check_*` не трогаются (явно out of scope).
## 7. Артефакты pipeline (создать/обновить в этом PR)
- `src/review_parse.py` — новый модуль.
- `tests/test_review_parse.py` — юнит-тесты парсера (см. 04-test-plan.yaml).
- Возможные дополнения в `tests/test_stage_engine.py` — проверка встраивания
текста в `task_desc` (rollback-ветки).
- `docs/work-items/ORCH-046/06-adr/ADR-001-*.md` — ADR (правка ядра).
- `docs/architecture/README.md` / `internals.md` — описание нового хелпера и
поведения заворотов (если reviewer сочтёт необходимым; компонент описать в
разделе Stage Engine / Откаты).
- `CHANGELOG.md` — запись о ORCH-046.
## 8. Контроль качества / проверка
```bash
python -m pytest tests/ -q # в контейнере; все тесты зелёные
```
Обязательно: стадия `deploy-staging` (8501) перед прод-деплоем (self-hosting).

View File

@@ -0,0 +1,99 @@
# Критерии приёмки — ORCH-046
Work Item ID: ORCH-046
Stage: analysis
Author: analyst
Date: 2026-06-06
Каждый критерий имеет чёткое условие PASS/FAIL. Reviewer/Tester проверяют по
этому списку.
## AC-1 — Дословные P0/P1 findings ревьюера в task_desc
**Условие:** при reviewer REQUEST_CHANGES (откат `review`/`testing`
`development`) строка `task_desc`, переданная в `enqueue_job("developer", …)`,
содержит ДОСЛОВНЫЙ текст findings уровня P0/P1 из `12-review.md` (не только
ссылку).
- **PASS:** в `task_desc` присутствуют дословные строки P0/P1 пунктов из секции
`## Findings` файла `12-review.md`.
- **FAIL:** `task_desc` содержит только ссылку на файл, без текста findings (при
наличии валидного файла с P0/P1).
## AC-2 — Причина падения тестера в task_desc
**Условие:** при tester FAIL (`check_tests_passed`, откат `testing`
`development`) строка `task_desc` содержит причину падения: `reason` из гейта +
релевантный фрагмент тела `13-test-report.md`.
- **PASS:** `task_desc` содержит `reason` И непустой фрагмент тела отчёта
(вывод pytest / FAIL-строки / Итог), когда отчёт валиден.
- **FAIL:** `task_desc` содержит только ссылку на файл без причины/фрагмента
(при наличии валидного отчёта).
## AC-3 — Ссылка на полный файл сохранена
**Условие:** в обеих ветках (reviewer, tester) `task_desc` по-прежнему содержит
ссылку на полный файл-артефакт (`docs/work-items/<id>/12-review.md` /
`13-test-report.md`) как дополнительный контекст.
- **PASS:** путь к файлу присутствует в `task_desc` в обоих сценариях.
- **FAIL:** ссылка на файл удалена/отсутствует.
## AC-4 — Парсер устойчив к отсутствию/битому файлу (graceful)
**Условие:** `extract_review_findings(path)` и `extract_test_failures(path)`
НИКОГДА не бросают исключение; при отсутствующем/нечитаемом/битом файле
возвращают `""`, а вызывающий код в `stage_engine` делает fallback на прежнюю
ссылку-строку.
- **PASS:** на несуществующем пути, пустом файле, файле без секций, битом
markdown/YAML — функции возвращают `""` без исключения; `advance_stage`
отрабатывает откат как раньше (ссылка-строка в `task_desc`).
- **FAIL:** любое исключение наружу из парсера или из `advance_stage` из-за
парсинга.
## AC-5 — Тесты зелёные + новые юнит-тесты парсера
**Условие:** существующие тесты не сломаны; добавлены юнит-тесты парсера,
покрывающие: findings есть / findings пусто / битый YAML(frontmatter) / только
P3 (нет P0/P1).
- **PASS:** `python -m pytest tests/ -q` зелёный; `tests/test_review_parse.py`
содержит как минимум кейсы: P0/P1 присутствуют → текст возвращён; нет
findings/только P2-P3 → `""`; битый файл → `""`; отсутствующий путь → `""`;
для test-report: FAIL-фрагмент извлечён / пустой отчёт → `""`.
- **FAIL:** падение существующих тестов или отсутствие перечисленных кейсов.
## AC-6 — Retry-счётчик и rollback НЕ изменены по поведению
**Условие:** логика `_developer_retry_count`, `MAX_DEVELOPER_RETRIES = 3`,
последовательность откатов и поля `AdvanceResult` (`rolled_back_to`,
`enqueued_agent`, `enqueued_job_id`, `alerted`) идентичны прежним.
- **PASS:** существующие тесты `test_stage_engine.py` на rollback/retry зелёные;
при 4-м заходе по-прежнему alert вместо enqueue; меняется только текст
`task_desc`.
- **FAIL:** изменилось число retry, порядок вызовов, или значения полей
`AdvanceResult`.
## AC-7 — Out-of-scope не затронут
**Условие:** не изменены: `check_*` гейты, реестр `QG_CHECKS`, сигнатуры
публичных функций (`advance_stage`, `_run_qg`, `check_*`), webhook-пути, формат
Plane-комментариев.
- **PASS:** `git diff` не содержит изменений в `src/qg/checks.py` (логика
гейтов), сигнатурах публичных функций, `src/webhooks/*`,
`usage.build_status_comment`; `test_qg_registry_snapshot` зелёный.
- **FAIL:** любое из перечисленного изменено.
## AC-8 — Документация и ADR обновлены (golden source)
**Условие:** правка ядра → заведён ADR (`06-adr/`), обновлён `CHANGELOG.md`, при
необходимости — `docs/architecture/README.md`/`internals.md` (раздел Stage
Engine / Откаты).
- **PASS:** присутствует `docs/work-items/ORCH-046/06-adr/ADR-001-*.md`; в
`CHANGELOG.md` есть запись ORCH-046.
- **FAIL:** ADR или запись в CHANGELOG отсутствуют.

View File

@@ -0,0 +1,108 @@
work_item: ORCH-046
description: >
Тест-план для встраивания дословного текста findings reviewer/tester в
task_desc при заворотах деву. Покрывает новый парсер src/review_parse.py
(graceful, never-raise) и две rollback-ветки src/stage_engine.py.
tests:
# --- Парсер review findings (extract_review_findings) -------------------
- id: TC-01
type: unit
description: "extract_review_findings возвращает дословный текст P0/P1 при их наличии в 12-review.md"
module: tests/test_review_parse.py
covers: [AC-1, AC-5]
expected: PASS
- id: TC-02
type: unit
description: "extract_review_findings возвращает '' когда есть только P2/P3 (нет must-fix P0/P1)"
module: tests/test_review_parse.py
covers: [AC-5]
expected: PASS
- id: TC-03
type: unit
description: "extract_review_findings возвращает '' для отсутствующего файла (несуществующий путь), без исключения"
module: tests/test_review_parse.py
covers: [AC-4]
expected: PASS
- id: TC-04
type: unit
description: "extract_review_findings возвращает '' для битого/пустого файла или markdown без секции ## Findings, без исключения"
module: tests/test_review_parse.py
covers: [AC-4, AC-5]
expected: PASS
- id: TC-05
type: unit
description: "extract_review_findings усекает очень длинные findings до лимита с маркером truncated"
module: tests/test_review_parse.py
covers: [AC-1]
expected: PASS
# --- Парсер test failures (extract_test_failures) ----------------------
- id: TC-06
type: unit
description: "extract_test_failures извлекает релевантный фрагмент тела (Вывод pytest / FAIL-строки / Итог) из 13-test-report.md с result: FAIL"
module: tests/test_review_parse.py
covers: [AC-2, AC-5]
expected: PASS
- id: TC-07
type: unit
description: "extract_test_failures возвращает '' для отсутствующего файла, без исключения"
module: tests/test_review_parse.py
covers: [AC-4]
expected: PASS
- id: TC-08
type: unit
description: "extract_test_failures возвращает '' для битого/пустого отчёта (нет тела/секций), без исключения"
module: tests/test_review_parse.py
covers: [AC-4, AC-5]
expected: PASS
# --- Интеграция со stage_engine (rollback task_desc) -------------------
- id: TC-09
type: integration
description: "advance_stage: reviewer REQUEST_CHANGES -> в enqueue_job('developer') task_desc содержит дословные P0/P1 findings И ссылку на 12-review.md"
module: tests/test_stage_engine.py
covers: [AC-1, AC-3]
expected: PASS
- id: TC-10
type: integration
description: "advance_stage: tester check_tests_passed FAIL -> task_desc содержит reason + фрагмент 13-test-report.md И ссылку на файл"
module: tests/test_stage_engine.py
covers: [AC-2, AC-3]
expected: PASS
- id: TC-11
type: integration
description: "advance_stage: reviewer REQUEST_CHANGES при отсутствующем/битом 12-review.md -> graceful fallback, task_desc = прежняя ссылка-строка, без исключения"
module: tests/test_stage_engine.py
covers: [AC-4, AC-3]
expected: PASS
- id: TC-12
type: integration
description: "advance_stage: rollback/retry поведение неизменно — последовательность откатов, _developer_retry_count, alert на 4-й заход, поля AdvanceResult"
module: tests/test_stage_engine.py
covers: [AC-6]
expected: PASS
# --- Регресс / неизменность out-of-scope ------------------------------
- id: TC-13
type: integration
description: "Реестр QG_CHECKS не изменён (snapshot), гейты check_* нетронуты"
module: tests/test_qg_registry_snapshot.py
covers: [AC-7]
expected: PASS
- id: TC-14
type: integration
description: "Полный регресс существующего набора зелёный: python -m pytest tests/ -q"
module: tests/
covers: [AC-5, AC-6, AC-7]
expected: PASS

View File

@@ -0,0 +1,143 @@
# ADR-001: дословный текст findings reviewer/tester встраивается в `task_desc` через отдельный graceful-парсер
- **Статус:** Accepted
- **Дата:** 2026-06-06
- **Задача:** ORCH-046
- **Область:** ЯДРО `src/stage_engine.py` (rollback-ветки) + новый модуль `src/review_parse.py`. Общий прод-инстанс (orchestrator + enduro-trails), self-hosting.
## Контекст
При заворотах задачи на `development` (откат) `stage_engine` формирует `task_desc`,
который попадает в `.task-dev.md` запускаемого developer-агента. В двух ветках
`_handle_qg_failure_rollbacks` этот текст содержит **только ссылку на файл-артефакт**:
- reviewer REQUEST_CHANGES (`src/stage_engine.py` ~стр. 419) → `…Fix findings in docs/work-items/<id>/12-review.md`;
- tester `check_tests_passed` FAIL (~стр. 455) → `…Fix failures described in docs/work-items/<id>/13-test-report.md`.
Developer-агент получает инструкцию «иди читай файл»; ключевые претензии (P0/P1
ревьюера, причина падения тестера) теряются — агент повторяет ту же ошибку, и
задача заворачивается снова. Это «испорченный телефон»: расход retry-бюджета
(`MAX_DEVELOPER_RETRIES = 3`), токенов и простой конвейера (для всех проектов
общего инстанса).
Ограничение из BRD/ТЗ (вариант A, выбран Owner): минимальная, низкорисковая
правка ядра. Любая регрессия в формировании `task_desc` или (тем более)
исключение в `advance_stage` останавливает конвейер ВСЕХ проектов — следовательно
извлечение текста обязано быть полностью graceful.
## Решение
Встраивать **дословный текст ключевых замечаний** в `task_desc` при заворотах,
сохраняя ссылку на полный файл как дополнительный контекст. Извлечение вынести в
отдельный defensive-модуль, чтобы изолировать blast radius от ядра.
1. **Новый модуль `src/review_parse.py`** с двумя чистыми функциями чтения с диска:
- `extract_review_findings(path: str) -> str` — дословные пункты P0/P1 из секции
`## Findings` файла `12-review.md`;
- `extract_test_failures(path: str) -> str` — релевантный фрагмент тела
`13-test-report.md` (приоритет: `## Вывод pytest` → FAIL-строки `## Результаты`
`## Итог`).
- **Контракт «never raise»** (как `src/frontmatter.py` и
`src/qg/checks.py::_parse_tests_verdict`): любая ошибка — нет файла, IOError,
кривой markdown/YAML, нет секции — возвращает `""`. Логирование на
`logger.debug` (`logging.getLogger("orchestrator.review_parse")`). Никаких
сетевых вызовов.
- Результат усекается модульными лимитами `MAX_FINDINGS_CHARS`,
`MAX_FAILURES_CHARS` (≈2000) с маркером `…(truncated)`; полный контекст всегда
остаётся в файле.
2. **Две ветки `_handle_qg_failure_rollbacks` в `src/stage_engine.py`** строят путь
через `get_worktree_path(repo, branch)` (как `_check_review_approved_by_branch`),
вызывают соответствующий парсер и:
- если результат непустой — встраивают findings/фрагмент **дословно** под
подзаголовком + оставляют ссылку как «полный контекст»;
- если результат пустой — `task_desc` остаётся **как сейчас** (graceful fallback
на ссылку-строку);
- tester-ветка дополнительно всегда включает `reason` из гейта (он уже доступен).
3. **Изоляция ядра.** Меняется ТОЛЬКО содержимое строки `task_desc`, передаваемой в
`enqueue_job`. Последовательность отката (`update_task_stage`
`notify_stage_change``plane_notify_stage` → [`set_issue_in_progress` для
тестера] → проверка `_developer_retry_count` < `MAX_DEVELOPER_RETRIES`
`enqueue_job`/`send_telegram`), значения `AdvanceResult` (`rolled_back_to`,
`enqueued_agent`, `enqueued_job_id`, `alerted`) и Plane-комментарии — без
изменений.
### Почему отдельный модуль, а не inline в `stage_engine`
- Тестируемость: парсер покрывается юнит-тестами `tests/test_review_parse.py`
изолированно от тяжёлого `advance_stage`.
- Blast radius: вся парсинг-логика (и её исключения) физически отделена от
hot-path ядра; ядро только подставляет строку и делает try-around-граничный
fallback.
- Согласованность с уже принятым паттерном defensive-парсеров
(`frontmatter.py`).
### Почему НЕ переиспользуется `frontmatter.read_frontmatter_value`
Тот хелпер читает одиночное значение из YAML-frontmatter. Здесь нужно извлекать
**тело markdown** (подсекции `## Findings`/`### P0`, фрагменты `## Вывод pytest`),
а не frontmatter-ключ. Это другая задача парсинга; общий контракт «never raise»
повторяется намеренно (как уже зафиксировано в ORCH-016/ADR-001 §5 — слияние
парсеров отдельной задачей).
### Почему per-work-item ADR, а не глобальный
Изменение НЕ добавляет гейт/стадию/компонент и НЕ меняет топологию или реестр
`QG_CHECKS` — это обогащение содержимого `task_desc` в существующих rollback-ветках
плюс вспомогательный модуль. По прецеденту ORCH-047/ADR-001 такого класса правки
фиксируются per-work-item ADR. Глобальный `docs/architecture/adr/` не требуется.
### Альтернативы (отклонены)
- **Inline-парсинг прямо в `stage_engine`** — отклонено: раздувает ядро, хуже
тестируется, исключения ближе к hot-path.
- **Менять промпты reviewer/tester, чтобы они сами клали суть в `task_desc`** —
отклонено: `task_desc` формирует ядро, а не агент; зависит от дисциплины двух
агентов вместо детерминированного кода; шире поверхность регрессии.
- **Передавать весь файл целиком в `task_desc`** — отклонено: раздувает промпт
developer-агента и стоимость токенов; теряется фокус на must-fix. Усечение по
P0/P1 + лимит решает проблему «испорченного телефона» дешевле.
## Последствия
- **Плюс:** developer-агент видит суть претензий (P0/P1, причина FAIL) сразу в
`.task-dev.md`; меньше повторных заворотов, экономия retry-бюджета и токенов на
всех проектах общего инстанса.
- **Плюс:** при битом/отсутствующем артефакте поведение не хуже текущего (ссылка
сохраняется); ссылка на полный файл присутствует всегда (AC-3).
- **Плюс:** изменение аддитивное — публичные сигнатуры (`advance_stage`, `_run_qg`,
`check_*`), реестр `QG_CHECKS`, webhook-пути и `build_status_comment` не
затрагиваются; снапшот `test_qg_registry_snapshot` остаётся зелёным (AC-7).
- **Минус/ограничение:** парсинг тела markdown чувствительнее к формату артефактов,
чем чтение одного frontmatter-ключа. Митигировано: распознавание P0/P1 устойчиво
к регистру/тире; при несовпадении формата — пустой результат и fallback на
ссылку (никогда не исключение).
- **Минус:** усечение лимитом может обрезать длинные findings — приемлемо, полный
контекст остаётся в файле, ссылка сохранена.
- **Self-hosting риск:** правка ядра в общем прод-контейнере. Обязателен прогон
`deploy-staging` (8501) перед прод-деплоем; прод-контейнер `orchestrator` (8500)
не перезапускать в рамках разработки/тестинга. Граничный риск — исключение из
парсера в `advance_stage`; закрыт контрактом «never raise» + юнит-кейсами на
битый/пустой/отсутствующий ввод (AC-4, AC-5).
## Влияние на документацию (golden source)
В PR разработки (вместе с кодом) обновить:
- `docs/architecture/README.md` — раздел **Stage Engine** / **Откаты**: упомянуть,
что `task_desc` при заворотах reviewer/tester несёт дословные findings + ссылку,
и новый модуль `src/review_parse.py` (defensive, never-raise).
- `CHANGELOG.md` — запись ORCH-046.
- `docs/architecture/internals.md` — по усмотрению reviewer, если детализируется
поток отката.
## Связи
- BRD/ТЗ/AC: `docs/work-items/ORCH-046/01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`.
- Образцы паттерна «never raise»: `src/frontmatter.py`,
`src/qg/checks.py::_parse_tests_verdict`.
- Каноны артефактов: `.openclaw/agents/reviewer.md` (`12-review.md` `## Findings`),
`.openclaw/agents/tester.md` (`13-test-report.md` `result:` + тело).
- Прецедент per-work-item ADR на правку парсинга: ORCH-047/ADR-001.
- Технические риски: `docs/work-items/ORCH-046/10-tech-risks.md`.
- Staging-страховка: `docs/architecture/adr/adr-0003-staging-gate.md`.

View File

@@ -0,0 +1,29 @@
# Технические риски — ORCH-046
Work Item ID: ORCH-046
Stage: architecture
Author: architect
Date: 2026-06-06
Связано: `06-adr/ADR-001-embed-findings-in-task-desc.md`.
| # | Риск | Вероятн. | Влияние | Митигация | Контроль (AC/тест) |
|---|------|----------|---------|-----------|--------------------|
| R-1 | Исключение из парсера всплывает в `advance_stage` → встаёт конвейер ВСЕХ проектов (self-hosting, общий инстанс) | Низк. | **Критич.** | Контракт «never raise» в `review_parse.py`; вызов в `stage_engine` обёрнут так, что пустой результат → fallback на прежнюю ссылку-строку | AC-4; юнит-кейсы «нет файла / битый YAML / пустой / только P3» в `tests/test_review_parse.py` |
| R-2 | Регрессия в последовательности отката или полях `AdvanceResult` (меняется не только `task_desc`) | Низк. | Высок. | Жёсткий инвариант ТЗ §3.3: трогать ТОЛЬКО строку `task_desc`; порядок вызовов и условия retry неизменны | AC-6; существующие `tests/test_stage_engine.py` (rollback/retry) зелёные |
| R-3 | Парсер чувствителен к формату артефактов: дрейф `12-review.md`/`13-test-report.md` → пустой результат | Сред. | Низк. | Распознавание P0/P1 устойчиво к регистру/тире; при несовпадении → `""` + fallback на ссылку (деградация, не отказ) | AC-1/AC-2/AC-4 |
| R-4 | Раздувание `task_desc` длинными findings → рост стоимости/потеря фокуса developer-агента | Сред. | Низк. | Лимиты `MAX_FINDINGS_CHARS`/`MAX_FAILURES_CHARS` (~2000) + маркер `…(truncated)`; only P0/P1 (P2/P3 отброшены) | AC-1; проверка усечения в юнит-тестах |
| R-5 | Случайный выход за out-of-scope (правка `check_*`, `QG_CHECKS`, сигнатур, webhooks, `build_status_comment`) | Низк. | Сред. | Явный out-of-scope в ТЗ §4/§6; ревью diff | AC-7; `test_qg_registry_snapshot` зелёный |
| R-6 | Прод-деплой self без страховки staging | Низк. | **Критич.** | Обязательная стадия `deploy-staging` (8501); прод `orchestrator` (8500) не рестартить в разработке/тестинге | adr-0003; стадийный гейт `check_staging_status` |
| R-7 | Дублирование defensive-парсинга (3-й модуль рядом с `frontmatter.py` и `_parse_tests_verdict`) → техдолг | Сред. | Низк. | Осознанно принято (как ORCH-016/ADR-001 §5): малый blast radius важнее DRY; слияние парсеров — отдельная follow-up задача | — (техдолг, не блокер) |
## Заметки
- **Граничный try в ядре.** Даже при контракте «never raise» в `review_parse`,
вызов в `stage_engine` следует считать недоверенным: подстановка результата в
`task_desc` не должна зависеть от внутренней корректности парсера. Fallback на
ссылку-строку обязателен и при пустом результате, и при любой неожиданности.
- **Эскалация не требуется.** Изменение укладывается в принципы (минимум
зависимостей, raw-парсинг без новых либ, без новых компонентов/стадий/QG).
Лейбл `arch:major-change` НЕ ставится; возврат в Анализ не требуется — ТЗ
реализуемо без нарушения принципов.

View File

@@ -0,0 +1,83 @@
---
type: review
work_item_id: ORCH-046
verdict: APPROVED
version: 1
---
# Review ORCH-046
## Summary
Правка ядра «вариант A»: при заворотах на `development` `task_desc` теперь несёт
**дословный must-fix текст** (P0/P1 ревьюера, причина FAIL тестера) вместо одной
ссылки на файл. Извлечение вынесено в новый defensive-модуль `src/review_parse.py`
с контрактом «never raise»; две rollback-ветки `_handle_qg_failure_rollbacks`
встраивают текст и сохраняют ссылку как «Полный контекст», при пустом/битом
артефакте — graceful-фоллбэк на прежнюю строку.
Реализация полностью соответствует ТЗ (`02-trz.md`), ADR-001 и всем критериям
приёмки. Документация обновлена в этом же PR. Тесты зелёные (`461 passed`).
Проверено по осям:
**1. Соответствие ТЗ.** Сигнатуры `extract_review_findings`/`extract_test_failures`
точно как в ТЗ §2; never-raise, логирование на `logger.debug`, модульные лимиты
`MAX_FINDINGS_CHARS`/`MAX_FAILURES_CHARS`, отбрасывание frontmatter, устойчивость
P0/P1-заголовков к регистру/тире, пропуск плейсхолдеров `(если есть)`/`<…>`,
приоритет источников тестера (`## Вывод pytest` → FAIL-строки `## Результаты`
`## Итог`). Префикс `task_desc`, `reason` в tester-ветке, ссылка-фоллбэк — как
предписано §3. API/БД/QG не тронуты (§46).
**2. Соответствие ADR-001.** Отдельный модуль (blast radius), путь через
`get_worktree_path`, изоляция ядра (меняется только строка `task_desc`),
последовательность отката и поля `AdvanceResult` сохранены. Per-work-item ADR
обоснован. Реализация ⇄ решение совпадают.
**3. Качество кода.** Docstrings на всех публичных функциях; defensive `_read`
ловит `OSError`, внешний `try/except Exception` в обоих экстракторах гарантирует
never-raise (подтверждено кейсом на directory-path). Регэксп `_P01_HEADER_RE`
корректно отсекает ложные совпадения (`P05` и т.п.). Код читабелен, без дублей.
**4. Качество тестов.** `tests/test_review_parse.py` покрывает TC-01..08 (findings
есть / только P2-P3 / нет файла / битый YAML / усечение / регистр-тире / directory).
`tests/test_stage_engine.py::TestRollbackTaskDescEmbedding` проверяет встраивание
в обе ветки, graceful-фоллбэк, неизменность retry/rollback на 4-м заходе (alert
вместо enqueue). Содержательные, не тривиальные.
## Findings
### P0 — Blocker
- [ ] (нет)
### P1 — Must fix
- [ ] (нет)
### P2 — Should fix
- [ ] (нет)
## Соответствие критериям приёмки
- AC-1 (дословные P0/P1 в `task_desc`) — PASS: `Findings (P0/P1):\n{findings}`.
- AC-2 (причина тестера: `reason` + фрагмент тела) — PASS: `Причина: {reason}` + `Детали:`.
- AC-3 (ссылка на полный файл сохранена) — PASS: «Полный контекст»/fallback-ссылка в обеих ветках.
- AC-4 (graceful never-raise) — PASS: `""`→ссылка-фоллбэк, исключений нет (тесты TC-03/04/07/08, directory-path).
- AC-5 (тесты зелёные + новые юнит-тесты) — PASS: `461 passed`; все перечисленные кейсы присутствуют.
- AC-6 (retry/rollback не изменены) — PASS: TC-12 + существующие rollback-тесты зелёные.
- AC-7 (out-of-scope не затронут) — PASS: diff не касается `src/qg/checks.py`, `src/webhooks/*`, `usage.py`, `stages.py`, `main.py`; сигнатуры публичных функций не менялись.
- AC-8 (документация + ADR) — PASS: ADR-001 заведён, `CHANGELOG.md` и `docs/architecture/README.md` обновлены.
## Документация
Обновлена корректно и в том же PR (golden source соблюдён):
- `docs/work-items/ORCH-046/06-adr/ADR-001-embed-findings-in-task-desc.md` — заведён (правка ядра).
- `CHANGELOG.md` — запись ORCH-046 в `[Unreleased] / Added`.
- `docs/architecture/README.md` — добавлен компонент **Review/Test Parsers** и раздел **Обогащение `task_desc` при заворотах (ORCH-046)**.
Изменение `src/` сопровождено обновлением документации — требование п.4/п.6 правил
агентов выполнено.
## Примечание (self-hosting)
Правка ядра в общем прод-инстансе. Перед прод-деплоем обязательна стадия
`deploy-staging` (8501) согласно ADR-001 / CLAUDE.md — это страховка следующих
стадий, не блокер ревью.

View File

@@ -0,0 +1,92 @@
---
type: test-report
work_item_id: ORCH-046
result: PASS
---
# Test Report — ORCH-046
Встраивание дословного must-fix текста findings reviewer/tester в `task_desc`
при заворотах на `development` (новый модуль `src/review_parse.py` + две
rollback-ветки `src/stage_engine.py`).
## Окружение
- Python: 3.12.13
- pytest: 8.3.3 (asyncio mode=AUTO)
- Ветка: feature/ORCH-046-stage-engine-pass-reviewer-tes
- Дата: 2026-06-06
## Результаты
| TC ID | Описание | Покрывает | Результат |
|-------|----------|-----------|-----------|
| TC-01 | `extract_review_findings` возвращает дословный P0/P1 текст | AC-1, AC-5 | PASS |
| TC-02 | `extract_review_findings``""` при только P2/P3 | AC-5 | PASS |
| TC-03 | `extract_review_findings``""` для отсутствующего файла | AC-4 | PASS |
| TC-04 | `extract_review_findings``""` для битого/без секции файла | AC-4, AC-5 | PASS |
| TC-05 | `extract_review_findings` усекает длинный текст с маркером truncated | AC-1 | PASS |
| TC-06 | `extract_test_failures` извлекает фрагмент тела (Вывод pytest/FAIL/Итог) | AC-2, AC-5 | PASS |
| TC-07 | `extract_test_failures``""` для отсутствующего файла | AC-4 | PASS |
| TC-08 | `extract_test_failures``""` для битого/пустого отчёта | AC-4, AC-5 | PASS |
| TC-09 | reviewer REQUEST_CHANGES → `task_desc` содержит P0/P1 + ссылку | AC-1, AC-3 | PASS |
| TC-10 | tester FAIL → `task_desc` содержит reason + фрагмент + ссылку | AC-2, AC-3 | PASS |
| TC-11 | graceful fallback при отсутствующем/битом файле (обе ветки) | AC-4, AC-3 | PASS |
| TC-12 | rollback/retry поведение неизменно (alert на 4-й заход, поля AdvanceResult) | AC-6 | PASS |
| TC-13 | Реестр `QG_CHECKS` не изменён (snapshot), гейты нетронуты | AC-7 | PASS |
| TC-14 | Полный регресс существующего набора зелёный | AC-5, AC-6, AC-7 | PASS |
Сопоставление TC ↔ тесты:
- TC-01..08 → `tests/test_review_parse.py` (`TestExtractReviewFindings`, `TestExtractTestFailures`), 14 кейсов, все PASS.
- TC-09..12 → `tests/test_stage_engine.py::TestRollbackTaskDescEmbedding`, все PASS.
- TC-13 → `tests/test_qg_registry_snapshot.py` (registry/callables/transitions snapshot), все PASS.
- TC-14 → полный прогон `pytest tests/`**461 passed**.
## Smoke test API (read-only, прод-инстанс не затронут)
| Endpoint | HTTP | Ответ |
|----------|------|-------|
| GET /health | 200 | `{"status":"ok","service":"orchestrator"}` |
| GET /status | 200 | active_tasks включает task 37 (ORCH-046, stage=testing) |
| GET /queue | 200 | counts: queued=0, running=1, failed=0; breaker=closed; preflight_ok=true |
> `curl` в окружении отсутствует — smoke выполнен через `urllib`. Только GET-запросы,
> деструктивных операций над прод-контейнером не выполнялось (self-hosting safety).
## Вывод pytest
```
============================= test session starts ==============================
platform linux -- Python 3.12.13, pytest-8.3.3, pluggy-1.6.0
rootdir: .../feature_ORCH-046-stage-engine-pass-reviewer-tes
configfile: pytest.ini
plugins: anyio-4.13.0, asyncio-0.23.8
asyncio: mode=Mode.AUTO
...
======================== 461 passed, 1 warning in 7.59s ========================
```
Прицельный прогон ORCH-046 (`test_review_parse.py` + `test_stage_engine.py` +
`test_qg_registry_snapshot.py`): **53 passed**.
Единственный warning — преэкзистентный `PydanticDeprecatedSince20` в `src/config.py`
(не связан с ORCH-046).
## Покрытие критериев приёмки
| AC | Критерий | Подтверждение | Статус |
|----|----------|---------------|--------|
| AC-1 | Дословные P0/P1 в `task_desc` | TC-01, TC-09 | PASS |
| AC-2 | Причина тестера (reason + фрагмент) в `task_desc` | TC-06, TC-10 | PASS |
| AC-3 | Ссылка на полный файл сохранена | TC-09, TC-10, TC-11 | PASS |
| AC-4 | Парсер graceful (never-raise) | TC-03, TC-04, TC-07, TC-08, TC-11 | PASS |
| AC-5 | Тесты зелёные + новые юнит-тесты | TC-14 (461 passed) | PASS |
| AC-6 | Retry/rollback не изменены | TC-12 | PASS |
| AC-7 | Out-of-scope не затронут | TC-13 | PASS |
| AC-8 | Документация + ADR | проверено reviewer (12-review.md, APPROVED) | PASS |
## Итог
**PASS** — все 14 TC из тест-плана зелёные, полный регресс 461 passed,
smoke API 200 по всем эндпоинтам, прод-инстанс здоров. Все критерии приёмки
выполнены. Задача готова к стадии `deploy-staging` (8501) — обязательной
страховке self-hosting перед прод-деплоем.

View File

@@ -0,0 +1,90 @@
---
staging_status: FAILED
timestamp: 2026-06-06T04:47:45Z
base_url: http://localhost:8501
mode: stub
result: 9/10 checks PASS
failed_checks: [B6]
---
# Staging Gate Log — ORCH-046
Staging test suite **FAILED**. Exit code 1 (9/10 checks passed).
## Verdict
The staging gate is **red**: one check failed (`B6`). Per pipeline policy a
non-zero staging suite is `staging_status: FAILED` → rollback to `development`.
## Failed check
```
✗ FAIL B6 Registry: sandbox present, prod ET/ORCH absent
[sandbox=NO, prod-ET=YES(BAD!), prod-ORCH=YES(BAD!)]
```
**What it means.** The staging container's project registry is **not isolated**:
it sees the production projects `enduro-trails` (ET) and `orchestrator` (ORCH),
and the `orchestrator-sandbox` (SANDBOX) project is **absent**. This violates the
hard isolation invariant for staging (`docs/operations/INFRA.md`: «Staging видит
ТОЛЬКО `orchestrator-sandbox` (SANDBOX) — изоляция»). The staging gate exists
precisely to catch this class of safety breach before any prod deploy of the
self-hosting orchestrator.
**Triage note (for humans).** This is a **staging environment / configuration**
issue — the staging container's `ORCH_PROJECTS_JSON` is pointing at the prod
registry instead of the sandbox-only registry. It is **not** a code regression
introduced by the ORCH-046 changeset (which only touches `src/review_parse.py`
and rollback `task_desc` enrichment). However, the gate is authoritative and red,
so the work item cannot pass to `deploy`. Fix the staging `.env.staging` /
`ORCH_PROJECTS_JSON` to expose only SANDBOX, re-run the staging suite, and the
gate will go green.
> ⚠️ Safety note: the first run aborted at `A3` because `ORCH_STAGING` was not
> set in the runner env (the script's guard against accidentally hitting prod).
> Re-run with `ORCH_STAGING=true` against the staging URL (8501) executed the
> full suite. Prod (8500) was never touched.
## Full suite output
```
============================================================
ORCH-33 Staging Check Suite
base_url : http://localhost:8501
mode : stub
utc_time : 2026-06-06T04:47:27.628664+00:00
============================================================
[Block A] SMOKE
✓ PASS A1 GET /health → 200 status=ok [HTTP 200, body={'status': 'ok', 'service': 'orchestrator'}]
✓ PASS A2 GET /queue → 200 with counts/max_concurrency/resilience [HTTP 200, keys=['counts', 'max_concurrency', 'poll_interval', 'resilience', 'recent']]
✓ PASS A3 ORCH_STAGING=true (not prod) [ORCH_STAGING=true]
[Block B] ACCESS
✓ PASS B4 Plane: sandbox project accessible [HTTP 200, found 5 project(s), sandbox=YES]
✓ PASS B5 Gitea: orchestrator-sandbox accessible, push=true [HTTP 200, permissions={'admin': True, 'push': True, 'pull': True}]
✗ FAIL B6 Registry: sandbox present, prod ET/ORCH absent [sandbox=NO, prod-ET=YES(BAD!), prod-ORCH=YES(BAD!)]
[Block C] E2E (mode=stub)
· C7: Creating issue in SANDBOX project...
✓ PASS C7 Create issue in Plane SANDBOX [HTTP 201, issue_id=2fcbcb0c-1b29-4b76-8ba8-a8fe42cebdb4]
· C8: Triggering pipeline via POST /webhook/plane ...
· Using HMAC signature (secret len=40)
✓ PASS C8 Trigger pipeline via /webhook/plane [HTTP 200, resp={'status': 'accepted'}]
· C9a: Polling for branch in orchestrator-sandbox (up to 60s)...
✓ PASS C9a Branch appears in orchestrator-sandbox [branch=feature/SANDBOX-011-staging-check-e2e-20260606t044]
· C9b: Checking staging job queue for analyst job (up to 30s)...
· (Plane comment check skipped: bot-tokens not added to SANDBOX project)
✓ PASS C9b Analyst job enqueued in staging queue [job_id=7, status=queued, agent=analyst]
[CLEANUP]
✓ PASS CLEANUP: deleted branch 'feature/SANDBOX-011-staging-check-e2e-20260606t044' (HTTP 204)
✓ PASS CLEANUP: deleted Plane issue 2fcbcb0c-1b29-4b76-8ba8-a8fe42cebdb4 (HTTP 204)
· CLEANUP DB: no task row found for plane_id=2fcbcb0c-1b29-4b76-8ba8-a8fe42cebdb4
· CLEANUP DB dedup: no such table: events_dedup
============================================================
RESULT: 9/10 checks PASS
============================================================
EXIT_CODE=1
```

View File

@@ -0,0 +1,7 @@
# Business Request: check_tests_passed: gate must read result: field from test report
Work Item ID: ORCH-047
## Description
TBD

View File

@@ -0,0 +1,57 @@
# BRD — ORCH-047: check_tests_passed должен читать поле `result:` из тест-отчёта
## 1. Контекст и проблема
Quality Gate `check_tests_passed` (`src/qg/checks.py`, функция-парсер `_parse_tests_verdict`) гейтит переход `testing → deploy-staging`. Он читает машиночитаемый вердикт из YAML-frontmatter артефакта `13-test-report.md`.
**Дефект (обнаружен дев-агентом в ходе ORCH-17, подтверждён 05.06.2026):**
парсер читает ТОЛЬКО поля `verdict:` и `status:`. Однако промпт тестер-агента (`.openclaw/agents/tester.md`, строки 5156 и 7880) предписывает эмитить машиночитаемое поле **`result: PASS|FAIL`** — и НЕ упоминает ни `verdict:`, ни `status:`.
В результате тестер, честно следующий своей инструкции (реальный отчёт ORCH-017: `result: PASS`, без `verdict:`/`status:`), упирается в ветку «ни verdict, ни status не заданы» → гейт возвращает `False` с причиной *"No machine-readable verdict/status in test report frontmatter"* → задача откатывается `testing → development`.
**Последствие:** ЛЮБАЯ задача, где тестер пишет `result: PASS` (то есть строго по своей инструкции), застревает в бесконечной петле `testing ↔ development` до исчерпания `MAX_DEVELOPER_RETRIES`. Именно это крутило ORCH-17. ORCH-016 прошёл раньше лишь потому, что его отчёт избыточно нёс И `verdict:`, И `result:`.
**Корень:** рассинхрон контракта. Гейт (потребитель) и промпт тестера (производитель) описывают разные имена машиночитаемого поля.
## 2. Бизнес-цель
Привести контракт гейта `check_tests_passed` в соответствие с тем, что тестер-агенту реально велено эмитить, чтобы корректные тест-отчёты (`result: PASS`) проходили гейт, а отрицательные (`result: FAIL`) — надёжно откатывали задачу. Устранить ложноотрицательные срабатывания, ломающие конвейер всех проектов.
## 3. Заинтересованные стороны
- **Owner / Стрим, Слава** — выявили дефект при разборе ORCH-17 (05.06).
- **Все проекты общего прод-инстанса** (orchestrator self-hosting + enduro-trails) — потребители shared quality-gate. Это SHARED-изменение, влияет на всех.
- **Тестер-агент** — производитель `13-test-report.md`.
## 4. Объём работ (scope)
### В объёме
- `_parse_tests_verdict` читает `result:` как первоклассное машиночитаемое поле НАРАВНЕ с `verdict:` и `status:`.
- Семантика приоритетов сохраняется и распространяется на все три поля:
- negative-токен в ЛЮБОМ из трёх (`result`/`verdict`/`status`) → FAIL и авторитетен (перебивает positive в другом поле);
- при отсутствии negative — positive-токен в ЛЮБОМ из трёх → PASS;
- ни одно из трёх полей не задано → FAIL (нет машиночитаемого вердикта);
- заданы, но не распознаны → FAIL.
- Обратная совместимость: отчёты, несущие только `verdict:`/`status:` (стиль enduro-trails ET-001…ET-014, ORCH-016), продолжают работать ровно как раньше.
- **ADR** на изменение семантики shared testing-гейта (правило 2 CLAUDE.md — обязательно для сквозного изменения).
- Обновление документации: `docs/architecture/README.md` (строка про машинные ключи вердикт-парсера), `CHANGELOG.md`.
### Вне объёма
- Изменение промпта тестера (`.openclaw/agents/tester.md`). Контракт приводится со стороны гейта к тому, что тестеру УЖЕ велено эмитить; промпт не трогаем.
- Изменение других гейтов (`check_reviewer_verdict`, `check_deploy_status`, `check_staging_status`) — у них свои поля (`verdict:`, `deploy_status:`, `staging_status:`), они вне этого дефекта.
- Изменения ORCH-017 (про ссылки) — это отдельный work item.
## 5. Ограничения и риски
- **SHARED quality-gate, общий прод-инстанс.** Изменение затрагивает enduro-trails наравне с orchestrator. Регресс недопустим: набор положительных/отрицательных токенов и поведение для старого формата (`verdict:`/`status:`) должны остаться неизменными.
- **Self-hosting.** Орк правит сам себя; деплой проходит через обязательную стадию `deploy-staging` (8501). Прод-контейнер `orchestrator` (8500) не ронять.
- Изменение читает только frontmatter, никогда не прозу (канон гейтов из `docs/architecture/README.md`).
- Парсер не должен бросать исключения ни при каком вводе (битый YAML, пустой файл, frontmatter-не-mapping) → всегда `(False, reason)`.
## 6. Эталонный код
Дев-агент уже написал референс-реализацию в ветке `feature/ORCH-017` (`src/qg/checks.py` + `tests/test_qg.py`, 23 теста). Его допустимо использовать как ориентир, но оформить чисто через данный work item с собственным ADR.
## 7. Критерий успеха
Тест-отчёт с одним лишь `result: PASS` проходит гейт `check_tests_passed`; с `result: FAIL` — нет. Старый формат (`verdict:`/`status:`) не регрессирует. Все pytest зелёные. ADR заведён.

View File

@@ -0,0 +1,68 @@
# ТЗ — ORCH-047: `_parse_tests_verdict` читает `result:` наравне с `verdict:`/`status:`
## 1. Задействованные модули `src/`
| Файл | Что меняется |
|------|--------------|
| `src/qg/checks.py` | Функция `_parse_tests_verdict` (стр. ~223265). Добавить чтение поля `result:` из frontmatter и включить его в проверку токенов наравне с `verdict:`/`status:`. Обновить докстринг функции и `check_tests_passed`. |
Точка входа `check_tests_passed(repo, work_item_id, branch)` (стр. ~182) и реестр `QG_CHECKS` НЕ меняются (сигнатура и имя гейта те же).
## 2. Требуемое поведение `_parse_tests_verdict`
Вход — строковое тело `13-test-report.md`. Выход — `tuple[bool, str]`.
1. Нет frontmatter (`content` не начинается с `---`) → `(False, "No YAML frontmatter ...")`.
2. Frontmatter некорректен (split по `---` даёт < 3 частей) → `(False, "Malformed YAML frontmatter ...")`.
3. YAML не парсится → `(False, "Invalid YAML frontmatter ...: <e>")` (никогда не raise).
4. YAML не mapping → `(False, "Malformed YAML frontmatter ... (not a mapping)")`.
5. Прочитать три поля, нормализовать (`str(...).upper().strip()`, защита от `None`):
- `verdict`
- `status`
- **`result`НОВОЕ**
6. Если ВСЕ три пусты → `(False, "No machine-readable verdict/status/result in test report frontmatter")`.
7. Собрать объединённую строку полей `fields = f"{verdict} {status} {result}"`.
8. Если в `fields` встречается ЛЮБОЙ negative-токен (`_TESTS_NEGATIVE_TOKENS`) → `(False, "Test verdict: <значение> (<NEG>)")`. **Negative авторитетен** — проверяется ПЕРВЫМ, перебивает любой positive.
9. Иначе если встречается ЛЮБОЙ positive-токен (`_TESTS_POSITIVE_TOKENS`) → `(True, "Test verdict: <значение> (PASS)")`.
10. Иначе (заданы, но не распознаны) → `(False, "No recognized PASS verdict in frontmatter (...)")`.
Наборы токенов НЕ изменяются (важно для обратной совместимости с enduro-trails):
```python
_TESTS_NEGATIVE_TOKENS = ("BLOCKED", "FAILED", "FAIL", "REQUEST_CHANGES", "REJECT", "RED")
_TESTS_POSITIVE_TOKENS = ("PASSED", "PASS", "READY-TO-DEPLOY", "READY_TO_DEPLOY", "GREEN", "APPROVED")
```
> Примечание для разработчика (порядок токенов): negative-список проверяется раньше positive — это даёт авторитетность отрицания. Внутри positive-набора `"PASSED"` идёт перед `"PASS"` лишь для аккуратного reason-текста; на результат (bool) порядок не влияет, т.к. это подстрочный поиск.
## 3. Контракт поля (golden source)
После изменения машиночитаемыми полями testing-гейта считаются **три равноправных**: `result:` (канон промпта тестера), `verdict:`, `status:` (легаси/enduro-trails). Достаточно ЛЮБОГО одного. Это и есть приведение гейта к тому, что тестеру велено эмитить в `.openclaw/agents/tester.md` (`result: PASS|FAIL`).
## 4. Изменения API
Нет. HTTP-эндпоинты (`/health`, `/status`, `/queue`, вебхуки) не затрагиваются. Сигнатуры функций гейта не меняются.
## 5. Изменения схемы БД
Нет.
## 6. Требования к новым QG checks
Новых гейтов нет. Меняется внутренняя логика существующего `check_tests_passed` (через `_parse_tests_verdict`). Реестр `QG_CHECKS` без изменений → снапшот-тест `tests/test_qg_registry_snapshot.py` должен остаться зелёным.
## 7. Артефакты pipeline (создать/обновить в этом PR)
- `docs/work-items/ORCH-047/06-adr/ADR-001-*.md`**обязательно** (правило 2 CLAUDE.md): ADR на изменение семантики SHARED testing-гейта (влияет на все проекты общего инстанса). Заводит архитектор.
- `docs/architecture/README.md` — обновить строку о вердикт-парсере (раздел «Plane Sync», п. про машинные ключи): для testing-гейта перечислить `result:`/`verdict:`/`status:`.
- `CHANGELOG.md` — запись `fix:` про ORCH-047.
- `tests/test_qg.py` — добавить кейсы на `result:` (см. `04-test-plan.yaml`).
## 8. Нефункциональные требования
- Парсер не бросает исключений ни на каком вводе.
- Изменение читает только frontmatter, не прозу (канон гейтов).
- Полная обратная совместимость: существующие тесты `TestCheckTestsPassed` остаются зелёными без правок (кроме, возможно, переименования reason-строки в п.6 BRD — текст причины «No machine-readable verdict/status...» обновляется на «...verdict/status/result...», соответствующий ассерт при наличии обновить).
## 9. Деплой
Self-hosting: стандартный путь через `deploy-staging` (8501) перед прод-деплоем. Прод-контейнер `orchestrator` (8500) не перезапускать в рамках разработки/тестинга.

View File

@@ -0,0 +1,68 @@
# Критерии приёмки — ORCH-047
Каждый критерий имеет однозначное условие PASS/FAIL.
## AC-01 — `result: PASS` проходит гейт (главный кейс ORCH-17)
- **Дано:** `13-test-report.md` с frontmatter, содержащим только `result: PASS` (без `verdict:`/`status:`).
- **Ожидается:** `check_tests_passed(...)``(True, ...)`, в reason присутствует «PASS».
- **PASS:** возвращается True. **FAIL:** возвращается False.
## AC-02 — `result: FAIL` откатывает задачу
- **Дано:** frontmatter с `result: FAIL` (без `verdict:`/`status:`).
- **Ожидается:** `(False, ...)`, reason содержит токен отрицания (`FAIL`).
- **PASS:** False. **FAIL:** True.
## AC-03 — Negative авторитетен поверх positive (в т.ч. между полями)
- **Дано:** `result: PASS`, но `verdict: BLOCKED` (или `status: failed`).
- **Ожидается:** `(False, ...)`, reason упоминает negative-токен (`BLOCKED`/`FAILED`).
- **PASS:** False. **FAIL:** True.
## AC-04 — Positive в любом из трёх полей даёт PASS
- **Дано (каждый подкейс отдельно):**
- только `verdict: PASS`;
- только `status: PASSED`;
- только `result: ready-to-deploy`.
- **Ожидается:** все три → `(True, ...)`.
- **PASS:** все True. **FAIL:** хоть один False.
## AC-05 — Обратная совместимость (enduro-trails / ORCH-016)
- **Дано:** существующие реальные формы из `TestCheckTestsPassed`:
- `verdict: PASS` + `status: pass`;
- `verdict: PASS — ready-to-deploy`;
- `verdict: ready-to-deploy` + `status: PASSED`;
- `verdict: stage:ready-to-deploy` + `status: pass`;
- `verdict: BLOCKED` + проза «23 passed».
- **Ожидается:** результаты идентичны прежним (PASS-кейсы → True, BLOCKED → False). Старые тесты `TestCheckTestsPassed` зелёные.
- **PASS:** поведение не изменилось. **FAIL:** любой регресс.
## AC-06 — Ни одно из трёх полей не задано → FAIL
- **Дано:** frontmatter без `result`/`verdict`/`status` (например, только `type:`/`version:`); тело может содержать «Result: PASS» прозой.
- **Ожидается:** `(False, ...)`, причина про отсутствие машиночитаемого вердикта.
- **PASS:** False. **FAIL:** True.
## AC-07 — Только проза, без frontmatter → FAIL
- **Дано:** отчёт без YAML-frontmatter, в теле «Result: PASS / All tests passed».
- **Ожидается:** `(False, ...)`, причина про отсутствие frontmatter. Прозу не читаем.
- **PASS:** False. **FAIL:** True.
## AC-08 — Битый YAML → FAIL без исключения
- **Дано:** некорректный YAML во frontmatter.
- **Ожидается:** `(False, ...)` c упоминанием YAML/frontmatter, функция НЕ бросает исключение.
- **PASS:** False и нет raise. **FAIL:** raise или True.
## AC-09 — Отчёт отсутствует → FAIL
- **Дано:** файла `13-test-report.md` нет.
- **Ожидается:** `(False, "...not found...")`.
- **PASS:** False. **FAIL:** True.
## AC-10 — Реестр гейтов неизменен
- **Ожидается:** `QG_CHECKS` содержит ровно те же ключи, что и до изменения; `tests/test_qg_registry_snapshot.py` зелёный.
- **PASS:** снапшот совпал. **FAIL:** снапшот изменился.
## AC-11 — Документация и ADR обновлены (правило 2/6 CLAUDE.md)
- **Ожидается:** заведён `docs/work-items/ORCH-047/06-adr/ADR-001-*.md`; обновлены `docs/architecture/README.md` (вердикт-парсер testing-гейта) и `CHANGELOG.md`.
- **PASS:** все три присутствуют и описывают изменение. **FAIL:** что-либо отсутствует → REQUEST_CHANGES на review.
## AC-12 — Полный регресс зелёный
- **Ожидается:** `pytest tests/ -q` — все тесты PASS.
- **PASS:** exit code 0. **FAIL:** любой упавший тест.

View File

@@ -0,0 +1,97 @@
work_item: ORCH-047
module_under_test: src/qg/checks.py::_parse_tests_verdict (via check_tests_passed)
test_file: tests/test_qg.py
notes: >
Добавить в класс TestCheckTestsPassed. Шаблон записи отчёта — существующий
хелпер self._write(dir, content). Наборы токенов не меняются; проверяем, что
поле result: теперь равноправно с verdict:/status:, а старые кейсы не регрессируют.
tests:
- id: TC-01
type: unit
description: "result: PASS без verdict/status -> гейт PASS (главный кейс ORCH-17, AC-01)"
module: tests/test_qg.py
fixture_frontmatter: "---\ntype: test-report\nresult: PASS\n---\n\n# Test Report\n"
expected: PASS
- id: TC-02
type: unit
description: "result: FAIL без verdict/status -> гейт FAIL, reason содержит FAIL (AC-02)"
module: tests/test_qg.py
fixture_frontmatter: "---\nresult: FAIL\n---\n\nbody\n"
expected: FAIL
- id: TC-03
type: unit
description: "result: PASS, но verdict: BLOCKED -> negative авторитетен -> FAIL (AC-03)"
module: tests/test_qg.py
fixture_frontmatter: "---\nresult: PASS\nverdict: BLOCKED\n---\n\n23 passed\n"
expected: FAIL
- id: TC-04
type: unit
description: "result: PASS, но status: failed -> negative авторитетен -> FAIL (AC-03)"
module: tests/test_qg.py
fixture_frontmatter: "---\nresult: PASS\nstatus: failed\n---\n\nbody\n"
expected: FAIL
- id: TC-05
type: unit
description: "result: ready-to-deploy (positive-токен, без слова PASS) -> PASS (AC-04)"
module: tests/test_qg.py
fixture_frontmatter: "---\nresult: ready-to-deploy\n---\n\nbody\n"
expected: PASS
- id: TC-06
type: unit
description: "Только verdict: PASS (легаси) -> PASS, без регресса (AC-05)"
module: tests/test_qg.py
fixture_frontmatter: "---\nverdict: PASS\nstatus: pass\n---\n\nbody\n"
expected: PASS
- id: TC-07
type: unit
description: "verdict: BLOCKED + проза '23 passed' (ET-013 баг) -> FAIL, без регресса (AC-05)"
module: tests/test_qg.py
fixture_frontmatter: "---\nverdict: BLOCKED\n---\n\nTests: 23 passed, 0 failed.\n"
expected: FAIL
- id: TC-08
type: unit
description: "Ни result, ни verdict, ни status; тело с прозой 'Result: PASS' -> FAIL (AC-06)"
module: tests/test_qg.py
fixture_frontmatter: "---\ntype: test-report\nversion: 1\n---\n\nResult: PASS\n"
expected: FAIL
- id: TC-09
type: unit
description: "Нет frontmatter, проза 'Result: PASS' -> FAIL (AC-07)"
module: tests/test_qg.py
fixture_frontmatter: "# Test Report\n\nResult: PASS\nAll tests passed.\n"
expected: FAIL
- id: TC-10
type: unit
description: "Битый YAML во frontmatter -> FAIL без исключения, reason про YAML/frontmatter (AC-08)"
module: tests/test_qg.py
fixture_frontmatter: "---\nresult: [unclosed\n : : :\n---\n\nbody PASS\n"
expected: FAIL
- id: TC-11
type: unit
description: "Файл 13-test-report.md отсутствует -> FAIL, reason 'not found' (AC-09)"
module: tests/test_qg.py
fixture_frontmatter: null
expected: FAIL
- id: TC-12
type: unit
description: "Реестр QG_CHECKS не изменился -> снапшот зелёный (AC-10)"
module: tests/test_qg_registry_snapshot.py
expected: PASS
- id: TC-13
type: integration
description: "Полный регресс pytest tests/ -q зелёный, существующий TestCheckTestsPassed без правок логики (AC-05, AC-12)"
module: tests/
expected: PASS

View File

@@ -0,0 +1,80 @@
# ADR-001: testing-гейт читает `result:` наравне с `verdict:`/`status:`
- **Статус:** Accepted
- **Дата:** 2026-06-05
- **Задача:** ORCH-047
- **Область:** SHARED quality-gate `check_tests_passed` (общий прод-инстанс: orchestrator + enduro-trails)
## Контекст
Quality Gate `check_tests_passed` (`src/qg/checks.py`, парсер `_parse_tests_verdict`) гейтит
переход `testing → deploy-staging`, читая машиночитаемый вердикт ТОЛЬКО из YAML-frontmatter
артефакта `13-test-report.md` (канон гейтов: frontmatter, никогда не проза — см.
`docs/architecture/README.md`).
Существует рассинхрон контракта между производителем и потребителем вердикта:
- **Потребитель** (`_parse_tests_verdict`) читает поля `verdict:` и `status:`.
- **Производитель** (`.openclaw/agents/tester.md`, строки 5156, 7880) предписывает тестеру
эмитить машиночитаемое поле **`result: PASS|FAIL`** и НЕ упоминает `verdict:`/`status:`.
Тестер, честно следуя своей инструкции, пишет `result: PASS` без `verdict:`/`status:`. Парсер
попадает в ветку «ни verdict, ни status не заданы» → `(False, "No machine-readable
verdict/status…")` → откат `testing → development` и петля до исчерпания
`MAX_DEVELOPER_RETRIES`. Это наблюдалось на ORCH-17; ORCH-016 прошёл лишь потому, что его отчёт
избыточно нёс И `verdict:`, И `result:`.
Корень — несовпадение имён поля контракта, а не логики токенов. Наборы positive/negative-токенов
исправны и менять их нельзя (обратная совместимость с реальными отчётами enduro-trails
ET-001…ET-014).
## Решение
Привести контракт гейта к тому, что тестеру УЖЕ велено эмитить — со стороны гейта, не трогая
промпт тестера.
1. `_parse_tests_verdict` читает **три равноправных** машиночитаемых поля из frontmatter:
`result:` (канон промпта тестера), `verdict:`, `status:` (легаси/enduro-trails). Достаточно
ЛЮБОГО одного непустого.
2. Семантика приоритетов сохраняется и распространяется на все три поля через объединённую строку
`fields = f"{verdict} {status} {result}"`:
- negative-токен (`_TESTS_NEGATIVE_TOKENS`) в любом поле → FAIL и **авторитетен** (проверяется
первым, перебивает positive в другом поле);
- иначе positive-токен (`_TESTS_POSITIVE_TOKENS`) в любом поле → PASS;
- ни одно из трёх не задано → FAIL («No machine-readable verdict/status/result…»);
- заданы, но не распознаны → FAIL.
3. Наборы токенов **не изменяются**.
4. Парсер не бросает исключений ни на каком вводе (битый YAML, пустой файл, frontmatter-не-mapping)
→ всегда `(False, reason)`.
5. Сигнатура `check_tests_passed`, имя гейта и реестр `QG_CHECKS` **не меняются** — снапшот
`tests/test_qg_registry_snapshot.py` остаётся зелёным.
### Альтернативы (отклонены)
- **Править промпт тестера** (`verdict:` вместо `result:`) — отклонено: контракт уже задокументирован
для тестера как `result:`; единичная правка гейта дешевле и не требует переучивать агента, плюс
ломала бы совместимость со старыми отчётами, где встречается `verdict:`/`status:`.
- **Глобальный ADR в `docs/architecture/adr/`** — не требуется: изменение не добавляет гейт/стадию/
компонент и не меняет топологию; это приведение парсинга существующего гейта к контракту. Канон
гейтов в README обновляется точечно.
## Последствия
- **Плюс:** корректные отчёты `result: PASS` проходят гейт; `result: FAIL` надёжно откатывает.
Петля `testing ↔ development` устранена для всех проектов общего инстанса.
- **Плюс:** полная обратная совместимость — отчёты только с `verdict:`/`status:` работают как
раньше; существующие тесты `TestCheckTestsPassed` зелёные без правок (кроме обновления reason-текста
«…verdict/status…» → «…verdict/status/result…»).
- **Минус/ограничение:** число распознаваемых имён поля растёт до трёх — формально шире поверхность
«случайного PASS». Митигируется тем, что negative-токен авторитетен и читается только frontmatter.
- **SHARED-риск:** изменение затрагивает enduro-trails наравне с orchestrator. Регресс по наборам
токенов недопустим → они заморожены; покрытие — `04-test-plan.yaml` (AC-04/AC-05).
- **Self-hosting:** деплой строго через `deploy-staging` (8501); прод-контейнер `orchestrator`
(8500) не перезапускать в рамках разработки/тестинга.
## Связи
- BRD/ТЗ: `docs/work-items/ORCH-047/01-brd.md`, `02-trz.md`.
- Канон гейтов и вердикт-парсер: `docs/architecture/README.md`.
- Промпт-производитель: `.openclaw/agents/tester.md` (`result: PASS|FAIL`).
- adr-0003 (staging-гейт) — обязательная страховка перед прод-деплоем self.

View File

@@ -0,0 +1,10 @@
# Технические риски — ORCH-047
| # | Риск | Вероятность | Влияние | Митигация |
|---|------|-------------|---------|-----------|
| R-1 | Регресс набора токенов ломает enduro-trails (SHARED-гейт, общий прод-инстанс) | Низкая | Высокое | Наборы `_TESTS_NEGATIVE_TOKENS`/`_TESTS_POSITIVE_TOKENS` **заморожены** (не трогать). Покрытие AC-05 на реальных формах ET-001…ET-014 + ORCH-016. |
| R-2 | Новое поле `result:` расширяет поверхность ложного PASS | Низкая | Среднее | Negative-токен авторитетен (проверяется первым, перебивает positive). Читается только frontmatter, не проза (AC-03, AC-06, AC-07). |
| R-3 | Парсер бросает исключение на битом вводе → падение `_run_qg` | Низкая | Высокое | Defensive-контракт сохранён: любой ввод (нет frontmatter / битый YAML / не-mapping / пустой) → `(False, reason)`, никогда raise (AC-08). |
| R-4 | Незаметное изменение реестра гейтов | Очень низкая | Среднее | Сигнатура, имя гейта и `QG_CHECKS` неизменны; снапшот `tests/test_qg_registry_snapshot.py` зелёный (AC-10). |
| R-5 | Self-hosting: деплой роняет прод-контейнер всех проектов | Низкая | Высокое | Деплой только через `deploy-staging` (8501); прод `orchestrator` (8500) не перезапускать в dev/test (CLAUDE.md, adr-0003). |
| R-6 | Изменение поведения без обновления golden-source доки → REQUEST_CHANGES на review | Средняя | Низкое | ADR-001 заведён; `docs/architecture/README.md` (вердикт-парсер) обновлён архитектором; `CHANGELOG.md` — дев в том же PR (AC-11). |

View File

@@ -0,0 +1,62 @@
---
type: review
work_item_id: ORCH-047
verdict: APPROVED
version: 3
---
# Review ORCH-047
## Summary
Гейт `check_tests_passed` (через `_parse_tests_verdict`) теперь читает `result:` наравне с
`verdict:`/`status:`. Реализация точно соответствует ТЗ (`02-trz.md`), ADR-001 и критериям
приёмки. Независимый прогон: `pytest tests/ -q`**442 passed**; снапшот реестра гейтов не
изменился. Документация (README, ADR-001, CHANGELOG) обновлена в том же PR. Блокеров и
must-fix нет → APPROVED.
## Findings
### P0 — Blocker
- нет
### P1 — Must fix
- нет
### P2 — Should fix
- нет
### P3 — Nice-to-have
- [ ] Докстринг `check_tests_passed` (≈стр. 184) по-прежнему говорит «Gate the testing ->
deploy transition», тогда как фактический переход — `testing → deploy-staging`.
Несоответствие предсуществующее, этим PR не введено; чистая косметика, не блокирует.
## Соответствие ТЗ и AC
- **ТЗ §2** — все 10 правил поведения реализованы: чтение `result:` (стр. 261, нормализация
`str(...).upper().strip()` + защита от `None`); все три пусты → корректная reason-строка
«...verdict/status/result...» (стр. 263264); объединённая строка `fields = "{verdict}
{status} {result}"` (стр. 267); negative-токен проверяется ПЕРВЫМ и авторитетен
(стр. 268270); positive (стр. 271273); fallback на нераспознанные (стр. 275279).
Наборы `_TESTS_NEGATIVE_TOKENS`/`_TESTS_POSITIVE_TOKENS` не тронуты. ✅
- **ТЗ §4/§5/§6** — сигнатура `check_tests_passed`, имя гейта, `QG_CHECKS`, HTTP-API, схема БД
не изменены. Снапшот `tests/test_qg_registry_snapshot.py` зелёный (AC-10). ✅
- **AC-01..AC-09** — покрыты новыми кейсами в `TestCheckTestsPassed`: `result: PASS/FAIL`,
авторитетность negative между полями (`verdict: BLOCKED`, `status: failed` поверх
`result: PASS`), `result: ready-to-deploy`, отсутствие машинных полей (reason упоминает
`result`). Легаси-кейсы остались зелёными без правок логики (AC-05). ✅
- **AC-12** — `pytest tests/ -q` → 442 passed (независимый прогон ревьюера). ✅
## Соответствие ADR
- ADR-001 (`06-adr/ADR-001-result-field-in-tests-gate.md`): решение «три равноправных поля,
токены заморожены, negative авторитетен, реестр/сигнатура неизменны» полностью отражено
в коде.
- Глобальный ADR обоснованно не требуется (изменение не добавляет гейт/стадию/компонент,
не меняет топологию) — согласуется с конвенцией CLAUDE.md. SHARED-риск общего инстанса
(orchestrator + enduro-trails) учтён: токены заморожены, обратная совместимость покрыта
тестами.
## Документация
ОБНОВЛЕНА в том же PR (правило 2/6 CLAUDE.md, AC-11):
- `docs/architecture/README.md` — строка вердикт-парсера: для testing-гейта перечислены
`result:`/`verdict:`/`status:` + пометка про авторитетность negative. ✅
- `docs/work-items/ORCH-047/06-adr/ADR-001-result-field-in-tests-gate.md` — заведён. ✅
- `CHANGELOG.md` — запись в `Fixed` про ORCH-047. ✅

View File

@@ -0,0 +1,78 @@
---
type: test-report
work_item_id: ORCH-047
result: PASS
---
# Test Report — ORCH-047
`check_tests_passed` / `_parse_tests_verdict` читает `result:` наравне с `verdict:`/`status:`.
## Окружение
- Python: 3.12.13
- pytest: 8.3.3
- Ветка: feature/ORCH-047-check-tests-passed-gate-must-r
- Среда: dev worktree (прод-контейнер `orchestrator` :8500 не затронут)
- Дата: 2026-06-05
## Smoke test API (prod :8500, read-only)
| Endpoint | Результат |
|----------|-----------|
| `GET /health` | `{"status":"ok","service":"orchestrator"}` — OK |
| `GET /status` | 200, активные задачи отдаются (ORCH-047 в testing) — OK |
| `GET /queue` | 200, counts/breaker/preflight в норме (running:1, failed:0) — OK |
## Результаты (план `04-test-plan.yaml`)
| TC ID | Описание | Тест | Результат |
|-------|----------|------|-----------|
| TC-01 | `result: PASS` без verdict/status → PASS (AC-01) | `test_result_pass_passes` | PASS |
| TC-02 | `result: FAIL` → FAIL, reason содержит FAIL (AC-02) | `test_result_fail_fails` | PASS |
| TC-03 | `result: PASS` + `verdict: BLOCKED` → negative авторитетен → FAIL (AC-03) | `test_result_pass_but_verdict_blocked_fails` | PASS |
| TC-04 | `result: PASS` + `status: failed` → FAIL (AC-03) | `test_result_pass_but_status_failed_fails` | PASS |
| TC-05 | `result: ready-to-deploy` → PASS (AC-04) | `test_result_ready_to_deploy_passes` | PASS |
| TC-06 | Легаси `verdict: PASS` → PASS, без регресса (AC-05) | `test_verdict_pass_passes` | PASS |
| TC-07 | `verdict: BLOCKED` + проза «23 passed» → FAIL (AC-05) | `test_passed_count_in_body_but_blocked_verdict_fails` | PASS |
| TC-08 | Нет машинных полей, проза «Result: PASS» → FAIL (AC-06) | `test_no_machine_field_reason_mentions_result` | PASS |
| TC-09 | Нет frontmatter → FAIL (AC-07) | `test_no_frontmatter_fails` | PASS |
| TC-10 | Битый YAML → FAIL без исключения (AC-08) | `test_invalid_yaml_fails_no_exception` | PASS |
| TC-11 | Отчёт отсутствует → FAIL «not found» (AC-09) | `test_no_report` | PASS |
| TC-12 | Реестр `QG_CHECKS` неизменен (AC-10) | `test_qg_registry_snapshot.py` (3 теста) | PASS |
| TC-13 | Полный регресс зелёный (AC-05, AC-12) | `pytest tests/` | PASS |
## Покрытие критериев приёмки
| AC | Статус |
|----|--------|
| AC-01 `result: PASS` проходит | PASS |
| AC-02 `result: FAIL` откатывает | PASS |
| AC-03 negative авторитетен между полями | PASS |
| AC-04 positive в любом из трёх полей → PASS | PASS |
| AC-05 обратная совместимость (TestCheckTestsPassed) | PASS |
| AC-06 ни одно поле не задано → FAIL | PASS |
| AC-07 только проза без frontmatter → FAIL | PASS |
| AC-08 битый YAML → FAIL без raise | PASS |
| AC-09 отчёт отсутствует → FAIL | PASS |
| AC-10 реестр гейтов неизменен | PASS |
| AC-11 ADR/README/CHANGELOG обновлены | PASS |
| AC-12 полный регресс зелёный | PASS |
AC-11 проверено вручную:
- `docs/work-items/ORCH-047/06-adr/ADR-001-result-field-in-tests-gate.md` — присутствует.
- `docs/architecture/README.md` — строка вердикт-парсера перечисляет `result:`/`verdict:`/`status:`.
- `CHANGELOG.md` — запись `fix:` про ORCH-047.
## Вывод pytest
```
tests/test_qg.py ............................... TestCheckTestsPassed (все PASS,
включая новые test_result_* и легаси-кейсы)
tests/test_qg_registry_snapshot.py::test_tc20_qg_callables_unchanged PASSED
tests/test_qg_registry_snapshot.py::test_tc20_stage_transitions_unchanged PASSED
...
======================== 442 passed, 1 warning in 7.77s ========================
```
(1 warning — предсуществующий PydanticDeprecatedSince20 в `src/config.py`, не связан с ORCH-047.)
## Итог
PASS — все 13 TC и 12 AC выполнены, полный регресс зелёный (442 passed), smoke OK,
реестр гейтов не изменён. Задача готова к стадии deploy-staging.

View File

@@ -0,0 +1,83 @@
---
staging_status: FAILED
timestamp: 2026-06-05T21:30:45Z
base_url: http://localhost:8501
mode: stub
result: 9/10 checks PASS
exit_code: 1
---
# Staging Gate Log — ORCH-047
Staging test suite **FAILED**: 9/10 checks passed, exit code 1.
## Verdict
The live staging service on `:8501` is healthy and the full E2E pipeline ran
correctly against the **sandbox** project (issue created → webhook accepted →
branch created in `orchestrator-sandbox` → analyst job enqueued → cleanup OK).
The single failing check is **B6 — Registry isolation**: the project registry as
seen by the test harness still contains the production projects
(`enduro-trails`, `ORCH`) and does **not** isolate to the sandbox project only.
This violates the staging isolation requirement (CLAUDE.md: "staging — только
sandbox-проект"). Because the staging gate returned a non-zero exit code, the
machine verdict is `FAILED` and the task is rolled back to `development`.
### Notes for follow-up (development)
- B6 imports `src.projects.known_plane_project_ids()` and asserts the registry
contains the sandbox id (`8c5a3025-…`) while the prod ids
(`7a79f0a9-…` ET, `8da6aa25-…` ORCH) are absent. It observed
`sandbox=NO, prod-ET=YES(BAD!), prod-ORCH=YES(BAD!)`.
- This is a staging-environment / registry-isolation signal, not a verdict on the
ORCH-047 code change itself (which targets the `check_tests_passed` gate).
Investigate whether the staging container's isolated project registry env is
loaded, or whether the harness's in-process registry import is reading the host
(`/repos/orchestrator`) prod env instead of the container's env.
- Deployer did **not** modify any production infrastructure, registry, `.env`,
or `docker-compose.yml` to alter this result (per deployer mandate).
## Full test output
```
============================================================
ORCH-33 Staging Check Suite
base_url : http://localhost:8501
mode : stub
utc_time : 2026-06-05T21:30:45.071676+00:00
============================================================
[Block A] SMOKE
✓ PASS A1 GET /health → 200 status=ok [HTTP 200, body={'status': 'ok', 'service': 'orchestrator'}]
✓ PASS A2 GET /queue → 200 with counts/max_concurrency/resilience [HTTP 200, keys=['counts', 'max_concurrency', 'poll_interval', 'resilience', 'recent']]
✓ PASS A3 ORCH_STAGING=true (not prod) [ORCH_STAGING=true]
[Block B] ACCESS
✓ PASS B4 Plane: sandbox project accessible [HTTP 200, found 5 project(s), sandbox=YES]
✓ PASS B5 Gitea: orchestrator-sandbox accessible, push=true [HTTP 200, permissions={'admin': True, 'push': True, 'pull': True}]
✗ FAIL B6 Registry: sandbox present, prod ET/ORCH absent [sandbox=NO, prod-ET=YES(BAD!), prod-ORCH=YES(BAD!)]
[Block C] E2E (mode=stub)
· C7: Creating issue in SANDBOX project...
✓ PASS C7 Create issue in Plane SANDBOX [HTTP 201, issue_id=5040c202-592f-45d0-9463-ca1e9944e6ba]
· C8: Triggering pipeline via POST /webhook/plane ...
· Using HMAC signature (secret len=40)
✓ PASS C8 Trigger pipeline via /webhook/plane [HTTP 200, resp={'status': 'accepted'}]
· C9a: Polling for branch in orchestrator-sandbox (up to 60s)...
✓ PASS C9a Branch appears in orchestrator-sandbox [branch=feature/SANDBOX-010-staging-check-e2e-20260605t213]
· C9b: Checking staging job queue for analyst job (up to 30s)...
· (Plane comment check skipped: bot-tokens not added to SANDBOX project)
✓ PASS C9b Analyst job enqueued in staging queue [job_id=6, status=queued, agent=analyst]
[CLEANUP]
✓ PASS CLEANUP: deleted branch 'feature/SANDBOX-010-staging-check-e2e-20260605t213' (HTTP 204)
✓ PASS CLEANUP: deleted Plane issue 5040c202-592f-45d0-9463-ca1e9944e6ba (HTTP 204)
· CLEANUP DB: no task row found for plane_id=5040c202-592f-45d0-9463-ca1e9944e6ba
· CLEANUP DB dedup: no such table: events_dedup
============================================================
RESULT: 9/10 checks PASS
============================================================
EXIT_CODE=1
```

View File

@@ -0,0 +1,7 @@
# Business Request: staging B6 check reads registry from host worktree, not staging container
Work Item ID: ORCH-048
## Description
TBD

View File

@@ -0,0 +1,86 @@
# 01 — Business Requirements Document (BRD)
**Work Item:** ORCH-048
**Title:** staging B6 check reads registry from host worktree, not staging container
**Stage:** analysis
**Author:** analyst
**Date:** 2026-06-06
---
## 1. Контекст и проблема
`scripts/staging_check.py` — suite живых проверок staging-стенда orchestrator (порт 8501, ADR-0003). Деплоер запускает его на стадии `deploy-staging` и пишет `staging_status:` в `15-staging-log.md`. FAIL любого чека = откат на `development`.
Блок B содержит проверку **B6 «Registry: sandbox present, prod ET/ORCH absent»** — она должна подтверждать, что в staging-реестре проектов есть только sandbox-проект и НЕТ боевых проектов (enduro-trails / orchestrator). Это страховка изоляции: staging не должен обслуживать прод-проекты.
**B6 даёт ложный FAIL** (`prod-ET=YES(BAD!)`, `prod-ORCH=YES(BAD!)`), хотя сама изоляция реестра в staging РАБОТАЕТ корректно.
### Root cause (подтверждён прямым запуском, Стрим, 06.06)
- Внутри контейнера `orchestrator-staging` `known_plane_project_ids()` корректно отдаёт `count=1, sandbox=True, ET=False, ORCH=False`. `.env.staging` верно задаёт `ORCH_PROJECTS_JSON` = только sandbox. **Изоляция реестра исправна.**
- Все остальные чеки (A1A3, B4, B5, блок C E2E) обращаются к работающему staging-инстансу по HTTP и **зелёные**.
- **B6 — единственный чек, который не ходит по HTTP, а импортирует Python-код локально.** В блоке B6 (строки ~263284) выполняется:
```python
sys.path.insert(0, "/repos/orchestrator") # ХОСТ-worktree
importlib.reload(sys.modules["src.projects"]) # подхватывает env ТЕКУЩЕГО процесса
from src.projects import known_plane_project_ids
```
- Деплоер по факту запускает скрипт **с хоста** (`.openclaw/agents/deployer.md`: `python3 scripts/staging_check.py --base-url http://localhost:8501`). В env хост-процесса `ORCH_PROJECTS_JSON` НЕ задан → `src.projects` грузит встроенный `_DEFAULT_PROJECTS` (ET + ORCH) → `known_plane_project_ids()` возвращает боевые id → **ложный FAIL**.
- Иными словами, B6 проверяет реестр НЕ того окружения, реестр которого реально использует staging-инстанс. Гипотеза деплоера про misconfig staging-контейнера — **опровергнута**.
## 2. Бизнес-цель
B6 должен достоверно отражать реестр проектов **именно работающего staging-инстанса** (изолированное окружение), а не реестр, восстановленный из локального импорта в произвольном process-env. При этом B6 обязан по-прежнему ловить реальное нарушение изоляции.
## 3. Заинтересованные стороны
| Роль | Интерес |
|------|---------|
| Deployer-агент | Достоверный сигнал staging-гейта; нет ложных откатов на development |
| Owner / прод | Изоляция staging от прод-проектов реально проверяется (не ложно-зелёная и не ложно-красная) |
| Self-hosting pipeline | `deploy-staging` — обязательная страховка перед прод-деплоем орка; ложный FAIL блокирует доставку всех ORCH-задач |
## 4. Объём (Scope)
### В объёме
- Исправление блока B6 в `scripts/staging_check.py`, чтобы он читал реестр в окружении staging-инстанса.
- Тест на корректность B6: оба исхода (PASS при чистой изоляции; FAIL при попадании прод-проекта в staging-реестр).
- Обновление документации B6 (`docs/operations/STAGING_CHECK.md`, при необходимости `docs/architecture/README.md`/CHANGELOG) в том же PR.
### Вне объёма (НЕ ТРОГАТЬ)
- `src/projects.py` — реестр работает корректно.
- `.env` / `.env.staging` — конфигурация верна.
- Прод-логика оркестратора.
- Остальные staging-чеки B1B5 и блок C E2E — зелёные.
## 5. Бизнес-требования
| ID | Требование |
|----|------------|
| BR-1 | B6 на staging даёт PASS (`sandbox=YES`, `prod-ET=NO`, `prod-ORCH=NO`), читая реестр из окружения staging-инстанса, а не из локального импорта хост-worktree. |
| BR-2 | B6 по-прежнему детектирует реальное нарушение изоляции: если бы прод-проект реально попал в staging-реестр, B6 обязан выдать FAIL. |
| BR-3 | Остальные staging-чеки не сломаны; `src/projects.py` и `.env*` не изменяются. |
| BR-4 | Существующие unit-тесты остаются зелёными (`pytest tests/ -q`). |
| BR-5 | Документация B6 обновлена в том же PR (golden source). |
## 6. Допущения и ограничения
- Решение должно быть минимально инвазивным и не затрагивать прод-логику.
- Скрипт `scripts/staging_check.py` использует только stdlib (нет `requests`/`httpx`) — это конвенция файла, её нужно сохранить.
- Способ запуска suite может варьироваться (с хоста / `docker exec` внутри контейнера) — выбранное решение должно быть корректным для канонического способа запуска деплоером и задокументировано.
## 7. Критерий успеха (бизнес)
- staging-прогон `scripts/staging_check.py` → **B6 PASS** при работающей изоляции.
- При искусственно нарушенной изоляции → **B6 FAIL** (проверяется тестом, без реального изменения staging).
- `python -m pytest tests/ -q` — зелёный.
## 8. Открытые вопросы (для архитектора)
Бизнес-запрос предлагает три варианта реализации (выбор за архитектором, см. 02-trz §4):
- (а) B6 читает реестр через HTTP-эндпоинт staging-инстанса;
- (б) B6 выполняет проверку через subprocess в окружении staging-контейнера (`docker exec`);
- (в) staging_check запускается ВНУТРИ staging-контейнера и читает собственный process-env (убрать host-path хак).
Предпочтение бизнес-запроса: минимально инвазивный вариант, не трогающий прод-логику.

View File

@@ -0,0 +1,118 @@
# 02 — Техническое задание (ТЗ / TRZ)
**Work Item:** ORCH-048
**Title:** staging B6 check reads registry from host worktree, not staging container
**Stage:** analysis
**Author:** analyst
**Date:** 2026-06-06
> Это ТЗ фиксирует требования и инварианты. Выбор одного из трёх архитектурных вариантов (§4) — за архитектором (ADR). Анализ варианты НЕ выбирает.
---
## 1. Задействованные модули
| Путь | Роль | Характер изменений |
|------|------|--------------------|
| `scripts/staging_check.py` | Suite живых staging-проверок; блок B6 (~строки 263284) | **Изменяется** — переписать механику получения реестра в B6 |
| `tests/` (новый файл, напр. `tests/test_staging_check_b6.py`) | Unit-тест корректности B6 | **Создаётся** |
| `docs/operations/STAGING_CHECK.md` | Док запуска suite | **Обновляется** (описание B6 + способ запуска) |
| `docs/architecture/README.md` / `CHANGELOG.md` | Golden source | **Обновляется** при необходимости |
### НЕ изменять (жёсткий инвариант scope)
- `src/projects.py` — реестр работает корректно.
- `.env`, `.env.staging`, `.env.example` — конфиг верен.
- Прод-логику оркестратора (`src/main.py` прод-роуты, `src/webhooks/*`, `src/stage_engine.py`, `src/qg/*`) — кроме случая варианта (а), если архитектор решит добавить read-only эндпоинт (см. §4а, отдельно обоснованный риск).
- Блоки A1A3, B4, B5 и блок C E2E в `staging_check.py`.
## 2. Текущее поведение (то, что чиним)
Блок B6 (`scripts/staging_check.py`):
```python
sys.path.insert(0, "/repos/orchestrator") # хост-worktree path
import importlib
if "src.projects" in sys.modules:
importlib.reload(sys.modules["src.projects"]) # перечитывает env ТЕКУЩЕГО процесса
from src.projects import known_plane_project_ids
known = known_plane_project_ids()
```
Проблема: реестр строится из `ORCH_PROJECTS_JSON` **process-env того процесса, в котором исполняется скрипт**. При запуске деплоером с хоста (`python3 scripts/staging_check.py --base-url http://localhost:8501`) переменная не задана → `_DEFAULT_PROJECTS` (ET+ORCH) → ложный FAIL. B6 не отражает реестр работающего staging-инстанса.
## 3. Требуемое поведение (контракт B6)
| ID | Требование |
|----|------------|
| TR-1 | B6 определяет набор «известных staging-инстансу Plane project id» из источника, который **гарантированно отражает окружение работающего staging-инстанса** (порт 8501 / контейнер `orchestrator-staging`), а не из локального импорта в process-env скрипта. |
| TR-2 | B6 PASS ⟺ `SANDBOX_PROJECT_ID ∈ known` И `PROD_ET_PROJECT_ID ∉ known` И `PROD_ORCH_PROJECT_ID ∉ known`. Идентификаторы — те же константы, что уже в скрипте. |
| TR-3 | B6 сохраняет формат вывода `Results.add(label, passed, detail)` с человекочитаемым detail (`sandbox=…, prod-ET=…, prod-ORCH=…`). |
| TR-4 | При недоступности источника реестра B6 даёт **детерминированный FAIL** с понятным detail (не падает с необработанным исключением, не даёт ложный PASS). |
| TR-5 | Скрипт остаётся на stdlib (без сторонних зависимостей), если выбранный вариант это допускает. |
| TR-6 | Удаляется зависимость B6 от хардкод-пути `/repos/orchestrator` для построения реестра (host-path хак), несовместимого с целью проверки. |
## 4. Варианты реализации — РЕШЕНИЕ ВЛАДЕЛЬЦА (обязательно)
> **РЕШЕНИЕ ПРИНЯТО ВЛАДЕЛЬЦЕМ ПРОЕКТА (Слава, 06.06): выбран ВАРИАНТ (в).**
> Архитектор НЕ выбирает заново — он фиксирует вариант (в) в ADR с обоснованием ниже.
>
> ### Почему (в), а НЕ (а) и НЕ (б)
> - **(а) HTTP-эндпоинт `GET /projects`** — ОТКЛОНЁН. Порождает «курицу-яйцо»: B6 ходит на эндпоинт **работающего** staging-инстанса, а эндпоинт запечён в Docker-образ → на первом прогоне его в живом инстансе ещё нет (404) → ложный FAIL → откат. Требует ручного bootstrap-деплоя. Это ровно тот класс поломки автономности, который мы устраняем. (Подтверждено на проде 06.06: `GET /projects` на 8501 → 404 → deploy-staging FAILED.)
> - **(б) `docker exec` subprocess** — ОТКЛОНЁН. Хрупкое экранирование (см. `docs/history/LESSONS_2026-06-05.md`), зависимость от docker-CLI и имени контейнера.
> - **(в) запуск suite ВНУТРИ staging-контейнера + чтение собственного process-env** — ВЫБРАН. B6 не зависит от того, что отдаёт инстанс по HTTP; `staging_check.py` берётся из mount (свежий код сразу, без ребилда образа); реестр читается из env самого `orchestrator-staging`. **Курицы-яйца нет ни на первом прогоне, ни в будущем.** Автономность не ломается.
>
> ### Что обязан зафиксировать архитектор в ADR (вариант в)
> 1. Убрать из B6 host-path хак `sys.path.insert(0, "/repos/orchestrator")` и `importlib.reload(src.projects)`.
> 2. Канонизировать запуск suite ВНУТРИ контейнера: `docker exec orchestrator-staging python3 <путь к staging_check.py> --base-url http://localhost:8501` (или эквивалент, где cwd/PYTHONPATH и env — staging-контейнера). Код импортируется из кода контейнера, env уже staging.
> 3. **Синхронно** обновить `.openclaw/agents/deployer.md` (способ запуска suite через `docker exec`, НЕ с хоста) и `docs/operations/STAGING_CHECK.md` — иначе host-запуск воспроизведёт баг.
> 4. Логику вердикта B6 вынести в чистую функцию `_evaluate_b6(known: set[str]) -> tuple[bool, str]` (TR-2/§9) для unit-теста на оба исхода (AC-2).
> 5. НЕ добавлять HTTP-эндпоинт `/projects` и НЕ трогать прод-`src/main.py`. НЕ трогать `src/projects.py`, `.env*`, прочие чеки A/B4/B5/C.
>
> ### Нюанс топологии (учесть)
> `Dockerfile` НЕ копирует `scripts/` в образ → `staging_check.py` доступен в контейнере только через mount `/repos/orchestrator/scripts/...`. Архитектор должен указать в ADR корректный путь запуска внутри контейнера, учитывая этот mount (а не `/app/scripts`).
---
## 4-original. Варианты реализации (исходный анализ — справочно)
## 4. Варианты реализации (выбор — архитектор, в ADR)
Бизнес-запрос предлагает три варианта. Анализ перечисляет их с известными плюсами/минусами; решение и обоснование — в `06-adr/`.
### (а) HTTP-эндпоинт staging-инстанса
B6 запрашивает реестр у работающего staging-инстанса по HTTP (как делают A/B4/B5/C).
- **Сейчас подходящего эндпоинта НЕТ.** `/health`, `/status`, `/queue` реестр проектов не отдают (`src/main.py`).
- Потребуется добавить read-only эндпоинт (напр. `GET /projects`, отдающий `known_plane_project_ids()` или список репо/prefix). Это касается прод-`main.py` → выходит за «не трогать прод-логику», но изменение read-only и низкорисковое — архитектор взвешивает.
- Плюс: B6 гарантированно читает реестр именно того процесса, что обслуживает webhooks. Единый HTTP-стиль с остальными чеками.
### (б) Subprocess в окружении staging-контейнера
B6 выполняет `docker exec orchestrator-staging python3 -c "from src.projects import known_plane_project_ids; ..."` и парсит stdout.
- Плюс: не трогает прод-`main.py`; читает env контейнера напрямую.
- Минус: требует доступности docker-CLI и имени контейнера из среды запуска suite; усложняет запуск «изнутри контейнера»; есть нюансы экранирования (см. `docs/history/LESSONS_2026-06-05.md`).
### (в) Запуск suite внутри контейнера + чтение собственного process-env
Канонизировать запуск `staging_check.py` ВНУТРИ `orchestrator-staging` (`docker exec orchestrator-staging python3 …`), убрать `sys.path.insert(0, "/repos/orchestrator")`, импортировать `src.projects` из кода контейнера (его cwd/PYTHONPATH), env уже staging.
- Плюс: минимально инвазивно, не трогает прод-логику и `src.projects`; согласуется с «рекомендуемым способом запуска» в `STAGING_CHECK.md §Способы запуска.1`.
- Условие: деплоер должен запускать suite через `docker exec` (а не с хоста). Нужно синхронно обновить `.openclaw/agents/deployer.md` и `STAGING_CHECK.md`, иначе host-запуск воспроизведёт баг.
- Нюанс: внутри контейнера код лежит в `/app` (Dockerfile `COPY`), а `/repos/orchestrator` — отдельный mount; импорт должен резолвиться из кода, чьим env реально живёт инстанс.
## 5. Изменения API
- Варианты (б) и (в): **нет** изменений API.
- Вариант (а): новый read-only эндпоинт (напр. `GET /projects`) — точная схема ответа определяется архитектором. Если выбран — задокументировать в `docs/architecture/README.md` (таблица API) и `CHANGELOG.md`.
## 6. Изменения схемы БД
Нет.
## 7. Требования к новым QG checks
Нет новых QG. Поведение `check_staging_status` (ADR-0003) не меняется — меняется только достоверность одного из чеков suite, чей агрегат пишется в `15-staging-log.md`.
## 8. Артефакты pipeline, создаваемые/обновляемые
- Код: `scripts/staging_check.py` (B6), новый тест в `tests/`.
- Док: `docs/operations/STAGING_CHECK.md`; при выборе варианта (а) — `docs/architecture/README.md` (API) и `CHANGELOG.md`; при выборе (в) — `.openclaw/agents/deployer.md` (способ запуска) и `STAGING_CHECK.md`.
- ADR: `docs/work-items/ORCH-048/06-adr/ADR-001-*.md` — обоснование выбранного варианта.
## 9. Тестируемость
- Логика «PASS/FAIL по набору known id» B6 должна быть выделена в чистую, юнит-тестируемую функцию (напр. `_evaluate_b6(known: set[str]) -> tuple[bool, str]`), чтобы тест проверял оба исхода без поднятия staging-инстанса/docker. План — `04-test-plan.yaml`.
## 10. Definition of Done
- BR-1…BR-5 (01-brd) выполнены.
- staging-прогон → B6 PASS; `pytest tests/ -q` зелёный.
- Док и (при необходимости) ADR обновлены в том же PR.

View File

@@ -0,0 +1,67 @@
# 03 — Критерии приёмки (Acceptance Criteria)
**Work Item:** ORCH-048
**Title:** staging B6 check reads registry from host worktree, not staging container
**Stage:** analysis
**Author:** analyst
**Date:** 2026-06-06
Каждый критерий формулирует чёткое условие PASS/FAIL. Источник — бизнес-запрос ORCH-048 (AC-1…AC-4) + BRD.
---
## AC-1 — B6 PASS на staging, читая реестр из staging-окружения
**Условие PASS:**
- При staging-прогоне `scripts/staging_check.py` (канонический способ запуска, выбранный архитектором) чек **B6** выдаёт `✓ PASS` c detail `sandbox=YES, prod-ET=NO(good), prod-ORCH=NO(good)`.
- Набор known id, по которому судит B6, получен из окружения работающего staging-инстанса (HTTP-эндпоинт / docker-окружение контейнера / собственный process-env при запуске внутри контейнера), **не** из локального импорта `src.projects` в произвольном process-env с host-path хаком `/repos/orchestrator`.
**FAIL, если:** B6 даёт ложный FAIL (`prod-ET=YES(BAD!)` / `prod-ORCH=YES(BAD!)`) при фактически исправной изоляции; либо реестр в B6 по-прежнему строится локальным импортом, зависящим от env процесса-запускателя.
## AC-2 — B6 ловит РЕАЛЬНОЕ нарушение изоляции (оба исхода покрыты тестом)
**Условие PASS:**
- Существует unit-тест, проверяющий логику вердикта B6 на **двух** входах:
1. «чистый» staging-реестр (`known = {SANDBOX}`) → B6 вердикт **PASS**;
2. «загрязнённый» реестр (например `known = {SANDBOX, PROD_ET}` и/или `{SANDBOX, PROD_ORCH}`) → B6 вердикт **FAIL**.
- Тест не требует поднятия живого staging-инстанса/docker (логика вердикта изолирована и тестируема, см. 02-trz §9).
**FAIL, если:** покрыт только один исход; либо B6 даёт PASS при наличии прод-проекта в реестре (потеря защитной функции).
## AC-3 — Остальные staging-чеки не сломаны; src/projects.py и .env не тронуты
**Условие PASS:**
- Блоки A1A3, B4, B5 и блок C (E2E) в `scripts/staging_check.py` функционально не изменены (формат вывода и логика прежние).
- `git diff` work item НЕ содержит изменений в `src/projects.py`, `.env`, `.env.staging`, `.env.example`.
- Прод-логика оркестратора не затронута. Исключение допускается только если архитектор в ADR выбрал вариант (а) и добавил read-only эндпоинт — тогда изменение ограничено добавлением этого эндпоинта, прод-поведение существующих роутов неизменно.
**FAIL, если:** изменён `src/projects.py` или любой `.env*`; либо затронута/сломана логика прочих чеков.
## AC-4 — Существующие unit-тесты зелёные
**Условие PASS:**
- `python -m pytest tests/ -q` завершается с кодом 0; все ранее зелёные тесты остаются зелёными; новый тест B6 (AC-2) проходит.
**FAIL, если:** любой тест падает.
## AC-5 — Документация обновлена в том же PR (golden source)
**Условие PASS:**
- `docs/operations/STAGING_CHECK.md` отражает исправленную механику B6 и канонический способ запуска suite.
- При выборе варианта (а): обновлены таблица API в `docs/architecture/README.md` и `CHANGELOG.md`.
- При выборе варианта (в): обновлены `.openclaw/agents/deployer.md` (запуск через `docker exec`) и `STAGING_CHECK.md`.
- Заведён ADR `docs/work-items/ORCH-048/06-adr/ADR-001-*.md` с обоснованием выбранного варианта.
**FAIL, если:** код изменён, а соответствующая док/ADR не обновлены.
---
## Сводная проверка (как мерить приёмку)
| AC | Команда / действие | Ожидаемый результат |
|----|--------------------|---------------------|
| AC-1 | staging-прогон suite (выбранным способом) | `B6 … ✓ PASS [sandbox=YES, prod-ET=NO(good), prod-ORCH=NO(good)]` |
| AC-2 | `pytest tests/test_staging_check_b6.py -q` | оба кейса (clean→PASS, polluted→FAIL) зелёные |
| AC-3 | `git diff --name-only` по ветке | нет `src/projects.py`, нет `.env*`; чеки A/B4/B5/C не изменены по сути |
| AC-4 | `python -m pytest tests/ -q` | exit 0, все PASS |
| AC-5 | ревью diff документации | STAGING_CHECK.md + ADR-001 присутствуют и согласованы с кодом |

View File

@@ -0,0 +1,97 @@
work_item: ORCH-048
title: staging B6 check reads registry from host worktree, not staging container
stage: analysis
notes: >
B6 в staging_check.py должен оценивать реестр окружения работающего staging-инстанса.
Для тестируемости логика вердикта B6 выделяется в чистую функцию (напр.
_evaluate_b6(known: set[str]) -> tuple[bool, str]); тесты бьют именно её и не
поднимают живой staging-инстанс/docker. Идентификаторы — те же константы из скрипта:
SANDBOX_PROJECT_ID=8c5a3025-4f9d-4190-b79f-fa06276bb27e,
PROD_ET_PROJECT_ID=7a79f0a9-5278-49cd-9007-9a338f238f9c,
PROD_ORCH_PROJECT_ID=8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a.
tests:
- id: TC-01
type: unit
description: >
B6-вердикт PASS при чистом staging-реестре: known={SANDBOX} ->
passed=True, detail содержит sandbox=YES, prod-ET=NO, prod-ORCH=NO. (AC-1, AC-2)
module: tests/test_staging_check_b6.py
expected: PASS
- id: TC-02
type: unit
description: >
B6-вердикт FAIL при попадании прод-ET в реестр: known={SANDBOX, PROD_ET} ->
passed=False, detail помечает prod-ET как нарушение. (AC-2)
module: tests/test_staging_check_b6.py
expected: PASS
- id: TC-03
type: unit
description: >
B6-вердикт FAIL при попадании прод-ORCH в реестр: known={SANDBOX, PROD_ORCH} ->
passed=False, detail помечает prod-ORCH как нарушение. (AC-2)
module: tests/test_staging_check_b6.py
expected: PASS
- id: TC-04
type: unit
description: >
B6-вердикт FAIL при отсутствии sandbox в реестре: known=set() (пусто) ->
passed=False (sandbox absent), детерминированно, без исключения. (AC-2, TR-4)
module: tests/test_staging_check_b6.py
expected: PASS
- id: TC-05
type: unit
description: >
B6-вердикт FAIL при загрязнении и ET, и ORCH одновременно:
known={SANDBOX, PROD_ET, PROD_ORCH} -> passed=False. (AC-2)
module: tests/test_staging_check_b6.py
expected: PASS
- id: TC-06
type: unit
description: >
Источник реестра в B6 больше не зависит от host-path хака
sys.path.insert(0,"/repos/orchestrator"): проверить (статически/через структуру
кода или мок источника), что построение known не делается локальным импортом
src.projects из произвольного process-env. (AC-1, TR-6)
module: tests/test_staging_check_b6.py
expected: PASS
- id: TC-07
type: unit
description: >
Деградация источника реестра (HTTP-ошибка / недоступный контейнер / битый ответ)
-> B6 даёт детерминированный FAIL с понятным detail, а не ложный PASS и не
необработанное исключение. (TR-4)
module: tests/test_staging_check_b6.py
expected: PASS
- id: TC-08
type: unit
description: >
Регрессия реестра: существующие тесты src/projects.py остаются зелёными,
подтверждая, что src/projects.py не изменён. (AC-3, AC-4)
module: tests/test_projects.py
expected: PASS
- id: TC-09
type: integration
description: >
Полный прогон pytest без падений после правок:
`python -m pytest tests/ -q` -> exit 0. (AC-4)
module: tests/
expected: PASS
- id: TC-10
type: integration
description: >
Живой staging-прогон (ручной, вне CI): запустить scripts/staging_check.py
выбранным архитектором способом против orchestrator-staging (8501) ->
B6 == PASS (sandbox=YES, prod-ET=NO, prod-ORCH=NO); блоки A/B4/B5/C не сломаны.
(AC-1, AC-3) Выполняется деплоером на стадии deploy-staging.
module: scripts/staging_check.py
expected: PASS

View File

@@ -0,0 +1,139 @@
# ADR-001: B6 читает реестр через запуск suite ВНУТРИ staging-контейнера
## Статус
Accepted
- **Задача:** ORCH-048
- **Дата:** 2026-06-06
- **Автор:** architect
- **Решение варианта:** принято Владельцем проекта (Слава, 06.06) — вариант **(в)**. Архитектор фиксирует и обосновывает.
## Контекст
Чек **B6 «Registry: sandbox present, prod ET/ORCH absent»** в `scripts/staging_check.py`
(блок B, ~строки 263284) — страховка изоляции staging: подтверждает, что в реестре
проектов работающего staging-инстанса есть только sandbox-проект и НЕТ боевых
(enduro-trails / orchestrator).
B6 даёт **ложный FAIL** (`prod-ET=YES(BAD!)`, `prod-ORCH=YES(BAD!)`), хотя изоляция
реестра в staging исправна. Root cause (подтверждён прямым запуском, 06.06):
```python
sys.path.insert(0, "/repos/orchestrator") # host-worktree path
import importlib
if "src.projects" in sys.modules:
importlib.reload(sys.modules["src.projects"]) # перечитывает env ТЕКУЩЕГО процесса
from src.projects import known_plane_project_ids
known = known_plane_project_ids()
```
B6 — единственный чек, который не ходит к инстансу по HTTP, а импортирует Python-код
локально и строит реестр из `ORCH_PROJECTS_JSON` **process-env того процесса, в котором
исполняется скрипт**. Деплоер фактически запускает suite **с хоста**
(`python3 scripts/staging_check.py --base-url http://localhost:8501`), где
`ORCH_PROJECTS_JSON` не задан → `src.projects` грузит встроенный `_DEFAULT_PROJECTS`
(ET + ORCH) → ложный FAIL. B6 проверяет реестр НЕ того окружения, реестр которого
реально использует staging-инстанс.
### Топология (ключевой факт для решения)
- Контейнер `orchestrator-staging`: `WORKDIR /app`, `ENV PYTHONPATH=/app`; код приложения
**скопирован** в образ (`Dockerfile: COPY src/ ./src/`) → живёт в `/app/src/`.
- `.env.staging` (env_file контейнера) задаёт `ORCH_PROJECTS_JSON` = только sandbox.
- `Dockerfile` **НЕ копирует** `scripts/` в образ. Скрипт доступен в контейнере только
через bind-mount `/home/slin/repos:/repos``/repos/orchestrator/scripts/staging_check.py`.
Из этого следует: при запуске `docker exec orchestrator-staging python3
/repos/orchestrator/scripts/staging_check.py` интерпретатор добавляет в `sys.path[0]`
каталог скрипта (`/repos/orchestrator/scripts`), а `import src.projects` резолвится через
`PYTHONPATH=/app``/app/src/projects.py` (собственный код контейнера) с env из
`.env.staging`. Это ровно реестр работающего staging-инстанса — без HTTP, без host-path хака.
## Решение
Принят **вариант (в): канонизировать запуск suite ВНУТРИ `orchestrator-staging` и читать
собственный process-env контейнера.**
Архитектурно фиксируется (детальная реализация — стадия development):
1. **Убрать из B6 host-path хак:** удалить `sys.path.insert(0, "/repos/orchestrator")` и
`importlib.reload(sys.modules["src.projects"])`. Импорт `from src.projects import
known_plane_project_ids` остаётся, но резолвится из кода контейнера (`/app/src` через
`PYTHONPATH=/app`), env которого — staging (`.env.staging`).
2. **Канонизировать запуск suite внутри контейнера** (а не с хоста):
```bash
docker exec orchestrator-staging \
python3 /repos/orchestrator/scripts/staging_check.py \
--base-url http://localhost:8501 --mode stub
```
`--base-url http://localhost:8501` корректен изнутри контейнера: сеть `network_mode: host`.
Путь к скрипту — `/repos/orchestrator/scripts/...` (mount), а НЕ `/app/scripts` (в образе
scripts отсутствует).
3. **Синхронно обновить документацию запуска** (этот же PR), иначе host-запуск воспроизведёт
баг:
- `.openclaw/agents/deployer.md` — команда стадии `deploy-staging` через `docker exec`.
- `docs/operations/STAGING_CHECK.md` — канонический способ запуска и описание механики B6.
4. **Логику вердикта B6 вынести в чистую функцию** `_evaluate_b6(known: set[str]) ->
tuple[bool, str]`, инвариант (TR-2): `passed ⟺ SANDBOX ∈ known ∧ PROD_ET ∉ known ∧
PROD_ORCH ∉ known`; `detail` сохраняет формат `sandbox=…, prod-ET=…, prod-ORCH=…` (TR-3).
Функция юнит-тестируема без поднятия инстанса/docker (TC-01…TC-07).
5. **Детерминированная деградация (TR-4):** при недоступности источника реестра (ошибка
импорта/построения `known`) B6 даёт FAIL с понятным detail, без необработанного исключения
и без ложного PASS.
### Границы (scope guards — обязательны)
- **НЕ** добавлять HTTP-эндпоинт `GET /projects`; **НЕ** трогать прод-`src/main.py`,
`src/webhooks/*`, `src/stage_engine.py`, `src/qg/*`.
- **НЕ** изменять `src/projects.py`, `.env`, `.env.staging`, `.env.example`.
- **НЕ** менять блоки A1A3, B4, B5 и блок C (E2E): формат вывода и логика прежние.
- Реестр QG и стадий не меняется; ADR-0003 (`check_staging_status`) в силе — меняется только
достоверность одного чека внутри suite, чей агрегат пишется в `15-staging-log.md`.
## Альтернативы (отклонены)
### (а) HTTP-эндпоинт `GET /projects` работающего staging-инстанса — ОТКЛОНЁН
Порождает «курицу-яйцо»: B6 ходит на эндпоинт **работающего** инстанса, а эндпоинт запечён
в Docker-образ → на первом прогоне его в живом инстансе ещё нет (404) → ложный FAIL → откат.
Требует ручного bootstrap-деплоя. Это ровно тот класс поломки автономности, который мы
устраняем. Подтверждено на проде 06.06: `GET /projects` на 8501 → 404 → deploy-staging FAILED.
(Предыдущая итерация архитектора выбрала (а); решение отклонено Владельцем, код и ADR(а)
удалены, ветка откатана к analyst-артефактам.)
### (б) `docker exec` subprocess + парсинг stdout — ОТКЛОНЁН
`docker exec orchestrator-staging python3 -c "..."` из процесса suite. Хрупкое экранирование
(`docs/history/LESSONS_2026-06-05.md`), зависимость от наличия docker-CLI и имени контейнера
в среде запуска, усложняет запуск «изнутри контейнера».
### (в) Запуск suite внутри контейнера + собственный process-env — ВЫБРАН
B6 не зависит от того, что отдаёт инстанс по HTTP; `staging_check.py` берётся из mount (свежий
код сразу, без ребилда образа); реестр читается из env самого `orchestrator-staging`. Курицы-яйца
нет ни на первом прогоне, ни в будущем. Минимально инвазивно, прод-логика и `src/projects.py` не
тронуты. Согласуется с «рекомендуемым способом запуска» (`STAGING_CHECK.md §Способы запуска.1`).
## Последствия
**Плюсы**
- B6 достоверно отражает реестр работающего staging-инстанса; ложные FAIL/откаты устранены.
- Автономность self-hosting не ломается: нет bootstrap-зависимости от запечённого в образ кода.
- Свежий `staging_check.py` подхватывается из mount без ребилда образа.
- Защитная функция B6 сохранена и покрыта юнит-тестами на оба исхода (PASS/FAIL).
**Минусы / ограничения**
- Запуск suite **обязан** идти через `docker exec` внутри `orchestrator-staging`. Запуск с
хоста воспроизведёт исходный баг (host-env без `ORCH_PROJECTS_JSON`). Это закреплено в
`deployer.md` и `STAGING_CHECK.md`; способ «с хоста» остаётся возможен, только если env
хоста корректно повторяет staging (не рекомендуется, помечено).
- Деплоер должен иметь доступ к docker-CLI/сокету (есть: `/var/run/docker.sock` смонтирован в
контейнер оркестратора, у которого deployer-агент исполняется; `deployer.md` tools: Bash docker).
## Связи
- ADR-0003 (`docs/architecture/adr/adr-0003-staging-gate.md`) — staging-гейт, который этот чек
обслуживает.
- ORCH-6 / `src/projects.py` — реестр проектов (источник `known_plane_project_ids()`),
НЕ изменяется.
- `docs/history/LESSONS_2026-06-05.md` — обоснование отказа от варианта (б).

View File

@@ -0,0 +1,69 @@
---
type: review
work_item_id: ORCH-048
verdict: APPROVED
version: 1
---
# Review ORCH-048
## Summary
PR чинит ложный FAIL чека **B6** в `scripts/staging_check.py`: реестр проектов теперь
читается из окружения работающего staging-инстанса (вариант «в», выбранный Владельцем и
зафиксированный в ADR-001), host-path хак `sys.path.insert(0, "/repos/orchestrator")` +
`importlib.reload` удалён. Реализация соответствует ТЗ, ADR-001 и всем критериям приёмки.
Документация обновлена синхронно. `pytest tests/ -q`**470 passed**.
Соответствие осям проверки:
- **ТЗ (02-trz):** TR-1…TR-6 выполнены. TR-1/TR-6 — реестр строится из process-env
инстанса, host-path хак удалён. TR-2 — инвариант `passed ⟺ SANDBOX ∈ known ∧ PROD_ET ∉
known ∧ PROD_ORCH ∉ known` в `_evaluate_b6`. TR-3 — формат detail сохранён. TR-4 —
детерминированный FAIL при недоступности источника (`_run_b6` ловит `Exception`, нет
ложного PASS, нет необработанного исключения). TR-5 — stdlib. §9 — логика вердикта
вынесена в чистую `_evaluate_b6` для unit-теста.
- **ADR-001:** реализация дословно следует пунктам 15 решения и scope-guards.
HTTP-эндпоинт не добавлен, прод-`src/main.py` не тронут.
- **AC-1…AC-5:** AC-1 — механика читает реестр инстанса; AC-2 — оба исхода покрыты
(TC-01 clean→PASS, TC-02/03/05 polluted→FAIL); AC-3 — `git diff` не содержит
`src/projects.py`/`.env*`, блоки A1A3/B4/B5/C не тронуты; AC-4 — 470 passed; AC-5 —
STAGING_CHECK.md, deployer.md, CHANGELOG, ADR-001 обновлены в этом же PR.
- **Качество кода:** чистые функции, докстринги на всех новых функциях, defensive-обработка,
`sys` остаётся используемым (`sys.exit`), без мёртвых импортов. Тесты содержательные
(7 TC + happy-path wiring + статическая проверка отсутствия хака).
## Findings
### P0 — Blocker
- нет
### P1 — Must fix
- нет
### P2 — Should fix
- нет
### P3 — Nice-to-have
- [ ] `test_tc06_no_host_path_hack_in_source` и `test_tc06_registry_loader_uses_src_projects`
носят одинаковый префикс `tc06` — формально это два разных кейса; имена можно было бы
развести для читаемости отчёта pytest. Косметика, на приёмку не влияет.
## Документация
Полностью обновлена в том же PR (golden source соблюдён):
- `docs/operations/STAGING_CHECK.md` — канонический способ запуска (способ 1 через
`docker exec`), способ «с хоста» помечен как невалидный/воспроизводящий баг, добавлена
секция «Механика чека B6».
- `.openclaw/agents/deployer.md` — команда стадии `deploy-staging` переведена на
`docker exec orchestrator-staging python3 /repos/orchestrator/scripts/staging_check.py …`
с пояснением, почему host-запуск ломает B6.
- `CHANGELOG.md` — запись в разделе Fixed с полным описанием root cause и решения.
- ADR `docs/work-items/ORCH-048/06-adr/ADR-001-b6-registry-via-in-container-run.md`
обоснование варианта (в), отклонённые (а)/(б), scope-guards.
`docs/architecture/README.md` обновлять не требовалось: API, реестр стадий и `QG_CHECKS`
не менялись (изменение касается только достоверности одного чека внутри suite).
**Вердикт: APPROVED** — P0/P1 отсутствуют.

View File

@@ -0,0 +1,79 @@
---
type: test-report
work_item_id: ORCH-048
result: PASS
---
# Test Report — ORCH-048
**Title:** staging B6 check reads registry from host worktree, not staging container
**Stage:** testing
**Branch:** feature/ORCH-048-staging-b6-check-reads-registr
## Окружение
- Python: 3.12.13
- pytest: 8.3.3
- Дата: 2026-06-06T07:06Z
- Prod API (8500): `/health` 200 ok, `/status` 200 (ORCH-048 в stage=testing), `/queue` 200 (breaker closed, preflight ok)
## Результаты
| TC ID | Тип | Описание | Результат |
|-------|-----|----------|-----------|
| TC-01 | unit | `known={SANDBOX}` → B6 PASS, detail sandbox=YES/prod-ET=NO/prod-ORCH=NO | PASS |
| TC-02 | unit | `known={SANDBOX,PROD_ET}` → B6 FAIL, prod-ET помечен нарушением | PASS |
| TC-03 | unit | `known={SANDBOX,PROD_ORCH}` → B6 FAIL, prod-ORCH помечен нарушением | PASS |
| TC-04 | unit | `known=set()` (нет sandbox) → детерминированный FAIL без исключения | PASS |
| TC-05 | unit | `known={SANDBOX,PROD_ET,PROD_ORCH}` → B6 FAIL | PASS |
| TC-06 | unit | Нет host-path хака `/repos/orchestrator`; реестр строится не локальным импортом в произвольном process-env | PASS |
| TC-07 | unit | Деградация источника реестра → детерминированный FAIL с понятным detail (не ложный PASS, не необработанное исключение) | PASS |
| TC-08 | unit | Регрессия `src/projects.py` (16 тестов) зелёные — реестр не изменён | PASS |
| TC-09 | integration | `python -m pytest tests/ -q` → exit 0 | PASS |
| TC-10 | integration | Живой staging-прогон B6 на 8501 | DEFERRED — выполняется деплоером на стадии deploy-staging (см. 04-test-plan TC-10) |
Доп. покрытие: `test_run_b6_records_pass_for_clean_registry` (happy-path wiring `_run_b6`).
## Покрытие критериев приёмки
| AC | Подтверждение | Статус |
|----|---------------|--------|
| AC-1 | B6 PASS на чистом реестре (TC-01), источник — окружение инстанса, host-path хак удалён (TC-06) | PASS |
| AC-2 | Оба исхода покрыты: clean→PASS (TC-01), polluted→FAIL (TC-02/03/05), без sandbox→FAIL (TC-04) | PASS |
| AC-3 | `git diff origin/main...HEAD` НЕ содержит `src/projects.py` / `.env*`; блоки A/B4/B5/C не тронуты | PASS |
| AC-4 | `pytest tests/ -q` → exit 0, 470 passed | PASS |
| AC-5 | STAGING_CHECK.md, deployer.md, CHANGELOG.md, ADR-001 обновлены в том же PR (подтверждено review) | PASS |
## Проверка scope (AC-3)
Изменённые файлы ветки vs origin/main:
```
.openclaw/agents/deployer.md
CHANGELOG.md
docs/operations/STAGING_CHECK.md
docs/work-items/ORCH-048/* (артефакты задачи)
scripts/staging_check.py
tests/test_staging_check_b6.py
```
Forbidden-path check: OK — `src/projects.py` и `.env*` НЕ затронуты.
## Вывод pytest
Полный прогон:
```
470 passed, 1 warning in 9.07s
pytest exit code: 0
```
(warning — PydanticDeprecatedSince20 в `src/config.py`, предсуществующий, к ORCH-048 не относится.)
B6 suite:
```
tests/test_staging_check_b6.py ......... [9 passed]
9 passed, 1 warning in 0.29s
```
projects-регрессия (TC-08):
```
16 passed, 1 warning in 0.31s
```
## Итог
**PASS** — все unit/integration тесты зелёные (470 passed, exit 0), smoke API prod исправен, scope-инвариант AC-3 соблюдён. Живой staging-прогон B6 (TC-10) выполняется деплоером на стадии deploy-staging.

View File

@@ -0,0 +1,42 @@
---
deploy_status: SUCCESS
timestamp: 2026-06-06T07:12:00Z
work_item: ORCH-048
target: orchestrator (prod, self-hosting)
restart_required: false
rebuild_required: false
staging_gate: SUCCESS
---
# Production Deploy Log — ORCH-048
Production rollout of ORCH-048 (`fix(staging_check): B6 reads registry from running staging instance env`) is **complete on merge** — no prod container rebuild or restart was required, and none was performed.
## Precondition: staging gate
`deploy` is reachable only because the staging gate (`deploy-staging`) passed:
- `15-staging-log.md``staging_status: SUCCESS`, **10/10 checks PASS** (incl. B6 registry-isolation, the fix's target), run inside `orchestrator-staging` (8501).
## Change scope (why no restart)
The work item changes touch **only bind-mounted / non-runtime artifacts**`src/` (the code running in the prod container) and the `Dockerfile` are untouched:
| File | Kind | How it reaches prod |
|------|------|---------------------|
| `scripts/staging_check.py` | bind-mounted (`/home/slin/repos``/repos`); **not** copied into the image (`scripts/` absent from `/app`) | host `git pull` → live immediately |
| `.openclaw/agents/deployer.md` | bind-mounted agent prompt, read at agent launch | host `git pull` → live on next agent run |
| `CHANGELOG.md`, `docs/operations/STAGING_CHECK.md` | docs | n/a |
| `tests/test_staging_check_b6.py` | test, not deployed | n/a |
Because nothing in `src/` or the image changed, there is **no container rebuild and no restart** for the shared prod `orchestrator` (8500). Per CLAUDE.md / INFRA.md self-hosting rules, the prod container that serves all projects (enduro-trails + orchestrator) was **not** touched — zero group-risk.
## Deploy action
- **Prod container restart/rebuild:** not required, not performed (guardrail: never restart prod `orchestrator` within an ORCH task).
- **Real docker/SSH deploy hook** (`scripts/orchestrator-deploy-hook.sh`): not triggered by this agent (not explicitly instructed; reserved for Owner per ORCH-36).
- **Effective rollout:** merge of this branch to `main` + routine host `git pull` makes the corrected `staging_check.py` and `deployer.md` live; the prod app process is unaffected.
## Verdict
`deploy_status: SUCCESS` — staging gate green, change is bind-mount-only, prod instance untouched, no rollback needed.

View File

@@ -0,0 +1,50 @@
---
staging_status: SUCCESS
timestamp: 2026-06-06T07:08:59Z
base_url: http://localhost:8501
work_item: ORCH-048
mode: stub
result: 10/10 checks PASS
---
# Staging Gate Log — ORCH-048
Staging test suite completed against the live `orchestrator-staging` instance (port 8501). **All 10/10 checks passed.**
## Execution context
- **Where**: inside the `orchestrator-staging` container via Docker Engine API exec (canonical per ORCH-048 / ADR-001; `docker` CLI not present in this agent env, so the bind-mounted socket `/var/run/docker.sock` was used directly).
- **Command**: `python3 /repos/orchestrator/scripts/staging_check.py --base-url http://localhost:8501 --mode stub`
- **Exit code**: `0`
- **Container state**: `orchestrator-staging` running (Up 25 hours).
Running inside the container is required so the B6 registry-isolation check reads the registry from the running instance's own process-env (`.env.staging``ORCH_PROJECTS_JSON` = sandbox-only). This is precisely the behaviour ORCH-048 corrects.
## Results
```
[Block A] SMOKE
✓ PASS A1 GET /health → 200 status=ok
✓ PASS A2 GET /queue → 200 with counts/max_concurrency/resilience
✓ PASS A3 ORCH_STAGING=true (not prod)
[Block B] ACCESS
✓ PASS B4 Plane: sandbox project accessible (found 5 project(s), sandbox=YES)
✓ PASS B5 Gitea: orchestrator-sandbox accessible, push=true
✓ PASS B6 Registry: sandbox present, prod ET/ORCH absent [sandbox=YES, prod-ET=NO(good), prod-ORCH=NO(good)]
[Block C] E2E (mode=stub)
✓ PASS C7 Create issue in Plane SANDBOX
✓ PASS C8 Trigger pipeline via /webhook/plane
✓ PASS C9a Branch appears in orchestrator-sandbox
✓ PASS C9b Analyst job enqueued in staging queue
[CLEANUP]
✓ PASS CLEANUP: deleted sandbox branch, Plane issue, and DB rows
============================================================
RESULT: 10/10 checks PASS
============================================================
```
**B6 verdict (the ORCH-048 target check): PASS** — registry read from the running staging instance correctly shows sandbox present and prod ET/ORCH absent, with no false FAIL / spurious rollback.

View File

@@ -8,8 +8,14 @@ Checks:
Block C — E2E (create task in SANDBOX → trigger pipeline via /webhook/plane
→ verify branch + job enqueued → CLEANUP in finally)
Usage (inside the container or with correct env set):
python3 scripts/staging_check.py [--base-url http://localhost:8501] [--mode stub|full-real]
Usage — CANONICAL: run INSIDE the orchestrator-staging container (ORCH-048, ADR-001)
so B6 reads the registry from the running instance's own env (.env.staging):
docker exec orchestrator-staging \
python3 /repos/orchestrator/scripts/staging_check.py \
--base-url http://localhost:8501 [--mode stub|full-real]
Running from the host leaves ORCH_PROJECTS_JSON unset → B6 falls back to the
default (ET+ORCH) registry → false FAIL. See docs/operations/STAGING_CHECK.md.
Exit code: 0 = all PASS, non-zero = at least one FAIL.
@@ -214,6 +220,59 @@ SANDBOX_PROJECT_ID = "8c5a3025-4f9d-4190-b79f-fa06276bb27e"
PROD_ET_PROJECT_ID = "7a79f0a9-5278-49cd-9007-9a338f238f9c"
PROD_ORCH_PROJECT_ID = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"
B6_LABEL = "B6 Registry: sandbox present, prod ET/ORCH absent"
def _evaluate_b6(known: set[str]) -> tuple[bool, str]:
"""Pure verdict logic for the B6 registry-isolation check (ORCH-048).
PASS ⟺ SANDBOX ∈ known ∧ PROD_ET ∉ known ∧ PROD_ORCH ∉ known (TR-2).
``detail`` keeps the human-readable ``sandbox=…, prod-ET=…, prod-ORCH=…``
format (TR-3). Isolated from any I/O so both outcomes are unit-testable
without a live staging instance or docker (02-trz §9, ADR-001).
"""
sandbox_present = SANDBOX_PROJECT_ID in known
et_absent = PROD_ET_PROJECT_ID not in known
orch_absent = PROD_ORCH_PROJECT_ID not in known
passed = sandbox_present and et_absent and orch_absent
detail = (
f"sandbox={'YES' if sandbox_present else 'NO'}, "
f"prod-ET={'NO(good)' if et_absent else 'YES(BAD!)'}, "
f"prod-ORCH={'NO(good)' if orch_absent else 'YES(BAD!)'}"
)
return passed, detail
def _known_project_ids_from_registry() -> set[str]:
"""Registry of the *running staging instance* — its own process-env (ORCH-048).
The suite is canonically run INSIDE ``orchestrator-staging`` via
``docker exec`` (ADR-001), so ``src.projects`` resolves through the
container's ``PYTHONPATH=/app`` to ``/app/src/projects.py`` and reads
``ORCH_PROJECTS_JSON`` from ``.env.staging``. This reflects exactly the
registry the live instance serves webhooks with — no host-path hack, no HTTP
bootstrap dependency.
"""
from src.projects import known_plane_project_ids
return known_plane_project_ids()
def _run_b6(results: Results) -> None:
"""Run the B6 registry-isolation check and record its verdict.
Builds the known-id set from the running instance's registry and applies
``_evaluate_b6``. Any failure to obtain the registry yields a deterministic
FAIL with a clear detail (TR-4) — never an unhandled exception and never a
false PASS.
"""
try:
known = _known_project_ids_from_registry()
except Exception as e:
results.add(B6_LABEL, False, f"registry source unavailable: {e}")
return
passed, detail = _evaluate_b6(known)
results.add(B6_LABEL, passed, detail)
def block_b(results: Results):
print(f"\n{_BOLD}[Block B] ACCESS{_RESET}")
@@ -260,28 +319,11 @@ def block_b(results: Results):
except Exception as e:
results.add("B5 Gitea: orchestrator-sandbox accessible, push=true", False, str(e))
# B6 — Registry: sandbox in known IDs, prod ET/ORCH NOT in known IDs
try:
# Import from inside the container (script runs in /repos/orchestrator context)
sys.path.insert(0, "/repos/orchestrator")
# Force reload to pick up container env
import importlib
if "src.projects" in sys.modules:
importlib.reload(sys.modules["src.projects"])
from src.projects import known_plane_project_ids
known = known_plane_project_ids()
sandbox_present = SANDBOX_PROJECT_ID in known
et_absent = PROD_ET_PROJECT_ID not in known
orch_absent = PROD_ORCH_PROJECT_ID not in known
ok = sandbox_present and et_absent and orch_absent
detail = (
f"sandbox={'YES' if sandbox_present else 'NO'}, "
f"prod-ET={'NO(good)' if et_absent else 'YES(BAD!)'}, "
f"prod-ORCH={'NO(good)' if orch_absent else 'YES(BAD!)'}"
)
results.add("B6 Registry: sandbox present, prod ET/ORCH absent", ok, detail)
except Exception as e:
results.add("B6 Registry: sandbox present, prod ET/ORCH absent", False, str(e))
# B6 — Registry: sandbox in known IDs, prod ET/ORCH NOT in known IDs (ORCH-048).
# Reads the registry of the running staging instance from its own process-env
# (canonical: docker exec inside orchestrator-staging — ADR-001). No host-path
# hack; deterministic FAIL if the registry source is unavailable (TR-4).
_run_b6(results)
# ---------------------------------------------------------------------------

View File

@@ -121,10 +121,27 @@ class Settings(BaseSettings):
log_keep_max: int = 500
# ORCH-045: quality-gate CI poll/retry. check_ci_green polls the Gitea
# combined commit status up to ci_poll_max_attempts times, sleeping
# ci_poll_interval_s between attempts, to ride out a transient pending
# state right after the developer push (race fix, see ORCH-017).
# ci_poll_max_attempts -> max status polls (env ORCH_CI_POLL_MAX_ATTEMPTS)
# ci_poll_interval_s -> seconds between polls (env ORCH_CI_POLL_INTERVAL_S)
ci_poll_max_attempts: int = 12
ci_poll_interval_s: int = 10
# Telegram notifications
telegram_bot_token: str = ""
telegram_chat_id: str = ""
# ORCH-042: режим live-трекера задачи.
# edit -> карточка редактируется на месте (editMessageText), ДЕФОЛТ (как было).
# bump -> при обновлении старое сообщение удаляется и карточка отправляется
# заново вниз чата (deleteMessage + sendMessage + repoint message_id),
# тихо (disable_notification). Одна карточка на задачу в обоих режимах.
# Неизвестное/пустое значение трактуется как edit (см. notifications).
tracker_mode: str = "edit"
class Config:
env_prefix = "ORCH_"
env_file = ".env"

View File

@@ -68,6 +68,62 @@ def send_telegram(text: str, disable_notification: bool = False):
return None
# Telegram error descriptions that mean a deleteMessage target is already gone /
# can't be deleted (>48h, already deleted, invalid id). Treated as "no longer our
# problem" -> the caller proceeds to send a fresh card. NOT a transient failure.
_DELETE_GONE_MARKERS = (
"message to delete not found",
"message can't be deleted",
"message_id_invalid",
)
def delete_telegram(message_id: int) -> bool:
"""Delete a Telegram message. Never raises.
Returns True if the message is gone after the call (deleted now, OR Telegram
says it's already not there / can't be deleted -> treat as "no longer our
problem", caller proceeds to send a fresh card). Returns False only on a
transient failure (network / timeout / 5xx / unknown error) where the old
message may still be alive.
"""
s = _get_settings()
if not s.telegram_bot_token or not s.telegram_chat_id:
# No creds -> nothing was deleted; mirror the other helpers' no-op path.
return False
try:
url = f"https://api.telegram.org/bot{s.telegram_bot_token}/deleteMessage"
resp = httpx.post(
url,
json={
"chat_id": s.telegram_chat_id,
"message_id": message_id,
},
timeout=5,
)
data = resp.json()
if data.get("ok"):
return True
# ok:false -> classify. "Already gone / can't delete" is an expected,
# non-transient outcome (>48h, already deleted) -> the old message is no
# longer there, caller should still send a fresh card.
desc = str(data.get("description") or "").lower()
if any(m in desc for m in _DELETE_GONE_MARKERS):
logger.debug(
f"delete_telegram(mid={message_id}): already gone ({desc!r})"
)
return True
# Unknown 400 / 5xx -> transient; the old message may still be alive.
logger.warning(
f"delete_telegram(mid={message_id}): delete failed ({desc!r})"
)
return False
except Exception as e:
# Network / timeout -> transient; old message may still be alive.
logger.warning(f"delete_telegram(mid={message_id}): transient error: {e}")
return False
# edit_telegram outcome codes -> let update_task_tracker decide what to do:
# "ok" edit applied -> nothing else to do
# "not_modified" Telegram says text is identical (400 "message is not
@@ -166,19 +222,23 @@ def _get_work_item_id(task_id: int) -> str:
# the agent whose agent_runs rows describe that stage's work. "Ревью БРД" is NOT
# an agent stage — it is the human approve gate rendered between Analysis and
# Architecture from the task's brd_review_* timestamps.
# ORCH-042 (BR-11): display-labels are Russian. Stage KEYS (analysis, …) and
# agent names (analyst, …) are NOT touched — they are wired to
# _STAGE_ACTIVE_AGENT, last_done and the DB. Only the 2nd tuple element changed.
_TRACKER_STAGES = [
("analysis", "Analysis", "analyst"),
("architecture", "Architecture", "architect"),
("development", "Development", "developer"),
("review", "Review", "reviewer"),
("testing", "Testing", "tester"),
("deploy", "Deploy", "deployer"),
("analysis", "Анализ", "analyst"), # Анализ
("architecture", "Архитектура", "architect"), # Архитектура
("development", "Разработка", "developer"), # Разработка
("review", "Код ревью", "reviewer"), # Код ревью
("testing", "Тестирование", "tester"), # Тестирование
("deploy", "Внедрение", "deployer"), # Внедрение
]
# Map a pipeline stage -> the agent that is RUNNING while the task sits in it.
# (development is entered after architecture finishes, etc.) Used to render the
# "🔄 <Stage> … идёт" line for the currently-active stage.
_BRD_LABEL = "\u0420\u0435\u0432\u044c\u044e \u0411\u0420\u0414" # "Ревью БРД"
# ORCH-042 (BR-9): "Подтверждение BRD" (was "Ревью БРД").
_BRD_LABEL = "Подтверждение BRD"
_STAGE_ACTIVE_AGENT = {
"analysis": "analyst",
@@ -232,7 +292,8 @@ def render_task_tracker(task_id: int) -> str:
the BRD-review timestamps, then renders:
- one '✅ <Stage> <dur> · <in>↓/<out>↑ · <cost> · <model>' line per finished
stage (latest run per stage),
- the '⏸️ Ревью БРД <dur> · твоё время[ ⏳]' line between Analysis/Architecture,
- the '✅/⏸️ Подтверждение BRD <dur> · твоё время[ ⏳]' line between
Analysis/Architecture (✅ once the approve-gate passed, ⏸️+⏳ while waiting),
- a '🔄 <Stage> … идёт' line for the active (in-progress) stage,
- the '💰 <in>↓ / <out>↑ · <cost>' totals,
- on done: '⏱️ Всего .. · агенты .. · твоё ..' and a '🔗 PR / 📦' line.
@@ -365,9 +426,11 @@ def render_task_tracker(task_id: int) -> str:
if stage_key == "analysis" and brd_started:
brd_label = f"{_BRD_LABEL:<13}"
if review_seconds is not None:
# ORCH-042 (BR-10): approve-gate passed -> \u2705 (was \u23f8\ufe0f). The
# still-waiting branch below keeps \u23f8\ufe0f + \u23f3 unchanged.
dur = _fmt_minutes(review_seconds)
lines.append(
f"\u23f8\ufe0f {brd_label} {dur} \u00b7 \u0442\u0432\u043e\u0451 \u0432\u0440\u0435\u043c\u044f"
f"\u2705 {brd_label} {dur} \u00b7 \u0442\u0432\u043e\u0451 \u0432\u0440\u0435\u043c\u044f"
)
else:
# Still waiting on the human (ended not stamped yet).
@@ -406,7 +469,7 @@ def render_task_tracker(task_id: int) -> str:
def _done_link(task_id: int, work_item_id) -> str | None:
"""Build the final '🔗 PR #n · 📦 deployed' line. Never raises -> None."""
"""Build the final '🔗 PR #n · 📦 Внедрено' line. Never raises -> None."""
try:
from .config import settings
from .db import get_db
@@ -436,7 +499,7 @@ def _done_link(task_id: int, work_item_id) -> str | None:
parts = []
if pr_part:
parts.append(pr_part)
parts.append("\U0001f4e6 deployed")
parts.append("\U0001f4e6 Внедрено") # ORCH-042 (BR-12): was "deployed"
return " \u00b7 ".join(parts)
except Exception:
return None
@@ -445,19 +508,49 @@ def _done_link(task_id: int, work_item_id) -> str | None:
def update_task_tracker(task_id: int):
"""Render + push the live tracker for a task. Never raises.
First call (no stored tracker_message_id): sendMessage (silent) and store the
returned message_id. Subsequent calls: editMessageText the stored message.
A NEW message is sent ONLY when the original is truly gone (deleted / too old
/ invalid id). On "not modified" (text unchanged) or transient failures
(network / timeout / 5xx / unknown 400) we do NOT send a new message — that
is exactly what produced duplicate trackers and orphaned (lagging) messages.
Two modes, selected by Settings.tracker_mode (env ORCH_TRACKER_MODE),
resolved case-insensitively here; anything other than "bump" -> "edit"
(ORCH-042). Both keep the "one card per task" invariant.
edit (DEFAULT):
First call (no stored tracker_message_id): sendMessage (silent) and store
the returned message_id. Subsequent calls: editMessageText the stored
message. A NEW message is sent ONLY when the original is truly gone
(deleted / too old / invalid id). On "not modified" (text unchanged) or
transient failures (network / timeout / 5xx / unknown 400) we do NOT send
a new message — that is exactly what produced duplicate trackers and
orphaned (lagging) messages.
bump (ORCH-042):
The card is re-created at the BOTTOM of the chat on every update:
best-effort delete_telegram(old_id) (its result NEVER blocks the send),
then sendMessage (silent), then re-point tracker_message_id to the new id
— but ONLY on a successful send (new_mid is not None), so a transient send
failure never wipes the pointer to None. At most ONE new message is sent
per call -> no duplicates within a call.
The tracker is always sent with disable_notification so it never pings —
only the dedicated alert helpers ping.
"""
try:
from .db import get_tracker_message_id, set_tracker_message_id
text = render_task_tracker(task_id)
mode = (_get_settings().tracker_mode or "edit").strip().lower()
mid = get_tracker_message_id(task_id)
if mode == "bump":
# bump: one card, always at the bottom (delete + send + repoint).
if mid is not None:
# best-effort; result does NOT gate the send (BR-6).
delete_telegram(mid)
new_mid = send_telegram(text, disable_notification=True)
if new_mid is not None:
set_tracker_message_id(task_id, new_mid)
# send returned None (no creds / transient) -> leave mid untouched;
# no duplicate within this call, redraws on the next transition.
return
# mode == "edit" (DEFAULT): existing behaviour, unchanged.
if mid is not None:
result = edit_telegram(mid, text)
if result in (EDIT_OK, EDIT_NOT_MODIFIED):

View File

@@ -1,6 +1,7 @@
"""Quality Gate checks — real implementations using Gitea/Plane API and filesystem."""
import os
import time
import logging
import subprocess
import httpx
@@ -82,23 +83,65 @@ def check_ci_green(repo: str, branch: str) -> tuple[bool, str]:
"""
Check if CI status is green for branch via Gitea API.
GET /repos/{owner}/{repo}/commits/{branch}/status
ORCH-045: polling with retry to fix a race condition. The gate used to do a
single status read right after the developer push; if CI was still ``pending``
for the first 1-3s (real case ORCH-017: polled 17:58:54 -> pending, CI went
green 17:58:55) the gate returned False once and the task stalled silently.
Behaviour now:
* ``success`` -> (True, "CI green") immediately.
* ``failure`` / ``error`` -> (False, "CI state: <state>") immediately
(CI is red, retrying is pointless).
* ``pending`` / unknown -> sleep ``ci_poll_interval_s`` and poll again,
up to ``ci_poll_max_attempts`` times.
* still pending after all attempts -> (False, "CI still pending after <T>s").
* 404 -> (False, "Branch not found or no status").
* transient httpx errors -> logged and retried within the attempt budget;
if every attempt errors -> (False, "API error: <e>").
"""
owner = settings.gitea_owner
url = f"{GITEA_BASE}/repos/{owner}/{repo}/commits/{branch}/status"
try:
resp = httpx.get(url, headers=GITEA_HEADERS, timeout=10)
if resp.status_code == 404:
return False, f"Branch '{branch}' not found or no status"
resp.raise_for_status()
data = resp.json()
state = data.get("state", "unknown")
if state == "success":
return True, "CI green"
return False, f"CI state: {state}"
except httpx.HTTPError as e:
logger.error(f"Gitea API error checking CI: {e}")
return False, f"API error: {e}"
attempts = settings.ci_poll_max_attempts
interval = settings.ci_poll_interval_s
last_state = "unknown"
last_error: Exception | None = None
for i in range(1, attempts + 1):
try:
resp = httpx.get(url, headers=GITEA_HEADERS, timeout=10)
if resp.status_code == 404:
return False, f"Branch '{branch}' not found or no status"
resp.raise_for_status()
data = resp.json()
last_state = data.get("state", "unknown")
last_error = None
if last_state == "success":
return True, "CI green"
if last_state in ("failure", "error"):
return False, f"CI state: {last_state}"
# non-terminal (pending / unknown / other) -> retry below
except httpx.HTTPError as e:
last_error = e
logger.error(f"check_ci_green: attempt {i}/{attempts} API error: {e}")
if i < attempts:
if last_error is not None:
logger.info(
f"check_ci_green: attempt {i}/{attempts}, error, retrying in {interval}s"
)
else:
logger.info(
f"check_ci_green: attempt {i}/{attempts}, state={last_state}, "
f"retrying in {interval}s"
)
time.sleep(interval)
if last_error is not None:
return False, f"API error: {last_error}"
return False, f"CI still pending after {attempts * interval}s"
def check_review_approved(repo: str, pr_number: int) -> tuple[bool, str]:
@@ -145,8 +188,11 @@ def check_tests_passed(repo: str, work_item_id: str, branch: str | None = None)
explicitly marked `verdict: BLOCKED` / `status: blocked` but whose prose mentioned
"23 passed" / "✅ PASS" / "All checks passed" was treated as a pass, and an
unfinished feature reached Done. This mirrors check_reviewer_verdict (S-5) and
check_deploy_status (БАГ 8): read ONLY the YAML frontmatter `verdict:` / `status:`
fields, never the body.
check_deploy_status (БАГ 8): read ONLY the YAML frontmatter, never the body.
ORCH-047: the machine verdict is read from any of three equal-rank frontmatter
fields — `result:` (canonical, what the tester prompt emits), `verdict:` or
`status:` (legacy / enduro-trails). See _parse_tests_verdict.
File: docs/work-items/<work_item_id>/13-test-report.md
"""
@@ -179,15 +225,20 @@ _TESTS_POSITIVE_TOKENS = ("PASSED", "PASS", "READY-TO-DEPLOY", "READY_TO_DEPLOY"
def _parse_tests_verdict(content: str) -> tuple[bool, str]:
"""Map a 13-test-report.md body to a quality-gate verdict by reading ONLY the
machine-readable `verdict:` (and corroborating `status:`) YAML frontmatter fields.
machine-readable YAML frontmatter fields — never the prose body.
Three equal-rank fields are accepted (ORCH-047): `result:` (the canonical field
the tester prompt `.openclaw/agents/tester.md` is told to emit, `result: PASS|FAIL`),
plus `verdict:` and `status:` (legacy / enduro-trails ET-001..ET-014). ANY single
non-empty field is sufficient. Token sets are frozen for backward compatibility.
Rules:
- No frontmatter / bad YAML / neither field present -> (False, reason).
- A negative token (BLOCKED/FAILED/...) in verdict OR status -> (False) and is
authoritative (ET-013 main case: verdict BLOCKED wins over any prose PASS).
- Otherwise a positive token (PASS/PASSED/READY-TO-DEPLOY/...) in verdict OR
status -> (True).
- Anything else (unrecognized / empty verdict) -> (False, reason).
- No frontmatter / bad YAML / none of the three fields present -> (False, reason).
- A negative token (BLOCKED/FAILED/...) in ANY field -> (False) and is
authoritative (ET-013 main case: verdict BLOCKED wins over any prose PASS, and
beats a positive token in another field).
- Otherwise a positive token (PASS/PASSED/READY-TO-DEPLOY/...) in ANY field -> (True).
- Anything else (fields set but unrecognized) -> (False, reason).
"""
import yaml
@@ -207,19 +258,25 @@ def _parse_tests_verdict(content: str) -> tuple[bool, str]:
verdict = str(fm.get("verdict", "") or "").upper().strip()
status = str(fm.get("status", "") or "").upper().strip()
result = str(fm.get("result", "") or "").upper().strip()
if not verdict and not status:
return False, "No machine-readable verdict/status in test report frontmatter"
if not verdict and not status and not result:
return False, "No machine-readable verdict/status/result in test report frontmatter"
fields = f"{verdict} {status}"
value = verdict or status or result
fields = f"{verdict} {status} {result}"
for neg in _TESTS_NEGATIVE_TOKENS:
if neg in fields:
return False, f"Test verdict: {verdict or status} ({neg})"
return False, f"Test verdict: {value} ({neg})"
for pos in _TESTS_POSITIVE_TOKENS:
if pos in fields:
return True, f"Test verdict: {verdict or status} (PASS)"
return True, f"Test verdict: {value} (PASS)"
return False, f"No recognized PASS verdict in frontmatter (verdict={verdict!r}, status={status!r})"
return (
False,
f"No recognized PASS verdict in frontmatter "
f"(verdict={verdict!r}, status={status!r}, result={result!r})",
)
def check_analysis_approved(repo: str, work_item_id: str, branch: str | None = None) -> tuple[bool, str]:

205
src/review_parse.py Normal file
View File

@@ -0,0 +1,205 @@
"""Defensive extractors for reviewer / tester artifact bodies (ORCH-046).
When a task is rolled back to ``development`` the stage engine builds the
``task_desc`` that ends up in the developer agent's ``.task-dev.md``. Historically
that text only carried a *link* to the artifact file (12-review.md /
13-test-report.md); the developer agent had to go read the file, and the key
must-fix points (reviewer P0/P1 findings, tester failure reason) were lost in
transit — "испорченный телефон" that burns the retry budget.
This module extracts the **verbatim** must-fix text so the stage engine can embed
it directly in ``task_desc`` (ADR docs/work-items/ORCH-046/06-adr/ADR-001-*).
Contract — **never raises** (mirrors ``src/frontmatter.py`` and
``src/qg/checks.py::_parse_tests_verdict``): any error — missing file, IOError,
malformed markdown/YAML, missing section — yields ``""``. The caller then falls
back to the previous link-only ``task_desc``. No network calls; disk reads only.
"""
import logging
import re
logger = logging.getLogger("orchestrator.review_parse")
# Truncation limits (module-level per ТЗ §2.3). The full context always stays in
# the artifact file; the embedded text is a focused excerpt.
MAX_FINDINGS_CHARS = 2000
MAX_FAILURES_CHARS = 2000
_TRUNCATED_MARKER = "\n…(truncated)"
# Recognize a `### P0`/`### P1` subsection header by the presence of the P0/P1
# token, tolerant to case and the dash/em-dash that follows it.
_P01_HEADER_RE = re.compile(r"(?<![A-Za-z0-9])p[01](?![0-9])", re.IGNORECASE)
def _read(path: str) -> str | None:
"""Read a file as UTF-8. Never raises; returns None on any OS error."""
try:
with open(path, "r", encoding="utf-8", errors="replace") as f:
return f.read()
except OSError as e:
logger.debug(f"review_parse: cannot open {path}: {e}")
return None
def _strip_frontmatter(content: str) -> str:
"""Drop a leading ``--- … ---`` YAML frontmatter block, if present."""
if content.startswith("---"):
parts = content.split("---", 2)
if len(parts) >= 3:
return parts[2]
return content
def _truncate(text: str, limit: int) -> str:
"""Trim ``text`` to ``limit`` chars, appending a truncation marker if cut."""
if len(text) <= limit:
return text
return text[:limit].rstrip() + _TRUNCATED_MARKER
def _section_body(md: str, heading_token: str) -> str:
"""Return the body lines under the first ``## <…heading_token…>`` heading.
Capture stops at the next level-2 (``## ``) heading. Matching is
case-insensitive substring match on the heading line, so callers pass a token
like ``"Вывод pytest"`` or ``"Findings"``. ``### ``-level headers do NOT
delimit the section (they start with ``"### "``, not ``"## "``).
"""
out: list[str] = []
capturing = False
for line in md.splitlines():
if line.startswith("## "):
if capturing:
break
if heading_token.lower() in line.lower():
capturing = True
continue
if capturing:
out.append(line)
return "\n".join(out)
def _is_placeholder_item(text: str) -> bool:
"""True for empty or template-placeholder list items (non-substantive).
The canonical reviewer template seeds each severity with
``- [ ] <описание> (если есть)``. Such lines must be ignored so an empty P0/P1
subsection does not leak the placeholder into ``task_desc``.
"""
t = text.strip()
if not t:
return True
if "(если есть)" in t:
return True
# An item whose entire payload is an angle-bracket placeholder, e.g. "<описание>".
if t.startswith("<") and t.endswith(">"):
return True
return False
def _item_payload(line: str) -> str | None:
"""If ``line`` is a markdown list item, return its payload text; else None.
Handles ``- foo``, ``* foo`` and checkbox forms ``- [ ] foo`` / ``- [x] foo``.
"""
m = re.match(r"\s*[-*]\s+(?:\[[ xX]?\]\s*)?(.*)$", line)
if not m:
return None
return m.group(1)
def _findings_subsections(findings_body: str):
"""Yield ``(header_line, body_lines)`` for each ``### `` subsection."""
header: str | None = None
body: list[str] = []
for line in findings_body.splitlines():
if line.startswith("### "):
if header is not None:
yield header, body
header = line
body = []
elif header is not None:
body.append(line)
if header is not None:
yield header, body
def extract_review_findings(path: str) -> str:
"""Дословный текст P0/P1 findings из 12-review.md. Never raises; '' при ошибке/пусто.
Reads the ``## Findings`` section of a reviewer report and returns the verbatim
P0 (Blocker) and P1 (Must fix) subsection items, suitable for embedding in a
rollback ``task_desc``. P2/P3 are ignored. Empty/placeholder-only subsections
are skipped; if no substantive P0/P1 item exists, returns ``""``. The result is
truncated to ``MAX_FINDINGS_CHARS``.
"""
content = _read(path)
if content is None:
return ""
try:
body = _strip_frontmatter(content)
findings_body = _section_body(body, "Findings")
if not findings_body.strip():
return ""
blocks: list[str] = []
for header, sub_body in _findings_subsections(findings_body):
if not _P01_HEADER_RE.search(header):
continue
kept: list[str] = []
for line in sub_body:
payload = _item_payload(line)
if payload is None:
continue
if _is_placeholder_item(payload):
continue
kept.append(line.rstrip())
if kept:
blocks.append("\n".join([header.rstrip(), *kept]))
if not blocks:
return ""
return _truncate("\n\n".join(blocks), MAX_FINDINGS_CHARS)
except Exception as e: # defensive: never raise out of the extractor
logger.debug(f"review_parse: extract_review_findings failed for {path}: {e}")
return ""
def extract_test_failures(path: str) -> str:
"""Релевантный фрагмент тела 13-test-report.md (причина FAIL). Never raises; '' при ошибке/пусто.
Picks the first non-empty source, in priority order:
1. ``## Вывод pytest`` — the pytest run output (shows failing tests);
2. rows of the ``## Результаты`` table that contain ``FAIL``;
3. ``## Итог`` — the verdict summary.
The result is truncated to ``MAX_FAILURES_CHARS``. The gate ``reason`` is added
by the caller; this returns the report-body excerpt on top of it.
"""
content = _read(path)
if content is None:
return ""
try:
# 1. pytest output.
pytest_out = _section_body(content, "Вывод pytest").strip()
if pytest_out:
return _truncate(pytest_out, MAX_FAILURES_CHARS)
# 2. FAIL rows from the results table.
results = _section_body(content, "Результаты")
fail_rows = [ln.rstrip() for ln in results.splitlines() if "FAIL" in ln.upper()]
if fail_rows:
return _truncate("\n".join(fail_rows).strip(), MAX_FAILURES_CHARS)
# 3. Verdict summary.
itog = _section_body(content, "Итог").strip()
if itog:
return _truncate(itog, MAX_FAILURES_CHARS)
return ""
except Exception as e: # defensive: never raise out of the extractor
logger.debug(f"review_parse: extract_test_failures failed for {path}: {e}")
return ""

View File

@@ -32,6 +32,7 @@ from dataclasses import dataclass, field
from .db import get_db, update_task_stage, enqueue_job
from .stages import get_next_stage, get_qg_for_stage, get_agent_for_stage
from .git_worktree import get_worktree_path
from .review_parse import extract_review_findings, extract_test_failures
from .qg.checks import QG_CHECKS
from .notifications import (
notify_stage_change,
@@ -416,12 +417,24 @@ def _handle_qg_failure_rollbacks(
result.rolled_back_to = "development"
retry_count = _developer_retry_count(task_id)
if retry_count < MAX_DEVELOPER_RETRIES:
task_desc = (
# ORCH-046: embed the verbatim P0/P1 findings into task_desc so the
# developer agent sees the must-fix points directly (not just a link).
# extract_review_findings never raises; "" -> graceful link-only fallback.
review_ref = f"docs/work-items/{work_item_id}/12-review.md"
review_path = os.path.join(get_worktree_path(repo, branch), review_ref)
findings = extract_review_findings(review_path)
head = (
f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n"
f"Stage: development\nNote: REQUEST_CHANGES from reviewer "
f"(attempt {retry_count+1}/3). Fix findings in "
f"docs/work-items/{work_item_id}/12-review.md"
f"(attempt {retry_count+1}/3)."
)
if findings:
task_desc = (
f"{head}\nFindings (P0/P1):\n{findings}\n"
f"Полный контекст: {review_ref}"
)
else:
task_desc = f"{head} Fix findings in {review_ref}"
new_job = enqueue_job("developer", repo, task_desc, task_id=task_id)
result.enqueued_agent = "developer"
result.enqueued_job_id = new_job
@@ -452,11 +465,23 @@ def _handle_qg_failure_rollbacks(
)
retry_count = _developer_retry_count(task_id)
if retry_count < MAX_DEVELOPER_RETRIES:
task_desc = (
# ORCH-046: embed the gate `reason` plus a verbatim excerpt of the
# test-report body (pytest output / FAIL rows / Итог) into task_desc.
# extract_test_failures never raises; "" -> graceful reason+link fallback.
report_ref = f"docs/work-items/{work_item_id}/13-test-report.md"
report_path = os.path.join(get_worktree_path(repo, branch), report_ref)
failures = extract_test_failures(report_path)
head = (
f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n"
f"Stage: development\nNote: Tests FAILED. "
f"Fix failures described in docs/work-items/{work_item_id}/13-test-report.md"
f"Stage: development\nNote: Tests FAILED. Причина: {reason}."
)
if failures:
task_desc = (
f"{head}\nДетали:\n{failures}\n"
f"Полный контекст: {report_ref}"
)
else:
task_desc = f"{head} Fix failures described in {report_ref}"
new_job = enqueue_job("developer", repo, task_desc, task_id=task_id)
result.enqueued_agent = "developer"
result.enqueued_job_id = new_job

27
tests/test_config.py Normal file
View File

@@ -0,0 +1,27 @@
"""ORCH-042: Settings.tracker_mode config field.
AC-1: tracker_mode defaults to "edit" and is read from env ORCH_TRACKER_MODE.
Settings is a Pydantic BaseSettings reading env at instantiation, so each case
builds a FRESH Settings() (the process-wide singleton is not mutated).
"""
from src.config import Settings
def test_tracker_mode_defaults_to_edit(monkeypatch):
# No env var -> default "edit" (TC-01 / AC-1).
monkeypatch.delenv("ORCH_TRACKER_MODE", raising=False)
assert Settings().tracker_mode == "edit"
def test_tracker_mode_reads_env_bump(monkeypatch):
# ORCH_TRACKER_MODE=bump -> "bump" (TC-01 / AC-1).
monkeypatch.setenv("ORCH_TRACKER_MODE", "bump")
assert Settings().tracker_mode == "bump"
def test_tracker_mode_reads_env_arbitrary(monkeypatch):
# The field is read verbatim from env; mode RESOLUTION (anything != "bump"
# -> edit) happens in notifications, not here (AC-1/AC-2 split).
monkeypatch.setenv("ORCH_TRACKER_MODE", "garbage")
assert Settings().tracker_mode == "garbage"

View File

@@ -93,38 +93,82 @@ class TestCheckArchitectureDone:
assert passed is False
def _ci_status_resp(state, status_code=200):
"""Build a MagicMock httpx response for the Gitea combined-status endpoint."""
mock_resp = MagicMock()
mock_resp.status_code = status_code
mock_resp.json.return_value = {"state": state}
mock_resp.raise_for_status = MagicMock()
return mock_resp
class TestCheckCIGreen:
"""ORCH-045: check_ci_green now polls with retry to ride out a transient
`pending` right after the developer push (race fix, see ORCH-017)."""
@patch("src.qg.checks.time.sleep")
@patch("src.qg.checks.httpx.get")
def test_ci_success(self, mock_get):
mock_resp = MagicMock()
mock_resp.status_code = 200
mock_resp.json.return_value = {"state": "success"}
mock_resp.raise_for_status = MagicMock()
mock_get.return_value = mock_resp
def test_ci_success_first_attempt(self, mock_get, mock_sleep):
mock_get.return_value = _ci_status_resp("success")
passed, reason = check_ci_green("enduro-trails", "feature/ET-001-test")
assert passed is True
assert "green" in reason.lower()
assert mock_get.call_count == 1
mock_sleep.assert_not_called()
@patch("src.qg.checks.time.sleep")
@patch("src.qg.checks.httpx.get")
def test_ci_pending(self, mock_get):
mock_resp = MagicMock()
mock_resp.status_code = 200
mock_resp.json.return_value = {"state": "pending"}
mock_resp.raise_for_status = MagicMock()
mock_get.return_value = mock_resp
def test_ci_pending_then_success(self, mock_get, mock_sleep):
# pending on the 1st poll, green on the 2nd -> success after one retry.
mock_get.side_effect = [
_ci_status_resp("pending"),
_ci_status_resp("success"),
]
passed, reason = check_ci_green("enduro-trails", "feature/ET-001-test")
assert passed is True
assert "green" in reason.lower()
assert mock_get.call_count == 2
assert mock_sleep.call_count == 1 # slept once between the two polls
@patch("src.qg.checks.time.sleep")
@patch("src.qg.checks.httpx.get")
def test_ci_failure_no_retry(self, mock_get, mock_sleep):
# CI is red -> terminal, return immediately without sleeping/retrying.
mock_get.return_value = _ci_status_resp("failure")
passed, reason = check_ci_green("enduro-trails", "feature/ET-001-test")
assert passed is False
assert "failure" in reason
assert mock_get.call_count == 1
mock_sleep.assert_not_called()
@patch("src.qg.checks.time.sleep")
@patch("src.qg.checks.httpx.get")
def test_ci_branch_not_found(self, mock_get):
def test_ci_pending_exhausts_attempts(self, mock_get, mock_sleep):
# Always pending -> after ci_poll_max_attempts polls return an explicit
# (False, "...pending...") so the operator sees the reason (no silent stall).
from src.qg.checks import settings as checks_settings
mock_get.return_value = _ci_status_resp("pending")
passed, reason = check_ci_green("enduro-trails", "feature/ET-001-test")
assert passed is False
assert "pending" in reason.lower()
assert mock_get.call_count == checks_settings.ci_poll_max_attempts
@patch("src.qg.checks.time.sleep")
@patch("src.qg.checks.httpx.get")
def test_ci_branch_not_found(self, mock_get, mock_sleep):
mock_resp = MagicMock()
mock_resp.status_code = 404
mock_get.return_value = mock_resp
passed, reason = check_ci_green("enduro-trails", "nonexistent")
assert passed is False
assert "not found" in reason.lower()
assert mock_get.call_count == 1
class TestCheckReviewApproved:
@@ -278,6 +322,64 @@ class TestCheckTestsPassed:
assert passed is False
assert "not found" in reason.lower()
# --- ORCH-047: `result:` is read as an equal-rank machine field ---
def test_result_pass_passes(self, setup_work_item_dir):
# TC-01 / AC-01: canonical tester field `result: PASS` (no verdict/status).
self._write(
setup_work_item_dir,
"---\ntype: test-report\nresult: PASS\n---\n\n# Test Report\n",
)
passed, reason = check_tests_passed("enduro-trails", "ET-001")
assert passed is True
assert "PASS" in reason
def test_result_fail_fails(self, setup_work_item_dir):
# TC-02 / AC-02: `result: FAIL` (no verdict/status) -> rollback, reason has FAIL.
self._write(setup_work_item_dir, "---\nresult: FAIL\n---\n\nbody\n")
passed, reason = check_tests_passed("enduro-trails", "ET-001")
assert passed is False
assert "FAIL" in reason
def test_result_pass_but_verdict_blocked_fails(self, setup_work_item_dir):
# TC-03 / AC-03: negative in another field is authoritative over result: PASS.
self._write(
setup_work_item_dir,
"---\nresult: PASS\nverdict: BLOCKED\n---\n\n23 passed\n",
)
passed, reason = check_tests_passed("enduro-trails", "ET-001")
assert passed is False
assert "BLOCKED" in reason
def test_result_pass_but_status_failed_fails(self, setup_work_item_dir):
# TC-04 / AC-03: status: failed authoritative over result: PASS.
self._write(
setup_work_item_dir,
"---\nresult: PASS\nstatus: failed\n---\n\nbody\n",
)
passed, reason = check_tests_passed("enduro-trails", "ET-001")
assert passed is False
assert "FAILED" in reason
def test_result_ready_to_deploy_passes(self, setup_work_item_dir):
# TC-05 / AC-04: positive token without the word PASS, in result field.
self._write(
setup_work_item_dir,
"---\nresult: ready-to-deploy\n---\n\nbody\n",
)
passed, reason = check_tests_passed("enduro-trails", "ET-001")
assert passed is True
def test_no_machine_field_reason_mentions_result(self, setup_work_item_dir):
# AC-06: none of result/verdict/status -> fail; reason now lists result too.
self._write(
setup_work_item_dir,
"---\ntype: test-report\nversion: 1\n---\n\nResult: PASS\n",
)
passed, reason = check_tests_passed("enduro-trails", "ET-001")
assert passed is False
assert "result" in reason.lower()
class TestCheckDeployStatus:
"""BUG 8: deploy -> done must be gated on the deployer's machine-readable

237
tests/test_review_parse.py Normal file
View File

@@ -0,0 +1,237 @@
"""Unit tests for src/review_parse (ORCH-046).
Covers the defensive extractors that pull verbatim must-fix text out of the
reviewer / tester artifacts for embedding into the rollback ``task_desc``:
- extract_review_findings (12-review.md, ## Findings -> P0/P1)
- extract_test_failures (13-test-report.md, pytest/FAIL/Итог excerpt)
Both must NEVER raise (return "" on missing/broken/empty input) and must ignore
template placeholders / non-must-fix severities. See 04-test-plan.yaml (TC-01..08).
"""
import os
import tempfile
import pytest
from src.review_parse import (
extract_review_findings,
extract_test_failures,
MAX_FINDINGS_CHARS,
MAX_FAILURES_CHARS,
)
@pytest.fixture
def write_file(tmp_path):
def _w(name: str, content: str) -> str:
p = tmp_path / name
p.write_text(content, encoding="utf-8")
return str(p)
return _w
# ---------------------------------------------------------------------------
# extract_review_findings
# ---------------------------------------------------------------------------
_REVIEW_WITH_FINDINGS = """---
type: review
work_item_id: ORCH-046
verdict: REQUEST_CHANGES
version: 1
---
# Review ORCH-046
## Summary
Несколько проблем.
## Findings
### P0 — Blocker
- [ ] Документация не обновлена при изменении src/review_parse.py
### P1 — Must fix
- [ ] extract_test_failures не обрабатывает пустой отчёт
- [ ] Отсутствует docstring у _section_body
### P2 — Should fix
- [ ] Переименовать переменную blocks в more descriptive
## Документация
Требует обновления README.
"""
class TestExtractReviewFindings:
def test_tc01_returns_verbatim_p0_p1(self, write_file):
"""TC-01: P0/P1 findings present -> verbatim text returned (AC-1, AC-5)."""
path = write_file("12-review.md", _REVIEW_WITH_FINDINGS)
out = extract_review_findings(path)
# P0 + P1 verbatim items present.
assert "Документация не обновлена при изменении src/review_parse.py" in out
assert "extract_test_failures не обрабатывает пустой отчёт" in out
assert "Отсутствует docstring у _section_body" in out
# Subsection headers preserved.
assert "P0" in out and "P1" in out
# P2 must NOT leak in.
assert "Переименовать переменную" not in out
def test_tc02_only_p2_p3_returns_empty(self, write_file):
"""TC-02: only P2/P3 (no must-fix P0/P1) -> '' (AC-5)."""
content = """---
verdict: REQUEST_CHANGES
---
## Findings
### P0 — Blocker
- [ ] <описание> (если есть)
### P1 — Must fix
- [ ] <описание> (если есть)
### P2 — Should fix
- [ ] Косметика в naming
"""
path = write_file("12-review.md", content)
assert extract_review_findings(path) == ""
def test_tc03_missing_file_returns_empty(self):
"""TC-03: non-existent path -> '' without raising (AC-4)."""
missing = os.path.join(tempfile.gettempdir(), "no-such-review-orch046.md")
assert extract_review_findings(missing) == ""
def test_tc04_broken_or_no_findings_section_returns_empty(self, write_file):
"""TC-04: empty file / markdown without ## Findings -> '' (AC-4, AC-5)."""
# Empty file.
assert extract_review_findings(write_file("empty.md", "")) == ""
# No Findings section.
no_section = "# Review\n\n## Summary\nвсё хорошо\n"
assert extract_review_findings(write_file("nofind.md", no_section)) == ""
# Broken YAML frontmatter (unterminated) — body parsing still graceful.
broken = "---\nverdict: [unclosed\n# Review\nno findings here\n"
assert extract_review_findings(write_file("broken.md", broken)) == ""
def test_tc05_long_findings_truncated(self, write_file):
"""TC-05: very long findings truncated to limit with marker (AC-1)."""
big_item = "- [ ] " + ("x" * 5000)
content = f"## Findings\n\n### P0 — Blocker\n{big_item}\n"
path = write_file("12-review.md", content)
out = extract_review_findings(path)
assert len(out) <= MAX_FINDINGS_CHARS + len("\n…(truncated)")
assert "…(truncated)" in out
def test_case_insensitive_and_dash_tolerant_header(self, write_file):
"""P0/P1 recognized regardless of case / dash style."""
content = """## Findings
### p0 - blocker
- [ ] Нижний регистр заголовка
### P1 — Must fix
- [ ] Em-dash заголовок
"""
out = extract_review_findings(write_file("12-review.md", content))
assert "Нижний регистр заголовка" in out
assert "Em-dash заголовок" in out
def test_never_raises_on_directory_path(self, tmp_path):
"""Passing a directory path must not raise -> ''."""
assert extract_review_findings(str(tmp_path)) == ""
# ---------------------------------------------------------------------------
# extract_test_failures
# ---------------------------------------------------------------------------
_REPORT_FAIL = """---
type: test-report
work_item_id: ORCH-046
result: FAIL
---
# Test Report — ORCH-046
## Окружение
- Python: 3.12
## Результаты
| TC ID | Описание | Результат |
|-------|----------|-----------|
| TC-01 | парсер findings | PASS |
| TC-09 | rollback task_desc | FAIL |
## Вывод pytest
FAILED tests/test_stage_engine.py::TestReviewerRequestChanges::test_embed - AssertionError
1 failed, 40 passed in 2.13s
## Итог
FAIL
"""
class TestExtractTestFailures:
def test_tc06_extracts_pytest_output(self, write_file):
"""TC-06: relevant body excerpt (pytest output) from FAIL report (AC-2, AC-5)."""
path = write_file("13-test-report.md", _REPORT_FAIL)
out = extract_test_failures(path)
assert "FAILED tests/test_stage_engine.py" in out
assert "1 failed, 40 passed" in out
def test_priority_falls_back_to_fail_rows(self, write_file):
"""No pytest section -> FAIL rows of the results table are used."""
content = """---
result: FAIL
---
## Результаты
| TC ID | Описание | Результат |
|-------|----------|-----------|
| TC-01 | ok | PASS |
| TC-09 | broken | FAIL |
## Итог
FAIL
"""
out = extract_test_failures(write_file("13-test-report.md", content))
assert "TC-09" in out
assert "broken" in out
# PASS rows are not failure-relevant.
assert "TC-01" not in out
def test_priority_falls_back_to_itog(self, write_file):
"""No pytest section and no FAIL rows -> Итог summary is used."""
content = """---
result: FAIL
---
## Итог
Регресс упал: смотрите CI лог.
"""
out = extract_test_failures(write_file("13-test-report.md", content))
assert "Регресс упал" in out
def test_tc07_missing_file_returns_empty(self):
"""TC-07: non-existent path -> '' without raising (AC-4)."""
missing = os.path.join(tempfile.gettempdir(), "no-such-report-orch046.md")
assert extract_test_failures(missing) == ""
def test_tc08_broken_or_empty_report_returns_empty(self, write_file):
"""TC-08: empty / section-less report -> '' without raising (AC-4, AC-5)."""
assert extract_test_failures(write_file("empty.md", "")) == ""
no_sections = "---\nresult: FAIL\n---\n\n# Test Report\nничего полезного\n"
assert extract_test_failures(write_file("nosec.md", no_sections)) == ""
def test_long_failures_truncated(self, write_file):
"""Long pytest output is truncated to the limit with a marker."""
big = "x" * 5000
content = f"## Вывод pytest\n{big}\n"
out = extract_test_failures(write_file("13-test-report.md", content))
assert len(out) <= MAX_FAILURES_CHARS + len("\n…(truncated)")
assert "…(truncated)" in out
def test_never_raises_on_directory_path(self, tmp_path):
assert extract_test_failures(str(tmp_path)) == ""

View File

@@ -101,6 +101,14 @@ def _jobs():
return [dict(r) for r in rows]
def _job_contents():
"""task_content of every enqueued job, oldest first (ORCH-046 task_desc check)."""
conn = get_db()
rows = conn.execute("SELECT task_content FROM jobs ORDER BY id").fetchall()
conn.close()
return [r[0] for r in rows]
def _add_developer_runs(task_id, n):
conn = get_db()
for _ in range(n):
@@ -335,6 +343,179 @@ class TestTesterFail:
assert _jobs() == []
# ---------------------------------------------------------------------------
# ORCH-046: rollback task_desc carries verbatim reviewer/tester must-fix text
# ---------------------------------------------------------------------------
_REVIEW_MD = """---
type: review
work_item_id: ET-001
verdict: REQUEST_CHANGES
version: 1
---
# Review ET-001
## Summary
Есть блокеры.
## Findings
### P0 — Blocker
- [ ] Гонка в claim_next_job: отсутствует guard в WHERE
### P1 — Must fix
- [ ] Нет обработки OSError при чтении отчёта
### P2 — Should fix
- [ ] Переименовать blocks
"""
_REPORT_MD = """---
type: test-report
work_item_id: ET-001
result: FAIL
---
# Test Report — ET-001
## Результаты
| TC ID | Описание | Результат |
|-------|----------|-----------|
| TC-09 | rollback | FAIL |
## Вывод pytest
FAILED tests/test_stage_engine.py::TestTaskDescEmbedding - AssertionError
1 failed, 50 passed in 3.01s
## Итог
FAIL
"""
class TestRollbackTaskDescEmbedding:
"""ORCH-046 AC-1/AC-2/AC-3/AC-4: the rollback task_desc embeds verbatim
must-fix text (reviewer P0/P1, tester reason + report excerpt) plus the link.
"""
def _patch_worktree(self, monkeypatch, tmp_path, work_item_id, filename, body):
"""Make get_worktree_path resolve to tmp_path and seed the artifact file."""
artifact = tmp_path / "docs" / "work-items" / work_item_id
artifact.mkdir(parents=True, exist_ok=True)
(artifact / filename).write_text(body, encoding="utf-8")
monkeypatch.setattr(
stage_engine, "get_worktree_path", lambda repo, branch: str(tmp_path)
)
def test_tc09_reviewer_embeds_p0_p1_and_link(self, monkeypatch, tmp_path):
"""TC-09: reviewer REQUEST_CHANGES -> task_desc has verbatim P0/P1 + link."""
monkeypatch.setattr(
stage_engine, "QG_CHECKS",
{**stage_engine.QG_CHECKS,
"check_reviewer_verdict": _fail("verdict: REQUEST_CHANGES")},
)
self._patch_worktree(monkeypatch, tmp_path, "ET-001", "12-review.md", _REVIEW_MD)
task_id = _make_task("review")
advance_stage(task_id, "review", "enduro-trails", "ET-001",
"feature/ET-001-x", finished_agent="reviewer")
contents = _job_contents()
assert len(contents) == 1
desc = contents[0]
# AC-1: verbatim P0/P1 findings.
assert "Гонка в claim_next_job: отсутствует guard в WHERE" in desc
assert "Нет обработки OSError при чтении отчёта" in desc
# P2 must not leak.
assert "Переименовать blocks" not in desc
# AC-3: link to full file preserved.
assert "docs/work-items/ET-001/12-review.md" in desc
def test_tc10_tester_embeds_reason_excerpt_and_link(self, monkeypatch, tmp_path):
"""TC-10: tester FAIL -> task_desc has reason + report excerpt + link."""
monkeypatch.setattr(
stage_engine, "QG_CHECKS",
{**stage_engine.QG_CHECKS,
"check_tests_passed": _fail("1 test failed")},
)
self._patch_worktree(
monkeypatch, tmp_path, "ET-001", "13-test-report.md", _REPORT_MD
)
task_id = _make_task("testing")
advance_stage(task_id, "testing", "enduro-trails", "ET-001",
"feature/ET-001-x", finished_agent="tester")
contents = _job_contents()
assert len(contents) == 1
desc = contents[0]
# AC-2: gate reason present.
assert "1 test failed" in desc
# AC-2: report body excerpt (pytest output) present.
assert "FAILED tests/test_stage_engine.py::TestTaskDescEmbedding" in desc
# AC-3: link to full file preserved.
assert "docs/work-items/ET-001/13-test-report.md" in desc
def test_tc11_reviewer_graceful_fallback_when_no_file(self, monkeypatch, tmp_path):
"""TC-11: missing/broken 12-review.md -> graceful link-only fallback (AC-4)."""
monkeypatch.setattr(
stage_engine, "QG_CHECKS",
{**stage_engine.QG_CHECKS,
"check_reviewer_verdict": _fail("verdict: REQUEST_CHANGES")},
)
# Worktree resolves but the review file does not exist.
monkeypatch.setattr(
stage_engine, "get_worktree_path", lambda repo, branch: str(tmp_path)
)
task_id = _make_task("review")
res = advance_stage(task_id, "review", "enduro-trails", "ET-001",
"feature/ET-001-x", finished_agent="reviewer")
# Rollback still happens exactly as before.
assert res.rolled_back_to == "development"
assert _stage(task_id) == "development"
contents = _job_contents()
assert len(contents) == 1
desc = contents[0]
# Falls back to the previous link-string behavior (no findings block).
assert "Fix findings in docs/work-items/ET-001/12-review.md" in desc
assert "Findings (P0/P1):" not in desc
def test_tc11_tester_graceful_fallback_keeps_reason(self, monkeypatch, tmp_path):
"""AC-2/AC-4: missing report -> reason still present, link fallback."""
monkeypatch.setattr(
stage_engine, "QG_CHECKS",
{**stage_engine.QG_CHECKS,
"check_tests_passed": _fail("2 tests failed")},
)
monkeypatch.setattr(
stage_engine, "get_worktree_path", lambda repo, branch: str(tmp_path)
)
task_id = _make_task("testing")
advance_stage(task_id, "testing", "enduro-trails", "ET-001",
"feature/ET-001-x", finished_agent="tester")
desc = _job_contents()[0]
assert "2 tests failed" in desc
assert "docs/work-items/ET-001/13-test-report.md" in desc
def test_tc12_retry_and_rollback_behavior_unchanged(self, monkeypatch, tmp_path):
"""TC-12 (AC-6): embedding does not change retry/rollback semantics.
4th developer attempt still alerts instead of enqueueing, even with a
valid review file present.
"""
monkeypatch.setattr(
stage_engine, "QG_CHECKS",
{**stage_engine.QG_CHECKS,
"check_reviewer_verdict": _fail("verdict: REQUEST_CHANGES")},
)
self._patch_worktree(monkeypatch, tmp_path, "ET-001", "12-review.md", _REVIEW_MD)
task_id = _make_task("review")
_add_developer_runs(task_id, 3) # already at the cap
res = advance_stage(task_id, "review", "enduro-trails", "ET-001",
"feature/ET-001-x", finished_agent="reviewer")
assert res.rolled_back_to == "development"
assert res.alerted is True
assert stage_engine.send_telegram.called
# No new developer job past the cap, regardless of embedding.
assert _jobs() == []
# ---------------------------------------------------------------------------
# BUG 8: deploy verdict gates deploy -> done (not the LLM exit code)
# ---------------------------------------------------------------------------

View File

@@ -0,0 +1,151 @@
"""ORCH-048: unit tests for the B6 registry-isolation verdict in staging_check.py.
B6 «Registry: sandbox present, prod ET/ORCH absent» is the staging-isolation
safety check. Its verdict logic is isolated into the pure function
``_evaluate_b6(known) -> (passed, detail)`` so both outcomes (clean staging
registry → PASS, polluted registry → FAIL) can be tested without standing up a
live staging instance or docker (02-trz §9, ADR-001).
These tests target that pure function plus the deterministic-degradation path
(``_run_b6``) and statically assert the host-path hack is gone (TR-6 / TC-06).
"""
import importlib.util
import pathlib
import pytest
# ---------------------------------------------------------------------------
# Load scripts/staging_check.py by path (scripts/ is not an importable package).
# ---------------------------------------------------------------------------
_SCRIPT_PATH = (
pathlib.Path(__file__).resolve().parent.parent / "scripts" / "staging_check.py"
)
def _load_module():
spec = importlib.util.spec_from_file_location("staging_check", _SCRIPT_PATH)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
sc = _load_module()
SANDBOX = sc.SANDBOX_PROJECT_ID
PROD_ET = sc.PROD_ET_PROJECT_ID
PROD_ORCH = sc.PROD_ORCH_PROJECT_ID
# ---------------------------------------------------------------------------
# TC-01 — clean staging registry → PASS
# ---------------------------------------------------------------------------
def test_tc01_clean_registry_passes():
passed, detail = sc._evaluate_b6({SANDBOX})
assert passed is True
assert "sandbox=YES" in detail
assert "prod-ET=NO(good)" in detail
assert "prod-ORCH=NO(good)" in detail
# ---------------------------------------------------------------------------
# TC-02 — prod-ET leaked into registry → FAIL
# ---------------------------------------------------------------------------
def test_tc02_prod_et_present_fails():
passed, detail = sc._evaluate_b6({SANDBOX, PROD_ET})
assert passed is False
assert "sandbox=YES" in detail
assert "prod-ET=YES(BAD!)" in detail
assert "prod-ORCH=NO(good)" in detail
# ---------------------------------------------------------------------------
# TC-03 — prod-ORCH leaked into registry → FAIL
# ---------------------------------------------------------------------------
def test_tc03_prod_orch_present_fails():
passed, detail = sc._evaluate_b6({SANDBOX, PROD_ORCH})
assert passed is False
assert "sandbox=YES" in detail
assert "prod-ET=NO(good)" in detail
assert "prod-ORCH=YES(BAD!)" in detail
# ---------------------------------------------------------------------------
# TC-04 — sandbox absent (empty registry) → deterministic FAIL, no exception
# ---------------------------------------------------------------------------
def test_tc04_empty_registry_fails_without_sandbox():
passed, detail = sc._evaluate_b6(set())
assert passed is False
assert "sandbox=NO" in detail
# ---------------------------------------------------------------------------
# TC-05 — both prod projects leaked → FAIL
# ---------------------------------------------------------------------------
def test_tc05_both_prod_present_fails():
passed, detail = sc._evaluate_b6({SANDBOX, PROD_ET, PROD_ORCH})
assert passed is False
assert "prod-ET=YES(BAD!)" in detail
assert "prod-ORCH=YES(BAD!)" in detail
# ---------------------------------------------------------------------------
# TC-06 — registry source no longer depends on the host-path hack (TR-6)
# ---------------------------------------------------------------------------
def test_tc06_no_host_path_hack_in_source():
source = _SCRIPT_PATH.read_text(encoding="utf-8")
# The host-worktree path injection and the env-of-the-launcher reload that
# caused the false FAIL must be gone from the B6 mechanics.
assert 'sys.path.insert(0, "/repos/orchestrator")' not in source
assert "importlib.reload" not in source
def test_tc06_registry_loader_uses_src_projects():
# The verdict input is built from src.projects.known_plane_project_ids()
# resolved via the running instance's own PYTHONPATH/env — not from a
# host-path-injected import. We verify the loader delegates to that function.
import src.projects as projects_mod
sentinel = {"sentinel-id"}
original = projects_mod.known_plane_project_ids
projects_mod.known_plane_project_ids = lambda: sentinel
try:
known = sc._known_project_ids_from_registry()
finally:
projects_mod.known_plane_project_ids = original
assert known == sentinel
# ---------------------------------------------------------------------------
# TC-07 — degraded registry source → deterministic FAIL (not false PASS, not raise)
# ---------------------------------------------------------------------------
def test_tc07_source_failure_is_deterministic_fail(monkeypatch):
def _boom():
raise RuntimeError("registry import blew up")
monkeypatch.setattr(sc, "_known_project_ids_from_registry", _boom)
results = sc.Results()
# Must not raise.
sc._run_b6(results)
assert len(results._items) == 1
label, passed, detail = results._items[0]
assert passed is False
assert "registry source unavailable" in detail
assert "registry import blew up" in detail
# ---------------------------------------------------------------------------
# _run_b6 happy path wiring (clean registry → PASS result recorded)
# ---------------------------------------------------------------------------
def test_run_b6_records_pass_for_clean_registry(monkeypatch):
monkeypatch.setattr(
sc, "_known_project_ids_from_registry", lambda: {SANDBOX}
)
results = sc.Results()
sc._run_b6(results)
assert len(results._items) == 1
_label, passed, detail = results._items[0]
assert passed is True
assert "sandbox=YES" in detail

View File

@@ -3,7 +3,7 @@
Covers (per DEV_TASK_TELEGRAM_TRACKER.md):
* short_model_name: provider/claude- prefix trimming.
* render_task_tracker: per-stage line format (in↓/out↑, model, cost, minutes),
the "⏸️ Ревью БРД · твоё время" line, the 💰 totals, and the finish block
the "✅/⏸️ Подтверждение BRD · твоё время" line, the 💰 totals, and the finish block
(⏱️ three times + 🔗/📦).
* first message -> sendMessage stores message_id; transition -> editMessageText.
* fallback: editMessageText fails -> a NEW message is sent and the id updated.
@@ -134,17 +134,17 @@ def test_render_in_progress_stage_lines_and_totals():
# Header in-progress
assert text.startswith("\U0001f6e0\ufe0f ET-012 \u00b7 \u0422\u0440\u0435\u043a\u0438")
# Per-stage format: in↓/out↑ · cost · model
assert "\u2705 Analysis" in text
assert "\u2705 Анализ" in text
assert "10\u043c" in text # analysis duration
assert "39.6k\u2191" in text # analysis out
assert "$2.38" in text
assert "opus-4-8" in text
assert "sonnet-4.6" in text # reviewer/tester model
# BRD review line (human time, ended)
assert "\u0420\u0435\u0432\u044c\u044e \u0411\u0420\u0414" in text
assert "Подтверждение BRD" in text
assert "\u0442\u0432\u043e\u0451 \u0432\u0440\u0435\u043c\u044f" in text
# Active stage
assert "\U0001f504 Deploy" in text
assert "\U0001f504 Внедрение" in text
assert "\u0438\u0434\u0451\u0442" in text
# Totals line present with 💰
assert "\U0001f4b0" in text
@@ -159,7 +159,7 @@ def test_render_brd_review_waiting_shows_hourglass():
in_tok=1000, out_tok=39600, cache_read=1_100_000, cost=2.38,
model="tokenator/claude-opus-4-8")
text = N.render_task_tracker(tid)
assert "\u0420\u0435\u0432\u044c\u044e \u0411\u0420\u0414" in text
assert "Подтверждение BRD" in text
assert "\u23f3" in text # hourglass while waiting
@@ -213,7 +213,7 @@ def test_render_omits_model_when_unknown():
in_tok=10, out_tok=5, cost=0.0, model=None)
text = N.render_task_tracker(tid)
# No trailing " · <model>" — line ends at cost.
line = [l for l in text.splitlines() if l.startswith("\u2705 Analysis")][0]
line = [l for l in text.splitlines() if l.startswith("\u2705 Анализ")][0]
assert line.rstrip().endswith("$0.00")
@@ -408,7 +408,7 @@ def test_render_active_stage_shows_attempt_on_second_run():
text = N.render_task_tracker(tid)
active = [l for l in text.splitlines()
if l.startswith("\U0001f504") and "Review" in l][0]
if l.startswith("\U0001f504") and "Код ревью" in l][0]
assert _POPYTKA in active
assert "2" in active
assert "\u0438\u0434\u0451\u0442" in active
@@ -426,7 +426,7 @@ def test_render_active_stage_no_attempt_on_first_run():
text = N.render_task_tracker(tid)
active = [l for l in text.splitlines()
if l.startswith("\U0001f504") and "Review" in l][0]
if l.startswith("\U0001f504") and "Код ревью" in l][0]
assert _POPYTKA not in active
assert "\u0438\u0434\u0451\u0442" in active
@@ -516,3 +516,112 @@ def test_qg_failure_does_not_send_separate_message(monkeypatch):
lambda text, disable_notification=False: sent.append(text) or 1)
N.notify_qg_failure(tid, "development", "check_ci_green", "CI state: pending")
assert sent == [] # QG-pending is log-only, never a separate ping
# --------------------------------------------------------------------------- #
# ORCH-042: mode resolution + text changes (edit-mode default)
# --------------------------------------------------------------------------- #
def _brd_line(text):
return [ln for ln in text.splitlines() if "Подтверждение BRD" in ln][0]
def test_unknown_mode_falls_back_to_edit_branch(monkeypatch):
"""TC-02/AC-2: garbage mode -> edit branch, no exception, no extra send."""
monkeypatch.setattr(N._get_settings(), "tracker_mode", "garbage", raising=False)
tid = _mk_task(stage="development")
_mk_run(tid, "analyst", "2026-06-04 09:00:00", "2026-06-04 09:10:00",
in_tok=10, out_tok=5, cost=0.1)
from src.db import set_tracker_message_id, get_tracker_message_id
set_tracker_message_id(tid, 777)
edited = {}
monkeypatch.setattr(N, "edit_telegram",
lambda mid, text: edited.update(mid=mid) or N.EDIT_OK)
monkeypatch.setattr(N, "send_telegram",
lambda *a, **k: (_ for _ in ()).throw(
AssertionError("garbage mode must take edit branch")))
monkeypatch.setattr(N, "delete_telegram",
lambda *a, **k: (_ for _ in ()).throw(
AssertionError("garbage mode must NOT bump-delete")))
N.update_task_tracker(tid) # must not raise
assert edited["mid"] == 777
assert get_tracker_message_id(tid) == 777 # unchanged
def test_render_brd_label_is_confirmation_not_review():
"""TC-18/AC-15: 'Подтверждение BRD' present, 'Ревью БРД' absent."""
tid = _mk_task(stage="architecture", brd_start="2026-06-04 10:00:00",
brd_end="2026-06-04 10:08:00")
_mk_run(tid, "analyst", "2026-06-04 09:00:00", "2026-06-04 09:10:00",
in_tok=10, out_tok=5, cost=0.1)
text = N.render_task_tracker(tid)
assert "Подтверждение BRD" in text
assert "Ревью БРД" not in text
def test_render_brd_passed_uses_check_not_pause():
"""TC-19/AC-16: approve-gate passed (ended set) -> BRD line starts with ✅."""
tid = _mk_task(stage="architecture", brd_start="2026-06-04 10:00:00",
brd_end="2026-06-04 10:08:00")
_mk_run(tid, "analyst", "2026-06-04 09:00:00", "2026-06-04 09:10:00",
in_tok=10, out_tok=5, cost=0.1)
line = _brd_line(N.render_task_tracker(tid))
assert line.startswith("") # ✅
assert not line.startswith("") # not ⏸️
assert "" not in line # no hourglass once passed
def test_render_brd_waiting_keeps_pause_and_hourglass():
"""TC-20/AC-16: still waiting (ended empty) -> ⏳ indicator, not ✅."""
tid = _mk_task(stage="analysis", brd_start="2026-06-04 10:00:00",
brd_end=None)
_mk_run(tid, "analyst", "2026-06-04 09:00:00", "2026-06-04 09:10:00",
in_tok=10, out_tok=5, cost=0.1)
line = _brd_line(N.render_task_tracker(tid))
assert "" in line # ⏳ still waiting
assert not line.startswith("") # NOT ✅ yet
def test_render_stage_labels_are_russian():
"""TC-21/AC-17: russian stage labels in both ✅- and 🔄-lines; no english."""
tid = _mk_task(stage="deploy")
_mk_run(tid, "analyst", "2026-06-04 09:00:00", "2026-06-04 09:10:00",
in_tok=10, out_tok=5, cost=0.1, model="tokenator/claude-opus-4-8")
_mk_run(tid, "architect", "2026-06-04 09:10:00", "2026-06-04 09:20:00",
in_tok=10, out_tok=5, cost=0.1, model="tokenator/claude-opus-4-8")
_mk_run(tid, "developer", "2026-06-04 09:20:00", "2026-06-04 09:30:00",
in_tok=10, out_tok=5, cost=0.1, model="tokenator/claude-opus-4-8")
_mk_run(tid, "reviewer", "2026-06-04 09:30:00", "2026-06-04 09:35:00",
in_tok=10, out_tok=5, cost=0.1, model="vibecode/claude-sonnet-4.6")
_mk_run(tid, "tester", "2026-06-04 09:35:00", "2026-06-04 09:40:00",
in_tok=10, out_tok=5, cost=0.1, model="vibecode/claude-sonnet-4.6")
_mk_run(tid, "deployer", "2026-06-04 09:40:00", None,
in_tok=0, out_tok=0, exit_code=None)
text = N.render_task_tracker(tid)
for ru in ("Анализ", "Архитектура", "Разработка", "Код ревью",
"Тестирование", "Внедрение"):
assert ru in text, f"missing russian label {ru!r}"
for en in ("Analysis", "Architecture", "Development", "Review",
"Testing", "Deploy"):
assert en not in text, f"english label leaked: {en!r}"
def test_render_done_says_vnedreno_not_deployed():
"""TC-22/AC-18: final line says '📦 Внедрено', not 'deployed'."""
tid = _mk_task(stage="done")
conn = get_db()
conn.execute(
"UPDATE tasks SET created_at='2026-06-04 09:00:00', "
"updated_at='2026-06-04 09:56:00' WHERE id=?", (tid,))
conn.commit()
conn.close()
_mk_run(tid, "deployer", "2026-06-04 09:50:00", "2026-06-04 09:56:00",
in_tok=400, out_tok=22400, cost=1.73, model="tokenator/claude-opus-4-8")
with patch("src.notifications.httpx") as _hx:
_resp = MagicMock(status_code=200)
_resp.json.return_value = [] # no PR
_hx.get.return_value = _resp
text = N.render_task_tracker(tid)
assert "\U0001f4e6 Внедрено" in text # 📦 Внедрено
assert "deployed" not in text

237
tests/test_tracker_bump.py Normal file
View File

@@ -0,0 +1,237 @@
"""ORCH-042: bump-mode live tracker + delete_telegram helper.
bump = delete(old) + send(new, silent) + repoint message_id. One card per task,
always at the bottom. Covers AC-7..AC-14 (TC-07..TC-17). The edit-mode regression
stays in tests/test_telegram_tracker.py.
Isolated temp DB; no network (httpx / low-level helpers are patched per case).
"""
import os
import tempfile
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
_test_db = os.path.join(tempfile.gettempdir(), "test_orchestrator_tracker_bump.db")
os.environ["ORCH_DB_PATH"] = _test_db
from unittest.mock import MagicMock, patch # noqa: E402
import pytest # noqa: E402
import src.db as db_module # noqa: E402
from src.db import ( # noqa: E402
init_db, get_db, get_tracker_message_id, set_tracker_message_id,
)
from src import notifications as N # noqa: E402
@pytest.fixture(autouse=True)
def setup_db(monkeypatch):
monkeypatch.setattr(db_module.settings, "db_path", _test_db, raising=False)
if os.path.exists(_test_db):
os.unlink(_test_db)
init_db()
yield
if os.path.exists(_test_db):
os.unlink(_test_db)
def _mk_task(stage="development", wid="ORCH-042"):
conn = get_db()
cur = conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title) "
"VALUES (?, ?, ?, ?, ?, ?)",
("p1", wid, "orchestrator", "feature/ORCH-042-x", stage, "bump test"),
)
tid = cur.lastrowid
conn.commit()
conn.close()
return tid
def _bump_mode(monkeypatch):
monkeypatch.setattr(N._get_settings(), "tracker_mode", "bump", raising=False)
# --------------------------------------------------------------------------- #
# bump mode behaviour
# --------------------------------------------------------------------------- #
def test_bump_first_call_sends_silent_no_delete(monkeypatch):
"""TC-07/AC-7,AC-9: first call (no id) -> NO delete, silent send, id stored."""
_bump_mode(monkeypatch)
tid = _mk_task(stage="analysis")
sends = []
monkeypatch.setattr(N, "send_telegram",
lambda text, disable_notification=False:
sends.append(disable_notification) or 555)
monkeypatch.setattr(N, "delete_telegram",
lambda mid: (_ for _ in ()).throw(
AssertionError("delete must not run on first call")))
N.update_task_tracker(tid)
assert sends == [True] # exactly one silent send
assert get_tracker_message_id(tid) == 555
def test_bump_repeat_deletes_then_sends_and_repoints(monkeypatch):
"""TC-08/AC-8,AC-9,AC-10: repeat -> delete(old) THEN send(silent), id repointed."""
_bump_mode(monkeypatch)
tid = _mk_task()
set_tracker_message_id(tid, 100)
order = []
monkeypatch.setattr(N, "delete_telegram",
lambda mid: order.append(("delete", mid)) or True)
monkeypatch.setattr(N, "send_telegram",
lambda text, disable_notification=False:
order.append(("send", disable_notification)) or 200)
N.update_task_tracker(tid)
assert order == [("delete", 100), ("send", True)] # delete before send, silent
assert get_tracker_message_id(tid) == 200 # repointed to the new card
def test_bump_delete_fail_still_sends(monkeypatch):
"""TC-09/AC-11: delete_telegram->False -> new card still sent, id updated."""
_bump_mode(monkeypatch)
tid = _mk_task()
set_tracker_message_id(tid, 100)
sends = []
monkeypatch.setattr(N, "delete_telegram", lambda mid: False) # >48h / transient
monkeypatch.setattr(N, "send_telegram",
lambda text, disable_notification=False:
sends.append(disable_notification) or 201)
N.update_task_tracker(tid)
assert sends == [True] # exactly one send despite delete failing
assert get_tracker_message_id(tid) == 201
def test_bump_send_none_keeps_old_id(monkeypatch):
"""TC-10/AC-13: send->None (transient) -> id NOT wiped, one send attempt."""
_bump_mode(monkeypatch)
tid = _mk_task()
set_tracker_message_id(tid, 100)
sends = []
monkeypatch.setattr(N, "delete_telegram", lambda mid: True)
monkeypatch.setattr(N, "send_telegram",
lambda text, disable_notification=False:
sends.append(1) or None)
N.update_task_tracker(tid) # must not raise
assert len(sends) == 1 # exactly one (failed) attempt, no retry/dupe
assert get_tracker_message_id(tid) == 100 # pointer preserved, not None
def test_bump_one_card_per_call(monkeypatch):
"""TC-11/AC-10: at most one send_telegram per update_task_tracker call."""
_bump_mode(monkeypatch)
tid = _mk_task()
set_tracker_message_id(tid, 100)
sends = []
monkeypatch.setattr(N, "delete_telegram", lambda mid: True)
monkeypatch.setattr(N, "send_telegram",
lambda text, disable_notification=False:
sends.append(1) or 202)
N.update_task_tracker(tid)
assert len(sends) == 1
# --------------------------------------------------------------------------- #
# delete_telegram classification (httpx mocked, never raises)
# --------------------------------------------------------------------------- #
def _del_resp(ok, description=None):
resp = MagicMock()
body = {"ok": ok}
if description is not None:
body["description"] = description
resp.json.return_value = body
return resp
def _patch_tg_creds(monkeypatch):
monkeypatch.setattr(N._get_settings(), "telegram_bot_token", "T", raising=False)
monkeypatch.setattr(N._get_settings(), "telegram_chat_id", "C", raising=False)
def test_delete_ok_true(monkeypatch):
"""TC-12: ok:true -> True."""
_patch_tg_creds(monkeypatch)
with patch("src.notifications.httpx") as hx:
hx.post.return_value = _del_resp(True)
assert N.delete_telegram(1) is True
@pytest.mark.parametrize("desc", [
"Bad Request: message to delete not found",
"Bad Request: message can't be deleted",
"Bad Request: MESSAGE_ID_INVALID",
])
def test_delete_gone_markers_are_true(monkeypatch, desc):
"""TC-13/AC-12: 'already gone / can't delete' -> True (not transient)."""
_patch_tg_creds(monkeypatch)
with patch("src.notifications.httpx") as hx:
hx.post.return_value = _del_resp(False, desc)
assert N.delete_telegram(1) is True
@pytest.mark.parametrize("desc", [
"Bad Request: some other unexpected error",
"Internal Server Error",
])
def test_delete_unknown_or_5xx_is_false(monkeypatch, desc):
"""TC-14/AC-12: unknown ok:false / 5xx -> False (old may still be alive)."""
_patch_tg_creds(monkeypatch)
with patch("src.notifications.httpx") as hx:
hx.post.return_value = _del_resp(False, desc)
assert N.delete_telegram(1) is False
def test_delete_exception_is_false(monkeypatch):
"""TC-15/AC-12,AC-14: timeout/network -> False, never raises."""
_patch_tg_creds(monkeypatch)
with patch("src.notifications.httpx") as hx:
hx.post.side_effect = Exception("read timeout")
assert N.delete_telegram(1) is False
def test_delete_no_creds_is_false_and_no_http(monkeypatch):
"""TC-16/AC-12: no token/chat_id -> False, HTTP not called."""
monkeypatch.setattr(N._get_settings(), "telegram_bot_token", "", raising=False)
monkeypatch.setattr(N._get_settings(), "telegram_chat_id", "", raising=False)
with patch("src.notifications.httpx") as hx:
assert N.delete_telegram(1) is False
hx.post.assert_not_called()
# --------------------------------------------------------------------------- #
# never raises in either mode
# --------------------------------------------------------------------------- #
def test_update_task_tracker_never_raises_bump(monkeypatch):
"""TC-17/AC-14: bump path swallows a render/DB explosion."""
_bump_mode(monkeypatch)
tid = _mk_task()
monkeypatch.setattr(N, "render_task_tracker",
lambda task_id: (_ for _ in ()).throw(RuntimeError("boom")))
# Must not raise.
N.update_task_tracker(tid)
def test_update_task_tracker_never_raises_edit(monkeypatch):
"""TC-17/AC-14: edit path swallows a render/DB explosion."""
monkeypatch.setattr(N._get_settings(), "tracker_mode", "edit", raising=False)
tid = _mk_task()
monkeypatch.setattr(N, "render_task_tracker",
lambda task_id: (_ for _ in ()).throw(RuntimeError("boom")))
N.update_task_tracker(tid)