# 0. 문서 상태
이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.

- 상태: confirmed
- 문서 ID: dcy-007_20260630_mcp-response-contract-ci-contract-versioning
- 이슈명: MCP response contract / CI contract versioning 정립
- 작성 시각(KST): 2026-06-30 18:19 KST
- 마지막 갱신 시각(KST): 2026-06-30 18:35 KST
- 대체됨: 없음
- 후속 Discovery 참조: 없음
- 생성된 REQ 참조: REQ-007 (`docs/srs/Interface/req-007_mcp-response-contract-versioning-governance.md`), REQ-008 (`docs/srs/Testing/req-008_ci-contract-regression-and-lint-required-checks.md`)

# 1. 계획 상태 요약
현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.

- 연계 문서 현황:
	- 선행 Discovery: `docs/discovery/dcy-006_20260630_pytest-apptest-smoke-ci-automation.md` (CI 검증 자산 자동 실행·게이트화. 본 Discovery는 그 위에 "계약/버저닝 계층"을 올린다.)
	- baseline 문서: `docs/interface-contract.md`(MCP response contract 정의처), `docs/project-structure.md`, `docs/runtime-flows.md`(CI 게이트/branch protection 경계 기록처)
- 해석:
	- dcy-006/REQ-006/BAT-006으로 `.github/workflows/ci.yml`와 synthetic fixture·smoke wrapper가 도입되어 "검증을 자동 실행·게이트화"하는 문제는 해소됐다. 그러나 `docs/interface-contract.md`는 여전히 "Formal versioning for MCP response contracts is not yet defined."와 "CI contract for tests/lint is not yet present."를 미해결 갭으로 남겨 둔다. 즉, 실행은 있으나 **계약과 버전 규율**이 비어 있다.
	- 본 Discovery는 (a) MCP 응답 shape의 formal versioning과 회귀 방지 규율, (b) lint를 포함한 CI required-check 계약과 branch protection 경계 명문화라는 두 contract 갭을 한 주기로 정립하는 것을 목표로 한다.

# 2. 요구사항 판정 결과
이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.

- 판정: 신규
- 근거
	- dcy-006은 "이미 있는 검증 자산을 CI로 자동 실행·게이트화"하는 실행 계층을 다뤘고, 응답 shape의 **버전 식별·회귀 잠금**이나 **lint 게이트 계약**을 독립 성공 기준으로 다루지 않았다(dcy-006 Out of Scope에 lint/커버리지 고도화 게이트가 후속으로 분리됨). 따라서 본 주제는 dcy-006의 미세 조정이 아니라 별도 contract governance unit이다.
	- `docs/interface-contract.md`(Status: draft)가 "Formal versioning for MCP response contracts is not yet defined."(L110)와 "CI contract for tests/lint is not yet present."(L112)를 명시적 미해결 갭으로 기록하고, branch protection required-check는 baseline 문서에서 "repository setting outside this codebase"로만 언급되어 형식 계약이 없다. 기존 후보 주기(dcy-004 browser evidence, dcy-005 dashboard ops hub)와도 문제 정의가 겹치지 않는다.

# 3. 문제점의 요약
문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.

