diff --git a/docs/releases/index.md b/docs/releases/index.md index 1b66789..2f55d6f 100644 --- a/docs/releases/index.md +++ b/docs/releases/index.md @@ -8,3 +8,8 @@ | REL ID | Profile | Status | Included Batch | Discovery/REQ Input | Link | | --- | --- | --- | --- | --- | --- | +| REL-001 | app-service | draft | BAT-001~BAT-020 | REQ-001~REQ-025 implemented baseline through dcy-015 | [rel-001_20260712_initial-jarca-ledger-service-baseline.md](rel-001_20260712_initial-jarca-ledger-service-baseline.md) | + +## Change Log + +- 2026-07-12 20:30 KST: 첫 explicit release-stage 문서로 REL-001 draft를 생성했다. 기존 lead-direct release 운영을 StagePilot release 단계로 전환하기 위한 baseline release다. diff --git a/docs/releases/rel-001_20260712_initial-jarca-ledger-service-baseline.md b/docs/releases/rel-001_20260712_initial-jarca-ledger-service-baseline.md new file mode 100644 index 0000000..79d1333 --- /dev/null +++ b/docs/releases/rel-001_20260712_initial-jarca-ledger-service-baseline.md @@ -0,0 +1,145 @@ +# REL-001 Initial Jarca Ledger service baseline + +- Release ID: REL-001 +- Status: draft +- Profile: app-service +- Created At (KST): 2026-07-12 20:30 KST +- Release Lead: dev-butler +- Repository: `genichin/jarca-ledger-mcp` +- Target branch: `main` +- Baseline commit at draft: `a3a680d00b8302a29657fa9a893de3486f76e755` + +## 1. Purpose + +This is the first explicit StagePilot release document for Jarca Ledger. Earlier delivery work was merged and operated directly by the lead without a separate release SDLC document. This release starts the release-stage record now that the project has grown enough to require explicit rollout, rollback, and post-release evidence. + +REL-001 establishes the current Jarca Ledger service baseline, including the MCP service, Streamlit dashboard, operational safety flows, import provenance policy, review/reconciliation workbench, Docker service topology, and the completed first-pass 월정산 dashboard. + +## 2. Included batches + +| Batch | Status at draft | Included REQ | Discovery | Summary | +| --- | --- | --- | --- | --- | +| BAT-001 | release-candidate | REQ-001 | dcy-001 | Category rule operations DB-path consistency and delete exposure | +| BAT-002 | release-candidate | REQ-002 | dcy-002 | Operational safety backup / restore / validation DB workflow | +| BAT-003 | release-candidate | REQ-003 | dcy-003 | Statement-unavailable manual evidence and balance reconciliation | +| BAT-004 | release-candidate | REQ-004 | dcy-004 | Browser / Streamlit E2E evidence recovery | +| BAT-005 | release-candidate | REQ-005 | dcy-005 | Dashboard operations hub, liquidity, monthly cashflow | +| BAT-006 | release-candidate | REQ-006 | dcy-006 | pytest / AppTest / smoke CI automation | +| BAT-007 | release-candidate | REQ-007, REQ-008 | dcy-007 | MCP response contract versioning and CI required checks | +| BAT-008 | release-candidate | REQ-009, REQ-010 | dcy-008 | Asset snapshots, manual assets, net-worth read model | +| BAT-009 | release-candidate | REQ-011, REQ-012 | dcy-009 | Manual asset CRUD and month-end snapshot close alignment | +| BAT-010 | release-candidate | REQ-013, REQ-014 | dcy-010 | Backend core layering and MCP/Streamlit adapter seam realignment | +| BAT-011 | release-candidate | REQ-015 | dcy-011 | Transactional write service split | +| BAT-012 | release-candidate | REQ-016 | dcy-011 | Import pipeline split | +| BAT-013 | release-candidate | REQ-017 | dcy-011 | Advanced finance workflow service split | +| BAT-014 | release-candidate | REQ-018 | dcy-011 | Adapter surface narrowing and baseline refresh | +| BAT-015 | release-candidate | REQ-019 | dcy-013 | Docker network MCP deployment and operating DB migration | +| BAT-016 | release-candidate | REQ-020 | dcy-012 | Review decision persistence and reconciliation workbench | +| BAT-017 | release-candidate | REQ-021 | dcy-014 | Import provenance and sensitive-data policy | +| BAT-018 | merged | REQ-023 | dcy-015 | 월정산 dashboard shell, KPI, cashflow, budget sections | +| BAT-019 | merged | REQ-024 | dcy-015 | 월정산 operational blockers, import/account, asset status sections | +| BAT-020 | merged | REQ-025 | dcy-015 | 월정산 evidence, next actions, docs, verification hardening | + +### Inclusion note + +The StagePilot `draft-release` baseline expects `release-candidate` batches. BAT-018 through BAT-020 are already `merged` because PR #6 and `confirm-req-implemented` completed before release-stage documentation was introduced. REL-001 treats those `merged` batches as release-ready because they have stronger merge-backed evidence than a local release-candidate state. + +## 3. Release profile decision + +- Selected profile: `app-service` +- Reason: the included scope covers a live MCP service, Streamlit dashboard, Docker deployment topology, database-backed workflows, and operational runtime checks. This is heavier than `docs-only` or `tooling`. + +## 4. Scope summary + +REL-001 releases the accumulated Jarca Ledger baseline through dcy-015: + +- Ledger data model and operational safety workflows +- Category rule and reconciliation operations +- Import provenance and sensitive-data protections +- MCP response contracts and CI regression gates +- Streamlit dashboard core operations pages +- Asset snapshot and manual asset flows +- Docker network MCP and dashboard service topology +- Review decision / reconciliation workbench +- Monthly settlement read-only dashboard first-pass flow + +## 5. Explicitly out of scope + +- New monthly settlement close persistence beyond existing approved capabilities +- New PDF / Excel / Markdown export for monthly settlement +- New MCP finance-agent monthly settlement summary tool +- New finance-domain policy decisions outside implemented REQs +- Database migration beyond the already merged/deployed baseline + +## 6. Rollout plan + +1. Confirm release document content and included batch set. +2. Run final local release gates from `main`: + - `ruff check .` + - `pytest -q` + - `scripts/ci_dashboard_http_smoke.py` + - Docker compose configuration validation, if deployment rollout is requested. +3. Confirm GitHub Actions status on the current `main` commit. +4. For service rollout, rebuild/restart the Synology Docker service stack using the existing runbook: + - `docker compose config --quiet` + - `docker compose build` + - `docker compose up -d --no-build jarca-ledger jarca-ledger-dashboard` +5. Verify app-service runtime health: + - `jarca-ledger` container state and health + - `jarca-ledger-dashboard` container state and health + - MCP tool discovery / `ledger_health_check` + - Dashboard HTTP smoke against `http://192.168.55.253:40059` +6. If checks pass, proceed to `confirm-release` and then capture post-release feedback. + +## 7. Rollback plan + +1. If release confirmation fails before deployment, leave this document in `draft` and record blockers. +2. If service rollout fails after deployment attempt: + - stop the failed containers with `docker compose stop jarca-ledger jarca-ledger-dashboard` if needed; + - redeploy the last known-good image or previous git commit from the Synology deployment working copy; + - preserve `/volume1/docker/jarca-ledger/data` and do not delete the production SQLite database; + - verify `ledger_health_check` and dashboard HTTP health after rollback. +3. If a data-safety issue is suspected, stop write-capable flows first, preserve the DB volume, and run backup/restore validation before further writes. +4. Document rollback evidence in the release feedback section or a follow-up release feedback artifact. + +## 8. Verification checklist + +### Repository / CI + +- [ ] `git status --short --untracked-files=no` is clean for tracked files. +- [ ] `origin/main` matches the intended release commit. +- [ ] GitHub Actions on the intended `main` commit are successful. +- [ ] `ruff check .` passes locally. +- [ ] `pytest -q` passes locally. +- [ ] `scripts/ci_dashboard_http_smoke.py` passes locally. + +### App-service runtime + +- [ ] `docker compose config --quiet` passes. +- [ ] `jarca-ledger` container is running and healthy. +- [ ] `jarca-ledger-dashboard` container is running and healthy. +- [ ] MCP streamable HTTP endpoint responds at the configured `/mcp` path. +- [ ] `ledger_health_check` succeeds and points to the expected `/data/ledger.sqlite3` DB path. +- [ ] Dashboard URL responds with HTTP 200. +- [ ] No sensitive local path/raw payload exposure is visible in dashboard smoke output. + +### StagePilot / documentation + +- [ ] Included batch statuses are release-ready or stronger (`release-candidate` / merge-backed `merged`). +- [ ] `docs/srs/index.md` marks included REQs as `Implemented`. +- [ ] `docs/batches/index.md` and this release document agree on included batches. +- [ ] Manual recovery exception for dcy-015 is visible in `.stagepilot/delivery/dcy-015_monthly-settlement/lead-manual-recovery-exception.md`. + +## 9. Known risks and notes + +- This is the first explicit release document; earlier operational deployment happened outside release-stage SDLC. +- BAT-001 through BAT-017 remain `release-candidate` and may have older evidence styles than the current harness. +- BAT-018 through BAT-020 are merge-backed and include an explicit dcy-015 manual recovery exception trail. +- GitHub Project 4 updates may remain blocked until the local `gh` token has Project scopes. + +## 10. Current draft status + +- Draft created: yes +- Confirmed: no +- Released/deployed by this release step: no +- Next step: run `confirm-release` after final release gates and rollout/rollback readiness review.