# REQ-008 CI contract regression and lint required checks

- Status: Implemented
- Type: Testing
- 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. 배경

REQ-006으로 GitHub Actions 기반 `pytest`/`AppTest`/HTTP smoke/DB safety smoke 게이트는 도입되었지만, MCP 성공 응답 shape 회귀를 자동 차단하는 contract regression gate와 lint required-check 계약은 아직 없다. 또한 branch protection required-check 목록과 synthetic-only CI 불변식이 코드 밖 운영 설정 또는 느슨한 baseline 문장에 머물러 있어, 어떤 게이트가 머지 차단 기준인지 단일 출처가 부족하다. dcy-007 confirmed Discovery에 따라 contract regression과 lint를 CI required-check 계약으로 편입하고, representative synthetic fixture 기반 회귀 검증 및 baseline 문서 정렬을 정의한다.

## 2. Intent

MCP 응답 shape 회귀와 lint 누락을 사람 리뷰에 의존하지 않고 CI required-check 계약으로 고정한다. 이 REQ의 목적은 representative contract regression과 `ruff` lint를 기존 안정 게이트 위에 추가하여, branch protection이 어떤 job 통과를 머지 조건으로 삼아야 하는지와 synthetic-only 검증 원칙을 단일 delivery 입력으로 만드는 것이다.

## 3. 범위

### In Scope
- representative MCP 성공 응답군에 대한 contract/snapshot 회귀 테스트를 도입한다.
- contract regression을 GitHub Actions required-check 후보 job으로 추가한다.
- `ruff` 기반 lint gate를 도입하고 required-check 기본안으로 고정한다.
- required-check 목록을 기존 4개 안정 job + `contract-regression` + `lint`로 문서화한다.
- synthetic-only CI 불변식과 branch protection/required-check 경계를 baseline 문서에 명시한다.

### Out of Scope
- 모든 MCP 도구 응답군 100% 전수 snapshot 커버리지.
- browser-screenshot evidence를 CI 필수 차단 게이트로 승격하는 작업.
- 실제 GitHub branch protection 토글 적용 자체.
- coverage percent gate, benchmark gate, flaky quarantine 같은 추가 품질 체계.

## 4. Requirement

### FR-1. Contract regression representative scope
- contract regression은 1차로 다음 대표 응답군을 다뤄야 한다.
  - `health/status`
  - `list`
  - `report`
  - `mutation success envelope`
- 각 그룹은 synthetic fixture 기반 고정 입력으로 결정적으로 재현 가능해야 한다.
- key 삭제, 타입 변경, 구조 변경 같은 비호환 변경이 발생하면 테스트가 실패해야 한다.
- additive field 추가는 정의된 정책에 따라 허용 가능해야 한다.

### FR-2. Synthetic-only contract fixture policy
- contract regression 테스트는 synthetic representative fixture만 사용해야 한다.
- fixture는 운영/목록/리포트/변경 결과를 모두 재현할 수 있어야 한다.
- fixture와 로그에는 운영 DB, 실계좌번호, 실잔액, `raw_payload`, 원본 파일명, 비밀번호가 포함되어서는 안 된다.

### FR-3. Lint gate
- 저장소는 `ruff`를 lint/정적분석 도구로 사용해야 한다.
- lint는 CI에서 required gate로 실행되어야 한다.
- 초기 룰셋은 보수적으로 시작하되, 명백한 스타일/정적 오류 회귀를 막을 수 있어야 한다.

### FR-4. Required-check contract
- CI required-check 기본안은 다음 6개 job이어야 한다.
  - `pytest-regression`
  - `dashboard-app-test`
  - `dashboard-http-smoke`
  - `db-safety-smoke`
  - `contract-regression`
  - `lint`
- 위 job 이름은 branch protection 안정성을 위해 의도 없이 변경되면 안 된다.
- 실제 GitHub branch protection 설정 적용은 운영자 실행 범위임을 문서에 명시해야 한다.

### FR-5. Baseline documentation alignment
- `docs/interface-contract.md`는 CI contract/tests-lint gap이 해소되는 방향으로 갱신되어야 한다.
- `docs/project-structure.md`는 required-check contract와 lint/contract-regression job 책임을 반영해야 한다.
- `docs/runtime-flows.md`는 PR/push → required-check → merge-blocking 흐름과 synthetic-only invariant를 반영해야 한다.
- 필요 시 runbook은 branch protection setting drift나 local reproduction 절차를 포함해야 한다.

## 5. Acceptance Criteria

- AC-1: representative MCP 응답군(`health/status`, `list`, `report`, `mutation success envelope`)에 대한 contract regression 테스트가 추가된다.
- AC-2: 비호환 응답 변경(key 삭제, 타입 변경, 구조 변경)을 주입했을 때 contract regression이 실패하는 검증 경로가 존재한다.
- AC-3: contract regression은 synthetic fixture만 사용하며 민감정보를 로그/fixture에 포함하지 않는다.
- AC-4: `ruff` 기반 lint gate가 CI에 추가되고 required gate로 동작한다.
- AC-5: CI required-check 기본안 6개 job이 문서에 명시되고, 기존 4개 안정 job 이름이 유지된다.
- AC-6: `docs/interface-contract.md`, `docs/project-structure.md`, `docs/runtime-flows.md`가 contract-regression/lint/required-check/synthetic-only 경계를 반영한다.
- AC-7: 실제 branch protection 토글 적용은 운영자 실행 범위임이 문서에 명시된다.

## 6. Impacted Area

- `.github/workflows/ci.yml`
- `tests/` 및 contract snapshot/fixture 자산
- `pyproject.toml`
- `docs/interface-contract.md`
- `docs/project-structure.md`
- `docs/runtime-flows.md`
- 필요 시 `docs/runbooks/`

## 7. Notes

- 이 REQ는 테스트/게이트/검증 계약을 다루므로 `Testing` 타입으로 관리한다.
- contract version scheme과 breaking/additive 분류 규칙 자체는 `REQ-007`에서 관리하고, 이 REQ는 그것을 회귀 게이트로 강제하는 경로를 다룬다.
- representative scope를 우선 도입하고, 전수 응답군 snapshot 확대는 후속 반복으로 남긴다.

## 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로 전환.