jarca-ledger-mcp/docs/releases/rel-001_20260712_initial-jarca-ledger-service-baseline.md

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

• 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: 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

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:

docker compose build
docker compose up -d --no-build jarca-ledger jarca-ledger-dashboard

Rollout result:

Container jarca-ledger Recreated / Started / Healthy
Container jarca-ledger-dashboard Recreated / Started

Runtime state after rollout:

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:

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:

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.