Clarify review finding contract and harden webhook secret failures

[Copilot]

This addresses the remaining review-thread feedback on the hosted adapter and contract docs. The PR aligns the v2 contract prose with the enforced schema and makes webhook-signature handling deterministic when the deployment is misconfigured.

• Contract doc alignment

  • Clarifies that each review finding always includes line and recommendation keys.
  • Documents that those fields are required but nullable, matching the JSON schema and validator behavior.

• Webhook routing hardening

  • Catches the missing-GITHUB_WEBHOOK_SECRET configuration error inside route_signed_delivery().
  • Returns a structured 500 response instead of letting the handler raise unexpectedly.

• Regression coverage

  • Adds a focused adapter test for the missing-webhook-secret path so the handler contract stays stable.

• Workflow security follow-up

  • Adds explicit read-only workflow permissions for CI.

Example of the routing change:

try:
    signature_valid = verify_webhook_signature(
        webhook_secret or WEBHOOK_SECRET, raw_body, signature
    )
except RuntimeError as exc:
    return {"ok": False, "status": 500, "error": str(exc)}

if not signature_valid:
    return {"ok": False, "status": 401, "error": "invalid signature"}

[Copilot]

Pull request overview

Updates the headless execution contract to v2 (including structured review evidence) and hardens the hosted Python adapter’s webhook routing so misconfiguration yields deterministic structured errors, with regression tests and CI hardening.

Changes:

• Bumps the documented and enforced contract to v2, adding required review output structure and optional hosted-review inputs (review_context, audit_instruction).
• Adds a hosted Python adapter plus unit tests, including deterministic handling for missing GITHUB_WEBHOOK_SECRET.
• Tightens contract enforcement in the Rust worker/API and adds CI workflow permissions + Python checks.

Reviewed changes

Copilot reviewed 14 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/headless-contract.md	Updates contract prose/examples to v2, including structured review and hosted-review inputs.
docs/contracts/session-brief.schema.json	Bumps brief schema to v2 and adds optional hosted-review fields.
docs/contracts/session-brief.example.json	Updates example brief to contract_version: "2".
docs/contracts/result.schema.json	Bumps result schema to v2; makes contract_version and review required and formalizes constraints.
docs/contracts/result.example.json	Updates example result to v2 and includes a review object.
deploy/coven-github/test_coven_github_adapter.py	Adds regression tests for mention parsing, webhook secret failure behavior, and PR evidence staleness detection.
deploy/coven-github/README.md	Documents the hosted dogfood adapter, inputs, and current v2 behavior expectations.
deploy/coven-github/coven_github_adapter.py	Introduces hosted adapter implementation, including webhook routing and v2 contract validation.
crates/worker/tests/contract.rs	Extends contract tests for v2 session briefs/results and hosted-review optional fields.
crates/worker/src/lib.rs	Validates result contract after deserialization and expands test coverage for contract rejection cases.
crates/worker/src/brief.rs	Enforces strict v2 contract_version deserialization and denies unknown fields; adds hosted-review optional fields.
crates/github/src/tasks.rs	Updates tests to include review: ReviewResult::none() in results.
crates/github/src/lib.rs	Bumps HEADLESS_CONTRACT_VERSION to "2" and introduces typed ReviewResult model in SessionResult.
.gitignore	Ignores hosted adapter deployment artifacts (private key, policy, state dir).
.github/workflows/ci.yml	Adds read-only job permissions and runs hosted adapter Python compile/tests in CI.

---

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

[BunsDev]

Closing as superseded by #31 (merged as b21d10e).

#34 and #31 were parallel implementations of the same contract-v2 hosted-review work. #31 (romgenie) landed after ~15 review rounds + independent local verification (cargo check/clippy/test + Python unittest all green). Comparing this PR's adapter against the now-merged version on main, they differ by a single blank line — this is a complete duplicate.

Additionally this PR commits __pycache__/*.pyc binaries, which #31's .gitignore now correctly excludes. No unique value to salvage. Thanks for the parallel effort!