From 2fc972a7bf6829f194d21adff20aee266fa7e1b7 Mon Sep 17 00:00:00 2001 From: Jarca Date: Wed, 8 Jul 2026 00:02:45 +0900 Subject: [PATCH] docs: approve review workbench req and batch --- .../design.md | 31 +++++++++++++ .../implementation.md | 17 +++++++ .../index.md | 36 +++++++++++++++ .../planning.md | 41 +++++++++++++++++ .../verification.md | 22 ++++++++++ docs/batches/index.md | 1 + ...on-persistence-reconciliation-workbench.md | 44 ++++++++++++++++++- docs/srs/index.md | 3 +- 8 files changed, 193 insertions(+), 2 deletions(-) create mode 100644 docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/design.md create mode 100644 docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/implementation.md create mode 100644 docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/index.md create mode 100644 docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/planning.md create mode 100644 docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/verification.md diff --git a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/design.md b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/design.md new file mode 100644 index 0000000..067db82 --- /dev/null +++ b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/design.md @@ -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. diff --git a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/implementation.md b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/implementation.md new file mode 100644 index 0000000..f7eda22 --- /dev/null +++ b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/implementation.md @@ -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. diff --git a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/index.md b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/index.md new file mode 100644 index 0000000..ecfd3f7 --- /dev/null +++ b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/index.md @@ -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. diff --git a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/planning.md b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/planning.md new file mode 100644 index 0000000..246cf7c --- /dev/null +++ b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/planning.md @@ -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. diff --git a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/verification.md b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/verification.md new file mode 100644 index 0000000..f470ff8 --- /dev/null +++ b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/verification.md @@ -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. diff --git a/docs/batches/index.md b/docs/batches/index.md index e4ad8f7..3495dc9 100644 --- a/docs/batches/index.md +++ b/docs/batches/index.md @@ -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/) | diff --git a/docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md b/docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md index 0e3864f..382dd57 100644 --- a/docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md +++ b/docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md @@ -1,6 +1,6 @@ # req-020: Review decision persistence and reconciliation workbench -- Status: Proposed +- Status: Approved - Type: Interface - Priority: High - Owner: 렛저장인 @@ -119,3 +119,45 @@ #### Validation Plan - Before implementation approval, verify additive migration safety, persisted decision/session round-trip, MCP and Streamlit contract compatibility, full pytest, lint, dashboard smoke, DB safety smoke, and baseline document updates. + +### CHG-20260708-01 +- Date: 2026-07-08 +- Author: 가웨인 + +#### Change Summary +- REQ-020 승인 게이트를 통과해 Status를 Approved로 전환했다. + +#### Intent +- dcy-012 confirmed 범위가 delivery input으로 충분히 구체화되었고, Priority/Owner/범위/Acceptance Criteria에 승인 blocker가 남아 있지 않아 batch planning 대상으로 확정하기 위해 승인했다. + +#### Acceptance Criteria Delta +- Added: + - none +- Updated: + - none +- Removed: + - none + +#### Impacted Area Delta +- Docs: + - `docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md` + - `docs/srs/index.md` +- Modules: + - none +- Tests: + - none + +#### Delivery Trace Delta +- Batches: + - none yet +- Releases: + - none + +#### Revalidation Impact +- Reverification Needed: yes +- Existing Implementation Invalidated: no +- Status Recommendation: keep-current +- Follow-up Action: run `suggest-batch-reqs` or draft the batch, then issue the StagePilot `lead -> delivery-runner` kickoff after the batch boundary is ready. + +#### Validation Plan +- Validate through StagePilot doctor, index consistency checks, and CI after commit. Delivery validation remains owned by the later batch verification gate. diff --git a/docs/srs/index.md b/docs/srs/index.md index ed7144f..10b2be8 100644 --- a/docs/srs/index.md +++ b/docs/srs/index.md @@ -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 | Proposed | 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 | Approved | High | 렛저장인 | [req-020_review-decision-persistence-reconciliation-workbench.md](Interface/req-020_review-decision-persistence-reconciliation-workbench.md) | ## Recent Change Log Summary @@ -96,3 +96,4 @@ - 2026-07-03 08:23 KST: BAT-014 adapter narrowing + baseline refresh 구현과 AppTest/full pytest/MCP discovery evidence를 근거로 `REQ-018`을 Implemented로 전환했다. - 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 상태로 전환했다.