jarca-ledger-mcp/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/planning.md

BAT-016 Planning: Review decision persistence and reconciliation workbench

Planning Status

• Status: completed
• Profile: standard
• Design Gate: yes
• Design Gate Rationale: REQ-020 changes persistence schema, application service contracts, MCP tools, Streamlit UI flow, and operating hub aggregation. A design document is required before implementation.

Objective

Turn REQ-020 into a delivery plan for persisted review decisions and reconciliation sessions without changing existing public contracts destructively.

Work Slices

1. Persistence foundation
   • Add review decision and reconciliation session schema via additive/idempotent migration.
   • Add service helpers with validation DB coverage.
2. Application integration
   • Connect cross-transfer review queue, reconciliation report, and uncategorized workbench to persisted decision/session state.
   • Preserve existing response fields with additive extensions only.
3. Streamlit workbench
   • Add minimal operator actions for record/update/hold/recheck/release.
   • Reflect persisted state in dashboard/workbench counts.
4. Network MCP surface
   • Add safe read/mutation tools for review decisions and reconciliation sessions.
   • Exclude destructive delete/reset tools.
5. Baseline and verification
   • Update data model, project structure, runtime flows.
   • Add pytest, MCP surface smoke, Streamlit/dashboard and DB safety evidence.

Acceptance Source

• REQ-020 Acceptance Criteria 1-10.

Dependencies

• dcy-013/BAT-015 network MCP endpoint remains the deployment substrate; BAT-016 does not redesign transport.
• Existing SQLite migration path must remain additive/idempotent.
• Existing dashboard and MCP consumers must keep their current response fields.

Milestones

1. Schema + service implementation.
2. Adapter/UI integration.
3. Targeted tests and full local regression.
4. StagePilot artifact update and PR/CI validation.

Risks

• Source-of-truth ambiguity between current transaction/account state and persisted decision state.
• Session granularity mismatch across account-level reconciliation and item-level review decisions.
• Sensitive memo/payload over-storage.
• MCP/Streamlit contract drift.

Handoff Readiness

• Ready for design drafting: completed.
• Ready for implementation: completed after design decisions below.
• Lead authority needed before delivery: no additional user decision is currently open; scope is approved in dcy-012 and REQ-020.
• Kanban status: deliberately not used for this recovery path per explicit user instruction.