From dbe12f1a543dc991f03aba141c9504b2b0a52bfc Mon Sep 17 00:00:00 2001 From: Matysh Date: Thu, 13 Aug 2026 17:13:54 +0300 Subject: [PATCH] docs: state the invariant the pipeline was missing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A review run always moves the label. The rule is written down because its absence cost a real stall: a green code review whose merge conflicted left the label alone, the waiting author polled thirty times and reported the limit as exhausted, and a verdict that existed reached nobody. Both documents now say what S6-in-progress means when the verdict was green and only the merge failed — rebase, not rework, and the verdict still stands. They also say that a label which did not change means the run failed rather than the work, so the answer is logs and the owner, not more polling. Cycles are counted per stage. Issue: #114 User-Visible: no --- AGENTS.md | 26 ++++++++++++++++++++------ PROCESS.md | 19 +++++++++++++++++++ 2 files changed, 39 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 76c0f8a7..028ab9d6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -126,8 +126,14 @@ nothing to users and does not touch the integration branch, so it needs no comma **Do not merge into `dev` by hand.** On a green code review the pipeline rebases the task branch onto `dev`, pushes it, and only then sets `S8-merged` — the label asserts the code is in `dev`, so the merge has to happen first or the label lies -in between. If the rebase conflicts, the pipeline says so in the issue and leaves -the task in `S7-code-review`; resolving the conflict is the author's job. +in between. + +If the rebase conflicts the pipeline says so in the issue and sends the task back +to `S6-in-progress`. The verdict still stands: nothing needs reviewing again, the +remaining work is the rebase. Resolve it, push the branch, re-apply +`S7-code-review`. The second review run is not a formality — after a rebase onto a +moved `dev` this is different code, and accepting it unchecked is how regressions +arrive. Cycles are counted per stage, so a code review spends its own budget. Everything else still requires the owner's explicit command: pushing `main`, creating tags, publishing betas and releases, closing issues. @@ -171,10 +177,18 @@ the comment only explains it. Do not wait at all while `blocked` is set — the is waiting on the owner, not on the reviewer. On exhausting the attempts, stop and tell the owner: a failed run leaves the label where it was, forever. -What the new label means: `S5-ready` — write the code; `S3-spec` — read the verdict -and revise the spec, then re-apply `S4-spec-review`; `S6-in-progress` — revise the -code, then re-apply `S7-code-review`; `S8-merged` — accepted and already in `dev`, -nothing left to do; `review-4` — the cycle limit is spent, stop and wait for the owner. +What the new label means: + +| Now reads | What happened | What you do | +|---|---|---| +| `S5-ready` | the spec is accepted | write the code | +| `S3-spec` | the spec came back | read the verdict, revise, re-apply `S4-spec-review` | +| `S6-in-progress` | the code came back | revise, re-apply `S7-code-review` — **or**, if the verdict was green and only the merge conflicted, just rebase and re-apply. The comment says which | +| `S8-merged` | accepted and already in `dev` | nothing | +| `review-4` | the cycle limit is spent | stop, the owner decides | + +**After a review run the label always changes.** If it did not, the run itself +failed rather than the work — say so to the owner instead of polling on. The exchange happens in **issue comments** — there is no local message bus. Verdict format: diff --git a/PROCESS.md b/PROCESS.md index de69da47..f0d32cf9 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -618,6 +618,25 @@ Medium-находку, кладёт документ в `docs/reviews/` ветк секунд, не более 30 попыток. Смотреть на метку, а не на комментарий: метка и есть состояние. При `blocked` не ждать — задача ждёт владельца. +**После прогона ревью метка меняется всегда.** Инвариант появился не сразу: первая +редакция при конфликте слияния оставляла метку на месте, и это оказалось тупиком — +автор ждёт смену метки, метка не менялась, и он тридцать раз опрашивал впустую, +чтобы отчитаться «лимит исчерпан» при зелёном вердикте. Состояние, из которого +никто не может выйти и о котором никто не узнает, для конвейера хуже громкой +ошибки. + +Поэтому зелёное код-ревью с неудавшимся слиянием ведёт не в `S8-merged`, а в +`S6-in-progress`: работа действительно вернулась к автору, только осталась не +правка кода, а ребейз. Вердикт при этом в силе, переделывать нечего. После ребейза +метка `S7-code-review` возвращается и ревью идёт заново — не формальность: +после ребейза на ушедший вперёд `dev` это другой код. + +Если метка не сменилась, значит упал сам прогон, а не работа: смотреть логи и +сообщать владельцу, а не продолжать опрос. + +Цикл считается **по этапу**: вердикт по ТЗ не расходует бюджет код-ревью. Раньше +считались все вердикты подряд, и первое код-ревью #89 получило `r2/4`. + --- ## 11. Исключения