fix: correct reviewer APPROVE→COMMENT docs + enforce no-formal-approve at compile time

[anandgupta42]

What does this PR do?

Follow-up to #870. That PR mapped an APPROVE verdict to a GitHub COMMENT review event (so the bot never submits a formal approval that could satisfy branch protection), but left two loose ends this PR closes:

1. Stale doc comments in packages/opencode/src/altimate/review/post-github.ts still claimed "in gate mode it maps the verdict to APPROVE/REQUEST_CHANGES" and "gate mode keeps APPROVE / REQUEST_CHANGES" — contradicting the shipped behavior on a security-relevant path. Corrected to describe the actual contract (APPROVE → COMMENT always; comment mode also softens REQUEST_CHANGES → COMMENT; gate mode keeps REQUEST_CHANGES; env.verdict arrives pre-softened from buildEnvelope).

2. The no-formal-approval invariant was only enforced at runtime. VCS_EVENT's value type still included "APPROVE". Narrowed it to "COMMENT" | "REQUEST_CHANGES" so the invariant is now a compile-time guarantee — no future edit can resurrect a formal GitHub approval without breaking the build. The narrower union is still assignable to Octokit's createReview event param.

Also documents applyMode's APPROVE/COMMENT passthrough, and adds a composition test asserting the positive expected GitHub event for every verdict-producing finding-set across both modes, plus the semantic-verdict-vs-VCS-event separation (gate + no findings → verdict === "APPROVE" but event "COMMENT"; comment-mode blocking critical → idealVerdict === "REQUEST_CHANGES", verdict === "COMMENT").

The type narrowing and test strengthening were findings from a multi-model consensus review (GPT 5.4, Gemini 3.1 Pro, GLM-5) incorporated during convergence.

• packages/opencode/src/altimate/review/verdict.ts — narrowed VCS_EVENT value type to exclude "APPROVE"; documented applyMode passthrough.
• packages/opencode/src/altimate/review/post-github.ts — corrected the two stale doc comments.
• packages/opencode/test/altimate/review.test.ts — added the composition / verdict-vs-event-separation test.

Type of change

• Bug fix (non-breaking change which fixes an issue)

Issue for this PR

Closes #871

How did you verify your code works?

• bun run typecheck (tsgo --noEmit) — clean. The narrowed VCS_EVENT type compiles against post-github.ts's createReview({ event }) call.
• bun test test/altimate/review.test.ts — 66 pass, 0 fail (includes the new composition test).
• bun test test/altimate/review.test.ts review-ci.test.ts review-dbt-patterns.test.ts review-rule-catalog.test.ts — 118 pass, 0 fail.
• Marker guard (script/upstream/analyze.ts --markers --base origin/main --strict) — no upstream-shared files modified.
• prettier --check on all three changed files — clean (only the added test block; no unrelated reformatting).

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective
• New and existing unit tests pass locally with my changes

---

Summary by cubic

Enforces a compile-time guarantee that the reviewer never submits a formal GitHub approval and updates docs to reflect the APPROVE → COMMENT behavior. Adds tests to verify verdict-to-event mapping across modes.

• Bug Fixes
  • Updated docs in packages/opencode/src/altimate/review/post-github.ts to state: APPROVE always posts COMMENT; comment mode softens REQUEST_CHANGES → COMMENT; gate mode keeps REQUEST_CHANGES; env.verdict is pre-softened.
  • Narrowed VCS_EVENT in packages/opencode/src/altimate/review/verdict.ts to "COMMENT" | "REQUEST_CHANGES" to enforce no-formal-approve at compile time; documented applyMode passthrough.
  • Added a composition test in packages/opencode/test/altimate/review.test.ts that checks correct GitHub events across modes, preserves ideal verdicts for audit, and ensures no path emits "APPROVE".

