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

6.2 KiB Raw Blame History