jsfamily/jarca-ledger-mcp
5
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9400c0178c03fb82741b80f5f21cf4e1c9f6c9a0
jarca-ledger-mcp/docs/releases/rel-001_20260712_initial-jarca-ledger-service-baseline.md
T
Jarca 9400c0178c docs: confirm REL-001 release 
Record app-service rollout evidence from Docker rebuild/redeploy, container health, MCP smoke, dashboard smoke, local gates, and CI before promoting REL-001 to confirmed.
2026-07-12 20:54:10 +09:00

214 lines
10 KiB
Markdown
Raw Blame History

# REL-001 Initial Jarca Ledger service baseline
- Release ID: REL-001
- Status: confirmed
- 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
- [x] `git status --short --untracked-files=no` is clean for tracked files.
- [x] `origin/main` matches the intended release commit.
- [x] GitHub Actions on the intended `main` commit are successful.
- [x] `ruff check .` passes locally.
- [x] `pytest -q` passes locally.
- [x] `scripts/ci_dashboard_http_smoke.py` passes locally.
### App-service runtime
- [x] `docker compose config --quiet` passes.
- [x] `jarca-ledger` container is running and healthy.
- [x] `jarca-ledger-dashboard` container is running and healthy.
- [x] MCP streamable HTTP endpoint responds at the configured `/mcp` path.
- [x] `ledger_health_check` succeeds and points to the expected `/data/ledger.sqlite3` DB path.
- [x] Dashboard URL responds with HTTP 200.
- [x] No sensitive local path/raw payload exposure is visible in dashboard smoke output.
### StagePilot / documentation
- [x] Included batch statuses are release-ready or stronger (`release-candidate` / merge-backed `merged`).
- [x] `docs/srs/index.md` marks included REQs as `Implemented`.
- [x] `docs/batches/index.md` and this release document agree on included batches.
- [x] 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: yes
- Released/deployed by this release step: yes
- Next step: monitor post-release behavior and run `capture-release-feedback` when operational observations are available.
## 11. Confirmation and deployment evidence
- Confirmed At (KST): 2026-07-12 20:53 KST
- Confirmed By: dev-butler
- Release commit before confirmation-doc update: `ae24b758492a44f1b9168243c4336f612475de53`
- GitHub Actions run: `29191002538`, conclusion `success`
- Docker image rebuilt: `jarca-ledger:latest`
- Docker image ID: `sha256:cce8536555b78e4aed89f60a9bc1c3182180e2d0cf583f17bb8f77ac532ee175`
- Docker image created: `2026-07-12T20:51:08.467711129+09:00`
### Local release gates
```text
ruff check . -> All checks passed
pytest -q -> 62 passed, 4 skipped
scripts/ci_dashboard_http_smoke.py -> success=true, http_status=200
docker compose config --quiet -> OK
```
### Docker rollout evidence
Commands executed from `/home/ubuntu/workspaces/jarca-ledger-mcp`:
```bash
docker compose build
docker compose up -d --no-build jarca-ledger jarca-ledger-dashboard
```
Rollout result:
```text
Container jarca-ledger Recreated / Started / Healthy
Container jarca-ledger-dashboard Recreated / Started
```
Runtime state after rollout:
```text
jarca-ledger Up About a minute (healthy), 0.0.0.0:8000->8000/tcp
jarca-ledger-dashboard Up 31 seconds (healthy), 0.0.0.0:40059->8501/tcp
restart policy unless-stopped for both containers
mount /volume1/docker/jarca-ledger/data -> /data
```
### Runtime smoke evidence
Dashboard smoke:
```text
http://192.168.55.253:40059/_stcore/health -> 200 text/plain; charset=utf-8
http://192.168.55.253:40059/?page=요약 -> 200 text/html; charset=utf-8
```
MCP smoke via Streamable HTTP client:
```text
tool discovery -> 65 tools
ledger_health_check -> success=true
server -> jarca-ledger-mcp
db_path -> /data/ledger.sqlite3
schema_version -> 11
active_transactions -> 6249
```
### Confirm-release decision
REL-001 passes the `app-service` release gate because rollout, rollback plan, local verification, GitHub Actions, container health, MCP smoke, and dashboard smoke evidence are all present. REL-001 is promoted from `draft` to `confirmed`.
Reference in New Issue View Git Blame Copy Permalink