feat(opencode): separate semantic and merge decisions

[seonghobae]

Purpose

Implement the test-first, production-independent part of Task 5 in the OpenCode review-quality plan: a versioned decision envelope that keeps semantic source review separate from merge readiness.

Exact stacked identity

• stacked base branch: feat/opencode-review-gold-corpus (PR feat(opencode): add head-matched gold corpus tooling #831);
• exact stacked base SHA: 2d3100b27d1d979e6e2f3ead2fc278b08a840b44;
• branch: feat/opencode-review-decision-envelope;
• corrected test-only RED head: 48a609d177b2fcd5d8a261570bc845ad5abb1af3;
• exact current GREEN and doctoring head: c3133887df775605bfca2aaaa8b94094aec609fc;
• state: Draft, mechanically mergeable, not eligible to merge before its stacked predecessors integrate.

No check, review, approval, or comment from PR #829 or #831 authorizes this stacked head. If either predecessor moves or integrates, this branch must be reconciled once onto the resulting exact protected base and every exact-head evidence surface regenerated.

Test-first lineage

The first branch run exposed a test-support import-path defect rather than the intended product gap, so it is not counted as the authoritative RED. The test harness was corrected without adding production behavior.

Run 31259792839 then checked out exact test-only head 48a609d177b2fcd5d8a261570bc845ad5abb1af3 and failed during collection because scripts/ci/opencode_review_decision.py did not exist. That is the valid RED evidence for the permanent contract.

Production implementation, strict validation, additional branch-coverage regressions, doctoring, and changelog traceability were added without deleting, skipping, weakening, or converting any permanent test into an expected failure.

Implemented decision contract

Semantic channel

• complete, unavailable, and failed semantic states;
• exact reviewed-head binding for completed reviews;
• unavailable or failed review must abstain and cannot carry findings;
• semantic verdicts APPROVE, COMMENT, REQUEST_CHANGES, and ABSTAIN;
• complete source findings with path, positive line, defect class, severity, blocking classification, trigger, impact, root cause, fix direction, and regression target;
• duplicate case-insensitive finding identities rejected.

Merge-readiness channel

• exact-head coverage, independent-approval, branch-protection, required-check, and advisory-check evidence;
• readiness states READY, BLOCKED, and UNKNOWN;
• failed, cancelled, skipped-required, and neutral-required evidence treated as hard blockers;
• pending, queued, and absent evidence treated as unknown rather than success;
• advisory-check failure recorded without blocking unless repository policy marks the check required;
• duplicate case-insensitive check names rejected.

Non-conflation invariant

A coverage or check failure may block merge readiness but cannot create a source finding, severity, path, line, trigger, root cause, or code-fix instruction. A valid semantic finding remains present even when infrastructure evidence independently fails.

The Markdown renderer physically separates Semantic findings from Infrastructure and policy blockers; only semantic findings may render path:line.

Evidence integrity

• strict exact-field schemas at every layer;
• strict Boolean/integer/enumeration handling;
• safe repository-relative source paths;
• duplicate JSON member rejection;
• non-finite JSON number rejection;
• exact-head binding for semantic review, policy evidence, and every check;
• deterministic canonical input and decision SHA-256 receipts;
• atomic JSON and Markdown output;
• stable CLI validation status.

Exact-current-head verification

OpenCode Review Decision Quality CI run 31260754829 checked out exact head c3133887df775605bfca2aaaa8b94094aec609fc with persisted credentials disabled and completed successfully:

• 29 passed;
• total production statements: 232/232;
• total production branches: 76/76;
• production statement and branch coverage: 100%;
• opencode_review_decision.py: 81 statements, 30 branches, 100%;
• decision primitives: 83 statements, 22 branches, 100%;
• decision validation: 68 statements, 24 branches, 100%;
• compileall: success;
• clean-tree verification: success.

The exact regression for the observed failure mode proves that a complete defect-free semantic review plus failed coverage yields review_verdict=APPROVE, merge_readiness=BLOCKED, no source finding, and one path-free coverage blocker.

docs/doctoring/opencode-review-decision-envelope.md records the decision matrix, exact-head contract, strict evidence boundary, security/privacy constraints, later dispatch integration sequence, monitoring, rollback, limitations, and APA 7th references to GitHub protection/check semantics, NIST SSDF 1.1 and 800-218A, SLSA 1.2, and empirical code-review research. CHANGELOG.md records the bounded capability.

Production writer boundary

This PR deliberately does not edit .github/workflows/opencode-review-dispatch.yml. Active central branches #789, #812, #816, and #827 modify that workflow. Editing it here would violate the repository-writer lease and risk discarding unrelated exact-head repairs.

Dispatch integration remains a later protected slice after writer clearance. It must begin with a fresh failing production contract requiring the dispatch to continue bounded semantic review when safe source evidence exists, publish source comments only from validated semantic findings, and route coverage/check/approval/protection failures exclusively through the merge-readiness channel.

Safety and acceptance

• no production dispatch, reviewer credential, model policy, provider secret, branch protection, merge path, or publication behavior changes;
• no COPILOT_GITHUB_TOKEN use;
• no source finding synthesized from infrastructure state;
• no temporary, one-shot, self-modifying, or write-capable workflow;
• exact-head checkout uses immutable action pins and persisted credentials disabled;
• the workflow token remains read-only.

Keep Draft and do not merge until PR #829 and #831 integrate, this branch is reconciled onto the exact protected base, the complete organization quality/security/review suite reruns on the resulting exact head, no valid unresolved finding remains, and a qualifying independent non-author formal approval exists. Pending, queued, skipped-required, status-only, author-only, stale-head, predecessor-head, synthetic-merge, rate-limited, or absent evidence is not acceptance.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8466bf09-a574-44c2-8804-d5664b3eeb81

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[seonghobae]

@opencode-agent @cwl-noema-review

Review-only request for exact stacked head c3133887df775605bfca2aaaa8b94094aec609fc against exact stacked base 2d3100b27d1d979e6e2f3ead2fc278b08a840b44 (feat/opencode-review-gold-corpus, PR #831).

Inspect the complete 10-file diff, the corrected RED→GREEN lineage, semantic-versus-merge decision matrix, coverage-failure non-conflation invariant, hard-blocked versus unknown evidence classification, exact-head binding, strict JSON and scalar boundaries, duplicate rejection, path-free infrastructure blockers, deterministic receipts, atomic output, exact-head CI, APA 7th doctoring, rollback, and the explicit production-dispatch writer boundary.

Do not modify the branch; update or retarget the base; synthesize source findings from infrastructure state; approve on behalf of an author; merge; release; weaken tests; alter reviewer credentials, model policy, provider secrets, or branch protection; edit .github/workflows/opencode-review-dispatch.yml; or reuse predecessor-head evidence.