// Perform monthly journal migration using hledger close --migrate to close the previous month and open the new month with proper balance assertions and account initialization.
| name | monthly-migration |
| description | Perform monthly journal migration using hledger close --migrate to close the previous month and open the new month with proper balance assertions and account initialization. |
Note: Use full path ledger/[year]/[year]-[month]/[name].journal (e.g., ledger/2024/2024-01/self.journal).
Guide for migrating journals at the start of each month.
Examples: See ./examples.md for canonical migration commands and verification steps.
Quick reference: See .agents/instructions/agent-glossary.instructions.md for short definitions.
self.journal and self.alternatives.journal need migrationpython -m check successfullyhledger close --migrate -f ledger/YYYY/YYYY-MM/self.journal for each journal to generate closing/opening transactions.self.journal exist and include the correct prelude (include ../../../preludes/self.journal).bun run format and bun run check).chore(migration): header and include migration context in the commit message.For detailed examples and edge cases, see .agents/instructions/developer-workflows.instructions.md and ./examples.md. (Examples and a short checklist are in examples.md.)
Do:
self.journal and self.alternatives.journal= 0.00 CURRENCYDon't:
cat ledger/2025/2025-12/self.journal | tail -50 # View closing
cat ledger/2026/2026-01/self.journal | head -50 # View opening
Edit hledger journal files following best practices and conventions. Includes prelude includes, balance assertions, tagging, formatting, and validation procedures with anti-patterns to avoid.
Transcribe transactions from source documents into the hledger ledger. Handles raw data (receipts, invoices, bank statements, OCR text) with proper status markers, tagging, and account registration. For multiple entries, uses a separate subagent for each transaction to enable parallelization and focused scope.
Strict, step-by-step workflow for upserting Octopus card transactions to the ledger. Requires explicit user clarification for any ambiguity. Enforces contextual matching, mapping, and privacy rules. No guessing or inference allowed.
Add a new payee (merchant, person, organization, or UUID) to the correct preludes journal file, maintaining strict lexicographical order.
Match Octopus Wallet statement rows to journal transactions and update transaction datetimes. Runs only when explicitly requested.
Validate hledger journal files using check/format scripts. Includes validation procedures and local hook (Husky + lint-staged) verification.