Document Contract-Driven Development for component interfaces

## Problem

We have guidance for repository layout, including [Using Spec Kit in a Monorepo](https://github.com/github/spec-kit/blob/main/docs/guides/monorepo.md), but need architectural guidance for the agreement between interacting components.

The starting point is not how many repositories exist. Whenever a component exposes an interface to a consumer outside its implementation boundary, define the externally observable obligations that consumer can rely on. This applies to a website calling an API, services exchanging events, applications using libraries, automation invoking a CLI, and components exchanging files—not only microservices or multi-repo products.

If no contract exists, defining it and agreeing on its ownership is part of the work. Repository coordination cannot substitute for that agreement.

## Proposed documentation

Add a **Contract-Driven Development** guide, analogous to the monorepo guide, explaining how this practice fits within Spec-Driven Development:

- Product requirements establish intended behavior.
- Interface contracts establish how independently implemented components collaborate to deliver it.
- Each component owns its implementation spec and plan against the agreed contract; do not copy another component's implementation plan.

Define a contract in terms of inputs, outputs, errors, observable behavior, and relevant interaction and compatibility guarantees. Its form should fit the interface; a schema can help but does not necessarily express all behavioral obligations.

### Ownership and sharing

One side owns the authoritative contract, usually the component exposing the interface. Consumers participate in agreeing on it and on changes; ownership does not permit unilateral incompatible changes.

Within one repository, both sides can reference the same definition. Across repositories, consumers pin a published contract version or synchronize a versioned copy, recording the authoritative source and exact revision. Consumer copies are not competing, independently edited definitions, and must not silently follow “latest”. Changes are proposed at the authoritative source and adopted deliberately by consumers.

### Verification and evolution

Explain provider and consumer verification against the agreed contract, including negative cases and behavior beyond schema shape. Consumer mocks alone do not establish provider conformance; include integration validation.

Cover compatibility, versioned adoption, rollout readiness, deprecation, and rollback. Distinguish publishing or merging a contract from deploying an implementation that supports it. A pinned contract identifies an agreement, not proof that a deployed provider implements it.

## Illustrative example and attribution

Use the control-plane (`r1`), data-plane (`r2`), and integration-tests (`r3`) scenario from [github/spec-kit#4465](https://github.com/github/spec-kit/discussions/4465) as one application of the general guidance—not its defining scope. Start by identifying the interaction, defining the contract if absent, and naming its authoritative owner. The test project consumes the agreed contract rather than defining a competing one.

Credit @TongyiDai for the [accepted answer](https://github.com/github/spec-kit/discussions/4465#discussioncomment-18363513) and the [requested practical merge-order follow-up](https://github.com/github/spec-kit/discussions/4465#discussioncomment-18443427). The follow-up contributes a useful contract-evolution example: additive compatible changes, provider-before-consumer deployment where appropriate, version-aware integration tests, immutable references, readiness tracking, and reverse-order rollback while preserving the old contract through migration.

That example complements this guide but begins with a contract change already defined. The broader guidance must first teach how to define and agree on the interaction contract. An umbrella spec or repository is one possible coordination arrangement in the discussion, not a requirement of this guide. Readiness can be tracked in an appropriate existing issue or roadmap.

Related: [github/spec-kit#4583](https://github.com/github/spec-kit/issues/4583) asks for multi-repo product support and guidance. This issue addresses the architecture-first contract guidance relevant to that request; it does not require or promise a new multi-repo CLI feature.

## Acceptance criteria

- [ ] Add documentation called **Contract-Driven Development**, applicable across architectures and repository layouts, defining “external consumer” relative to the component's implementation boundary.
- [ ] Explain how to identify interactions and define a missing contract, including inputs, outputs, errors, behavior, and compatibility expectations.
- [ ] Explain one authoritative owner, consumer participation, direct same-repo references, and pinned artifacts or synchronized versioned copies across repositories.
- [ ] Show how agreed contracts inform each component's existing SDD workflow without duplicating implementation plans or assuming agents can automatically access other repositories.
- [ ] Cover provider and consumer verification, integration validation, and deliberate compatible evolution, including rollout and rollback constraints.
- [ ] Include the illustrative control-plane/data-plane/integration-tests example, credit @TongyiDai, and distinguish initial contract definition from subsequent evolution.
- [ ] Link the guide from appropriate existing documentation and navigation, including the monorepo guide and SDD overview.
- [ ] Clearly distinguish documented conventions from automated enforcement.

## Out of scope

No mandatory umbrella repository, atomic multi-repo commits, cross-repository dependency resolver, release orchestrator, or new CLI commands. No changes to core commands or templates are required by this documentation issue. This is a proposal for guidance, not an announcement of an implemented capability or a delivery-date commitment.

## Agent assistance

Drafted and filed on behalf of @mnriem by GitHub Copilot (model: gpt-6-astra), at the user's explicit request in interactive mode. Agent assistance covered source review, a bounded duplicate search, issue drafting, and filing. The user supplied and approved the architectural direction and authorized filing; the issue text is agent-authored. No implementation, pull request, or discussion reply is part of this filing task.

Start with docs/guides/monorepo.md and the existing SDD overview to understand the documentation structure and navigation. Add a general Contract-Driven Development guide covering contract definition, ownership, verification, evolution, and the control-plane/data-plane/integration-tests example, then link it from the relevant documentation. Done means all acceptance criteria are addressed without adding commands or automated enforcement.

Scritto dal modello di indicizzazione a partire dal testo della issue.