[codex] Require structured hosted reviews and repair loop

[romgenie]

Summary

• Require hosted review runs to emit structured headless review results with evidence, reviewed files, findings, limitations, and no-findings rationale.
• Add hosted coven-github dogfood adapter support for publishing structured review evidence back to GitHub.
• Add opt-in COVEN_REVIEW_FIX_LOOPS for bounded hosted review repair cycles using prior structured findings as explicit repair instructions.
• Enforce v2 result contract validation before hosted review loops or publication.
• Persist per-cycle artifacts and publish loop metadata so future dogfood runs can show whether findings were actually rechecked.

Issue tags

• Primary hosted-review hardening track: Hosted Review Mode — security & memory hardening track coven-code#119
• Runtime-side structured review contract: [codex] Upstream hosted review dogfood stack coven-code#132
• Adapter queue/idempotency scope: Add durable task queue and GitHub delivery idempotency #2
• Adapter auth/publication boundary: Split agent read auth from publication write auth #4
• Familiar routing and repository policy: Add installation-scoped familiar routing and repository policy #7
• Future PR/push/commit review trigger scope: Implement PR, push, and commit review triggers #10
• Structured review output and deterministic publication gates: Add structured review output and deterministic publication gates #11

Refs OpenCoven/coven-code#119
Related to OpenCoven/coven-code#132, #2, #4, #7, #10, #11

Commit issue-linking note

Some commits in this stacked PR use the shorthand #119 because they were created while working across the paired coven-code and coven-github branches. For cross-repository review, treat those commit references as OpenCoven/coven-code#119; this PR body records the explicit cross-repository links.

Upstreaming note

This upstream PR is created from the research fork branch codex/review-fix-loop. It intentionally contains the full stacked research work for:

• structured hosted review contract
• bounded hosted review fix loop
• hosted adapter contract hardening

Validation

• python -B -m py_compile deploy\coven-github\coven_github_adapter.py
• focused Python adapter assertions for routing and result-contract validation
• cargo fmt --all
• cargo check --workspace
• cargo clippy --workspace --all-targets -- -D warnings
• cargo test --workspace
• git diff --check (only Windows line-ending warnings)

Behavior

• Default behavior remains unchanged unless COVEN_REVIEW_FIX_LOOPS is set above 0.
• Review repair loops are bounded and clamped to at most 5 iterations.
• Hosted review publication only consumes terminal, contract-valid v2 results.

[romgenie]

Reviewed the structured review contract and hosted adapter changes. I found several actionable issues around contract enforcement, webhook security, policy gating, and review evidence completeness.

[romgenie]

Reviewed the current PR head after the previous fixes. The build/test suite passes locally, but I found additional contract and routing issues that should be addressed before merging.

[romgenie]

Reviewed PR #31 for contract/schema drift, hosted adapter safety, review evidence handling, and repair-loop behavior. I found two remaining contract enforcement gaps worth addressing.

[romgenie]

Reviewed the latest PR #31 head (cacece4) for remaining contract/schema/validator drift and hosted adapter behavior. I found two additional contract consistency issues worth addressing before merge.

[romgenie]

Reviewed latest PR #31 head (6bdfb7b) for remaining schema/validator/runtime drift. I found two contract consistency issues worth addressing.

[romgenie]

Reviewed latest PR #31 head (2cc54f7) for remaining contract/schema drift. I found two actionable consistency issues.

[romgenie]

Ready to merge

[romgenie]

@BunsDev Ready for your review.

[Copilot]

Pull request overview

This PR upgrades the coven-code ↔ coven-github headless interface to contract v2, adding a structured hosted-review result envelope (evidence, reviewed files, findings, limitations, and no-findings rationale) and introducing a hosted dogfood Python adapter that can publish those results back to GitHub and optionally run a bounded “review fix loop”.

Changes:

• Bump the headless contract to v2 across docs + JSON schemas, adding structured review output and optional hosted review_context / audit_instruction.
• Add a deployment-specific Python hosted adapter (plus unit tests) to capture PR evidence, validate v2 results, publish review output, and optionally perform bounded repair cycles.
• Enforce v2 result-contract validation in the Rust worker and extend CI to compile + test the hosted adapter.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/headless-contract.md	Updates contract documentation to v2 and defines structured review requirements.
docs/contracts/session-brief.schema.json	Updates session brief JSON schema to require v2 contract_version and allow hosted review context fields.
docs/contracts/session-brief.example.json	Updates session brief example to v2.
docs/contracts/result.schema.json	Updates result JSON schema to v2 and adds structured review envelope rules.
docs/contracts/result.example.json	Updates result example to v2, including review envelope.
deploy/coven-github/test_coven_github_adapter.py	Adds unit tests for mention parsing and PR evidence staleness detection.
deploy/coven-github/README.md	Documents hosted dogfood adapter behavior, inputs, and fix-loop toggle.
deploy/coven-github/coven_github_adapter.py	Implements hosted adapter: routing, evidence capture, v2 validation, publication, and bounded repair loop.
crates/worker/tests/contract.rs	Expands contract tests to v2, including hosted review fields and stricter parsing rules.
crates/worker/src/lib.rs	Adds v2 result-contract validation and updates worker plumbing for the new result shape.
crates/worker/src/brief.rs	Tightens session-brief deserialization (deny unknown fields, enforce v2 contract_version) and adds optional hosted review context.
crates/github/src/tasks.rs	Updates test fixtures to include v2 review field.
crates/github/src/lib.rs	Bumps HEADLESS_CONTRACT_VERSION to 2 and adds ReviewResult / related types to the API model.
.gitignore	Ignores hosted adapter deployment-local secrets/policy/state paths.
.github/workflows/ci.yml	Extends CI to py_compile + run hosted adapter unit tests before Rust checks/tests.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[BunsDev]

Approved after independent local verification of head d03b5a2:

• Python adapter: py_compile OK + 3 unittest tests pass
• cargo check --all-targets: clean (all 4 crates)
• cargo clippy --all-targets -D warnings: clean
• cargo test --all: 29 unit + 9 contract tests, 0 failures

Contract-v2 tests validate wire-naming, contract-version enforcement, unknown-field rejection, and golden deserialization. No unresolved review threads; author signed off "Ready to merge". CI workflow + .gitignore diffs reviewed and clean.

Note: this PR renames the CI job to "python + cargo check + clippy + test"; updating branch-protection required-check context accordingly at merge.