- 현재 상태
	- MCP 응답 contract에 formal versioning이 없다: `docs/interface-contract.md`는 "Preserve existing success response shapes unless a migration/REQ explicitly approves a breaking change."(L51)라는 호환성 규칙만 두고, 응답 contract에 버전 식별자·변경 등급(additive/breaking) 분류·버전 changelog 규율이 없다. 동일 문서가 "Formal versioning for MCP response contracts is not yet defined."(L110)로 갭을 자인한다. 결과적으로 호환성 위반을 자동으로 잡는 기준선이 없다.
	- 응답 shape 회귀를 막는 게이트가 없다: 응답은 `server.py` 시그니처에서 Python dict로 반환되지만(L39-42), 성공 응답 shape를 고정·검증하는 contract/snapshot 회귀 테스트가 없어, 의도치 않은 키 삭제·타입 변경·구조 변경이 조용히 머지될 수 있다. 추가 필드는 additive 권장이지만 이를 강제하는 자동 검사가 없다.
	- CI 계약 중 tests는 도입됐으나 lint는 비어 있다: dcy-006으로 `.github/workflows/ci.yml`의 필수 게이트 job(`pytest-regression`, `dashboard-app-test`, `dashboard-http-smoke`, `db-safety-smoke`)이 생겼지만, `pyproject.toml`의 dev extra는 `pytest>=8.0.0`뿐이며 ruff/flake8/black/mypy 등 lint·정적분석 도구나 그 CI job이 없다. `docs/interface-contract.md` L112의 "tests/lint" 중 **lint** 부분이 여전히 미해결이다.
	- branch protection/required-check 경계가 형식 계약이 아니다: `docs/project-structure.md` L139는 "branch protection required-check enforcement is a repository setting outside this codebase.", `docs/runtime-flows.md` L61은 "Stable job names are intended for branch protection configuration outside the repository."로 기록한다. 즉 어떤 job이 required check인지, 누가 어떻게 그 설정을 유지하는지가 코드 밖 설정에 흩어져 있고 문서화된 계약으로 고정돼 있지 않다.
	- synthetic-only 경계는 흐름 문서에 있으나 contract 차원으로 승격되지 않았다: `docs/runtime-flows.md` L119는 "CI gates must use synthetic/temp DBs only. The default operating DB path ... is forbidden ..."로 기록하고 `scripts/ci_fixture_db.py`가 기본 운영 DB 경로를 거부한다. 그러나 이 synthetic-only 경계가 CI contract의 명시 불변식(invariant)으로 버전 규율과 함께 묶여 있지는 않다.
- 기대 상태
	- MCP 성공 응답 contract에 버전 식별자와 변경 등급(additive vs breaking) 규율, 버전 changelog가 정의되어, 호환성 위반이 리뷰·게이트에서 객관적으로 판별된다.
	- 대표 MCP 응답 shape에 대한 contract/snapshot 회귀 테스트가 존재해, 키 삭제·타입 변경 같은 비호환 변경이 CI에서 자동 차단된다.
	- CI required-check 계약이 문서로 고정되어, tests 게이트(dcy-006)에 더해 lint 게이트가 정의되고, 어떤 job이 required check이며 무엇이 blocker/best-effort인지 단일 출처에서 확인된다.
	- branch protection/required-check 경계와 synthetic-only CI 경계가 `docs/project-structure.md`·`docs/runtime-flows.md`·`docs/interface-contract.md`에 형식 계약으로 명문화되어 후속 REQ/Batch가 참조 가능하다.
- 이해관계자
	- 렛저장인(운영자 겸 작성자) — MCP 응답 contract와 CI required-check 계약을 정의·유지하고 branch protection 설정을 운영하는 주체
	- MCP 클라이언트/Hermes Agent — 안정적인 응답 shape에 의존하는 소비자. 호환성 회귀의 직접 피해자.
	- 검수관/리뷰어 — contract 버전·회귀 게이트·required-check 결과를 호환성·QC 판정 근거로 사용하는 주체
	- StagePilot 후속 SDLC(REQ/Batch) 수행자 — 본 Discovery를 contract/CI 버저닝 요구사항으로 정제
- 제약사항
	- 개인 금융정보를 다루므로 contract 예시·snapshot·CI 로그에 실계좌번호·잔액·`raw_payload`·원본 파일명·비밀번호가 포함되어서는 안 된다. 모든 contract 회귀 검증은 synthetic fixture를 사용한다.
	- 응답 contract 변경은 기존 호환성 규칙(L51, additive 우선·breaking은 REQ 승인 필요)을 깨지 않아야 하며, 버저닝 도입 자체가 기존 성공 shape를 변경해서는 안 된다(버전 메타는 additive로 도입).
	- branch protection은 코드 밖 repository setting이므로 본 주기 산출물은 "어떤 job이 required인지"의 계약 명문화와 설정 절차 문서화까지로 하고, 실제 GitHub 설정 토글은 운영자 승인·실행 사항으로 남긴다.

## 주요 사용자 시나리오
사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.

- 작성자가 MCP 도구 응답에서 키 이름을 바꾸거나 필드를 제거하면, contract 회귀 테스트가 CI에서 비호환 변경을 감지해 머지를 차단하고, 의도된 변경이라면 버전 등급 상향과 changelog 갱신을 요구한다.
- MCP 클라이언트(Hermes Agent)가 특정 응답 shape에 의존해 자동화를 구성할 때, contract 버전과 changelog를 통해 어떤 변경이 호환 가능한 additive인지, 어떤 변경이 breaking인지 예측 가능하게 판단한다.
- 작성자가 PR을 올리면 CI가 lint 게이트를 실행해 스타일·정적 오류를 조기에 잡고, required-check 목록에 포함된 job 통과 없이는 `main` 머지가 차단된다.
- 검수관이 호환성/QC 판정을 작성할 때, contract 버전·회귀 게이트 통과 로그와 required-check 결과를 1차 근거로 인용하고, 환경 의존 검증(browser evidence)은 dcy-004 로컬 절차로 보강한다.

# 4. 이번에 정의할 변경
이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.

- MCP 응답 contract의 formal versioning 규율을 정의한다: 버전 식별자, additive/breaking 변경 등급 분류, 버전 changelog 위치와 갱신 규칙을 `docs/interface-contract.md` 기준으로 정립한다.
- 대표 MCP 성공 응답 shape에 대한 contract/snapshot 회귀 테스트를 도입하고, 이를 CI 필수 게이트로 연결해 비호환 응답 변경을 자동 차단한다.
- CI contract에 lint/정적분석 게이트를 추가하고(`docs/interface-contract.md` L112의 lint 갭 해소), tests 게이트(dcy-006)와 함께 required-check 계약을 단일 출처에 문서화한다.
- branch protection/required-check 경계와 synthetic-only CI 경계를 형식 계약으로 baseline 문서에 반영한다: `docs/project-structure.md`(L139)와 `docs/runtime-flows.md`(L61, L119)의 느슨한 서술을 "required-check 계약 + synthetic-only 불변식"으로 승격하고, `docs/interface-contract.md`의 Current Gaps(L110-L112)를 갱신한다.

## 영향 범위
변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.

- 코드 영향:
	- `tests/` — MCP 대표 응답 shape contract/snapshot 회귀 테스트 신설(synthetic fixture 기반). 기존 테스트 자산은 보존.
	- `.github/workflows/ci.yml` — lint job 추가 및 contract 회귀 테스트의 필수 게이트 편입. 기존 job 이름(`pytest-regression` 등)은 branch protection 안정성을 위해 보존.
	- `pyproject.toml` — lint/정적분석 도구(예: ruff)와 그 설정 추가 가능성. dev extra 구성 확장(현재 `dev=["pytest>=8.0.0"]`).
	- `jarca_ledger_mcp/server.py` 등 — 응답 contract 버전 메타를 additive로 노출할지 여부 검토(노출 시 기존 성공 shape는 보존). 본 주기에서는 contract 정의·회귀 게이트가 우선이며 런타임 버전 필드 노출은 범위 경계에서 결정.
- 문서 영향:
	- `docs/interface-contract.md` — Compatibility Rules에 버전 식별자·변경 등급·changelog 규율 추가, Current Gaps(L110-L112) 갱신.
	- `docs/project-structure.md` — branch protection required-check 계약 항목 명문화(L139 승격).
	- `docs/runtime-flows.md` — CI validation gates 흐름에 lint job·contract 회귀 게이트 추가, required-check/synthetic-only 불변식 명시(L61, L119 승격).
	- `docs/runbooks/` — branch protection required-check 설정/회복 runbook 후보, contract breaking 변경 처리 runbook 후보.
- 운영 영향:
	- 응답 호환성 회귀가 CI에서 조기 차단되어 MCP 클라이언트 신뢰도가 올라간다.
	- required-check 목록이 문서로 고정되어 branch protection 설정/감사가 재현 가능해진다.
	- lint 게이트로 스타일·정적 오류가 리뷰 이전에 걸러진다.

# 5. 요구사항 목록
실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.

## 기능 요구사항
- FR-1: MCP 응답 contract에 formal versioning 규율을 정의해야 한다 — 버전 식별자, additive/breaking 변경 등급 분류 기준, 버전 changelog 위치·갱신 규칙을 `docs/interface-contract.md`에 명문화한다.
- FR-2: 대표 MCP 성공 응답 shape(예: health/status, list/계좌, report 계열)에 대한 contract/snapshot 회귀 테스트를 synthetic fixture 기반으로 제공하고, 키 삭제·타입 변경 등 비호환 변경 시 실패하도록 한다.
- FR-3: 위 contract 회귀 테스트를 `.github/workflows/ci.yml`의 필수 게이트로 편입하여 push/PR에서 자동 실행·차단되도록 한다.
- FR-4: CI contract에 lint/정적분석 게이트를 추가해야 한다 — lint 도구·대상 경로·실패 시 차단 여부를 정의하고 `pyproject.toml`과 CI workflow에 반영한다(`docs/interface-contract.md` L112 lint 갭 해소).
- FR-5: CI required-check 계약과 branch protection 경계, synthetic-only CI 불변식을 `docs/project-structure.md`와 `docs/runtime-flows.md`에 반영하고("repository setting outside this codebase" 서술을 형식 계약으로 승격), `docs/interface-contract.md`의 Current Gaps(L110-L112)를 갱신해야 한다.

## 비기능 요구사항
성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.

- NFR-1: 버저닝 도입은 후방 호환이어야 한다 — 버전 메타/contract 정의를 추가하더라도 기존 MCP 성공 응답 shape를 변경하지 않는다(additive 원칙, `docs/interface-contract.md` L51 준수).
- NFR-2: contract 회귀 테스트와 lint 게이트는 결정적이어야 한다 — synthetic fixture·고정 입력으로 동일 커밋에 동일 결과를 산출하고 flaky 실패를 최소화한다.
- NFR-3: contract 예시·snapshot·CI 로그에 실계좌번호·잔액·`raw_payload`·원본 파일명·비밀번호 등 민감정보가 평문 노출되어서는 안 되며, 모든 contract 검증은 synthetic fixture만 사용한다(`docs/runtime-flows.md` L119 불변식 준수).
- NFR-4: required-check 계약은 기존 안정 job 이름(`pytest-regression`, `dashboard-app-test`, `dashboard-http-smoke`, `db-safety-smoke`)을 보존해 branch protection 설정을 깨지 않으면서 확장 가능해야 한다.

## 범위 경계
이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.

- In Scope
	- MCP 응답 contract의 formal versioning 규율 정의(버전 식별자·변경 등급·changelog)
	- 대표 응답 shape contract/snapshot 회귀 테스트 도입 및 CI 필수 게이트 편입
	- lint/정적분석 CI 게이트 추가와 required-check 계약 문서화
	- branch protection/required-check 경계와 synthetic-only 불변식의 baseline 문서 명문화 및 interface-contract Current Gaps 갱신
- Out of Scope
	- 모든 MCP 도구에 대한 100% 응답 shape snapshot 커버리지(대표 그룹 우선, 전수 커버리지는 후속). 누락 범위는 문서에 명시.
	- 응답 contract의 breaking 변경 실제 수행(본 주기는 버저닝·회귀 게이트 정립까지이며 호환성 마이그레이션은 별도 REQ).
	- 배포/릴리스 자동화(CD), 외부 호스팅 도입(dcy-006 Out of Scope 유지).
	- 실제 GitHub branch protection 토글 적용(코드 밖 repository setting). 본 주기는 required-check 계약 명문화와 설정 절차 문서화까지로 한정.
	- 커버리지 목표치 강제·성능 벤치마크 게이트 같은 고도화 품질 게이트(후속 반복).

# 6. 리스크/가정 목록
불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.

## 리스크
- R-1 (Medium): contract/snapshot 회귀 테스트가 지나치게 엄격하면 정상적인 additive 변경(필드 추가)까지 실패시켜 개발 마찰이 커진다.
	- 완화 방안: 회귀 기준을 "키 삭제·타입 변경·구조 변경은 실패, additive 필드 추가는 허용"으로 등급화하고, snapshot 갱신 절차와 변경 등급 판정 가이드를 함께 문서화한다.
- R-2 (Medium): lint 도구를 required 게이트로 한 번에 강제하면 기존 코드베이스에서 대량 위반이 발생해 도입이 막힐 수 있다.
	- 완화 방안: lint 도입 시 초기 룰셋을 보수적으로 잡거나 단계적 적용(우선 best-effort → 안정화 후 required)을 선택지로 두고, 사용자 결정으로 차단 여부를 확정한다.
- R-3 (Low): branch protection이 코드 밖 설정이라, 문서화한 required-check 계약과 실제 GitHub 설정이 시간이 지나며 어긋날 수 있다(drift).
	- 완화 방안: required-check 계약을 단일 출처(baseline 문서)에 고정하고, 설정/감사 절차를 runbook 후보로 남겨 drift를 점검 가능하게 한다.

## 가정
아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.

- A-1: dcy-006/REQ-006/BAT-006의 CI workflow(`.github/workflows/ci.yml`)와 synthetic fixture builder(`scripts/ci_fixture_db.py`)가 운영 가능한 상태이며, 본 주기는 그 위에 contract 회귀·lint job을 확장한다.
- A-2: 대표 MCP 응답 그룹(health/status, list, report 계열)의 성공 shape는 synthetic fixture만으로 결정적으로 재현 가능하다.
- A-3: 응답 contract 버저닝은 메타데이터 additive 또는 문서·테스트 차원에서 도입 가능하며, 기존 성공 shape를 깨지 않고 적용할 수 있다.
- A-4: branch protection required-check 설정은 운영자가 GitHub repository setting에서 적용 가능하고, 본 주기 산출물(required-check 계약 문서)을 그 설정 근거로 사용할 수 있다.

## 오픈 질문
답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.

- OQ-1: MCP 응답 contract 버전 식별 체계를 무엇으로 확정할 것인가(semver 형식 contract 버전 vs 날짜 기반 vs 단조 증가 정수)와, 버전 메타를 런타임 응답에 additive로 노출할지 문서·테스트 차원에만 둘지?
	- 상태: Answered
	- 결정: contract 버전 체계는 SemVer 스타일 `major.minor`로 시작하며 초기값은 `1.0`이다. breaking change는 `major`, additive/backward-compatible change는 `minor`를 올린다. 초기 단계에서는 버전 메타를 런타임 응답에 노출하지 않고, `docs/interface-contract.md`와 contract regression test/snapshot metadata에서 우선 관리한다.
	- 종료 근거: 사용자 승인으로 버전 체계와 노출 범위가 확정되었으며, 이는 FR-1/NFR-1과 REQ acceptance 기준의 기본안으로 사용한다.
- OQ-2: lint/정적분석 게이트를 어떤 도구로, 처음부터 required 차단 게이트로 둘지 아니면 단계적(best-effort 후 required)으로 둘지?
	- 상태: Answered
	- 결정: lint 도구는 `ruff`를 사용하고, 처음부터 required 차단 게이트로 둔다. 단, 초기 룰셋은 기존 코드베이스를 과도하게 흔들지 않도록 보수적으로 시작한다.
	- 종료 근거: 사용자 승인으로 lint 도구와 차단 강도가 확정되었으며, 이는 FR-4와 required-check 계약 정의의 기본안으로 사용한다.

# 7. 초기 성공 기준
이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.

- S-1: MCP 대표 응답 shape의 키를 삭제하거나 타입을 바꾸는 의도적 비호환 변경을 주입하면 contract 회귀 테스트가 CI에서 실패해 머지를 차단함을 재현 가능하게 확인한다.
- S-2: lint 게이트가 CI에서 실행되어 의도적 lint 위반에 대해 정의된 차단 강도대로 동작하고(required면 차단, best-effort면 경고), 로그·아티팩트에 민감정보가 노출되지 않음을 확인한다.
- S-3: MCP 응답 contract 버저닝 규율과 required-check/synthetic-only 계약이 `docs/interface-contract.md`(Current Gaps L110-L112 갱신), `docs/project-structure.md`(L139 승격), `docs/runtime-flows.md`(L61/L119 승격)에 반영되어 후속 REQ/Batch에서 참조 가능하다.

## 측정 방식 및 데이터 출처
각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.

- S-1 측정 방식: 비호환 변경 주입 시 contract 회귀 테스트 fail 재현 확인 / 데이터 출처: CI workflow 실행 로그, contract/snapshot 테스트 결과, synthetic fixture DB
- S-2 측정 방식: lint job 실행 로그와 의도적 위반에 대한 차단/경고 동작 확인, 로그·아티팩트 민감정보 미노출 검수 / 데이터 출처: CI job 로그·아티팩트, `pyproject.toml` lint 설정
- S-3 측정 방식: baseline·interface-contract 문서 갱신 여부 리뷰(갭 항목 해소·계약 승격 확인) / 데이터 출처: `docs/interface-contract.md`, `docs/project-structure.md`, `docs/runtime-flows.md`, `docs/runbooks/`

# 8. REQ로 넘기기 전 확인 체크
REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.

- [x] 범위(In Scope/Out of Scope) 확정
	- 기준: 본 주기를 contract 버저닝 정립 + 대표 shape 회귀 게이트 + lint 게이트 + 계약 문서화까지로 한정하고, breaking 마이그레이션·전수 snapshot·실제 branch protection 토글은 제외한다는 점을 사용자가 승인했다.
- [x] 성공 지표의 측정 방식/데이터 출처 확정
	- 기준: CI 실행 로그·contract 회귀 테스트·lint 로그·baseline 문서 갱신을 acceptance 측정 근거로 사용한다는 점을 승인했다.
- [x] High 영향 리스크 우선순위 및 해소 방향 확정
	- 기준: 본 Discovery에 현재 High 리스크는 없으며, 회귀 게이트 과엄격(R-1)은 additive 허용 규칙과 snapshot 갱신 절차로, lint 도입 마찰(R-2)은 보수적 `ruff` 룰셋으로 완화한다는 방향을 확정했다.
- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
	- 기준: OQ-1(버전 체계·노출 범위)과 OQ-2(lint 도구·차단 강도)를 모두 Answered로 정리했다.
- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
	- 기준: 사용자(진환 고)가 권장안을 승인하고 confirm 진행을 요청했다.

# 9. 파일 처리 결과
이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.

- 처리 결과: 생성
- 생성 경로: docs/discovery/dcy-007_20260630_mcp-response-contract-ci-contract-versioning.md
- 참조 문서:
	- docs/discovery/dcy-006_20260630_pytest-apptest-smoke-ci-automation.md
	- docs/interface-contract.md
	- docs/project-structure.md
	- docs/runtime-flows.md
	- stage-pilot/templates/project-structure.md
	- stage-pilot/templates/runtime-flows.md

# 10. 사용자 결정 필요 항목 요약
사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.

## 확정안
- Contract version scheme: SemVer 스타일 `major.minor`를 사용하고 초기값은 `1.0`으로 둔다. breaking change는 `major`, additive/backward-compatible change는 `minor`를 올린다.
- Runtime exposure: 초기 단계에서는 버전 메타를 런타임 응답에 노출하지 않고, `docs/interface-contract.md`와 contract regression test/snapshot metadata에서 우선 관리한다.
- Lint tool / gate strictness: `ruff`를 사용하고 처음부터 required 차단 게이트로 둔다. 단, 초기 룰셋은 보수적으로 시작한다.
- Required check list: `pytest-regression`, `dashboard-app-test`, `dashboard-http-smoke`, `db-safety-smoke`, `contract-regression`, `lint`를 required-check 계약 기본안으로 둔다. 실제 GitHub branch protection 토글 적용은 운영자 실행 범위다.
- Contract snapshot scope: 1차 범위는 `health/status`, `list`, `report`, `mutation success envelope` 대표 응답군으로 한정하고, 전수 커버리지는 후속 반복으로 미룬다.
- Synthetic contract fixture policy: 운영/목록/리포트/변경 결과를 모두 재현하는 synthetic 대표 fixture 세트를 사용하며, 운영 DB·실계좌번호·실잔액·`raw_payload`·원본 파일명·비밀번호는 포함하지 않는다.

## REQ 단계 입력으로 넘길 항목
- `contract-regression` 테스트 대상 응답군의 세부 tool 목록과 snapshot 파일 구조
- `ruff` 초기 룰셋의 세부 enable/ignore 목록
- representative synthetic fixture 응답 샘플 세트의 파일 경로와 생성 방식

# 11. Discovery Freeze
REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.

## 섹션 참조
- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)

## Freeze 플래그
- Handoff Decision: 승인
- Handoff Rationale: 사용자 승인으로 contract version scheme, lint gate, required-check 목록, snapshot 우선 범위, synthetic fixture 정책이 확정되었다. 남은 세부 항목은 REQ 단계 입력으로 정리 가능하며 Discovery 차원의 차단 사유가 아니다.
- Ready for REQ Drafting: true
- Confirmed By: 진환 고
- Confirmed At (KST): 2026-06-30 18:34 KST