docs: approve review workbench req and batch

2026-07-08 00:02:45 +09:00
parent 62efc30fd8
commit 2fc972a7bf
8 changed files with 193 additions and 2 deletions
@@ -0,0 +1,31 @@
+# BAT-016 Design: Review decision persistence and reconciliation workbench
+
+## Design Status
+- Status: draft
+- Owner: delivery-runner to complete with dev-impl input before implementation.
+
+## 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.
+
+## 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.
+
+## 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.
@@ -0,0 +1,17 @@
+# BAT-016 Implementation Log
+
+## Status
+- Not started.
+
+## Implementation Owner
+- dev-builder / dev-impl under delivery-runner orchestration.
+
+## 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.
+
+## Log
+- 2026-07-08 00:00 KST: Batch scaffolded by lead. No implementation performed yet.
@@ -0,0 +1,36 @@
+# BAT-016: Review decision persistence and reconciliation workbench
+
+- Profile: standard
+- Status: draft
+- Included REQ: REQ-020
+- Source Discovery: dcy-012
+- Created At (KST): 2026-07-08 00:00 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.
+- 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.
+- Operating hub indicators for pending review, held/recheck, unreconciled accounts, last reconciliation close time, and uncategorized recommendation backlog.
+- Baseline updates in `docs/data-model.md`, `docs/project-structure.md`, and `docs/runtime-flows.md`.
+
+## Excluded Scope
+- Additional HTTP transport redesign beyond the existing dcy-013 network MCP endpoint.
+- Multi-user authorization and role-based approval workflows.
+- Automatic scheduling, push notifications, and external messaging integrations.
+- AI-based final decision automation.
+- Raw financial evidence storage expansion or sensitive source payload retention.
+- Destructive delete/reset MCP tools for review decisions or reconciliation sessions.
+
+## Documents
+- [planning.md](planning.md)
+- [design.md](design.md)
+- [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.
@@ -0,0 +1,41 @@
+# BAT-016 Planning: Review decision persistence and reconciliation workbench
+
+## Planning Status
+- Status: draft
+- 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.
+
+## Work Slices
+1. Persistence foundation
+   - Add review decision and reconciliation session schema via additive/idempotent migration.
+   - Add repository/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, contract/smoke, Streamlit AppTest/HTTP smoke, and DB safety evidence.
+
+## Acceptance Source
+- REQ-020 Acceptance Criteria 1-10.
+
+## 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: yes.
+- Ready for implementation: no; design must define schema, state transitions, and interface contracts first.
+- Lead authority needed before delivery: no additional user decision is currently open; scope is approved in dcy-012 and REQ-020.
@@ -0,0 +1,22 @@
+# BAT-016 Verification
+
+## Status
+- Not started.
+
+## QC Owner
+- dev-reviewer / dev-qc under delivery-runner orchestration.
+
+## 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.
+
+## Verdict
+- Pending.
+
+## Evidence
+- None yet.
@@ -23,3 +23,4 @@
 | 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/) |