[documentation] v2 design: on-chain GitHub merge proof (PRD NG2, deferred)

[yinkscss]

Context

PRD non-goal NG2 defers on-chain GitHub light client / ZK proof of merge. v1 uses authorized gateway attestation (oracle model).

Problem

Contributors ask whether WaveFlow trusts GitHub. We need a published v2 design doc explaining tradeoffs and why v1 uses gateway attestation.

Proposed scope

• Add docs/future/on-chain-github-proof.md design outline
• Compare oracle vs light client cost, latency, and Soroban feasibility
• Explicitly mark out of v1 scope; link PRD NG2

Acceptance criteria

• Document states v1 scope exclusion clearly
• Summarizes security model of current gateway
• Lists open research questions for v2
• Linked from PRD appendix or README future work section

References

• docs/PRD.md NG2, OQ3
• crates/gateway/src/webhook.rs
• contracts/waveflow-escrow/src/contract.rs (record_merge gateway auth)