Task: Generate INTERFACES.md — Machine-Interface Contract

Task: Generate INTERFACES.md — Machine-Interface Contract

Objective

Produce an INTERFACES.md that serves as the single source of truth for how independently-developed components communicate across machine boundaries: HTTP endpoints, events, and the wire-level conventions that govern both. The document merges what older guidance often split across separate wire-format, API-style, event-registry, and evolution-policy documents, because those four are always read together by the same downstream agents. For every boundary it pins the field-casing, timestamp, ID, enum, null-versus-missing, pagination, filtering, and error-response conventions; names the authentication scheme and idempotency semantics; declares the versioning strategy; catalogues every endpoint under a stable EP-name with exact request/response shapes and the error codes it may emit (cited to ERRORS.md, never inlined); catalogues every event under a stable EVT-name with producer, consumers, delivery guarantee, and payload schema; and commits an evolution policy with compatibility promises and deprecation windows.

INTERFACES.md is the document that decides when code, tests, and other artifacts disagree about the wire. Downstream readers include every IA (for the endpoints and events they realise), /data, /behavior, /security, /quality, /operations, every boundary-touching per-unit /SPEC.md, every /code-review, and /system-verification. The defining discipline — and the commonest failure — is every endpoint and event entry is self-sufficient: an agent implementing either side of the boundary can produce compatible serialisation/deserialisation code from a single entry, without opening another file.

Inputs

1. DOMAIN.md (required) — for entity and event names, bounded-context owners, and invariants that inform shapes. Every event name in § 7 must match a EVT-name from DOMAIN § 7; every endpoint's vocabulary must use glossary canonical forms.
2. ARCHITECTURE.md (required) — for components, boundaries, and cross-component flows. Boundaries enumerated in § 1 trace to architecture boundaries; transformation points named in § 6 per-endpoint entries trace to architecture data-flow sections.
3. Surface IAs that call the system (auto-discovered — one per surface that exists) — WEB_IA.md, CLI_IA.md, MOBILE_IA.md, TUI_IA.md, VOICE_IA.md. Each IA enumerates the EP-name it invokes; every such citation must match an endpoint entry in § 6.
4. Existing type definitions in the codebase (optional, auto-discovered) — TypeScript interfaces, Rust structs, Protobuf messages, OpenAPI specs. When refining, these are evidence of already-implemented shapes. Conflicts between sources are never resolved silently — they become open questions.
5. Existing INTERFACES.md (auto-discovered — only if refining) — read fully; every assigned EP-name and EVT-name is permanent. New endpoints and events take new unused IDs. Retired IDs remain with (retired) markers.
6. Known contract issues (optional) — bug reports pinning specific mismatch fixes. Every pinned fix must land in the relevant entry or be surfaced as an open question if the correct shape is ambiguous.

Read set size: 2 required + up to 5 surface IAs + optional existing sources. Read all required inputs and all IAs in scope end-to-end. Truncated reads cause silent contract drift.

Workflow

Interface-contract construction proceeds in seven phases: boundary identification, global convention extraction, auth/idempotency/versioning policy, endpoint catalogue, event catalogue, evolution policy, validation. Phases are sequential; revisit earlier phases if a later phase reveals an inconsistency.

Phase 1: Boundary Identification

Enumerate every machine boundary in the system. A boundary exists wherever:

• Two components developed by different teams or agents communicate over a network protocol (HTTP, WebSocket, message bus).
• A client and server are implemented in different languages or repositories.
• An intermediary component receives one shape and forwards another.

For each boundary capture: descriptive name (Server API ↔ Client, Server ↔ Git Engine, Worker ↔ Message Bus), components on each side (from ARCHITECTURE.md), native casing on each side (the language-native convention — snake_case for Rust, camelCase for TypeScript), and coverage status (new | partially documented in ARCHITECTURE.md | fully documented elsewhere; if fully documented, the row cites the location and the boundary does not repeat the documentation).

Boundaries already fully documented elsewhere appear in § 1's table with a pointer — never re-documented below. The document fills gaps.

Phase 2: Global Wire Conventions