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.