docs(rules): the coai feature gate — when to call it, what the verdicts mean

[oleksandrdubyna88]

What this adds

common/coai-feature-gate.md (common.coai-feature-gate) — the caller's rule for the review server's fourth stage, review_feature: one review of a whole plan of three or more epics, after its last epic and before the release. It lives here because the server gates every repository in the family (operator, 2026-09-26). It is short on purpose: the tool description carries the parameters and limits; the rule says

• when — once, for a plan of 3+ epics (the server's COAI_FEATURE_MIN_EPICS, default 3), fully implemented, before the release; not per epic, since each epic's own code round stays;
• what to pass — planPath (the review's identity, passed again as feature to resolve/status/ask_human), baseRef = the commit the first epic branched from, every epic with its summary and branch or PR, honest lessons (an empty category says why, in at least 20 characters), callerModel;
• the verdicts — proceed; revise → resolve every finding, fix and commit the accepted ones, and run a second round with again: true only after a reviewer failure, a blocking finding or the person's request — otherwise one round, and never more than two; call_human stops the shipping, not the task (also the answer when every reviewer failed); skipped never blocks;
• a finding the caller cannot judge goes to consult before resolve;
• nothing checks whether it was run — no checker, no CI step, no counting. This repository holds guidance, never enforcement.

It carries a <!-- coai-feature v1 --> marker in the shape of the other four coai rules, so a consumer can generate from it later. It is not added to canonical-markers.test.mjs, because no consumer build reads it yet.

Two batched edits (approved by the operator to ride with the next conventions change)

• common/coai-consultant.md, trigger 7: "a cadence consultation counts only when it has one" is replaced with "A cadence consultation counts only after close_consult records solved, not_solved or abandoned." The marker rises to <!-- coai-consultant v4 --> with it (coai's CONSULTANT_VERSION 3 → 4), so pasted copies see the text as new.
• README, promote-release: the dispatch takes a required reason input beside the sha (-f reason="…"); without it the dispatch answers 422.

Records and checks

• research/rule-bodies.json: the new entry added by hand, as a new rule must be; common.coai-feature-gate and common.coai-consultant recorded with node tools/rule-bodies.mjs --update naming exactly those two ids.
• research/module_tests.md: a short section on what checks the new rule and what deliberately does not.
• Local results: npm test 236 pass / 0 fail / 1 skipped; npm run check resolved; ownership-check OK (34 rules, no undeclared references); rule-bodies OK; plan-lifecycle clean; adapter-check OK; branch-protection selftest OK.

Do not promote to release until coai ships review_feature (mcp ≥ 0.39.0); the promotion starts the six-consumer pin cascade.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Документация
  • Уточнены требования к ручному запуску продвижения релиза: вместе с SHA нужно указать причину. Без неё GitHub возвращает ошибку 422, и workflow не запускается.
  • Уточнено, когда консультация считается завершённой, и какие исходы позволяют продолжить работу после отказа в раунде кода.
  • Добавлено руководство по сквозной проверке планов из трёх и более эпиков перед выпуском: описаны входные данные, вердикты и условия повторного раунда. Проверка не запускается автоматически и не контролируется CI.

[github-actions]

@coderabbitai review

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: oleksandrdubyna88/dew_flow_conventions/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 5e329e21-2f6c-402f-93f2-f5a227725c14

📥 Commits

Reviewing files that changed from the base of the PR and between ddad1d9 and d180929.

📒 Files selected for processing (4)

• common/coai-consultant.md
• common/coai-feature-gate.md
• research/module_tests.md
• research/rule-bodies.json

🚧 Files skipped from review as they are similar to previous changes (2)

• common/coai-consultant.md
• research/module_tests.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Обновлены инструкции запуска promote-release и условие завершения cadence-консультации. Добавлено правило проверки функции перед выпуском для планов минимум из трёх эпиков. Связанные сведения внесены в исследовательскую документацию и реестр правил.

Changes

Инструкции запуска выпуска

Layer / File(s)	Summary
Параметр reason для promote-release README.md	Команда gh workflow run передаёт обязательные reason и SHA. Если reason отсутствует, GitHub отвечает 422 и не запускает workflow.

Завершение cadence-консультации

Layer / File(s)	Summary
Условие завершения консультации common/coai-consultant.md, research/rule-bodies.json	Консультация засчитывается после записи через close_consult исхода solved, not_solved или abandoned. В режиме require code round остаётся отклонённым до записи исхода, кроме случая, когда консультанта нельзя получить. Обновлены версия маркера и хеш правила.

Проверка функции перед выпуском

Layer / File(s)	Summary
Правило проверки функции common/coai-feature-gate.md, research/module_tests.md, research/rule-bodies.json	Добавлено правило условной проверки функции для планов минимум из трёх эпиков. Оно описывает входные данные, обработку вердиктов и предел в два раунда. Исследовательская документация и реестр описывают правило и отмечают отсутствие автоматического контроля запуска.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Suggested reviewers: oleksandrdubyna-create

Merge Risk: ⚪ Minimal · up to d1809

The documented release and review workflows have no identified issue requiring a change before merge.

Architecture Summary

Architecture risk: 🔵 Low · up to d1809

The change affects 3 systems.

Changed systems: common, research, README.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — common (service) was modified; 2 changed files map to changed impact.
• observed — research (service) was modified; 2 changed files map to changed impact.
• observed — README.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in README.md: В инструкции к promote-release добавлен обязательный ввод reason для сводки запуска и обновлена команда gh workflow run, передающая его вместе с SHA. Указано, что без reason запуск отклоняется с ответом 422.
• observed — Modified behavior in common/coai-consultant.md: Версия в HTML-комментарии изменена с v3 на v4.
• observed — Modified behavior in common/coai-consultant.md: Уточнено, что cadence-консультация засчитывается после записи через close_consult исхода solved, not_solved или abandoned; в режиме require code round группы отклоняется до записи исхода, кроме случая, когда консультанта нельзя получить. Ранее требовалось лишь наличие outcome.
• observed — Modified behavior in common/coai-feature-gate.md: Добавлено руководство по условной сквозной проверке функции: оно задаёт условия и параметры вызова, обработку вердиктов и повторного раунда, консультацию по неоценимым замечаниям, отсутствие автоматического контроля запуска и критерии завершения. Уточнено, что повтор после сбоя запрашивает только неудачных рецензентов, а call_human возвращается, если второй раунд всё ещё завершается сбоем или содержит blocking.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Заголовок точно описывает основное изменение: добавление правила CoAI feature gate и разъяснение условий его вызова и вердиктов.
Description check	✅ Passed	Описание подробно раскрывает изменение правила, связанные правки, результаты проверок и ограничение на продвижение в release. Отдельные заголовки шаблона Evidence, The cascade и The reviewer отсутству…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud