feat: implement dcy-007 contract governance and ci gates

2026-06-30 20:06:39 +09:00
parent 26b815d723
commit 7fd1b45bd5
20 changed files with 1038 additions and 22 deletions
@@ -1,6 +1,6 @@
 # REQ-005 Dashboard operations hub/liquidity/monthly cashflow

- Status: Approved
+- Status: Implemented
 - Type: Interface
 - Priority: High
 - Owner: 렛저장인
@@ -8,6 +8,7 @@
 - Batch: BAT-005
 - Created At (KST): 2026-06-29
 - Approved At (KST): 2026-06-29 21:08 KST
+- Implemented At (KST): 2026-06-30 16:48 KST

 ## 1. 배경

@@ -90,4 +91,4 @@
 - `liquidity_bucket`의 권위 소스는 계좌 단위로 고정하며 거래/카테고리 override는 이번 범위에서 제외한다.
 - 운영 DB, 원본 금융 파일, 민감정보를 사용하지 않고 synthetic/validation DB에서 대시보드 evidence를 생성한다.
 - dcy-004 QC 결과에 따라 UI 영향 batch는 browser screenshot/snapshot evidence를 필수로 한다.
- 이 REQ는 구현 기준으로 승인되었으며, 후속 batch에서 구현·검증을 진행한다.
+- 이 REQ는 BAT-005 `release-candidate` 상태, `verification.md`의 AC mapping, `pytest -q` PASS, synthetic DB 기반 Streamlit screenshot/DOM evidence를 근거로 Implemented로 전환했다. 남은 blocker는 없다.
@@ -0,0 +1,93 @@
+# 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로 전환.
@@ -0,0 +1,105 @@
+# 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로 전환.
@@ -33,7 +33,7 @@

 ## Next Requirement ID

- Current: `REQ-007`
+- Current: `REQ-009`
 - Rule: `Requirement Register`에 있는 가장 큰 REQ 번호보다 정확히 1 커야 한다.

 ## Requirement Register
@@ -44,8 +44,10 @@
 | REQ-002 | 운영 안전 백업·복구·검증 DB 워크플로우 | Non-Functional | Implemented | High | 렛저장인 | [req-002_operational-safety-backup-restore-validation-db.md](Non-Functional/req-002_operational-safety-backup-restore-validation-db.md) |
 | REQ-003 | Statement-unavailable 계좌 수동 증빙 및 잔액대조 | Interface | Implemented | High | 렛저장인 | [req-003_statement-unavailable-manual-evidence-balance-reconciliation.md](Interface/req-003_statement-unavailable-manual-evidence-balance-reconciliation.md) |
 | REQ-004 | Browser/Streamlit E2E evidence 환경 복구 | Testing | Implemented | High | 렛저장인 | [req-004_browser-streamlit-e2e-evidence-recovery.md](Testing/req-004_browser-streamlit-e2e-evidence-recovery.md) |
-| REQ-005 | Dashboard operations hub/liquidity/monthly cashflow | Interface | Approved | High | 렛저장인 | [req-005_dashboard-operations-hub-liquidity-monthly-cashflow.md](Interface/req-005_dashboard-operations-hub-liquidity-monthly-cashflow.md) |
+| REQ-005 | Dashboard operations hub/liquidity/monthly cashflow | Interface | Implemented | High | 렛저장인 | [req-005_dashboard-operations-hub-liquidity-monthly-cashflow.md](Interface/req-005_dashboard-operations-hub-liquidity-monthly-cashflow.md) |
 | REQ-006 | pytest/AppTest/Smoke CI 자동화 | Testing | Implemented | High | 렛저장인 | [req-006_pytest-apptest-smoke-ci-automation.md](Testing/req-006_pytest-apptest-smoke-ci-automation.md) |
+| REQ-007 | MCP response contract versioning governance | Interface | Implemented | High | 렛저장인 | [req-007_mcp-response-contract-versioning-governance.md](Interface/req-007_mcp-response-contract-versioning-governance.md) |
+| REQ-008 | CI contract regression and lint required checks | Testing | Implemented | High | 렛저장인 | [req-008_ci-contract-regression-and-lint-required-checks.md](Testing/req-008_ci-contract-regression-and-lint-required-checks.md) |

 ## Recent Change Log Summary

@@ -57,6 +59,10 @@
 - 2026-06-29 KST: dcy-004 confirmed 범위로 REQ-004를 생성하고 BAT-004 browser evidence 구현·검증 대상으로 등록.
 - 2026-06-29 20:03 KST: dcy-005 confirmed 범위로 REQ-005를 Proposed 상태로 생성하고 dashboard operations hub/liquidity/monthly cashflow 요구사항으로 등록.
 - 2026-06-29 21:08 KST: REQ-005를 Approved로 전환하고 dcy-005 구현 입력으로 확정.
+- 2026-06-30 16:48 KST: BAT-005 구현·검증 evidence와 `pytest -q` PASS, synthetic Streamlit browser evidence를 근거로 REQ-005를 Implemented로 전환.
 - 2026-06-30 14:42 KST: dcy-006 confirmed 범위로 REQ-006을 Proposed 상태로 생성하고 GitHub Actions 기반 pytest/AppTest/HTTP smoke/DB safety smoke CI 요구사항으로 등록.
 - 2026-06-30 14:50 KST: REQ-006을 Approved로 전환하고 BAT-006 standard batch 입력으로 확정.
 - 2026-06-30 15:29 KST: BAT-006 구현과 jarcaledgerqc PASS_WITH_NOTES 검증을 근거로 REQ-006을 Implemented로 전환.
+- 2026-06-30 18:35 KST: dcy-007 confirmed 범위를 `REQ-007`(MCP response contract versioning governance)과 `REQ-008`(CI contract regression and lint required checks) Proposed 상태로 생성했다.
+- 2026-06-30 18:56 KST: `REQ-007`, `REQ-008`을 승인 게이트 재검토 후 Approved로 전환했다.
+- 2026-06-30 KST: BAT-007 구현과 contract regression/lint/smoke 검증 evidence를 근거로 `REQ-007`, `REQ-008`을 Implemented로 전환했다.