# REQ-007 MCP response contract versioning governance

- Status: Implemented
- Type: Interface
- Priority: High
- Owner: 렛저장인
- Source Discovery: `docs/discovery/dcy-007_20260630_mcp-response-contract-ci-contract-versioning.md`
- Batch: BAT-007
- Created At (KST): 2026-06-30 18:35 KST
- Approved At (KST): 2026-06-30 18:56 KST
- Implemented At (KST): 2026-06-30

## 1. 배경

현재 저장소는 MCP 도구의 성공 응답 shape에 대해 "기존 success response shape를 breaking change 없이 보존한다"는 호환성 원칙만 문서로 두고 있으나, formal versioning 규율과 변경 등급 체계가 없다. 그 결과 응답 키 삭제, 타입 변경, 중첩 구조 변경 같은 비호환 변경이 발생했을 때 이를 문서·리뷰·검증에서 어떤 버전 규칙으로 다뤄야 하는지 일관된 기준이 없다. dcy-007 confirmed Discovery에 따라 MCP response contract에 대한 버전 체계, 변경 등급 규칙, changelog/location 규율을 정의해 후속 회귀 게이트와 batch 검증의 기준선으로 고정한다.

## 2. Intent

MCP 성공 응답 contract에 대해 사람이 해석하는 호환성 원칙을 넘어서, 저장소 문서와 후속 QC/CI가 공통으로 참조할 수 있는 버전 governance 기준을 확정한다. 이 REQ의 목적은 모든 응답 payload를 즉시 바꾸는 것이 아니라, 어떤 변경이 additive인지 breaking인지, 어떤 문서가 source of truth인지, 버전 이력이 어디에서 관리되는지를 명확히 하여 후속 contract regression과 implementation batch가 흔들리지 않게 하는 것이다.

## 3. 범위

### In Scope
- MCP 성공 응답 contract의 버전 체계를 `major.minor` 형식으로 정의하고 초기값을 `1.0`으로 설정한다.
- additive/backward-compatible change와 breaking change의 판정 기준을 문서로 명시한다.
- contract 버전과 변경 이력을 어떤 문서/metadata에서 관리할지 규정한다.
- `docs/interface-contract.md`에 contract versioning governance와 compatibility rule을 반영한다.
- 런타임 응답에 버전 메타를 즉시 노출하지 않는 초기 운영 방침을 명시한다.

### Out of Scope
- 기존 MCP 성공 응답 shape를 실제로 breaking change 하는 작업.
- 런타임 응답 payload에 공통 `contract_version` 필드를 즉시 추가하는 작업.
- 모든 MCP 도구 응답을 한 번에 재설계하는 작업.
- CI workflow 구성, lint 게이트, branch protection 실제 설정 적용.

## 4. Requirement

### FR-1. Contract version scheme
- MCP 성공 응답 contract는 `major.minor` 체계를 사용해야 한다.
- 초기 contract version은 `1.0`이어야 한다.
- breaking change는 `major`를 증가시키고, additive/backward-compatible change는 `minor`를 증가시켜야 한다.

### FR-2. Change classification rule
- 다음 변경은 최소한 breaking change로 분류해야 한다.
  - 기존 key 삭제
  - 기존 key 타입 변경
  - 기존 중첩 구조/배열/객체 shape 변경으로 소비자 파싱이 깨지는 경우
- 다음 변경은 additive/backward-compatible change로 분류할 수 있어야 한다.
  - 기존 소비자를 깨지 않는 신규 optional field 추가
  - 기존 의미를 유지한 상태에서 설명/metadata를 문서에 보강하는 경우
- ambiguous case를 reviewer/QC가 판정할 수 있도록 예시를 남겨야 한다.

### FR-3. Governance source of truth
- contract version과 compatibility rule의 source of truth는 `docs/interface-contract.md`여야 한다.
- contract change log 또는 동등한 버전 이력 섹션이 존재해야 하며, 버전 증가 이유와 관련 REQ/BAT를 추적할 수 있어야 한다.
- REQ 또는 batch가 MCP 응답 shape에 영향을 주는 경우, 해당 문서가 contract version 영향 여부를 명시해야 한다.

### FR-4. Initial runtime exposure policy
- 초기 단계에서는 contract version 메타를 런타임 응답에 노출하지 않아야 한다.
- 대신 contract regression test/snapshot metadata와 `docs/interface-contract.md`를 통해 버전을 관리해야 한다.
- 런타임 노출이 필요해지면 별도 REQ 또는 승인된 migration으로 다뤄야 한다.

### FR-5. Baseline documentation alignment
- `docs/interface-contract.md`는 formal versioning 부재와 CI contract gap에 대한 Current Gaps 서술을 갱신해야 한다.
- 필요 시 `docs/project-structure.md`, `docs/runtime-flows.md`에 contract governance가 CI 회귀 게이트와 어떻게 연결되는지 참조 수준으로 반영해야 한다.

## 5. Acceptance Criteria

- AC-1: `docs/interface-contract.md`에 `major.minor` contract version 체계와 초기값 `1.0`이 명시된다.
- AC-2: breaking vs additive change 판정 기준이 최소 key 삭제, 타입 변경, 구조 변경, optional field 추가 예시와 함께 문서화된다.
- AC-3: contract change log 또는 동등한 버전 이력 규칙이 정의되고, 관련 REQ/BAT 추적 방식이 명시된다.
- AC-4: 초기 단계에서 contract version 메타를 런타임 응답에 노출하지 않는다는 운영 방침이 문서에 명시된다.
- AC-5: 응답 shape 영향 변경이 발생할 때 contract version 영향 여부를 검토해야 한다는 규칙이 문서에 반영된다.
- AC-6: 기존 성공 응답 shape를 즉시 변경하지 않는다는 backward-compatible 도입 원칙이 유지된다.

## 6. Impacted Area

- `docs/interface-contract.md`
- 필요 시 `docs/project-structure.md`
- 필요 시 `docs/runtime-flows.md`
- 후속 batch planning/QC에서 참조할 contract versioning 기준

## 7. Notes

- 이 REQ는 문서와 인터페이스 governance를 다루므로 `Interface` 타입으로 관리한다.
- contract version 자체는 CI 회귀 테스트 및 snapshot metadata와 연결되어야 하지만, 테스트/게이트 구체 구현은 `REQ-008`에서 다룬다.
- runtime payload version field는 이번 범위에서 제외하며, 후속 필요 시 별도 REQ로 분리한다.

## 8. Change Log

- 2026-06-30 18:35 KST: dcy-007 confirmed 범위를 바탕으로 Proposed 초안을 생성.
- 2026-06-30 18:56 KST: Discovery 결정사항과 승인 게이트를 재검토해 Approved로 전환.
- 2026-06-30 KST: BAT-007 implementation/verification evidence 기준으로 Implemented로 전환.