@fuzzle/opencode-accountant 0.4.6-next.1 → 0.4.6

package/docs/tools/reconcile-statement.md

@@ -1,529 +0,0 @@
-# reconcile-statement Tool
-
-The `reconcile-statement` tool validates that imported bank statement transactions result in the correct closing balance. It compares the expected balance (from CSV metadata or manual input) against the actual balance calculated by hledger.
-
-This tool is **restricted to the accountant agent only**.
-
-**Important**: This tool requires a `contextId` from a prior `classify-statements` and `import-statements` run. The context provides the account number needed to find the correct CSV file, especially when multiple accounts exist for the same provider/currency. See [Import Context Architecture](../architecture/import-context.md) for details.
-
-## Arguments
-
-| Argument         | Type   | Required | Default | Description                                                          |
-| ---------------- | ------ | -------- | ------- | -------------------------------------------------------------------- |
-| `contextId`      | string | Yes      | -       | Context ID from `classify-statements` (e.g., UUID)                   |
-| `closingBalance` | string | No       | -       | Manual closing balance override (e.g., `"CHF 2324.79"`)              |
-| `account`        | string | No       | -       | Manual hledger account override (e.g., `"assets:bank:ubs:checking"`) |
-
-### Context-Based Operation
-
-The tool operates exclusively via import contexts:
-
-1. Loads context from `.memory/{contextId}.json`
-2. Uses context's `accountNumber` to find the correct CSV file
-3. Uses context's `closingBalance` (unless manually overridden)
-4. Uses context's `filePath` to locate the imported CSV
-5. Updates context with reconciliation results
-
-**No fallback behavior**: If `contextId` is not provided or invalid, the tool will fail immediately. This ensures correct CSV file selection in multi-account scenarios.
-
-## Output Format
-
-### Success - Balance Reconciled
-
-When the actual balance matches the expected balance:
-
-```json
-{
-  "success": true,
-  "account": "assets:bank:ubs:checking",
-  "expectedBalance": "CHF 5432.10",
-  "actualBalance": "CHF 5432.10",
-  "lastTransactionDate": "2026-02-28",
-  "csvFile": "import/done/ubs/chf/ubs-0235-90250546.0-transactions-2026-02-01-to-2026-02-28.csv",
-  "metadata": {
-    "from-date": "2026-02-01",
-    "until-date": "2026-02-28",
-    "opening-balance": "4123.45",
-    "closing-balance": "5432.10",
-    "currency": "CHF",
-    "account-number": "0235-90250546.0"
-  },
-  "note": "✓ Balance reconciled successfully"
-}
-```
-
-### Failure - Balance Mismatch
-
-When the actual balance doesn't match the expected balance:
-
-```json
-{
-  "success": false,
-  "account": "assets:bank:ubs:savings",
-  "expectedBalance": "CHF 12500.00",
-  "actualBalance": "CHF 12490.00",
-  "difference": "CHF -10.00",
-  "lastTransactionDate": "2026-02-24",
-  "csvFile": "import/done/ubs/chf/ubs-0235-90250546.1-transactions-2026-02-22-to-2026-02-24.csv",
-  "error": "Balance mismatch: expected CHF 12500.00, got CHF 12490.00 (difference: CHF -10.00)",
-  "hint": "Check for missing transactions or incorrect rules. Review transactions around 2026-02-24."
-}
-```
-
-### Error - Context Not Found
-
-When the context ID is invalid or context file doesn't exist:
-
-```json
-{
-  "success": false,
-  "error": "Failed to load import context: abc123-...",
-  "hint": "Ensure the context ID is valid and the context file exists in .memory/"
-}
-```
-
-### Error - CSV File Not Found
-
-When the CSV file referenced by the context doesn't exist:
-
-```json
-{
-  "success": false,
-  "error": "CSV file not found: import/done/ubs/chf/transactions.csv",
-  "hint": "The file may have been moved or deleted. Context ID: abc123-..."
-}
-```
-
-### Error - No Closing Balance
-
-When closing balance cannot be determined from context, CSV metadata, or manual override:
-
-```json
-{
-  "success": false,
-  "csvFile": "import/done/revolut/eur/account-statement_2026-02.csv",
-  "error": "No closing balance found in CSV metadata or data",
-  "hint": "Provide closingBalance parameter manually. Example retry: reconcile-statement --contextId abc123-... --closingBalance \"EUR 1234.56\"",
-  "metadata": {
-    "from-date": "2026-02-01",
-    "until-date": "2026-02-28",
-    "currency": "EUR"
-  }
-}
-```
-
-### Error - Account Not Determined
-
-When hledger account cannot be determined from rules file or manual override:
-
-```json
-{
-  "success": false,
-  "csvFile": "import/done/ubs/chf/transactions.csv",
-  "error": "Could not determine account from rules file",
-  "hint": "Add 'account1 assets:bank:...' to ledger/rules/ubs-....rules or retry with: reconcile-statement --contextId abc123-... --account \"assets:bank:...\""
-}
-```
-
-## How It Works
-
-The reconciliation process follows these steps:
-
-### Step 1: Load Import Context
-
-```
-Load .memory/{contextId}.json
-  ↓
-Extract:
-  - accountNumber (e.g., "0235-90250546.1")
-  - closingBalance (e.g., "9001.55")
-  - filePath (e.g., "import/done/ubs/chf/...")
-```
-
-### Step 2: Find CSV File
-
-The tool uses the `filePath` from the import context to locate the CSV:
-
-```typescript
-const csvFile = path.join(directory, importContext.filePath);
-// Verify file exists, return error if not found
-```
-
-**Critical**: The file path comes from the context, which was updated when `import-statements` moved the file from `pending/` to `done/`.
-
-### Step 3: Determine Closing Balance
-
-Priority order:
-
-1. **Manual override** (`--closingBalance` parameter)
-2. **Context value** (`context.closingBalance`)
-3. **CSV metadata** (from CSV header, e.g., UBS files)
-4. **CSV data analysis** (inspect last transaction balance)
-
-If none available → ERROR (requires manual input)
-
-### Step 4: Determine Account
-
-Priority order:
-
-1. **Manual override** (`--account` parameter)
-2. **Rules file** (`account1` directive in matching `.rules` file)
-
-If none available → ERROR (requires manual input or rules file update)
-
-### Step 5: Query hledger Balance
-
-```
-Run: hledger balance --end {lastTransactionDate + 1 day} {account}
-  ↓
-Parse output to get actual balance
-  ↓
-Format as "CHF 5432.10"
-```
-
-### Step 6: Compare Balances
-
-```
-expectedBalance (from CSV) vs actualBalance (from hledger)
-  ↓
-Match? → SUCCESS
-  ↓
-Mismatch? → FAILURE (with difference calculated)
-```
-
-### Step 7: Update Context
-
-```
-Update .memory/{contextId}.json with:
-  - reconciledAccount
-  - actualBalance
-  - lastTransactionDate
-  - reconciled: true/false
-```
-
-## Balance Sources
-
-### Automatic Balance Detection
-
-**UBS**: Closing balance extracted from CSV header metadata (row with "Closing balance:")
-
-```csv
-...metadata rows...
-Closing balance:;9001.55;CHF
-...
-Trade date;Trade time;...
-2026-02-22;09:30:00;...
-```
-
-**Revolut**: No balance in CSV metadata → requires manual input
-
-```bash
-reconcile-statement --contextId abc123-... --closingBalance "EUR 1234.56"
-```
-
-### Balance Normalization
-
-The tool normalizes balances to format: `{CURRENCY} {amount}`
-
-Examples:
-
-- Input: `"CHF 2324.79"` → Used as-is
-- Input: `"2324.79"` (from CSV) + currency from context → `"CHF 2324.79"`
-- Input: `"2,324.79 CHF"` → Parsed and normalized to `"CHF 2324.79"`
-
-## Account Detection
-
-### Automatic Account Detection
-
-Accounts are detected from the matching rules file's `account1` directive:
-
-**Example rules file** (`ledger/rules/ubs-0235-90250546.0.rules`):
-
-```
-account1 assets:bank:ubs:checking
-account2 expenses:unknown
-
-fields date, time, description1, description2, ...
-
-if %description1 SALARY
-  account2 income:salary
-```
-
-The tool reads `account1 assets:bank:ubs:checking` to determine which account to reconcile.
-
-### Manual Account Override
-
-If rules file doesn't have `account1` or you want to override:
-
-```bash
-reconcile-statement --contextId abc123-... --account "assets:bank:ubs:checking"
-```
-
-## The Multi-Account Problem
-
-### Why Context ID is Required
-
-**Scenario**: You have two UBS CHF accounts:
-
-- Checking: `0235-90250546.0`
-- Savings: `0235-90250546.1`
-
-Both CSVs end up in `import/done/ubs/chf/`. Without context IDs, the tool would:
-
-❌ Search for: `provider=ubs`, `currency=chf`  
-❌ Find: BOTH CSV files  
-❌ Select: Most recent file (by modification time)  
-❌ Result: Wrong CSV reconciled against wrong account
-
-**With context IDs**:
-
-✓ Receive: `contextId` for checking account  
-✓ Load: Context with `accountNumber="0235-90250546.0"`  
-✓ Filter: CSVs by account number in filename  
-✓ Find: Exact CSV for checking account  
-✓ Result: Correct CSV reconciled against correct account
-
-See [Import Context Architecture](../architecture/import-context.md) for technical details.
-
-## Typical Workflow
-
-### Scenario 1: Automatic Reconciliation (via Pipeline)
-
-```bash
-# Pipeline handles everything automatically
-import-pipeline
-```
-
-**What happens**:
-
-1. `classify-statements` creates contexts for each CSV
-2. `import-statements` imports transactions (one context at a time)
-3. `reconcile-statement` receives contextId automatically
-4. Tool loads context, finds CSV by accountNumber
-5. Compares balances
-6. Updates context with results
-
-### Scenario 2: Manual Reconciliation
-
-```bash
-# Step 1: Classify and import first
-classify-statements
-# Output: { "classified": [{ "contextId": "abc123-...", ... }] }
-
-import-statements --contextId "abc123-..." --checkOnly false
-
-# Step 2: Reconcile using contextId
-reconcile-statement --contextId "abc123-..."
-```
-
-### Scenario 3: Override Closing Balance
-
-When CSV doesn't have balance metadata (e.g., Revolut):
-
-```bash
-# Get contextId from classify output
-classify-statements
-# Output: { "classified": [{ "contextId": "xyz789-...", "provider": "revolut", ... }] }
-
-# Import
-import-statements --contextId "xyz789-..." --checkOnly false
-
-# Reconcile with manual balance
-reconcile-statement --contextId "xyz789-..." --closingBalance "EUR 1234.56"
-```
-
-### Scenario 4: Override Account
-
-When rules file is missing `account1` directive:
-
-```bash
-reconcile-statement --contextId "abc123-..." --account "assets:bank:ubs:checking"
-```
-
-## Troubleshooting
-
-### Balance Mismatch
-
-**Symptom**: `Balance mismatch: expected CHF 12500.00, got CHF 12490.00 (difference: CHF -10.00)`
-
-**Common Causes**:
-
-1. **Missing transaction**: Check if a transaction was skipped during import
-
-   ```bash
-   # Compare CSV transaction count vs imported count
-   wc -l import/done/ubs/chf/transactions.csv
-   hledger register assets:bank:ubs:checking -b 2026-02-01 -e 2026-03-01 | wc -l
-   ```
-
-2. **Skip rule too aggressive**: A rule in the `.rules` file may be skipping legitimate transactions
-
-   ```bash
-   # Review skip rules in rules file
-   grep "^skip" ledger/rules/ubs-0235-90250546.0.rules
-   ```
-
-3. **Wrong date range**: Transactions outside the CSV's date range affecting balance
-
-   ```bash
-   # Check for transactions after the CSV's until-date
-   hledger register assets:bank:ubs:checking -b {until-date}
-   ```
-
-4. **Manual entries**: Transactions manually added to journal that aren't in CSV
-   ```bash
-   # Search for manual entries
-   grep assets:bank:ubs:checking ledger/2026.journal
-   ```
-
-### Wrong CSV Reconciled
-
-**Symptom**: Reconciling checking account but errors mention savings account transactions
-
-**Cause**: This shouldn't happen with context IDs. If it does:
-
-1. **Verify context**:
-
-   ```bash
-   jq . .memory/{contextId}.json
-   # Check that accountNumber matches the intended account
-   ```
-
-2. **Check CSV filename**:
-
-   ```bash
-   ls import/done/ubs/chf/
-   # Verify filename contains correct account number
-   ```
-
-3. **Verify rules file**:
-   ```bash
-   cat ledger/rules/ubs-0235-90250546.0.rules
-   # Check that account1 is correct
-   ```
-
-### Context Not Found
-
-**Error**: `Failed to load import context: abc123-...`
-
-**Solutions**:
-
-1. **Verify context file exists**:
-
-   ```bash
-   ls .memory/abc123-*.json
-   ```
-
-2. **Get valid contextId from classify output**:
-
-   ```bash
-   # Re-run classify to get current contextIds
-   classify-statements
-   ```
-
-3. **Check for typos**: Ensure contextId is copied correctly (UUIDs are long!)
-
-### No Closing Balance
-
-**Error**: `No closing balance found in CSV metadata or data`
-
-**Solutions**:
-
-1. **Provide manual balance**:
-
-   ```bash
-   reconcile-statement --contextId abc123-... --closingBalance "CHF 2324.79"
-   ```
-
-2. **Check CSV metadata**: Some providers include balance in header rows
-
-   ```bash
-   head -15 import/done/ubs/chf/transactions.csv
-   # Look for "Closing balance" or similar
-   ```
-
-3. **Update provider config**: Add balance extraction rules to `config/import/providers.yaml`
-
-### Account Not Determined
-
-**Error**: `Could not determine account from rules file`
-
-**Solutions**:
-
-1. **Add account1 to rules file**:
-
-   ```bash
-   # Edit rules file
-   echo "account1 assets:bank:ubs:checking" >> ledger/rules/ubs-0235-90250546.0.rules
-   ```
-
-2. **Provide manual account**:
-   ```bash
-   reconcile-statement --contextId abc123-... --account "assets:bank:ubs:checking"
-   ```
-
-## Context Updates
-
-After reconciliation, the context is updated with results:
-
-**Before reconciliation** (`.memory/abc123-....json`):
-
-```json
-{
-  "id": "abc123-...",
-  "accountNumber": "0235-90250546.0",
-  "closingBalance": "5432.10",
-  "transactionCount": 42
-}
-```
-
-**After successful reconciliation**:
-
-```json
-{
-  "id": "abc123-...",
-  "accountNumber": "0235-90250546.0",
-  "closingBalance": "5432.10",
-  "transactionCount": 42,
-  "reconciledAccount": "assets:bank:ubs:checking",
-  "actualBalance": "CHF 5432.10",
-  "lastTransactionDate": "2026-02-28",
-  "reconciled": true
-}
-```
-
-**After failed reconciliation**:
-
-```json
-{
-  "id": "abc123-...",
-  "reconciledAccount": "assets:bank:ubs:checking",
-  "actualBalance": "CHF 5422.10",
-  "lastTransactionDate": "2026-02-28",
-  "reconciled": false
-}
-```
-
-This provides an audit trail of reconciliation attempts.
-
-## Error Handling
-
-### Common Errors
-
-| Error                    | Cause                                     | Solution                                                       |
-| ------------------------ | ----------------------------------------- | -------------------------------------------------------------- |
-| Context not found        | Invalid contextId or missing context file | Verify contextId from classify-statements output               |
-| CSV file not found       | File was moved/deleted after import       | Re-run import-statements or check file location                |
-| No closing balance       | CSV metadata missing balance              | Provide `--closingBalance` manually                            |
-| Account not determined   | Rules file missing `account1`             | Add `account1` directive to rules file or provide `--account`  |
-| Balance mismatch         | Missing transactions or incorrect rules   | Check for skipped transactions, review skip rules              |
-| Multiple CSVs match      | Account number ambiguous                  | Shouldn't happen with contexts; check accountNumber in context |
-| hledger query failed     | Journal file corrupted or invalid         | Run `hledger check` to validate journal                        |
-| Last transaction missing | Import didn't include all transactions    | Check import logs, verify CSV was fully processed              |
-
-## See Also
-
-- [Import Context Architecture](../architecture/import-context.md) - Technical details on context system
-- [classify-statements Tool](classify-statements.md) - Creates contexts
-- [import-statements Tool](import-statements.md) - Updates contexts with import results
-- [import-pipeline Tool](import-pipeline.md) - Orchestrates classify → import → reconcile flow