# 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.