feat: complete dcy-015 monthly settlement dashboard

Merge dcy-015 monthly settlement dashboard delivery after local and GitHub Actions verification.
2026-07-12 20:16:36 +09:00
parent a4a913cdd6
commit 835728793e
171 changed files with 12231 additions and 5 deletions
@@ -0,0 +1,28 @@
+# 구현 증적 (impl-bat-018)
+
+## 변경 파일
+- `jarca_ledger_mcp/adapters/streamlit/overview_gateway.py`
+- `dashboard/app.py`
+- `tests/test_dashboard_app.py`
+
+## 수행 내용
+1. `overview_gateway`가 `get_monthly_settlement_summary` 를 스트림릿 용 게이트웨이로 노출하도록 서비스 seam 추가.
+2. `dashboard/app.py`에 `page_monthly_settlement(db_path: str)` 추가:
+   - `current_kst_month()` 기본값의 대상 월 텍스트 입력
+   - `overview_gateway.get_monthly_settlement_summary(...)` 호출
+   - 선택 월/기준일 표시
+   - `월간 핵심 KPI`, `현금흐름 / 지출 구조`, `예산 대비 점검` 섹션을 통한 read-only 렌더링
+3. Streamlit 네비게이션에 `"월정산"` 페이지 추가 및 dispatch 연결.
+4. `tests/test_dashboard_app.py`에 월정산 페이지 AppTest 기대 문자열/섹션 텍스트 검증 추가.
+5. 월정산 헤더에 `모드: 읽기 전용` 캡션 외부로 표시되는 읽기 전용 배지를 `st.markdown` 기반 HTML 칩으로 추가하고,
+   AppTest가 배지 텍스트를 별도 검사하도록 강화.
+
+## 검증
+- `/home/ubuntu/workspaces/jarca-ledger-mcp/.venv/bin/python -m ruff check .`
+  - 결과: `All checks passed!`
+- `/home/ubuntu/workspaces/jarca-ledger-mcp/.venv/bin/python -m pytest -q tests/test_dashboard_app.py`
+  - 결과: `....` (4 passed)
+
+## 잔여 리스크 / 한계
+- 월정산 섹션은 REQ-024/025의 블로커·계정·자산 상세, evidence/next-action 하드닝은 범위 밖이라 미구현.
+- 월정산 페이지는 `month` 쿼리 파라미터를 우선 사용하되, 미지정 시 `current_kst_month()`를 기본값으로 사용해 현재 월 표시 동작을 유지함.
@@ -0,0 +1,33 @@
+# BAT-018: Monthly settlement dashboard shell, KPI, cashflow, and budget
+
+- Profile: batch-lite
+- Status: release-candidate
+- Included REQ: REQ-023
+- Source Discovery: dcy-015
+- Root Delivery: dcy-015_monthly-settlement
+- Queue Item: 0
+- Created At (KST): 2026-07-12 10:31 KST
+
+## Objective
+Deliver the first visible `월정산` dashboard slice by adding the page shell, month selector/header status context, KPI cards, cashflow/spending structure, budget-vs-actual section, and existing-page CTA guidance on top of the implemented REQ-022 read model.
+
+## Included Scope
+- Add `월정산` to Streamlit navigation/routing in the isolated delivery worktree.
+- Render header/month selector with selected month, basis date, KST timestamp, and read-only status badge.
+- Render KPI cards for actual income, actual expense, net cashflow, savings rate, budget overrun count, and unresolved blocker count.
+- Render cashflow/spending structure and budget-vs-actual sections using the REQ-022 service/gateway seam rather than duplicating formulas in `dashboard/app.py`.
+- Add AppTest coverage for routing, key headings, month selector, and representative KPI/budget content.
+
+## Excluded Scope
+- Operational blocker/import/account/asset status sections tracked by REQ-024.
+- Evidence/next-action/doc hardening tracked by REQ-025.
+- Any monthly close persistence, export, MCP summary tool, or broader scope outside dcy-015 approved REQs.
+
+## Documents
+- [planning.md](planning.md)
+
+## Delivery Notes
+- Discovery root queue adopted exactly as handed off; no re-grouping or cross-REQ scope expansion applied.
+- REQ-022 remains an implemented dependency and must not be reimplemented by default.
+- BAT-018 implementation completed, and the third QC verdict (`.stagepilot/delivery/dcy-015_monthly-settlement/bat-018-qc-verdict-03.md`) passed after the bounded read-only badge rework closed the last REQ-023 gap.
+- The first canonical dev-qc supervised run stalled before producing a verdict artifact; see `.stagepilot/delivery/dcy-015_monthly-settlement/bat-018-qc-stall-escalation.md` for the recovered earlier blocker trail.
@@ -0,0 +1,43 @@
+# BAT-018 Planning: Monthly settlement dashboard shell, KPI, cashflow, and budget
+
+## Planning Status
+- Status: completed
+- Profile: batch-lite
+- Design Gate: no
+- Design Gate Rationale: REQ-023 is a bounded read-only dashboard slice that reuses the implemented REQ-022 read model and existing dashboard page patterns without introducing new persistence, interface contracts, or runtime flows beyond local page composition.
+
+## Objective
+Turn REQ-023 into the first user-visible `월정산` page slice while preserving the read-model/service boundary established in REQ-022.
+
+## Work Slices
+1. Page entry and header
+   - Add `월정산` navigation/routing.
+   - Provide month selector, basis date, KST timestamp, and read-only badge.
+2. KPI + visual summary
+   - Render representative KPI cards from the monthly settlement summary.
+   - Add cashflow/spending structure visuals/tables from existing grouped reports.
+3. Budget and CTA guidance
+   - Render budget-vs-actual status and representative CTA/menu hints.
+   - Add AppTest coverage for route/headings/representative content.
+
+## Acceptance Source
+- REQ-023 Acceptance Criteria AC-1 through AC-6.
+
+## Dependencies
+- REQ-022 monthly settlement read-model foundation.
+- Existing dashboard page rendering patterns and synthetic fixture DB generation.
+
+## Milestones
+1. Route/page shell visible in AppTest.
+2. KPI/cashflow/budget sections bound to read-model/gateway outputs.
+3. Relevant lint/test coverage passes in the isolated worktree.
+
+## Risks
+- UI code may accidentally duplicate service formulas instead of reusing the REQ-022 seam.
+- Representative fixture data may not expose all intended budget/KPI states without targeted assertions.
+- Section sprawl could bleed into REQ-024 scope if blocker/import/asset details are added too early.
+
+## Handoff Readiness
+- Ready for implementation: yes.
+- Lead authority needed before delivery: no additional user decision is currently open; scope is approved in dcy-015 / REQ-023.
+- Kanban status: deliberately not used.
@@ -0,0 +1,47 @@
+# 구현 증적 (impl-bat-019)
+
+## 상태
+- Status: impl-complete-qc-ready
+- Updated At (KST): 2026-07-12T19:10:00+09:00
+- Implementation context: `.stagepilot/delivery/dcy-015_monthly-settlement/impl-bat-019-implementation-context.md`
+- Root delivery state: `.stagepilot/delivery/dcy-015_monthly-settlement/state.json`
+
+## 변경 파일
+- `dashboard/app.py`
+- `tests/test_dashboard_app.py`
+- `.stagepilot/worker-progress/impl-bat-019-qc1-rework.md`
+
+## 실제 구현 내용
+1. `dashboard/app.py`
+   - `page_monthly_settlement()`에서 `거래 반영 / 계좌 상태` 블록을 보강해 대표 계좌 반영 상태(계좌명/기관/유형/마지막 동기화/잔액/상태)를 노출했다.
+   - `자산 / 순자산 마감 상태` 블록에 `자산 합계`, `총부채`, `자산 상세(경고/제외 요약)` 지표를 추가했다.
+   - 기존 CTA(확인필요 큐 이동, 계좌 화면 연결, Import 화면 연결, 자산/마감 이동)를 유지하면서 REQ-024의 미분류 경로 안내 텍스트(`미분류 페이지`)를 추가했다.
+2. `tests/test_dashboard_app.py`
+   - 월정산 AppTest에 REQ-024 요구 문구/미분류 안내/새 지표 라벨 존재 검증을 추가했고, raw path 유출 및 원문 payload 노출 없는지 재확인했다.
+   - QC verdict 01 후속 보강으로 대표 계좌 fixture 값(`CI Synthetic Checking`), 최근 동기화 시각(`2026-06-30T23:59:00+09:00`), 잔액(`1,250,000원`), 사용자 친화 상태(`정상`), 자산 상세(`경고 없음`), 자산 합계(`6,250,000원`), 총부채(`2,000,000원`)를 직접 고정 검증하도록 강화했다.
+
+## 구현/감독 근거
+- Worker progress artifact:
+  - `.stagepilot/worker-progress/impl-bat-019-qc1-rework.md`
+
+## runner 재검증 결과
+- `/tmp/jarca-test-venv/bin/ruff check dashboard/app.py tests/test_dashboard_app.py`
+  - 결과: pass
+- `/tmp/jarca-test-venv/bin/pytest tests/test_dashboard_app.py -q`
+  - 결과: pass (`4 passed`)
+
+## impl worker reported validation
+- `pytest`
+  - 결과: pass (`4 passed`)
+
+## QC에 전달할 확인 포인트
+- REQ-024 AC-1: 운영 블로커/검토 섹션이 내부 코드명 대신 사용자 친화 라벨로 보이는지 확인.
+- REQ-024 AC-2: 월정산 body text에 raw local path, raw payload, debug provenance가 없는지 확인.
+- REQ-024 AC-3: 자산 상태가 기존 `get_asset_snapshot_report` 서비스 경계를 재사용하는지 확인.
+- REQ-024 AC-4: 각 unresolved 흐름의 CTA가 실제 기존 페이지 이름 기준인지 확인.
+- REQ-024 AC-5/AC-6: AppTest와 관련 lint/test 근거가 충분한지 확인.
+
+## 잔여 리스크 / 한계
+- QC는 기존 상위 헤더 `정산 전 운영 블로커 점검`을 세부 섹션 위에 유지한 형태가 REQ-024 계약과 충돌하지 않는지 독립적으로 판단해야 한다.
+- QC는 지표 값 표기(`건` suffix 포함)가 기존 dashboard 관례와 수용 가능한지 확인해야 한다.
+- REQ-025 evidence/next-action/doc hardening은 이 batch 범위 밖이다.
@@ -0,0 +1,50 @@
+# BAT-019: Monthly settlement operational blockers, import/account, and asset status
+
+- Profile: batch-lite
+- Status: release-candidate
+- Included REQ: REQ-024
+- Source Discovery: dcy-015
+- Root Delivery: dcy-015_monthly-settlement
+- Queue Item: 1
+- Created At (KST): 2026-07-12 10:31 KST
+- Resume Prepared At (KST): 2026-07-12 13:11 KST
+
+## Objective
+Deliver the second `월정산` page slice by adding operational blocker, import/account status, and asset/net-worth status sections on top of the REQ-022 read model and REQ-023 page shell.
+
+## Included Scope
+- Render the 정산 전 검토 blocker section with user-facing labels and existing-page CTA guidance.
+- Render import/account freshness and status information without exposing raw file paths or raw payloads.
+- Render asset snapshot/net-worth status by reusing the existing asset snapshot/report service boundary.
+- Add representative dashboard/AppTest coverage for blocker/import/asset rendering.
+
+## Excluded Scope
+- KPI/cashflow/budget shell already covered by REQ-023.
+- Evidence/next-actions/docs/smoke hardening tracked by REQ-025.
+- Monthly settlement close writes, export, MCP summary tool, or policy changes outside approved REQs.
+
+## Implementation Readiness Seed
+- Target area: `dashboard.app.page_monthly_settlement(db_path)` after the existing BAT-018 blocker-count caption.
+- Service/adapter seams:
+  - `overview_gateway.list_cross_transfer_review_queue(limit=300, db_path=db_path)` + existing `get_transfer_review_items` helper.
+  - `reconciliation_gateway.get_review_operating_indicators(db_path=db_path)`.
+  - `reconciliation_gateway.get_balance_reconciliation_report(db_path=db_path)`.
+  - `overview_gateway.list_ledger_import_batches(limit=1, db_path=db_path)` with default minimal provenance.
+  - Add/read `overview_gateway.get_asset_snapshot_report(basis_date, db_path=db_path)` as a pass-through to existing service.
+- Expected data/return shape: see `.stagepilot/delivery/dcy-015_monthly-settlement/impl-bat-019-implementation-context.md` `## Return shape`.
+- Render insertion point: add `정산 전 검토`, `거래 반영 / 계좌 상태`, `자산 / 순자산 마감 상태` sections in that order after BAT-018 summary sections.
+- Representative test assertions: section labels, CTA text, representative metrics, and negative assertions for raw local path / raw payload leakage.
+- Forbidden data exposure: no `/home/...`, `~/.local/share/jarca/uploads`, `raw_payload`, raw PDF/XLSX contents, or debug-gated provenance.
+- Open questions: none for runner; if any listed seam/key is invalid, impl must write a blocker artifact instead of broad-searching.
+
+## Documents
+- [planning.md](planning.md)
+- [implementation.md](implementation.md)
+- Implementation context: `.stagepilot/delivery/dcy-015_monthly-settlement/impl-bat-019-implementation-context.md`
+
+## Delivery Notes
+- This slice depends on BAT-018 delivering the visible `월정산` page shell first.
+- REQ-021 provenance and sensitive-data policy must remain enforced on all import/account displays.
+- BAT-018 completed and REQ-023 is now Implemented, so BAT-019 is the active implementation slice for REQ-024.
+- Prior canonical supervised dev-impl launch stalled in a repeated context-compaction/read loop before code diff or completion evidence; see `.stagepilot/delivery/dcy-015_monthly-settlement/bat-019-impl-stall-escalation.md`.
+- Lead has rewritten this batch/context to the patch-ready harness standard before resume.
@@ -0,0 +1,56 @@
+# BAT-019 Planning: Monthly settlement operational blockers, import/account, and asset status
+
+## Planning Status
+- Status: ready-for-resume
+- Profile: batch-lite
+- Design Gate: no
+- Design Gate Rationale: REQ-024 extends the approved read-only monthly settlement UI with additional section composition and existing-service data exposure. The resume-ready context now pins exact read-only service seams, return shapes, render insertion point, tests, and forbidden data exposure, so no additional design artifact is required before implementation.
+
+## Objective
+Turn REQ-024 into a bounded follow-on slice after BAT-018 so the `월정산` page can show settlement-readiness blockers and status summaries without adding writes.
+
+## Work Slices
+1. Blocker summary section
+   - Use `overview_gateway.list_cross_transfer_review_queue` and `reconciliation_gateway.get_review_operating_indicators`.
+   - Show user-friendly unresolved item labels and counts.
+   - Add CTA/menu hints to existing review/import/reconciliation pages.
+2. Import/account status section
+   - Use `overview_gateway.list_ledger_import_batches(limit=1, db_path=db_path)` with minimal provenance only.
+   - Use `reconciliation_gateway.get_balance_reconciliation_report(db_path=db_path)` for account freshness/reconciliation status.
+   - Preserve REQ-021 privacy boundaries.
+3. Asset/net-worth status section
+   - Add/read `overview_gateway.get_asset_snapshot_report` as a pass-through to the existing service.
+   - Show preview/closed state and net worth summary.
+   - Add representative dashboard/AppTest assertions.
+
+## Acceptance Source
+- REQ-024 Acceptance Criteria AC-1 through AC-6.
+
+## Dependencies
+- REQ-022 monthly settlement summary foundation.
+- BAT-018 / REQ-023 page shell and navigation.
+- REQ-021 provenance and sensitive-data policy.
+
+## Implementation Readiness Seed
+- Target area: `dashboard.app.page_monthly_settlement(db_path)` after the existing BAT-018 blocker-count caption.
+- Service/adapter seams: `list_cross_transfer_review_queue`, `get_review_operating_indicators`, `get_balance_reconciliation_report`, `list_ledger_import_batches`, and `get_asset_snapshot_report` through `overview_gateway` where applicable.
+- Expected data/return shape: defined in `.stagepilot/delivery/dcy-015_monthly-settlement/impl-bat-019-implementation-context.md`.
+- Render insertion point: three sections after existing KPI/cashflow/budget summary: `정산 전 검토`, `거래 반영 / 계좌 상태`, `자산 / 순자산 마감 상태`.
+- Representative test assertions: labels, CTA/menu hints, representative metrics, no raw path/payload strings.
+- Forbidden exposure: absolute upload paths, raw payloads, debug-gated provenance, source hashes, or write/close action controls on `월정산`.
+- Open questions: none. Invalid seam/key should become a worker blocker artifact, not broad repository exploration.
+
+## Milestones
+1. Blocker section renders with readable labels.
+2. Import/account and asset sections render without sensitive leakage.
+3. Relevant lint/tests pass in the isolated worktree.
+
+## Risks
+- Existing import/account payloads may tempt direct raw-field display that violates REQ-021; use default minimal provenance only.
+- Asset snapshot preview data needs empty-state handling for fixture DBs.
+- CTA wording must remain tied to actual existing page names: `확인필요 큐`, `계좌`, `Import`, `자산/마감`.
+
+## Handoff Readiness
+- Ready for implementation: yes, after lead rewrite to patch-ready context.
+- Lead authority needed before delivery: no additional user decision is currently open; scope is approved in dcy-015 / REQ-024.
+- Kanban status: deliberately not used.
@@ -0,0 +1,19 @@
+# 검증 초안 (bat-019)
+
+## 대상
+- BAT-019 / REQ-024
+
+## 확인할 acceptance criteria
+- AC-1: blocker section이 internal code name이 아니라 사용자 친화적 label로 렌더링된다.
+- AC-2: import/account status가 raw local path 또는 raw payload를 노출하지 않는다.
+- AC-3: asset status가 existing asset snapshot service definition을 재사용한다.
+- AC-4: unresolved item type마다 기존 운영 화면 CTA/menu hint가 있다.
+- AC-5: AppTest 또는 동등한 dashboard test가 representative blocker/import/asset rendering을 검증한다.
+- AC-6: `python -m ruff check .` 및 관련 pytest/dashboard tests가 통과한다.
+
+## 증적 후보
+- `dashboard/app.py`
+- `tests/test_dashboard_app.py`
+- `jarca_ledger_mcp/adapters/streamlit/overview_gateway.py` (필요 시)
+- `.stagepilot/delivery/dcy-015_monthly-settlement/impl-bat-019.md`
+- `.stagepilot/delivery/dcy-015_monthly-settlement/qc-bat-019.md`
@@ -0,0 +1,45 @@
+# BAT-020 Implementation Evidence
+
+- Timestamp: 2026-07-12T19:20:23+09:00 (KST 기준)
+- Batch: BAT-020
+- REQ: REQ-025
+- Scope: 월정산 페이지 read-only Evidence / 다음 액션 하드닝, AppTest 검증 강화, docs 정합성 반영
+
+## 변경 파일
+- `dashboard/app.py`
+- `tests/test_dashboard_app.py`
+- `docs/project-structure.md`
+- `docs/runtime-flows.md`
+
+## 변경 요약
+1. `dashboard/app.py`
+   - `page_monthly_settlement()` 의 `자산 / 순자산 마감 상태` 블록 뒤에 `월정산 결과 / Evidence` 섹션 추가.
+   - 해당 섹션에서 `읽기 전용 근거 요약`과 함께 `close 준비 상태`, `source coverage`, `최근 Import`, `자산/마감`, `미해결 블로커`를 read-only 텍스트로 노출.
+   - 즉시 뒤 `다음 액션` 섹션 추가.
+   - 문구에 `예산 조정 후보`, `분류/검토 규칙 후보`, `대조/Import/백업 후속 작업`, `이번 범위에는 월정산 close 저장/실행이 포함되지 않습니다` 포함.
+   - 새로운 쓰기/마감 동작이나 close 실행 버튼은 추가하지 않음.
+
+2. `tests/test_dashboard_app.py`
+   - 월정산 페이지 AppTest 분기에서 위 요구 문자열을 검증하도록 assertion 확장.
+   - 기존 forbidden 문자열 검증 (`fixture.sqlite3`, `.local/share/jarca/uploads`, `/home/`, `raw_payload`) 유지.
+
+3. 문서
+   - `docs/project-structure.md`: 월정산 Evidence/다음 액션 책임 반영 및 change log 추가.
+   - `docs/runtime-flows.md`: 월정산 read-only evidence/next-action 운영 플로우 문서화 및 change log 추가.
+
+## 검증 명령
+- `/home/ubuntu/workspaces/jarca-ledger-mcp/.venv/bin/python -m ruff check .`
+- `/home/ubuntu/workspaces/jarca-ledger-mcp/.venv/bin/python -m pytest -q tests/test_dashboard_app.py`
+- `/home/ubuntu/workspaces/jarca-ledger-mcp/.venv/bin/python scripts/ci_dashboard_http_smoke.py`
+
+## AC 대응 매핑 (REQ-025)
+- AC-1: 월정산 페이지에 Evidence 헤더/요약 블록 노출
+  - `월정산 결과 / Evidence`, `읽기 전용 근거 요약` 텍스트 추가로 검증.
+- AC-2: 다음 액션 제시 및 read-only 경계 유지
+  - `다음 액션` 및 close 비포함 문구, 후보 항목 텍스트 추가.
+- AC-3: 근거 문자열 및 소스 범위 가시성 확보
+  - `close 준비 상태`, `source coverage`, `최근 Import`, `자산/마감` 노출.
+- AC-4: 기존 경량 UI 노출 및 위험 정보 차단
+  - `fixture.sqlite3`, `/home/`, `.local/share/jarca/uploads`, `raw_payload` 미포함 보장 (테스트로 확인).
+- AC-5: 문서 동기화
+  - project-structure/runtime-flows에 월정산 완료 하드닝 반영 및 change log 갱신.
@@ -0,0 +1,28 @@
+# BAT-020: Monthly settlement evidence, next actions, documentation, and verification hardening
+
+- Profile: batch-lite
+- Status: release-candidate
+- Included REQ: REQ-025
+- Source Discovery: dcy-015
+- Root Delivery: dcy-015_monthly-settlement
+- Queue Item: 2
+- Created At (KST): 2026-07-12 10:31 KST
+
+## Objective
+Deliver the final dcy-015 hardening slice by adding read-only evidence/next-action sections, updating supporting baseline docs, and strengthening completed-page verification after BAT-018 and BAT-019 are in place.
+
+## Included Scope
+- Render 월정산 결과 / Evidence and 다음 액션 sections with explicit read-only wording.
+- Update baseline docs that need to describe the read-model/page flow/deferred scope.
+- Strengthen dashboard smoke/AppTest/browser evidence as appropriate for the completed page.
+
+## Excluded Scope
+- Any close persistence, export, MCP summary tool, or other future monthly settlement automation.
+- Reopening earlier batch scope unless needed to fix concrete acceptance/test gaps discovered during hardening.
+
+## Documents
+- [planning.md](planning.md)
+
+## Delivery Notes
+- This slice should not introduce settlement-close writes; it only hardens the read-only page and its evidence trail.
+- `docs/interface-contract.md` changes remain conditional on an actual contract change; do not edit it by default.
@@ -0,0 +1,43 @@
+# BAT-020 Planning: Monthly settlement evidence, next actions, documentation, and verification hardening
+
+## Planning Status
+- Status: completed
+- Profile: batch-lite
+- Design Gate: no
+- Design Gate Rationale: REQ-025 is a read-only hardening/documentation slice that builds on already-delivered page sections and existing docs/test patterns without introducing new persistence, service contracts, or runtime flow ownership.
+
+## Objective
+Turn REQ-025 into the final hardening batch for the `월정산` page by adding evidence/next-action sections, updating docs, and strengthening completed-page verification.
+
+## Work Slices
+1. Evidence + next actions UI
+   - Render close-ready summary, major blockers, source coverage summary, and follow-up hints.
+   - Keep wording explicitly read-only.
+2. Baseline document alignment
+   - Update `docs/project-structure.md` and `docs/runtime-flows.md`.
+   - Touch `docs/interface-contract.md` only if the completed implementation actually changes an internal/external contract.
+3. Verification hardening
+   - Expand AppTest/pytest/smoke evidence for the completed page.
+
+## Acceptance Source
+- REQ-025 Acceptance Criteria AC-1 through AC-5.
+
+## Dependencies
+- BAT-018 / REQ-023 implemented page shell.
+- BAT-019 / REQ-024 implemented operational sections.
+- Existing read-only scope guardrails from dcy-015.
+
+## Milestones
+1. Evidence/next-action sections render on the completed page.
+2. Required baseline docs reflect the page flow and deferred scope.
+3. Ruff + pytest and any relevant dashboard smoke evidence pass.
+
+## Risks
+- Evidence wording may imply write/close capability that this scope does not implement.
+- Documentation drift may occur if the final UI structure differs from the discovery summary.
+- Over-broad verification edits could spill outside the monthly settlement slice.
+
+## Handoff Readiness
+- Ready for implementation: after BAT-018 and BAT-019 completion.
+- Lead authority needed before delivery: no additional user decision is currently open; scope is approved in dcy-015 / REQ-025.
+- Kanban status: deliberately not used.
@@ -0,0 +1,33 @@
+# Verification draft (BAT-020)
+
+## Target
+- BAT-020 / REQ-025
+
+## Acceptance mapping
+- AC-1: `dashboard/app.py` renders `월정산 결과 / Evidence`, `읽기 전용 근거 요약`, `다음 액션`, and the explicit no-close wording on the 월정산 page.
+- AC-2: `docs/project-structure.md` and `docs/runtime-flows.md` reflect the read-only evidence/next-action flow and deferred scope.
+- AC-3: `tests/test_dashboard_app.py` asserts the completed page structure; `scripts/ci_dashboard_http_smoke.py` passes.
+- AC-4: The page remains read-only: no close persistence/write button introduced; sensitive path/payload strings remain excluded by AppTest assertions.
+- AC-5: lint and targeted pytest checks pass for the changed slice.
+
+## Evidence bundle
+- Code/UI: `dashboard/app.py`
+- Tests: `tests/test_dashboard_app.py`
+- Baseline docs: `docs/project-structure.md`, `docs/runtime-flows.md`
+- Implementation notes: `docs/batches/bat-020_20260712_monthly-settlement-evidence-next-actions-verification-hardening/implementation.md`
+- Impl worker evidence:
+  - `.stagepilot/worker-supervision/impl-20260712T102306Z/final-result.json`
+  - `.stagepilot/worker-supervision/impl-20260712T102306Z/child.log`
+  - `.stagepilot/worker-progress/impl-bat-020.md`
+- Runner rechecks:
+  - `/home/ubuntu/workspaces/jarca-ledger-mcp/.venv/bin/python -m ruff check dashboard/app.py tests/test_dashboard_app.py docs/project-structure.md docs/runtime-flows.md`
+  - `/home/ubuntu/workspaces/jarca-ledger-mcp/.venv/bin/python -m pytest -q tests/test_dashboard_app.py`
+  - `/home/ubuntu/workspaces/jarca-ledger-mcp/.venv/bin/python scripts/ci_dashboard_http_smoke.py`
+
+## Suspicious areas for QC
+- Verify that `source coverage` and follow-up copy use existing monthly-settlement inputs only and do not imply new persistence capability.
+- Verify that deferred scope wording is consistent between UI and docs.
+- Verify that no local file paths, raw payloads, or debug provenance appear in the rendered body.
+
+## Ready for QC
+- Yes
@@ -25,7 +25,16 @@
 | 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 | release-candidate | REQ-020 | dcy-012 | [bat-016_20260708_review-decision-reconciliation-workbench](bat-016_20260708_review-decision-reconciliation-workbench/) |
 | BAT-017 | standard | release-candidate | REQ-021 | dcy-014 | [bat-017_20260708_import-provenance-sensitive-data-policy](bat-017_20260708_import-provenance-sensitive-data-policy/) |