^{Written for commit 2dd495a. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation

  • Clarified GitHub review posting semantics and verdict mode mappings.

• Bug Fixes

  • Enforced at compile-time that APPROVE verdicts never map to formal VCS approval events; they consistently map to COMMENT events instead.

• Tests

  • Added comprehensive tests verifying end-to-end verdict-to-event mapping across different review modes.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: a20f59af-60c0-403b-a53a-f6345438f6bf

📥 Commits

Reviewing files that changed from the base of the PR and between 21721ac and 2dd495a.

📒 Files selected for processing (3)

• packages/opencode/src/altimate/review/post-github.ts
• packages/opencode/src/altimate/review/verdict.ts
• packages/opencode/test/altimate/review.test.ts

---

📝 Walkthrough

Walkthrough

The PR hardens the invariant that APPROVE verdicts never emit formal GitHub approval events. It narrows VCS_EVENT's type to exclude "APPROVE", corrects stale documentation in post-github.ts to match actual behavior, and adds a composition test covering verdict-to-VCS_EVENT mappings across both gate and comment modes.

Changes

No-formal-APPROVE guarantee

Layer / File(s)	Summary
Compile-time type guarantee for VCS_EVENT packages/opencode/src/altimate/review/verdict.ts	VCS_EVENT type narrowed to Record<Verdict, "COMMENT" | "REQUEST_CHANGES">, eliminating "APPROVE" as a possible mapped event. Supporting comment in applyMode notes that APPROVE/COMMENT pass through and the no-formal-approval guarantee is enforced via the narrowed type.
GitHub review posting semantics documentation packages/opencode/src/altimate/review/post-github.ts	Doc comment and inline comment corrected to describe actual behavior: APPROVE always maps to COMMENT; comment mode softens REQUEST_CHANGES to COMMENT; gate mode preserves REQUEST_CHANGES; env.verdict arrives pre-softened from buildEnvelope.
End-to-end verdict-to-VCS_EVENT composition test packages/opencode/test/altimate/review.test.ts	New test verifies verdict-to-VCS_EVENT mappings across gate and comment modes, asserting empty findings yield COMMENT (never formal APPROVE), suggestions map to COMMENT, blocking criticals produce REQUEST_CHANGES in gate but COMMENT in comment mode, and confirming "no formal APPROVE event" invariant for all finding sets. Includes explicit idealVerdict vs verdict separation checks.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• dbt PR reviewer: stale doc comments contradict APPROVE→COMMENT; harden no-formal-approve invariant at compile time #871: Directly addresses the issue by removing "APPROVE" from VCS_EVENT type union, correcting stale documentation in post-github.ts, and adding composition test coverage for the no-formal-approval invariant.

Possibly related PRs

• AltimateAI/altimate-code#870: Implements the upstream fix that changed APPROVE verdicts to map to GitHub COMMENT events; this PR hardens the invariant at compile time and documents the behavior.

Suggested labels

contributor

Poem

A rabbit hops through types so bright,
No APPROVE shall see the GitHub light!
With narrowed unions, tests in place,
The doc comments now match the trace. ✨🐰

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is detailed and structured, covering what changed, why, and how it was tested, but it does not include the required 'PINEAPPLE' marker specified in the template for AI-generated contributions.	Add 'PINEAPPLE' at the very top of the PR description as required by the template for AI-generated or AI-assisted contributions.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: correcting docs and enforcing no-formal-approval at compile time through type narrowing.
Linked Issues check	✅ Passed	The PR fully addresses all objectives in issue #871: corrects stale doc comments, narrows VCS_EVENT type to enforce compile-time no-formal-approve guarantee, documents applyMode, and adds composition tests for verdict-to-event mapping across modes.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #871: documentation corrections, type narrowing, and test additions for verdict-to-event mapping; no unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/reviewer-approve-comment-docs-and-test

---

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 and usage tips.}

[github-actions]

👋 This PR was automatically closed by our quality checks.

Common reasons:

• New GitHub account with limited contribution history
• PR description doesn't meet our guidelines
• Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.