Integration contracts

docs/integrations/ — external system integration contracts

How outside systems (agent fleets, CI pipelines, audit harnesses) interact with the petrova control plane. Each file in this directory is a contract: the rules, the surface, the failure modes, the audit trail.

Current integrations

• kahn-fleet.md — KAHN-style agentic fleets calling petrova verbs to act on consumer repos.
  • Examples in examples/diagnose-then-fix.md, examples/failure-modes.md.

Adding a new integration

1. Open a decision doc in docs/decisions/ justifying the new integration’s surface.
2. Identify which existing verbs the integration uses; if a new verb is needed, that’s a separate proposal (extends spec/verbs/).
3. Document the contract here as <system>.md covering:
   • The boundary diagram.
   • Required handshake (registry entry, fleets_allowed, auth, AGENTS.xml capability).
   • End-to-end flow.
   • Failure modes and recovery per error code.
   • Identity / audit trail.
   • Explicit forbidden actions.
4. Add worked examples in examples/<system>-<scenario>.md.
5. Update the consumer’s AGENTS.xml to declare the capability.

Why these contracts matter

The petrova control plane’s authority comes from being narrow. Every external system that wants to write to a governed repo must pass through the verb surface. These contracts are how a new system gets admitted: by codifying its actor identity, its allowed verbs, its recovery procedures, and its audit cite-back.