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

BAT-007 Planning

Scope

• Implement REQ-007: MCP response contract versioning governance.
• Implement REQ-008: representative contract regression and lint required checks.
• Preserve existing success response shapes; runtime contract_version remains unexposed.
• Use synthetic/temp data only for tests and evidence.

Dependencies

• dcy-007 confirmed Discovery and approved REQ-007/REQ-008.
• Existing BAT-006 CI workflow and synthetic fixture policy.
• Existing service-layer functions that accept db_path for temp fixture tests.

Work plan

1. Add BAT-007 standard batch docs and index entry.
2. Add contract version 1.0 governance and CI required-check contract to baseline docs.
3. Add representative contract snapshot metadata and pytest regression for health/status, list, report, and mutation success envelope scopes.
4. Add ruff dev dependency/config and CI lint/contract-regression jobs while preserving existing job names.
5. Run narrow local verification: contract pytest, ruff, targeted regression that includes the new test, then full pytest if narrow gates pass.
6. If evidence satisfies ACs, move REQ-007 and REQ-008 to Implemented.

Risks and mitigations

• Over-strict snapshot failures: mitigate by required-subset/type checks so optional additive fields pass.
• Existing code lint churn: mitigate by conservative initial ruff rule set (E9, F).
• Branch protection cannot be toggled from code: document as external operator setting and keep stable job names.