feat: persist review workbench decisions (#1)

Merge dcy-012 / REQ-020 / BAT-016 implementation after green CI.
2026-07-08 10:22:53 +09:00
parent 2fc972a7bf
commit 698dd9e62e
28 changed files with 989 additions and 81 deletions
@@ -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.
@@ -1,17 +1,52 @@
 # BAT-016 Implementation Log

 ## Status
- Not started.
+- Implemented locally; release-candidate after verification.
+- Completed At (KST): 2026-07-08 07:11 KST
+- Branch: `feat/bat-016-review-decision-workbench`

 ## Implementation Owner
- dev-builder / dev-impl under delivery-runner orchestration.
+- 가웨인 direct recovery path. User explicitly prohibited Kanban after prior worker failures.

-## Expected Evidence
- Code diff summary by slice.
- Migration and validation DB evidence.
- MCP tool discovery and representative call evidence.
- Streamlit AppTest/HTTP smoke evidence.
- Full lint/test evidence.
+## Changed Files
+- `jarca_ledger_mcp/infrastructure/sqlite/schema.py`
+- `jarca_ledger_mcp/infrastructure/sqlite/migrations.py`
+- `jarca_ledger_mcp/application/review_decision_service.py`
+- `jarca_ledger_mcp/application/cross_transfer_service.py`
+- `jarca_ledger_mcp/application/reconciliation_service.py`
+- `jarca_ledger_mcp/application/uncategorized_workbench_service.py`
+- `jarca_ledger_mcp/application/system_services.py`
+- `jarca_ledger_mcp/service.py`
+- `jarca_ledger_mcp/adapters/mcp/tool_contracts.py`
+- `jarca_ledger_mcp/adapters/mcp/server.py`
+- `jarca_ledger_mcp/adapters/streamlit/transfers_gateway.py`
+- `jarca_ledger_mcp/adapters/streamlit/reconciliation_gateway.py`
+- `jarca_ledger_mcp/adapters/streamlit/categorization_gateway.py`
+- `dashboard/app.py`
+- `tests/test_review_decision_workbench.py`
+- `tests/test_service.py`
+- `tests/test_ledger_categories.py`
+- `docs/data-model.md`
+- `docs/project-structure.md`
+- `docs/runtime-flows.md`

-## Log
- 2026-07-08 00:00 KST: Batch scaffolded by lead. No implementation performed yet.
+## Implementation Summary
+- Raised SQLite schema version to `11` and added additive/idempotent `review_decisions` and `reconciliation_sessions` schema objects.
+- Added `review_decision_service.py` for safe non-destructive review decision and reconciliation session operations.
+- Added payload minimization to prevent raw payload/password/token/secret/file-path persistence.
+- Added review/session state enrichment to cross-transfer queue, balance reconciliation report, and uncategorized workbench outputs.
+- Added MCP tools for list/upsert/hold/recheck/release review decisions, list/upsert/close reconciliation sessions, and review operating indicators.
+- Added Streamlit actions and gateway exports for review decision/session workflow state.
+- Added regression tests for schema idempotency, sensitive payload filtering, reconciliation session round trip, report integration, and MCP tool surface.
+
+## Commands and Results
+- `python -m ruff check .` → passed.
+- `python -m pytest tests/test_review_decision_workbench.py -q` → `.... [100%]`.
+- `python -m pytest -q` → passed, with existing skipped tests preserved.
+- MCP surface smoke: required 9 review/session tools present; destructive delete/reset absent; tool count `65`.
+- DB safety smoke: schema version `11`, `PRAGMA integrity_check` `ok`, new tables present and empty on synthetic DB.
+
+## Notes
+- No production DB destructive operation was performed.
+- No raw financial evidence or secrets were added to repository fixtures.
+- Final PR/CI evidence remains the next gate after commit/push.
@@ -1,16 +1,17 @@
 # BAT-016: Review decision persistence and reconciliation workbench

 - Profile: standard
- Status: draft
+- Status: release-candidate
 - Included REQ: REQ-020
 - Source Discovery: dcy-012
 - Created At (KST): 2026-07-08 00:00 KST
+- Verification Completed At (KST): 2026-07-08 07:11 KST

 ## Objective
 Deliver the approved REQ-020 scope for persisted review decisions, reconciliation sessions, Streamlit workbench actions, network MCP additive tools, operating hub indicators, and baseline documentation.

 ## Included Scope
- Additive/idempotent persistence for `review_decisions` and `reconciliation_sessions` or an equivalent structure.
+- Additive/idempotent persistence for `review_decisions` and `reconciliation_sessions`.
 - Application/service integration for cross-transfer review queue, reconciliation report, and uncategorized workbench.
 - Streamlit workbench actions for decision create/update/hold/recheck/release.
 - Network MCP tools for safe review decision/session read and mutation operations.
@@ -31,6 +32,6 @@ Deliver the approved REQ-020 scope for persisted review decisions, reconciliatio
 - [implementation.md](implementation.md)
 - [verification.md](verification.md)

-## Harness Notes
- This batch is `standard` because REQ-020 changes persistence, interface surface, runtime flow, Streamlit UI, MCP tools, and baseline docs.
- After this batch scaffold is committed, lead should issue a kanban-backed `lead -> delivery-runner` kickoff on the shared development execution board.
+## Delivery Notes
+- User explicitly prohibited Kanban for this recovery path; delivery was completed directly on feature branch `feat/bat-016-review-decision-workbench`.
+- Local verification evidence is recorded in `verification.md`; final merge remains subject to PR/CI review.
@@ -1,18 +1,18 @@
 # BAT-016 Planning: Review decision persistence and reconciliation workbench

 ## Planning Status
- Status: draft
+- 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 that can be executed by delivery-runner with separated implementation and QC roles.
+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 repository/service helpers with validation DB coverage.
+   - 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.
@@ -24,11 +24,22 @@ Turn REQ-020 into a delivery plan that can be executed by delivery-runner with s
   - Exclude destructive delete/reset tools.
 5. Baseline and verification
   - Update data model, project structure, runtime flows.
-   - Add pytest, contract/smoke, Streamlit AppTest/HTTP smoke, and DB safety evidence.
+   - 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.
@@ -36,6 +47,7 @@ Turn REQ-020 into a delivery plan that can be executed by delivery-runner with s
 - MCP/Streamlit contract drift.

 ## Handoff Readiness
- Ready for design drafting: yes.
- Ready for implementation: no; design must define schema, state transitions, and interface contracts first.
+- 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.
@@ -1,22 +1,74 @@
 # BAT-016 Verification

 ## Status
- Not started.
+- local-pass
+- Verified At (KST): 2026-07-08 07:11 KST

 ## QC Owner
- dev-reviewer / dev-qc under delivery-runner orchestration.
+- 가웨인 direct recovery path; independent QC still recommended before merge because Kanban-based dev-reviewer was explicitly disabled by user instruction.

-## Required Verification
- REQ-020 AC 1-10 must be verified with direct evidence.
- `ruff check .` must pass.
- Full pytest must pass.
- MCP contract/regression and network MCP representative smoke must pass.
- Streamlit AppTest and HTTP smoke must pass.
- DB safety/migration regression must pass.
- Baseline document updates must be inspected.
+## Required Verification Mapping
+| REQ-020 AC | Evidence |
+|---|---|
+| AC1 additive/idempotent persistence | `tests/test_review_decision_workbench.py::test_review_decision_and_reconciliation_schema_are_additive_idempotent`; DB safety smoke showed schema `11`, integrity `ok`. |
+| AC2 review decision round-trip | `test_review_decision_round_trip_payload_sanitizes_sensitive_fields`. |
+| AC3 reconciliation session round-trip/hub basis | `test_reconciliation_session_round_trip_and_report_integration`. |
+| AC4 additive existing service payloads | Full pytest passed; report/workbench tests preserved; new fields are additive. |
+| AC5 network MCP safe tools | MCP tool surface smoke found required review/session tools and no destructive delete/reset tools. |
+| AC6 Streamlit workbench regression | Full pytest includes `tests/test_dashboard_app.py`; local pass. |
+| AC7 operating indicators | `get_review_operating_indicators` included in MCP smoke and session test checks last reconciliation close time. |
+| AC8 financial data safety | Payload sanitization test drops `raw_payload` and `file_path`; no real DB or raw evidence used. |
+| AC9 regression gates | `ruff check .` and full pytest passed locally. CI/PR evidence pending. |
+| AC10 baseline docs | `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md` updated. |
+
+## Local Evidence
+```text
+python -m ruff check .
+All checks passed!
+
+python -m pytest tests/test_review_decision_workbench.py -q
+.... [100%]
+
+python -m pytest -q
+........................ss......................ss... [100%]
+
+python -m pytest tests/test_contract_regression.py -q
+... [100%]
+
+python -m pytest --ignore=tests/test_dashboard_app.py -q
+....................ss......................ss... [100%]
+
+python -m pytest tests/test_dashboard_app.py -q
+.... [100%]
+
+python scripts/ci_dashboard_http_smoke.py --host 127.0.0.1 --port 18501 --timeout 45
+success=true, http_status=200, fixture=synthetic
+
+python scripts/ci_db_safety_smoke.py --timeout 45
+success=true, fixture_integrity=ok, restored_integrity=ok, operating_db_used=false
+
+MCP surface smoke
+close_reconciliation_session OK
+get_review_operating_indicators OK
+hold_review_decision OK
+list_reconciliation_sessions OK
+list_review_decisions OK
+mark_review_recheck OK
+release_review_decision OK
+upsert_reconciliation_session OK
+upsert_review_decision OK
+tool_count 65
+
+DB safety smoke
+schema_version 11
+integrity_check ok
+review_decisions 0
+reconciliation_sessions 0
+```
+
+## Residual Risk
+- Independent dev-reviewer QC was not run because user prohibited Kanban. Treat PR review/CI as the next independent gate.
+- Local verification passed, but GitHub Actions CI must still be checked after push.

 ## Verdict
- Pending.
-
-## Evidence
- None yet.
+- Local release-candidate.
@@ -23,4 +23,6 @@
 | BAT-013 | standard | release-candidate | REQ-017 | dcy-011 | [bat-013_20260703_advanced-workflow-service-split](bat-013_20260703_advanced-workflow-service-split/) |
 | BAT-014 | standard | release-candidate | REQ-018 | dcy-011 | [bat-014_20260703_adapter-surface-narrowing-baseline-refresh](bat-014_20260703_adapter-surface-narrowing-baseline-refresh/) |
 | BAT-015 | standard | release-candidate | REQ-019 | dcy-013 | [bat-015_20260707_docker-network-mcp-deployment](bat-015_20260707_docker-network-mcp-deployment/) |
-| BAT-016 | standard | draft | REQ-020 | dcy-012 | [bat-016_20260708_review-decision-reconciliation-workbench](bat-016_20260708_review-decision-reconciliation-workbench/) |
+| BAT-016 | standard | release-candidate | REQ-020 | dcy-012 | [bat-016_20260708_review-decision-reconciliation-workbench](bat-016_20260708_review-decision-reconciliation-workbench/) |
+
+- 2026-07-08 07:11 KST: BAT-016을 local verification 통과 근거로 release-candidate 상태로 전환했다. Kanban은 사용자 명시 지시로 사용하지 않았다.
@@ -193,6 +193,20 @@
  - Backup artifacts and validation DB copies must not be committed to git.
  - Restore execution is not a persisted MCP operation and requires script/runbook approval controls.

+## Entity: ReviewDecision
+- Source of Truth: `review_decisions`
+- Purpose: 공통 review/workbench envelope for cross-transfer review rows, reconciliation targets, and uncategorized recommendation items.
+- Lifecycle: pending -> decided/held/needs_recheck/ignored -> pending release when operator clears hold/recheck.
+- Key Fields: `id`, `target_type`, `target_id`, `status`, `decision_type`, `reason_code`, `memo`, `operator`, `decided_at`, `review_after`, sanitized JSON `target_payload`, `created_at`, `updated_at`.
+- State Rules: decisions are non-destructive and do not rewrite accounting fields by themselves. Existing read contracts are preserved by attaching additive `review_status` / `review_decision` metadata. `target_payload` omits raw payloads, passwords, tokens, secrets, and source file paths.
+
+## Entity: ReconciliationSession
+- Source of Truth: `reconciliation_sessions`
+- Purpose: 계좌별/기준일별 잔액대조 session close/open state and difference evidence.
+- Lifecycle: open -> closed, with `needs_recheck`/`ignored` available for operator triage.
+- Key Fields: `id`, `account_id`, `basis_date`, `expected_balance`, `actual_balance`, `difference`, `status`, `closed_at`, `source_note`, `memo`, `operator`, `created_at`, `updated_at`.
+- State Rules: account/basis-date rows are upserted idempotently; close records `closed_at`; destructive delete/reset workflow is not exposed.
+
 ## Consistency Rules
 - Actual cashflow reports include only categories whose `cashflow_kind` represents actual income or expense according to report semantics.
 - Account movement summaries should be separate from actual household income/expense summaries.
@@ -202,6 +216,8 @@
 - DB corrections should be narrow and memo-tagged.
 - Dashboard/MCP asset and net-worth reports use a shared valuation helper: account-backed items from `accounts.last_balance` plus non-transaction items from `manual_assets`.
 - Net worth is asset buckets (`cash`, `investment`, `deposit`, `real_estate`, `other`) minus absolute `loan` liabilities; missing valuations are excluded and reported, never inferred from transactions.
+- Review workbench state is sourced from `review_decisions`; pending/held/recheck counts must not be inferred by overwriting raw transaction evidence.
+- Reconciliation operating state is sourced from `reconciliation_sessions`; last close time is the max closed session `closed_at`.

 ## Persistence Notes
 - Schema changes should be additive/idempotent unless a destructive migration is explicitly approved and backed up.
@@ -209,11 +225,12 @@
 - Validation DB copies should live outside the repository and should be selected explicitly via `JARCA_LEDGER_DB_PATH` when used.
 - Passwords for encrypted imports are runtime-only inputs and are not part of the persisted model.
 - Raw payloads may contain sensitive financial evidence and should not be committed to git.
+- ReviewDecision `target_payload` is sanitized to omit `raw_payload`, passwords, tokens, secrets, and file paths before persistence.

 ## Current Gaps / Planned Changes
 - Formal schema migration documentation should be added before larger DB changes.
 - Some UI workflows need final E2E verification against real rows.
- Statement-unavailable account handling is tracked by REQ-003/BAT-003; future work may add a dedicated reconciliation workbench and persistent review-decision queue.
+- Statement-unavailable account handling is tracked by REQ-003/BAT-003; REQ-020/BAT-016 adds dedicated reconciliation sessions and persistent review-decision queue metadata.
 - BAT-009 implements manual asset CRUD mutation and month-end snapshot preview/close/correction service/MCP/dashboard workflow. Future work may add automatic market/real-estate valuation or scheduled month-end close.

 ## Change Log
@@ -223,3 +240,4 @@
 - 2026-06-29 KST: REQ-005/BAT-005 기준으로 `accounts.liquidity_bucket`, `last_balance` 기반 자산 유동성/부채/순자산 규칙 추가.
 - 2026-06-30 KST: REQ-009/REQ-010/BAT-008 기준으로 `manual_assets`, `asset_snapshots`, 권위 소스(`accounts.last_balance` + `manual_assets`), 순자산 산식/미평가 제외 정책 추가.
 - 2026-07-01 KST: REQ-011/REQ-012/BAT-009 기준으로 manual asset CRUD, snapshot preview/close, append-only correction metadata, latest-run read policy 추가.
+- 2026-07-08 KST: REQ-020/BAT-016 기준으로 `review_decisions`, `reconciliation_sessions`, review 상태값, payload 최소보관/마스킹 규칙, 운영 허브 집계 source-of-truth를 추가.
@@ -4,8 +4,8 @@
 - Baseline Seed: `.stage-pilot/bootstrap/baseline.yaml`
 - Status: draft
 - Owner: Jarca / project maintainer
- Last Updated (KST): 2026-07-07
- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-010, BAT-012, BAT-013, BAT-014, dcy-013/BAT-015
+- Last Updated (KST): 2026-07-08
+- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-010, BAT-012, BAT-013, BAT-014, dcy-013/BAT-015, dcy-012/REQ-020/BAT-016

 ## Project Summary
 - Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 자산/스냅샷, 현금흐름 분석을 SQLite에 저장하고 운영한다.
@@ -71,6 +71,7 @@ jarca-ledger-mcp/
 │   │   ├── imports_service.py
 │   │   ├── cross_transfer_service.py
 │   │   ├── reconciliation_service.py
+│   │   ├── review_decision_service.py
 │   │   ├── categorization_services.py
 │   │   └── uncategorized_workbench_service.py
 │   ├── infrastructure/
@@ -165,6 +166,8 @@ jarca-ledger-mcp/
  - Cross-account/self-transfer/cancel-original matching workflow ownership.
 - `jarca_ledger_mcp/application/reconciliation_service.py`
  - Manual/partial-import balance reconciliation preview ownership.
+- `jarca_ledger_mcp/application/review_decision_service.py`
+  - Persistent review-decision and reconciliation-session workflow ownership. Provides safe non-destructive create/update/hold/recheck/release/close helpers shared by Streamlit and MCP adapters.
 - `jarca_ledger_mcp/application/categorization_services.py`
  - Category rules, categorization preview/apply, ledger categories, and compatibility delegation to `uncategorized_workbench_service.py`.
 - `jarca_ledger_mcp/application/uncategorized_workbench_service.py`
@@ -242,3 +245,4 @@ jarca-ledger-mcp/
 - 2026-07-03 KST: REQ-013/REQ-014/BAT-010 기준으로 application / infrastructure / adapter layering, compatibility facade/shim, Streamlit gateway 구조를 반영했다.
 - 2026-07-03 KST: REQ-016/REQ-017/REQ-018 및 BAT-012/BAT-013/BAT-014 기준으로 import/advanced owning services, parser seam, MCP contract helper, page/domain Streamlit gateways를 반영했다.
 - 2026-07-07 KST: REQ-019/BAT-015 기준으로 Dockerfile/compose, `jarca-ledger` independent container, streamable-http MCP endpoint, Synology volume `/volume1/docker/jarca-ledger/data`, and Docker deployment runbook을 반영했다.
+- 2026-07-08 KST: REQ-020/BAT-016 기준으로 review decision service, schema version 11, MCP/Streamlit review workflow integration을 반영했다.
@@ -4,8 +4,8 @@
 - Baseline Seed: `.stage-pilot/bootstrap/baseline.yaml`
 - Status: draft
 - Owner: Jarca / project maintainer
- Last Updated (KST): 2026-07-07
- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-008, BAT-010, BAT-012, BAT-013, BAT-014, dcy-013/BAT-015
+- Last Updated (KST): 2026-07-08
+- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-008, BAT-010, BAT-012, BAT-013, BAT-014, dcy-013/BAT-015, dcy-012/REQ-020/BAT-016
 - Primary Runtime: mixed

 ## Project Summary
@@ -100,6 +100,15 @@
 3. Matched self-transfers become `이체 / 본인계좌이동`; investment movements become `이체 / 투자이동`; ambiguous rows remain `확인필요`.
 4. Cancel/refund rows can be linked to original expense rows; memo tags preserve manual link evidence.

+## Flow: `Review decision and reconciliation workbench persistence`
+1. Operator reviews cross-account transfer candidates, reconciliation differences, or uncategorized recommendations in Streamlit or via MCP.
+2. UI/MCP calls safe review decision tools such as `upsert_review_decision`, `hold_review_decision`, `mark_review_recheck`, and `release_review_decision`.
+3. `review_decision_service.py` validates status/decision type, minimizes `target_payload`, drops sensitive keys, and writes `review_decisions`.
+4. Reconciliation workflows call `upsert_reconciliation_session` or `close_reconciliation_session` for account/basis-date sessions stored in `reconciliation_sessions`.
+5. Cross-transfer queue, balance reconciliation report, and uncategorized workbench re-read persisted state and return additive fields such as `review_status`, `review_decision`, and `reconciliation_session`.
+6. Operating hub indicators aggregate pending review, held/recheck, unreconciled account count, last reconciliation close timestamp, and uncategorized recommendation backlog.
+7. MCP tool surface remains non-destructive; delete/reset of review/session state is intentionally absent.
+
 ## Flow: `Operational backup, validation DB, and restore smoke`
 1. Operator captures non-sensitive DB status evidence with `get_ledger_db_status`: path, size, mtime, sha256, integrity check, major table row counts, and aggregate totals.
 2. Operator creates a timestamped backup in `/root/.local/share/jarca/backups/ledger/` with `create_ledger_backup`; retention keeps the most recent 30 days or newest 20 files.
@@ -156,3 +165,4 @@
 - 2026-07-03 KST: REQ-013/REQ-014/BAT-010 기준으로 service facade → application, db shim → infrastructure/sqlite, MCP/Streamlit adapter seam flow를 반영했다.
 - 2026-07-03 KST: REQ-016/REQ-017/REQ-018 및 BAT-012/BAT-013/BAT-014 기준으로 imports/advanced owning services, parser seam, MCP tool_contracts, Streamlit page/domain gateway flow를 반영했다.
 - 2026-07-07 KST: REQ-019/BAT-015 기준으로 Docker network MCP service flow와 legacy `jarca` DB → `jarca-ledger` volume migration flow를 추가했다.
+- 2026-07-08 KST: REQ-020/BAT-016 기준으로 review decision/reconciliation workbench persistence flow와 운영 허브 지표 집계를 추가했다.
@@ -1,6 +1,6 @@
 # req-020: Review decision persistence and reconciliation workbench

- Status: Approved
+- Status: Implemented
 - Type: Interface
 - Priority: High
 - Owner: 렛저장인
@@ -161,3 +161,52 @@

 #### Validation Plan
 - Validate through StagePilot doctor, index consistency checks, and CI after commit. Delivery validation remains owned by the later batch verification gate.
+
+
+### CHG-20260708-02
+- Date: 2026-07-08
+- Author: 가웨인
+
+#### Change Summary
+- BAT-016 local implementation and verification evidence completed; REQ-020 Status moved to Implemented.
+
+#### Intent
+- dcy-012 confirmed scope now has additive persistence, Streamlit/MCP integration, operating indicators, tests, and baseline document updates on feature branch `feat/bat-016-review-decision-workbench`.
+
+#### Acceptance Criteria Delta
+- Added:
+  - none
+- Updated:
+  - none
+- Removed:
+  - none
+
+#### Impacted Area Delta
+- Docs:
+  - `docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/*`
+  - `docs/data-model.md`
+  - `docs/project-structure.md`
+  - `docs/runtime-flows.md`
+- Modules:
+  - `jarca_ledger_mcp/application/review_decision_service.py`
+  - `jarca_ledger_mcp/infrastructure/sqlite/schema.py`
+  - `jarca_ledger_mcp/infrastructure/sqlite/migrations.py`
+  - MCP, Streamlit, reconciliation, transfer, and uncategorized workbench integration surfaces
+- Tests:
+  - `tests/test_review_decision_workbench.py`
+  - schema-version expectations in existing DB health tests
+
+#### Delivery Trace Delta
+- Batches:
+  - BAT-016 release-candidate
+- Releases:
+  - none
+
+#### Revalidation Impact
+- Reverification Needed: yes before merge/release
+- Existing Implementation Invalidated: no
+- Status Recommendation: implemented-after-local-verification
+- Follow-up Action: push branch, open PR, and verify GitHub Actions CI.
+
+#### Validation Plan
+- Local evidence: `ruff check .`, targeted pytest, full pytest, MCP tool surface smoke, and DB safety smoke passed at 2026-07-08 07:11 KST. GitHub Actions CI remains the next external gate.
@@ -59,7 +59,7 @@
 | REQ-017 | Advanced finance workflow service split and compatibility-preserving domain isolation | Non-Functional | Implemented | High | 렛저장인 | [req-017_advanced-finance-workflow-service-split.md](Non-Functional/req-017_advanced-finance-workflow-service-split.md) |
 | REQ-018 | MCP/Streamlit adapter surface narrowing and baseline refresh for dcy-011 completion | Interface | Implemented | High | 렛저장인 | [req-018_adapter-surface-narrowing-baseline-refresh.md](Interface/req-018_adapter-surface-narrowing-baseline-refresh.md) |
 | REQ-019 | Docker network MCP deployment and operating DB migration | Deployment | Implemented | High | 렛저장인 | [req-019_docker-network-mcp-deployment.md](Deployment/req-019_docker-network-mcp-deployment.md) |
-| REQ-020 | Review decision persistence and reconciliation workbench | Interface | Approved | High | 렛저장인 | [req-020_review-decision-persistence-reconciliation-workbench.md](Interface/req-020_review-decision-persistence-reconciliation-workbench.md) |
+| REQ-020 | Review decision persistence and reconciliation workbench | Interface | Implemented | High | 렛저장인 | [req-020_review-decision-persistence-reconciliation-workbench.md](Interface/req-020_review-decision-persistence-reconciliation-workbench.md) |

 ## Recent Change Log Summary

@@ -97,3 +97,5 @@
 - 2026-07-07 22:23 KST: dcy-013 Docker network MCP 배포 범위로 REQ-019를 생성하고, BAT-015 구현·검증 evidence 및 운영 DB 이전 완료를 근거로 Implemented 상태로 등록했다.
 - 2026-07-07 23:53 KST: dcy-012 confirmed 범위를 `REQ-020` Proposed 상태로 생성하고 review decision persistence/reconciliation workbench 요구사항으로 등록했다.
 - 2026-07-08 00:00 KST: REQ-020을 승인 게이트 검토 후 Approved 상태로 전환했다.
+
+- 2026-07-08 07:11 KST: REQ-020을 BAT-016 local verification 근거로 Implemented 상태로 전환했다. CI/PR review는 후속 외부 gate로 남아 있다.