opencode-config/docs/decisions/019-pr-46-review-posting-tools.md

ADR-019: Deterministic review posting tools (post-review, post-docs-review)

Статус

Accepted (2026-07-24)

Контекст

Reviewer и docs-reviewer агенты постят verdict-комментарии на PR через raw gh pr comment с ручным форматированием heading + verdict line:

• reviewer: ## Code Review Summary + ### Verdict: APPROVE|REQUEST_CHANGES|NEEDS_DISCUSSION
• docs-reviewer: ## Docs Review Summary + ### Verdict: APPROVE|FIXED|NO_CHANGES

pipeline-status.py парсит эти комментарии regex'ами для определения статуса фаз REVIEW и DOCS:

• REVIEW_VERDICT_RE = re.compile(r"## Code Review Summary.*?###\s*Verdict:\s*(\w+)", re.IGNORECASE | re.DOTALL)
• DOCS_REVIEW_RE = re.compile(r"Docs Review", re.IGNORECASE) — substring match

Риски текущего подхода (raw gh pr comment):

1. Wrong heading — reviewer случайно пишет ## Code Review (без "Summary") или ## Review Summary → REVIEW_VERDICT_RE не матчит → pipeline NOT_DONE (блокировка)
2. Verdict typo — APROVE вместо APPROVE, REQUEST_CHANGES с пробелом → regex не матчит verdict → NOT_DONE
3. No mutual exclusion — любой агент может постить ## Code Review Summary (нет guard "только reviewer")
4. False positive — DOCS_REVIEW_RE substring match Docs Review (без ## prefix требования), теоретический false positive если любой комментарий упомянет "Docs Review" в тексте

Root cause: формат комментария контролируется промптом (soft guard), не type system. Модель может опечататься, забыть heading, изменить формат.

Решение

Детерминированные TS tools, которые гарантируют heading + verdict формат через type system:

1. post-review.ts tool (.opencode/tools/post-review.ts)

• Args: pr_number: number, verdict: enum(APPROVE, REQUEST_CHANGES, NEEDS_DISCUSSION), body: string
• Генерирует comment: ## Code Review Summary\n\n${body}\n\n### Verdict: ${verdict}
• Вызывает gh pr comment N --body <comment> --repo slaid098/opencode-config через spawnSync
• Body — содержимое БЕЗ heading и verdict (tool добавляет их сам)
• Verdict enum (zod) гарантирует: только APPROVE/REQUEST_CHANGES/NEEDS_DISCUSSION, опечатки отклоняются на schema layer

2. post-docs-review.ts tool (.opencode/tools/post-docs-review.ts)

• Args: pr_number: number, verdict: enum(APPROVE, FIXED, NO_CHANGES), body: string
• Генерирует comment: ## Docs Review Summary\n\n${body}\n\n### Verdict: ${verdict}
• Вызывает gh pr comment N --body <comment> --repo slaid098/opencode-config через spawnSync

3. Agent integration

• reviewer.md — секция "Output Format" переписана: gh pr comment → post_review({ pr_number, verdict, body }). 3 сценария (APPROVE/REQUEST_CHANGES/NEEDS_DISCUSSION). Rules 7/8 обновлены.
• docs-reviewer.md — секция "PR Comment (mandatory)" переписана: gh pr comment → post_docs_review({ pr_number, verdict, body }).

4. Role-based access (agent.tools map)

.opencode/opencode.json agent.tools map расширен:

Agent	post_review	post_docs_review
general	false	false
reviewer	true	false
docs-reviewer	false	true
memory-syncer	false	false

Mutual exclusion: только reviewer может постить code review, только docs-reviewer — docs review. General и memory-syncer не могут постить reviews. Это устраняет риск "любой агент постит review comment".

5. pipeline-status.py совместимость

Regex'ы НЕ изменены. Tools генерируют ровно тот формат, который regex ожидает:

• ## Code Review Summary (exact heading) + ### Verdict: <verdict> → REVIEW_VERDICT_RE матчит
• ## Docs Review Summary (contains Docs Review) → DOCS_REVIEW_RE матчит

6. Тестовая инфраструктура

tests/_ts_loader.mjs расширен:

• zodShim: добавлен enum: () => chain() метод (для tool.schema.enum(VERDICTS))
• stripTs: strip as const assertions + strip type <Name> = ... type alias declarations (TS-only синтаксис новых tools)

24 новых Python теста (12 на tool) + 14 TS тестов (документационные).

Альтернативы

• Оставить raw gh pr comment + усилить промпт — отклонено: промпт = soft guard, модель (GLM) игнорирует правила форматирования. Root cause (формат контролируется промптом, не type system) не устранён. Документировано в PR#85 (docs-reviewer marker) — промпт-правила ненадёжны.

• Validate comment format post-hoc в pipeline-status.py — отклонено: pipeline-status.py уже парсит regex'ами, но это detection, не prevention. Comment уже постит с wrong heading → pipeline NOT_DONE → нужно перезапустить reviewer. Tool предотвращает ошибку на этапе создания (prevention > detection).

• Параметризовать --repo через git remote (как ADR-007 для pipeline-status.py) — отклонено: out of scope. merge-pr.ts тоже хардкодит --squash --delete-branch (не параметризует repo). Для других репо — отдельный PR (параметризация всех tools). Сейчас tools специфичны для slaid098/opencode-config.

• Запретить raw gh pr comment в allow-list (принудить к tool) — отклонено: оставлено для обратной совместимости (fallback). Tools используют spawnSync напрямую (не через bash permission layer), так что raw gh pr comment* в allow-list не конфликтует. Если захотеть strict tool-only — отдельный PR с deny правилом gh pr comment*.

• Расширить DOCS_REVIEW_RE до ## Docs Review Summary (exact heading) — отклонено: risk of breaking existing comments. Tools уже генерируют exact heading, но старые comments (до этого PR) могут иметь другой формат. Substring match остаётся как tolerant fallback. Future PR может tighten regex после migration.