feat: implement dcy-007 contract governance and ci gates

docs/interface-contract.md

@@ -2,10 +2,10 @@
 
 - Baseline Mode: observed
 - Baseline Seed: `.stage-pilot/bootstrap/baseline.yaml`
-- Status: draft
+- Status: governed
 - Owner: Jarca / project maintainer
-- Last Updated (KST): 2026-06-29
-- Source Discovery / Batch: bootstrap-baseline
+- Last Updated (KST): 2026-06-30
+- Source Discovery / Batch: bootstrap-baseline, dcy-007, BAT-007
 
 ## Project Summary
 - Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 현금흐름 분석을 SQLite에 저장하고 운영한다.
@@ -40,6 +40,7 @@
 - Python dictionary payloads containing success data, counts, records, previews, reports, or error details.
 - Backup/status tools return metadata-only DB evidence: path, size, mtime, sha256, integrity check, table row counts, and aggregate totals.
 - Existing success shape compatibility is preferred; new fields should be additive where possible.
+- Contract version metadata is not exposed in runtime success payloads for version `1.0`; version governance is tracked in this document and contract regression snapshot metadata.
 
 ### Errors
 - Validation errors for invalid parameters or missing IDs.
@@ -49,10 +50,36 @@
 
 ### Compatibility Rules
 - Preserve existing success response shapes unless a migration/REQ explicitly approves a breaking change.
+- MCP success response contract version uses `major.minor`; the initial governed contract version is `1.0`.
+- Increment `major` for breaking changes, including required key removal, existing key type change, or nested object/list structure changes that break existing consumers.
+- Increment `minor` for backward-compatible additive changes, including optional field additions or documentation/test metadata that preserves existing payload semantics.
+- Ambiguous response-shape changes must identify contract impact in the owning REQ/BAT and be reviewed against this document before implementation.
 - Additive backup/status/list/hash tools are allowed; restore execution must not be added as an MCP tool.
 - Do not write secrets, raw passwords, raw_payload, full merchant/counterparty dumps, or full account identifiers into persistent output, skill files, or committed documentation.
 - Source evidence should remain auditable through raw fields and import batch records.
 
+### MCP Response Contract Version Governance
+- Source of truth: this `docs/interface-contract.md` section defines the active contract version, change classification rules, and runtime exposure policy.
+- Snapshot metadata: representative contract regression fixtures live under `tests/contract_snapshots/` and must carry the same contract version as this document.
+- Runtime exposure policy: `contract_version` remains unexposed in MCP success responses for `1.0`; adding it to runtime payloads requires a future approved REQ/migration because it changes every success envelope, even if additive.
+- Required first-wave regression scopes: health/status, list, report, and mutation success envelope responses.
+- Additive policy: contract tests intentionally assert a required subset and required types so newly added optional fields do not fail the gate.
+- Breaking-change policy: removing a required key, changing a required key type, or changing a required nested shape must fail contract regression unless an approved REQ/BAT updates the contract version and snapshot metadata.
+- Every REQ/BAT that changes MCP success response shapes must state one of: `contract impact: none`, `contract impact: additive minor`, or `contract impact: breaking major`.
+
+### MCP Response Contract Version Log
+| Version | Date (KST) | Change Type | Source | Notes |
+| --- | --- | --- | --- | --- |
+| 1.0 | 2026-06-30 | Initial governed baseline | dcy-007 / REQ-007 / BAT-007 | Formalizes compatibility governance without exposing runtime version fields or changing success payload shapes. |
+
+## Interface: CI Required-Check Contract
+- Required-check source of truth in code: `.github/workflows/ci.yml` job names are stable and must be mirrored by repository branch protection settings.
+- Required-check default set for PR/push merge blocking: `pytest-regression`, `dashboard-app-test`, `dashboard-http-smoke`, `db-safety-smoke`, `contract-regression`, `lint`.
+- `contract-regression` runs `pytest tests/test_contract_regression.py` against synthetic temp fixtures and representative response snapshot metadata.
+- `lint` runs `ruff check .` with the conservative BAT-007 initial rule set (`E9`, `F`) as a required blocking gate.
+- Actual GitHub branch protection toggles are repository settings outside this codebase; this document and the workflow define the intended contract for the operator to apply and audit.
+- CI contract tests, AppTest, HTTP smoke, and DB safety smoke must use synthetic/temp DBs only and must not read the default operating DB path.
+
 ## Interface: Streamlit Dashboard
 - Type: web-app
 - Actors: Local operator
@@ -107,9 +134,9 @@
 - Financial data and passwords are sensitive runtime inputs and should not be committed.
 
 ## Current Gaps / Planned Changes
-- Formal versioning for MCP response contracts is not yet defined.
-- Browser-level UI evidence criteria are captured in REQ-004; broader CI automation is still not present.
-- CI contract for tests/lint is not yet present.
+- Formal MCP response contract versioning is defined for version `1.0`; full tool-surface snapshot coverage remains a future expansion beyond the representative BAT-007 scope.
+- Browser-level UI evidence criteria are captured in REQ-004 and remain local evidence rather than a required CI gate unless a future REQ changes that policy.
+- CI tests/lint required-check contract is defined for the six stable jobs listed above; actual branch protection enforcement remains an operator-managed repository setting.
 
 ## Change Log
 - 2026-06-26 22:24 KST: Created by `bootstrap-baseline` from repository observation.
@@ -117,3 +144,4 @@
 - 2026-06-29 KST: REQ-003/BAT-003 기준으로 account statement status update와 balance reconciliation report contract 추가.
 - 2026-06-29 KST: REQ-004/BAT-004 기준으로 Streamlit browser evidence 산출물과 UI evidence gate 규칙 추가.
 - 2026-06-29 KST: REQ-005/BAT-005 기준으로 account `liquidity_bucket`, `get_asset_liquidity_report`, dashboard operations hub contract 추가.
+- 2026-06-30 KST: REQ-007/REQ-008/BAT-007 기준으로 MCP response contract `1.0` governance, representative contract-regression scope, `ruff` lint, six-job required-check contract를 추가.