# Budget Phase 1.1 Runtime Category Seed Pattern

Use this reference when extending FinanceManager's Budget/Cashflow module beyond the Phase-1 manual ledger foundation into category/tag administration, budget-plan seeding, and workbook-derived dry-run helpers.

## Scope

- Keep the feature set small and operational: budget categories, tags, budget-plan items, and workbook structure analysis.
- Do **not** turn this into a productive bank/card import, rule engine, duplicate engine, or raw spreadsheet migration unless the user explicitly approves that next phase.
- Preserve the user-facing pattern: **Preview → Confirm → Audit** is the write boundary for category/tag/plan mutations.

## Backend pattern

- Add schema through `src/jarvis_finance/storage/migrations.py` and bump the expected schema version in schema tests.
- For Phase-1.1-style budget plans, store money/plan values as exact Decimal text. Validate with Python `Decimal`; never route budget amounts through float.
- Tags should be archived/deactivated (`is_active`) rather than hard-deleted, unless a later cleanup workflow explicitly allows destructive deletion.
- Audit payloads should be safe and compact. Avoid raw internal clutter in user summaries.
- API endpoints should separate preview and confirm calls for create/archive operations.

## Frontend pattern

- Budget category/tag pages should show business labels and status, not prominent raw IDs.
- Tests should explicitly assert that the normal user-facing page does not expose raw technical IDs.
- Keep mocks aligned with API DTO changes; Vue build uses strict TypeScript and will fail on unused imports.
- Run frontend commands from `frontend/`, not the repo root.

## Excel/Budget workbook dry-run pattern

- Real budget workbooks must be downloaded/handled only in temporary/runtime locations, never committed.
- Report only aggregate structural facts: sheet selected, candidate counts, warning/unclean counts. Do not print real values, row contents, account names, or amounts.
- For old `.xls` files, use optional dependency support such as `budget-excel = ["xlrd>=2.0"]` rather than forcing it into every base install.
- Workbook parsers should detect the actual layout, including localized/short headers such as `was`, and prefer current-year/current sheets over archive/template sheets.
- Dry-run means no productive mutation: verify that ledger/cash/transaction productive tables are unchanged when appropriate.

## Verification gate

Recommended gate before commit/push:

```bash
python -m compileall -q src tests
PYTHONPATH=src pytest -q
(cd frontend && npm test && npm run build)
python -m ruff check <new-or-changed-python-files>
git diff --check
# run a staged/changelog-aware secret scan before commit
```

Notes:

- If full-repo Ruff is historically noisy, use scoped Ruff on new/changed files and state that full-repo Ruff has pre-existing findings.
- Remove or ignore generated caches/build outputs before Git-safety/staging.
- Run secret scans on the staged diff and relevant untracked new files before committing.
- If GitHub HTTPS push is unauthenticated but the FinanceManager token file is available outside the repo, use a temporary authenticated URL for push and `ls-remote` hash verification; do not set token-bearing remotes and do not print the token.

## Commit/push verification

- Stage only source/test/config files, not temp spreadsheets, runtime DBs, logs, frontend build output, or credentials.
- Commit with a feature-level message.
- Push the active branch.
- Verify `git rev-parse HEAD` equals `git ls-remote <authenticated-url-or-origin> refs/heads/<branch>`.
- Final report should include commit hash, remote hash equality, test gates, and a no-mutation/no-secret note for workbook handling.