jarca-ledger-mcp/docs/batches/bat-007_20260630_mcp-response-contract-ci-versioning/implementation.md

BAT-007 Implementation

Changed files

• .github/workflows/ci.yml
  • Added stable required-check candidate jobs: contract-regression, lint.
• pyproject.toml, uv.lock
  • Added ruff to dev dependencies and conservative E9/F initial lint config.
• tests/test_contract_regression.py
  • Added representative MCP response contract regression tests.
• tests/contract_snapshots/response_contract_v1_0.json
  • Added contract 1.0 metadata and required-subset schemas for health/status, list, report, and mutation success envelope scopes.
• docs/interface-contract.md
  • Added MCP response contract 1.0 governance, breaking/additive classification, runtime exposure policy, version log, and CI required-check contract.
• docs/project-structure.md, docs/runtime-flows.md
  • Updated baseline structure/flow docs for contract snapshots/tests, contract-regression, lint, branch-protection boundary, and synthetic-only invariant.
• docs/batches/index.md
  • Registered BAT-007.
• docs/batches/bat-007_20260630_mcp-response-contract-ci-versioning/{index,planning,design,implementation,verification}.md
  • Added standard batch delivery docs.
• docs/srs/Interface/req-007_mcp-response-contract-versioning-governance.md
• docs/srs/Testing/req-008_ci-contract-regression-and-lint-required-checks.md
• docs/srs/index.md
  • Updated REQ state to Implemented after verification evidence.

Implementation notes

• Runtime MCP success payloads were not changed.
• Contract version 1.0 is documented in docs/interface-contract.md and mirrored in tests/contract_snapshots/response_contract_v1_0.json.
• Contract regression is representative, not exhaustive.
• Lint gate uses conservative ruff rules: E9, F.
• All new test data uses pytest temp DBs and synthetic names/amounts only.

Verification command log

Executed from /root/projects/jarca-ledger-mcp.

1. uv sync --extra dev --extra dashboard

Result:

Resolved 72 packages in 1.37s
   Building jarca-ledger-mcp @ file:///root/projects/jarca-ledger-mcp
Downloading ruff (11.0MiB)
 Downloaded ruff
      Built jarca-ledger-mcp @ file:///root/projects/jarca-ledger-mcp
Prepared 3 packages in 2.94s
Uninstalled 2 packages in 18ms
Installed 3 packages in 338ms
 ~ jarca-ledger-mcp==0.1.0 (from file:///root/projects/jarca-ledger-mcp)
 - pytest==9.1.0
 + pytest==9.1.1
 + ruff==0.15.20

2. uv run pytest tests/test_contract_regression.py

Result:

...                                                                      [100%]
3 passed in 0.99s

3. uv run ruff check .

Result:

All checks passed!

4. uv run pytest --ignore=tests/test_dashboard_app.py

Result:

...............ss...............ss...                                    [100%]
33 passed, 4 skipped in 29.37s

5. uv run python scripts/ci_db_safety_smoke.py --timeout 45

Result:

{
  "success": true,
  "gate": "db-safety-smoke",
  "fixture": "synthetic",
  "fixture_integrity": "ok",
  "restore_smoke_exit_code": 0,
  "restored_exists": true,
  "restored_integrity": "ok",
  "health_success": true,
  "operating_db_used": false
}

6. uv run python scripts/ci_dashboard_http_smoke.py --host 127.0.0.1 --port 18501 --timeout 45

Result:

{
  "success": true,
  "gate": "dashboard-http-smoke",
  "fixture": "synthetic",
  "fixture_integrity": "ok",
  "http_status": 200,
  "attempts": 4,
  "cleanup": "terminated"
}