+| BAT-018 | batch-lite | release-candidate | REQ-023 | dcy-015 | [bat-018_20260712_monthly-settlement-dashboard-shell-kpi-cashflow-budget](bat-018_20260712_monthly-settlement-dashboard-shell-kpi-cashflow-budget/) |
+| BAT-019 | batch-lite | release-candidate | REQ-024 | dcy-015 | [bat-019_20260712_monthly-settlement-operational-blockers-import-account-asset-status](bat-019_20260712_monthly-settlement-operational-blockers-import-account-asset-status/) |
+| BAT-020 | batch-lite | release-candidate | REQ-025 | dcy-015 | [bat-020_20260712_monthly-settlement-evidence-next-actions-verification-hardening](bat-020_20260712_monthly-settlement-evidence-next-actions-verification-hardening/) |

 - 2026-07-08 07:11 KST: BAT-016을 local verification 통과 근거로 release-candidate 상태로 전환했다. Kanban은 사용자 명시 지시로 사용하지 않았다.
 - 2026-07-08 11:33 KST: BAT-017을 REQ-021 delivery batch로 draft 생성했다. Kanban은 사용자 명시 지시로 사용하지 않는다.
 - 2026-07-09 18:46 KST: PR #2 squash merge(`d9182f28`)와 CI/local verification 근거로 BAT-017을 release-candidate 상태로 전환했다.
+- 2026-07-12 10:31 KST: dcy-015 Discovery root queue를 BAT-018~BAT-020 세 개의 batch-lite 배치로 채택/생성했다. Kanban은 사용하지 않았다.
+- 2026-07-12 12:24 KST: BAT-018을 BAT-018 QC rerun 02 pass(`bat-018-qc-verdict-03.md`) 근거로 release-candidate 상태로 전환했다.
+- 2026-07-12 12:40 KST: BAT-019 canonical dev-impl supervised run이 code diff 없이 context-compaction loop에 빠져 blocked 상태로 전환하고 lead escalation artifact를 남겼다.
+
+- 2026-07-12 19:19 KST: BAT-019를 QC verdict 02 conditional pass와 lead reconciliation 근거로 release-candidate 상태로 전환했다.
+- 2026-07-12 19:37 KST: BAT-020을 canonical impl/QC pass 및 root delivery done 근거로 release-candidate 상태로 전환했다.