[pikann]

Summary

Adds the Git Provider SPI (gitprovider.v1) to the Go plugin SDK: the contract a Paca plugin implements to adapt one source-control platform (GitHub, GitLab, Gitea, …) to Paca's platform-neutral Git integration. Core owns everything that is not platform-specific (webhook endpoint and inbox, trigger routing, actor policy, agent runs, audit, MCP tools, UI); a provider only answers the platform-specific questions.

Design: docs/ai-agent/git-agent-workflow.md in the Paca repo (§5 SPI, §4 vocabulary and events).

What's included

Contract (gitprovider/)

• provider.go — the required Provider interface (identity setup, repositories, webhooks, credentials, reads, writes) and the optional interfaces gated by Capabilities: thread resolution, file read, code search, labels, reviewer requests, assignees, merge, check re-run, reactions, webhook management, identity deletion, access grants (granting an identity access to one more account/organization).
• types.go — neutral vocabulary: repositories, change requests, threads, comments, checks, normalized events (with addressed[] decided by the provider), permissions, capabilities, setup steps.
• errors.go — the closed error-code set (not_found, forbidden, conflict, rate_limited, validation, unsupported, transient, …) so core can retry and back off uniformly.
• doc.go — how to write a provider.

Wire contract

• wire.go — the operation table (22 required, 14 optional) and the wrappers that decode a request, call the interface and encode an Envelope. Optional operations are only served when their capability is declared.
• wiretypes.go — every request, response and event type, for contract testing.
• serve/ — serve.Register(ctx, provider) mounts the operations as internal-only POST /_git/<op> routes, so authors never write routes.
• testdata/wire-shapes.golden.json + wireshape_test.go — golden JSON shapes. Core keeps a synced copy of the types (scripts/sync-git-spi.sh in the Paca repo), and this test catches any drift.

Reference provider and conformance

• fakeprovider/ — an in-memory reference provider (and test harness), used as documentation by example and as core's integration-test double.
• conformance/ — a suite any provider runs against recorded webhook fixtures and a fake backend. It checks, among other things: signature verification, error classification, no secrets in errors or events, honest capabilities in both directions (a declared capability must be implemented and vice versa), ephemeral credentials carry an expiry, truncation is reported, event ids are deterministic, merge honours the expected head SHA, and access-grant states are single-use and bound to the user.
• fakeprovider/mutants_test.go + scripts/check-mutants.sh — 11 deliberately broken providers; the suite must fail every one. The script exits non-zero if any survives, so a weakened check is noticed.

Testing

go test ./gitprovider/...
sh scripts/check-mutants.sh   # every mutant must print "caught"

Both pass locally (all 11 mutants caught).

Notes for review

• Wire shapes are a compatibility surface: changing a type means regenerating the golden file on purpose.
• No credentials ever appear in events, errors or logs by contract, and the conformance suite enforces it.
• First consumer: the GitHub provider plugin (com.paca.github) in the Paca repo, which passes this conformance suite against a fake GitHub.