docs: initialize StagePilot baseline

.stage-pilot/bootstrap/baseline.yaml

@@ -0,0 +1,176 @@
+schema_version: 1
+capture_mode: observed
+
+project:
+  repository_name: jarca-ledger-mcp
+  display_name: Jarca Ledger MCP
+  summary: Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 현금흐름 분석을 SQLite에 저장하고 운영한다.
+  primary_domain: Korean household finance ledger and transaction reconciliation
+
+stack:
+  tech_stack:
+    - Python >=3.11
+    - FastMCP / MCP server
+    - SQLite
+    - Streamlit dashboard
+    - pandas / plotly dashboard dependencies
+    - PyMuPDF PDF parsing
+    - openpyxl + msoffcrypto-tool for encrypted Excel imports
+    - pytest test suite
+
+runtime:
+  primary_runtime: mixed
+  primary_entrypoints:
+    - name: jarca-ledger-mcp
+      purpose: MCP stdio server exposing ledger/account/category/import/report tools to Hermes Agent.
+    - name: dashboard/app.py
+      purpose: Streamlit dashboard for local ledger review, categorization, import, and manual reconciliation.
+    - name: pytest
+      purpose: Regression tests for service logic, import parsers, categorization rules, and transfer matching.
+
+interfaces:
+  contracts:
+    - name: MCP tool surface
+      type: internal-service
+      actors: Hermes Agent and MCP clients
+      purpose: Provide structured tools for ledger transactions, categories, budgets, imports, reports, and reconciliation.
+      stability: internal
+      inputs:
+        - Python function/tool arguments validated by server.py signatures.
+        - File paths and optional passwords for import preview/import tools.
+      outputs:
+        - Dictionary responses with success/error payloads; existing success shapes should remain backward compatible.
+      errors:
+        - validation_error for invalid parameters.
+        - parser/import-specific errors for unreadable files, password issues, validation failures, or duplicate handling.
+      compatibility_rules:
+        - Preserve existing success response shapes for existing tools unless a planned migration states otherwise.
+        - Additive optional fields are preferred over breaking argument changes.
+    - name: Streamlit dashboard
+      type: web-app
+      actors: Local operator using browser UI
+      purpose: Display actual cashflow, transaction lists, uncategorized triage, rule management, import batches, and review queues.
+      stability: internal
+      inputs:
+        - Local SQLite database selected through JARCA_LEDGER_DB_PATH or default path.
+        - Uploaded PDF/XLS/XLSX files for supported import paths.
+      outputs:
+        - Streamlit pages, tables, dialogs, categorization updates, import results, and reconciliation actions.
+      errors:
+        - UI-level error messages for unavailable service functions, parser failures, and validation problems.
+      compatibility_rules:
+        - User-facing category/cashflow semantics must remain stable; UI should surface cashflow_kind where classification matters.
+  shared_constraints:
+    - Financial import evidence must preserve raw provenance fields where available.
+    - Actual income/expense must stay separate from account movement, investment movement, and excluded double-count candidates.
+    - Destructive DB migrations are not allowed without explicit backup/approval flow.
+  current_gaps:
+    - Streamlit UX needs final verification for rule deletion, cancel/original linking, and import E2E flows.
+    - No formal CI workflow is present yet.
+    - Project was recently initialized as a git/GitHub repository; release and deployment policy is not yet documented.
+
+structure:
+  planned_top_level_areas:
+    - path: jarca_ledger_mcp/
+      responsibility: MCP server package, SQLite schema, service layer, import parsers, categorization, and reports.
+    - path: dashboard/
+      responsibility: Streamlit operator UI for ledger review and manual workflows.
+    - path: tests/
+      responsibility: pytest regression tests for parsers, service operations, categorization, and matching.
+    - path: docs/
+      responsibility: StagePilot baseline, Discovery, SRS, Batch, and Release documentation.
+    - path: .stage-pilot/
+      responsibility: StagePilot bootstrap seed and local process metadata.
+
+data_model:
+  persistence_backend: SQLite database at ~/.local/share/jarca/ledger.sqlite3 by default, overrideable through JARCA_LEDGER_DB_PATH.
+  entities:
+    - name: LedgerAccount
+      purpose: Represents bank, card, cash, investment, or loan accounts used to attach transaction evidence and balances.
+      source_of_truth: ledger_accounts table
+      lifecycle: created -> updated -> inactive/archived
+      key_fields:
+        - id :: text :: stable account identifier
+        - name :: text :: operator-facing account name
+        - type :: text :: bank/card/cash/investment/loan classification
+        - last_balance :: integer :: latest known balance when available
+      relationships:
+        - Transaction :: account_id links transaction rows to an account
+      state_rules:
+        - active=false hides accounts from default listings without deleting history.
+    - name: Transaction
+      purpose: Represents imported or manually entered financial event evidence with direction, amount, classification, provenance, and memo tags.
+      source_of_truth: transactions table
+      lifecycle: created/imported -> categorized/reconciled -> soft-deleted or retained
+      key_fields:
+        - transaction_date :: date text :: ledger date
+        - type :: text :: income/expense/transfer/refund/adjustment direction
+        - amount :: integer :: positive KRW amount
+        - category/subcategory :: text :: household ledger classification
+        - source/external_id/import_batch_id :: text :: import provenance and dedupe evidence
+      relationships:
+        - LedgerAccount :: account_id
+        - LedgerCategory :: category/subcategory
+        - ImportBatch :: import_batch_id
+      state_rules:
+        - amount is stored as a positive integer; type determines direction.
+        - refund/cancel rows should be linked to the original transaction when confirmed.
+    - name: LedgerCategory
+      purpose: Defines category/subcategory semantics and cashflow_kind used by reports.
+      source_of_truth: ledger_categories table
+      lifecycle: seeded/created -> updated -> inactive/deleted
+      key_fields:
+        - category :: text :: top-level category
+        - subcategory :: text :: optional subcategory
+        - cashflow_kind :: text :: income/expense/transfer/investment/debt_payment/exclude/unknown
+      relationships:
+        - Transaction :: category/subcategory lookup
+        - CategoryRule :: rule target category/subcategory
+      state_rules:
+        - cashflow_kind controls actual household cashflow inclusion semantics.
+    - name: CategoryRule
+      purpose: Defines automatic categorization rules with field, pattern, priority, and optional amount/day constraints.
+      source_of_truth: category_rules table
+      lifecycle: created -> previewed/applied -> updated/deactivated/deleted
+      key_fields:
+        - match_field :: text :: merchant/counterparty/raw_summary/etc.
+        - pattern :: text :: contains/equals/regex match pattern
+        - amount_min/amount_max/day_of_month :: integer :: optional match constraints
+        - priority :: integer :: deterministic rule ordering
+      relationships:
+        - Transaction :: candidate rows updated by matching rules
+      state_rules:
+        - Preview before broad application when changing rules.
+    - name: ImportBatch
+      purpose: Tracks grouped imports for rollback and audit.
+      source_of_truth: import_batches table
+      lifecycle: previewed -> imported -> optionally rolled back
+      key_fields:
+        - id :: text :: batch identifier
+        - source :: text :: import source kind
+        - imported_count/skipped_duplicate_count :: integer :: result summary
+      relationships:
+        - Transaction :: import_batch_id
+      state_rules:
+        - Rollback should soft-delete by default unless explicitly hard-deleted.
+  consistency_rules:
+    - transfer/investment/exclude cashflow kinds are excluded from actual income/expense reports unless an account-movement report is requested.
+    - Cross-account matches require same date, same amount, opposite direction, and compatible source labels before auto-confirmation.
+    - Imported rows should retain raw_summary/raw_payload/counterparty/balance_after when available.
+  persistence_notes:
+    - Schema changes should be idempotent and additive by default.
+    - Manual DB corrections should be narrow, ID-based, and memo-tagged for auditability.
+  current_gaps:
+    - Need formal migration/back-up procedure before destructive or structural migrations.
+    - Need final UI verification for rule deletion and cancel/original linkage.
+
+notes:
+  known_unknowns:
+    - Whether to add CI workflow and deployment/service management for the Streamlit dashboard.
+    - Final UX acceptance criteria for mobile dashboard pages and rule deletion behavior.
+    - Long-term handling policy for accounts where downloadable transaction statements are unavailable.
+
+metadata:
+  captured_at_kst: 2026-06-26 22:24
+  source: bootstrap-baseline-repo-observation
+  updated_from: repo-observation