docs: draft first Jarca Ledger release
Create REL-001 as the first explicit StagePilot release-stage document for the accumulated app-service baseline through dcy-015.
This commit is contained in:
Jarca
@@ -8,3 +8,8 @@
|
|||||||
|
|
||||||
| REL ID | Profile | Status | Included Batch | Discovery/REQ Input | Link |
|
| 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다.
|
||||||
|
|||||||
@@ -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.
|
||||||
Reference in New Issue
Block a user