gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
7fd1b45bd5ac24fb87e0ce1fac7ed76823157c20
jarca-ledger-mcp/docs/discovery/dcy-007_20260630_mcp-response-contract-ci-contract-versioning.md
T

25 KiB
Raw Blame History

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 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.

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

섹션 참조

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
View Git Blame Copy Permalink