feat: persist review workbench decisions (#1)

Merge dcy-012 / REQ-020 / BAT-016 implementation after green CI.

docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/design.md

@@ -1,31 +1,47 @@
 # BAT-016 Design: Review decision persistence and reconciliation workbench
 
 ## Design Status
-- Status: draft
-- Owner: delivery-runner to complete with dev-impl input before implementation.
+- Status: completed
+- Owner: 가웨인 direct recovery path; Kanban prohibited by user.
 
-## Required Design Decisions
-1. Persistence schema
-   - Define exact columns, indexes, uniqueness/idempotency keys, and schema migration path for `review_decisions` and `reconciliation_sessions`.
-   - Define whether target payload is JSON text and how sensitive content is minimized.
-2. State model
-   - Map UI labels to internal `status` and `decision_type` values from REQ-020.
-   - Define allowed transitions for pending/decided/held/needs_recheck/ignored.
-3. Application contracts
-   - Define additive fields returned by review queue, reconciliation report, and uncategorized workbench services.
-   - Define compatibility expectations for existing MCP and Streamlit consumers.
-4. MCP tool contracts
-   - Define names, arguments, responses, error handling, and non-goals for review decision/session tools.
-   - Explicitly exclude destructive delete/reset operations.
-5. Streamlit interaction model
-   - Define minimum UI actions, confirmation patterns, and feedback messages.
-6. Verification design
-   - Define fixtures and representative scenarios for persistence round-trip, contract compatibility, dashboard behavior, and DB safety.
+## Architecture Summary
+BAT-016 adds a small review-state layer beside the existing ledger facts. Transactions, accounts, imports, categories, and reports remain the financial source of truth; `review_decisions` and `reconciliation_sessions` store operator workflow state only. MCP and Streamlit adapters use the existing `service.py` facade and page/domain gateways, so the new behavior is additive to current consumers.
 
-## Initial Recommendation
-Use a common decision envelope with fields aligned to REQ-020 and target-specific payload fields stored as minimal JSON. Use reconciliation sessions as account/basis-date close records and allow review decisions to target either a session or a specific item.
+## Changed Areas
+- SQLite schema/migrations: schema version `11`, new `review_decisions` and `reconciliation_sessions` tables plus indexes.
+- Application: new `review_decision_service.py` owns decision/session persistence, payload sanitization, operating indicators, and attachment helpers.
+- Existing services: cross-transfer queue, reconciliation report, and uncategorized workbench attach persisted review/session state with additive fields.
+- MCP: safe review decision/session tools registered through `tool_contracts.py` and `server.py`.
+- Streamlit: dashboard actions for review decisions and reconciliation sessions through existing gateways.
+- Docs/tests: data model/project structure/runtime flow baselines and pytest coverage.
 
-## Design Completion Criteria
-- Schema and state transitions are explicit enough for dev-impl to implement without product reinterpretation.
-- MCP and Streamlit contracts are additive and testable.
-- Verification scenarios map directly to REQ-020 AC 1-10.
+## Key Decisions
+1. **Schema**
+   - `review_decisions`: common decision envelope with `target_type`, `target_id`, `status`, `decision_type`, `reason_code`, `memo`, `operator`, `decided_at`, `review_after`, `target_payload`, timestamps.
+   - `reconciliation_sessions`: account/basis-date session records with expected/actual/difference, `status`, `closed_at`, source/memo/operator, timestamps.
+   - Migrations are additive and idempotent using `CREATE TABLE IF NOT EXISTS` and `CREATE INDEX IF NOT EXISTS`.
+2. **State model**
+   - Review statuses: `pending`, `decided`, `held`, `needs_recheck`, `ignored`.
+   - Decision types: `account_transfer`, `real_expense`, `real_income`, `investment_transfer`, `excluded_from_analysis`, `duplicate_or_cancel`, `unknown`.
+   - Reconciliation statuses: `open`, `closed`, `needs_recheck`, `ignored`.
+3. **Payload safety**
+   - `target_payload` is minimal JSON text; known sensitive keys such as `raw_payload`, password/token/secret/file_path are dropped before persistence.
+4. **Contracts**
+   - Existing payloads remain compatible; new fields such as `review_status`, `review_decision`, and `reconciliation_session` are additive.
+   - MCP adds non-destructive tools only; no delete/reset tool is exposed.
+5. **Operating indicators**
+   - The service computes pending review, held/recheck, unreconciled account count, last reconciliation close time, and uncategorized recommendation backlog from persisted state plus current ledger state.
+
+## Edge Cases
+- Unknown/invalid status or decision type returns validation errors rather than writing inconsistent state.
+- Release/hold/recheck operations target the latest decision for a given target and preserve audit timestamps.
+- Reconciliation session `difference` can be supplied or derived from expected/actual values.
+- Empty or unparsable `target_payload` is reduced to `{}` or a short summary, never raw financial evidence expansion.
+
+## Architecture Impact
+- `both`: project structure gains `application/review_decision_service.py`; runtime flows gain review-decision/reconciliation workbench flow.
+
+## Reference Doc Update Plan
+- `docs/data-model.md`: add review/session entities, state values, and payload-minimization rules.
+- `docs/project-structure.md`: list `review_decision_service.py` ownership.
+- `docs/runtime-flows.md`: add review decision and reconciliation workbench runtime flow.