@dizzlkheinz/ynab-mcpb 0.16.1 → 0.17.0

package/docs/guides/TESTING.md

@@ -1,591 +0,0 @@
-# YNAB MCP Server - Testing Guide
-
-Comprehensive testing guide covering automated tests, manual test scenarios, and quality assurance processes.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Test Structure](#test-structure)
-- [Running Tests](#running-tests)
-- [Environment Setup](#environment-setup)
-- [Test Types](#test-types)
-- [Coverage Requirements](#coverage-requirements)
-- [Manual Test Scenarios](#manual-test-scenarios)
-- [Test Data Management](#test-data-management)
-- [Common Issues](#common-issues)
-
-## Overview
-
-The YNAB MCP Server includes both automated and manual testing capabilities:
-
-**Automated Tests**:
-1. **Unit Tests** - Test individual components in isolation
-2. **Integration Tests** - Test component interactions with mocked dependencies
-3. **End-to-End Tests** - Test complete workflows with real YNAB API (optional)
-4. **Performance Tests** - Test response times, memory usage, and load handling
-
-**Manual Testing**:
-- Comprehensive test scenarios for Claude Desktop integration
-- Feature verification workflows
-- Performance and reliability validation
-
-## Test Structure
-
-```
-src/
-├── __tests__/                     # Global test utilities and E2E tests
-│   ├── setup.ts                   # Test environment setup
-│   ├── testUtils.ts               # Shared test utilities
-│   ├── testRunner.ts              # Comprehensive test runner
-│   ├── workflows.e2e.test.ts      # End-to-end workflow tests
-│   ├── comprehensive.integration.test.ts  # Integration tests
-│   └── performance.test.ts        # Performance and load tests
-├── server/__tests__/              # Server component tests
-├── tools/__tests__/               # Tool-specific tests
-└── types/__tests__/               # Type definition tests
-```
-
-## Running Tests
-
-### Quick Test Commands
-
-```bash
-# Run all tests with coverage
-npm test
-
-# Run specific test types
-npm run test:unit           # Unit tests only (fast, mocked)
-npm run test:integration    # Integration tests (mocked API)
-npm run test:e2e           # End-to-end tests (real API)
-npm run test:performance   # Performance tests
-
-# Generate coverage report
-npm run test:coverage
-
-# Run comprehensive test suite with detailed reporting
-npm run test:comprehensive
-
-# Watch mode for test development
-npm run test:watch
-```
-
-## Environment Setup
-
-### For Unit and Integration Tests (using mocks):
-```bash
-# Optional - will use mock token if not provided
-YNAB_ACCESS_TOKEN=your_test_token
-```
-
-### For End-to-End Tests (using real YNAB API):
-```bash
-# Required for E2E tests
-YNAB_ACCESS_TOKEN=your_real_ynab_personal_access_token
-
-# Optional - specify test budget/account IDs
-TEST_BUDGET_ID=your_test_budget_id
-TEST_ACCOUNT_ID=your_test_account_id
-
-# Optional - skip E2E tests
-SKIP_E2E_TESTS=true
-```
-
-## Test Types
-
-### Unit Tests
-- Test individual functions and classes in isolation
-- Use mocked dependencies
-- Fast execution (< 10 seconds)
-- No external API calls
-
-### Integration Tests
-- Test component interactions
-- Use mocked YNAB API responses
-- Validate complete tool workflows
-- Medium execution time (10-30 seconds)
-
-### End-to-End Tests
-- Test against real YNAB API
-- Validate complete user workflows
-- Slower execution (30-60 seconds)
-- **Warning**: Creates real data in your test budget
-
-### Performance Tests
-- Test response times and memory usage
-- Validate performance under load
-- Test error handling performance
-- Medium execution time (15-30 seconds)
-
-## Coverage Requirements
-
-The test suite enforces minimum coverage thresholds:
-
-- **Lines**: 80%
-- **Functions**: 80%
-- **Branches**: 80%
-- **Statements**: 80%
-
----
-
-# Manual Test Scenarios
-
-Comprehensive test scenarios for manually validating the YNAB MCP server with Claude Desktop.
-
-## 1. Setup Verification Tests
-
-### 1.1 Server Startup and Connection
-
-**Objective**: Verify the server starts successfully and Claude Desktop connects.
-
-**Steps**:
-1. Build the project: `npm run build`
-2. Configure Claude Desktop with MCP server settings
-3. Restart Claude Desktop
-4. Check MCP servers list in Claude Desktop
-
-**Expected Results**:
-- Build completes without errors
-- Claude Desktop shows "ynab-mcp-server" in connected servers
-- No connection errors in Claude Desktop logs
-
-**Success Criteria**: Server appears as connected in Claude Desktop interface
-
-### 1.2 YNAB Token Authentication
-
-**Objective**: Verify YNAB Personal Access Token is valid and working.
-
-**Steps**:
-1. Ask Claude: "Can you run the diagnostic_info tool?"
-2. Check the returned authentication status
-3. Verify user information is retrieved
-
-**Expected Results**:
-- Diagnostic info returns successfully
-- Authentication status shows "authenticated: true"
-- User information includes YNAB user details
-
-**Success Criteria**: No authentication errors, user data present
-
-### 1.3 System Status Verification
-
-**Objective**: Verify all server components are initialized properly.
-
-**Steps**:
-1. Run diagnostic_info tool
-2. Review system configuration
-3. Check cache initialization
-4. Verify environment variables
-
-**Expected Results**:
-- All services report healthy status
-- Cache is initialized with correct settings
-- Environment variables loaded properly
-- Tool registry shows all tools
-
-**Success Criteria**: All system components report healthy status
-
-## 2. Basic Functionality Tests
-
-### 2.1 Budget Management
-
-**Objective**: Test basic budget listing and selection functionality.
-
-**Steps**:
-1. Ask Claude: "List my YNAB budgets"
-2. Note the budget names returned
-3. Ask Claude: "Set my default budget to [budget_name]"
-4. Ask Claude: "What is my current default budget?"
-
-**Expected Results**:
-- Budget list returns user's budgets with names and IDs
-- Default budget is set successfully
-- Cache warming is triggered automatically
-- Default budget query returns the selected budget
-
-**Success Criteria**: Budget operations work without errors, cache warming occurs
-
-### 2.2 Account Listing
-
-**Objective**: Test account retrieval and caching behavior.
-
-**Steps**:
-1. Ask Claude: "List my accounts" (first time)
-2. Note response time
-3. Ask Claude: "List my accounts" (second time)
-4. Compare response times
-5. Check diagnostic_info for cache hits
-
-**Expected Results**:
-- First request fetches from YNAB API
-- Second request is faster (cache hit)
-- Both requests return identical account data
-- Cache metrics show hit count increase
-
-**Success Criteria**: Caching improves response time, data consistency maintained
-
-### 2.3 Transaction Retrieval
-
-**Objective**: Test transaction listing with various filters.
-
-**Steps**:
-1. Ask Claude: "Show me recent transactions"
-2. Ask Claude: "Show me transactions from a specific account"
-3. Ask Claude: "Show me transactions from the last 30 days"
-4. Ask Claude: "Show me uncategorized transactions"
-
-**Expected Results**:
-- All transaction queries return appropriate data
-- Filters work correctly (account, date range, categorization status)
-- Response times are reasonable
-- Data format is consistent
-
-**Success Criteria**: All transaction filters work correctly, consistent formatting
-
-## 3. Enhanced Caching Tests
-
-### 3.1 Cache Warming Verification
-
-**Objective**: Verify cache warming works after setting default budget.
-
-**Steps**:
-1. Clear cache (restart server or use diagnostic tools)
-2. Set default budget
-3. Check cache metrics immediately after
-4. Verify accounts, categories, and payees are cached
-
-**Expected Results**:
-- Cache warming triggers automatically
-- Accounts, categories, and payees are pre-loaded
-- Subsequent requests for these data types are fast
-- Cache hit rate improves dramatically
-
-**Success Criteria**: Cache warming pre-loads commonly used data
-
-### 3.2 LRU Eviction Testing
-
-**Objective**: Test cache eviction when limits are reached.
-
-**Steps**:
-1. Set cache limit to low value (via environment variables)
-2. Request data for multiple different filters
-3. Check cache metrics for evictions
-4. Verify least recently used items are evicted first
-
-**Expected Results**:
-- Cache respects maximum entry limits
-- Older entries are evicted as new ones are added
-- Most frequently accessed data remains cached
-- No memory leaks occur
-
-**Success Criteria**: LRU eviction maintains cache within limits
-
-### 3.3 Stale-While-Revalidate Testing
-
-**Objective**: Test stale data serving while refreshing in background.
-
-**Steps**:
-1. Cache some data and wait for it to become stale
-2. Request the stale data
-3. Verify immediate response with stale data
-4. Confirm background refresh occurs
-
-**Expected Results**:
-- Stale data is served immediately for fast response
-- Background refresh updates the cache
-- User gets immediate response, cache stays fresh
-- No blocking on refresh operations
-
-**Success Criteria**: Stale-while-revalidate provides fast responses while maintaining freshness
-
-## 4. Tool Registry Tests
-
-### 4.1 All Tools Accessibility
-
-**Objective**: Verify all tools are accessible through Claude Desktop.
-
-**Steps**:
-1. Ask Claude to list available YNAB tools
-2. Test a selection of tools from different categories:
-   - Budget management (list_budgets, set_default_budget)
-   - Account management (list_accounts, get_account)
-   - Transaction management (list_transactions, create_transaction)
-   - Monthly data analysis (get_month, list_months)
-   - Utility tools (diagnostic_info, convert_amount)
-
-**Expected Results**:
-- All tools are accessible and respond correctly
-- Parameter validation works consistently
-- Error handling is uniform across tools
-- Tool descriptions are helpful and accurate
-
-**Success Criteria**: All tools accessible with consistent behavior
-
-### 4.2 Parameter Validation
-
-**Objective**: Test parameter validation across different tools.
-
-**Steps**:
-1. Try tools with missing required parameters
-2. Try tools with invalid parameter values
-3. Try tools with correct parameters
-4. Test optional parameter handling
-
-**Expected Results**:
-- Missing required parameters result in clear error messages
-- Invalid parameters are rejected with helpful guidance
-- Valid parameters are processed correctly
-- Optional parameters work when provided or omitted
-
-**Success Criteria**: Consistent parameter validation with helpful error messages
-
-## 5. Transaction Management Tests
-
-### 5.1 Transaction Creation
-
-**Objective**: Test creating new transactions.
-
-**Steps**:
-1. Ask Claude: "Create a test transaction for $10.00 groceries"
-2. Verify transaction appears in YNAB
-3. Check transaction details
-4. Clean up test transaction
-
-**Expected Results**:
-- Transaction is created successfully
-- All details are recorded correctly
-- Transaction appears in YNAB interface
-- Appropriate account and category are used
-
-**Success Criteria**: Transaction creation works with accurate data
-
-### 5.2 Transaction Export
-
-**Objective**: Test transaction export functionality.
-
-**Steps**:
-1. Ask Claude: "Export my transactions to a file"
-2. Check export directory for file
-3. Review exported data format
-4. Verify data completeness
-
-**Expected Results**:
-- Export file is created in correct directory
-- File contains accurate transaction data
-- Format is readable and well-structured
-- All requested transactions are included
-
-**Success Criteria**: Export creates complete, accurate files
-
-### 5.3 CSV Comparison
-
-**Objective**: Test CSV comparison functionality.
-
-**Steps**:
-1. Use a sample CSV file
-2. Ask Claude: "Compare this CSV with my YNAB transactions"
-3. Review matching results
-4. Check unmatched transaction identification
-
-**Expected Results**:
-- CSV parsing works correctly
-- Transaction matching algorithms function properly
-- Unmatched transactions are identified
-- Clear reporting of comparison results
-
-**Success Criteria**: CSV comparison accurately identifies matches and discrepancies
-
-### 5.4 Account Reconciliation
-
-**Objective**: Test comprehensive account reconciliation.
-
-**Steps**:
-1. Prepare CSV export from your bank
-2. Ask Claude: "Reconcile my checking account with this CSV"
-3. Review matching analysis
-4. Check balance verification
-5. Review recommendations
-
-**Expected Results**:
-- Smart duplicate matching works correctly
-- Automatic date adjustment handles timezone issues
-- Balance matching provides exact reconciliation
-- Comprehensive reporting shows all details
-
-**Success Criteria**: Reconciliation accurately matches transactions and balances
-
-## 6. Error Handling Tests
-
-### 6.1 Missing Budget ID Scenarios
-
-**Objective**: Test behavior when no default budget is set.
-
-**Steps**:
-1. Clear default budget setting
-2. Try tools that require budget context
-3. Check error messages
-4. Verify recovery guidance
-
-**Expected Results**:
-- Clear error messages about missing budget
-- Helpful guidance on setting default budget
-- No system crashes or unclear errors
-- Easy recovery path provided
-
-**Success Criteria**: Clear error messages with actionable recovery steps
-
-### 6.2 Invalid Parameter Testing
-
-**Objective**: Test handling of invalid parameters.
-
-**Steps**:
-1. Try tools with malformed parameters
-2. Test with out-of-range values
-3. Try with incorrect data types
-4. Test with missing required fields
-
-**Expected Results**:
-- Validation catches all invalid parameters
-- Error messages clearly identify the problem
-- Suggestions for correct parameter format
-- No system instability from bad inputs
-
-**Success Criteria**: Robust parameter validation with helpful error messages
-
-### 6.3 YNAB API Error Scenarios
-
-**Objective**: Test handling of YNAB API errors.
-
-**Steps**:
-1. Test with expired token (if possible)
-2. Test during YNAB API maintenance
-3. Test with network connectivity issues
-4. Test with rate limiting scenarios
-
-**Expected Results**:
-- Graceful handling of API errors
-- Clear error messages about external issues
-- No server crashes or hangs
-- Appropriate retry mechanisms
-
-**Success Criteria**: Robust error handling for external API issues
-
-## 7. Performance Tests
-
-### 7.1 Response Time Verification
-
-**Objective**: Verify acceptable response times with and without caching.
-
-**Steps**:
-1. Measure response times for fresh requests
-2. Measure response times for cached requests
-3. Compare performance improvements
-4. Test with large data sets
-
-**Expected Results**:
-- Fresh requests complete within reasonable time (< 5 seconds)
-- Cached requests are significantly faster (< 1 second)
-- Large data sets are handled efficiently
-- No performance degradation over time
-
-**Success Criteria**: Response times meet performance expectations
-
-### 7.2 Concurrent Request Handling
-
-**Objective**: Test server behavior under concurrent load.
-
-**Steps**:
-1. Make multiple simultaneous requests
-2. Check for race conditions
-3. Verify data consistency
-4. Monitor resource usage
-
-**Expected Results**:
-- Concurrent requests handled properly
-- No race conditions in cache or data
-- Consistent results across all requests
-- Reasonable resource usage
-
-**Success Criteria**: Stable performance under concurrent load
-
-### 7.3 Memory Usage Monitoring
-
-**Objective**: Verify memory usage remains stable during extended use.
-
-**Steps**:
-1. Monitor baseline memory usage
-2. Perform extended testing session
-3. Check for memory leaks
-4. Verify cache size limits are respected
-
-**Expected Results**:
-- Memory usage remains stable over time
-- No significant memory leaks detected
-- Cache eviction prevents unbounded growth
-- Resource usage stays within acceptable limits
-
-**Success Criteria**: Stable memory usage without leaks
-
-## Test Data Management
-
-### Mock Data
-- Unit and integration tests use mock data
-- Mock responses are defined in test files
-- No real API calls or data modification
-
-### E2E Test Data
-- E2E tests create real data in your YNAB budget
-- Test transactions are automatically cleaned up
-- Test accounts cannot be deleted via API (manual cleanup required)
-- Use a dedicated test budget to avoid affecting real data
-
-## Common Issues and Solutions
-
-### E2E Tests Skipped
-```
-⏭️ E2E tests skipped (no API key or SKIP_E2E_TESTS=true)
-```
-**Solution**: Set `YNAB_ACCESS_TOKEN` environment variable
-
-### Coverage Below Threshold
-```
-⚠️ Coverage below target (<80%)
-```
-**Solution**: Add more tests or remove untestable code from coverage
-
-### Performance Tests Failing
-```
-❌ Performance assertion failed: 1500ms > 1000ms
-```
-**Solution**: Optimize code or adjust performance thresholds
-
-### Connection Errors in Claude Desktop
-**Solution**:
-1. Verify Node.js version (18+)
-2. Check build completed successfully
-3. Verify MCP server configuration
-4. Restart Claude Desktop completely
-
-## Test Execution Guidelines
-
-1. **Prerequisites**: Ensure .env file is configured with valid YNAB token
-2. **Environment**: Use development configuration for detailed logging
-3. **Documentation**: Record results for each test scenario
-4. **Issues**: Log any problems with steps to reproduce
-5. **Performance**: Record timing measurements for performance tests
-6. **Cleanup**: Clean up test data after testing (transactions, exports)
-
-## Success Criteria Summary
-
-- ✅ All basic functionality works correctly
-- ✅ Enhanced caching provides performance improvements
-- ✅ Error handling is robust and helpful
-- ✅ All tools are accessible and functional
-- ✅ Transaction management works reliably
-- ✅ Performance meets or exceeds expectations
-- ✅ Integration with Claude Desktop is seamless
-- ✅ Security and reliability standards are met
-
----
-
-For automated testing implementation details, see the source code in `src/__tests__/`.
-For additional testing checklists, see `../development/TESTING_CHECKLIST.md`.

package/docs/reconciliation-flow.md

@@ -1,83 +0,0 @@
----
-title: 'Automated Reconciliation Flow'
-status: 'active'
-last_updated: '2025-11-12'
-owners:
-  - '@ynab-mcpb/tooling'
-related_docs:
-  - reference/API.md#reconcile_account
-  - reference/TOOLS.md#reconcile_account
-  - guides/TESTING.md#comprehensive-account-reconciliation
-  - reference/TROUBLESHOOTING.md#reconciliation
----
-
-# Automated Reconciliation Flow
-
-Deterministic playbook for reconciling a YNAB account with a bank statement inside the MCP host. The flow runs newest → oldest, stops the moment balances align, and emits both a narrative and machine-readable payload for assistants and downstream automation.
-
-## Prerequisites & Environment
-- Provide a valid `.env` cloned from `.env.example`, including `YNAB_ACCESS_TOKEN`, cache knobs, and any per-budget rate limits. Run `npm run validate-env` whenever secrets change.
-- Install dependencies with `npm install`, keep `node` ≥ 20, and prefer `npm run dev` while editing to recompile TypeScript incrementally.
-- Reconciliation tools assume access to CSV statements on disk (`csv_file_path`) or piped data (`csv_data`). Files should stay inside the workspace to avoid sandbox denials.
-- Vitest snapshot directories (`test-results/`) must be writable; dry-run audits reference these to highlight regression diffs.
-
-## Schema & Data Contracts
-- **Input contract** – `ReconcileAccountSchema` (`src/tools/reconciliation/index.ts`) enforces budget/account ids, CSV source, statement balance, and guard rails like date/amount tolerances, automation toggles, and confidence thresholds. Every entry path calls `ReconcileAccountSchema.parse(...)` before touching the YNAB API.
-- **CSV normalization** – `autoDetectCSVFormat` plus `extractDateRangeFromCSV` deduce header presence, delimiter, debit/credit pairs, and generate the reconciliation window (min/max ± 5 days buffer).
-- **Structured output** – `buildReconciliationPayload` + `responseFormatter` return `version: '2.0'` JSON (see `docs/schemas/reconciliation-v2.json`) alongside the human narrative. This payload captures matches, actions, balance deltas, and flags like `audit_trail_complete`.
-- **Audit snapshot** – `buildBalanceReconciliation` records `precision_calculations`, `discrepancy_analysis`, and `final_verification` booleans, ensuring downstream tooling can prove reconciliation outcomes without re-querying YNAB.
-
-## Configuration Knobs (Schema Excerpts)
-- Matching tolerances: `date_tolerance_days` (0-7, default 5) and `amount_tolerance_cents` (default 1¢) gate candidate searches; `confidence_threshold` (0.8) controls risk when auto-clearing.
-- Automation toggles: `auto_create_transactions`, `auto_update_cleared_status`, `auto_adjust_dates`, `auto_unclear_missing`, `dry_run`, and `balance_verification_mode` (`ANALYSIS_ONLY`, `GUIDED_RESOLUTION`, `AUTO_RESOLVE`).
-- CSV format overrides: `csv_format.{date_column, amount_column, debit_column, credit_column, date_format, has_header, delimiter}` keep unusual exports usable without retooling the parser.
-- Safety rails: `require_exact_match` and `max_resolution_attempts` prevent runaway loops; `include_structured_data` controls whether assistants receive the payload blob.
-
-## Logging & Auditability
-- Every mutation funnels through `responseFormatter` with `execution.summary` stats plus `matches_found`, `transactions_created`, and `transactions_updated` counts for dashboards.
-- `buildBalanceReconciliation` emits `audit_trail_complete`, balance math, and likely-cause hints whenever a discrepancy persists.
-- `executor.ts` annotates each action with reasons (e.g., "marked as cleared, date adjusted"), giving a linear log for SOC review.
-- Tests under `src/tools/reconciliation/__tests__/` assert both narrative text and structured payloads; failures drop sanitized artifacts into `test-results/` for diffing.
-
-## Numbered Steps, Rationale, and Validation Hooks
-### Step 1 — Input validation & window detection
-- **Rationale**: Prevents wasting API calls on malformed CSVs and ensures the comparison window brackets all relevant transactions.
-- **What happens**: Parse CSV metadata, normalize amounts/dates, derive min/max window ±5 days, and hydrate default tolerances through `ReconcileAccountSchema.parse(...)`. Liability accounts invert statement balance sign for consistent delta math.
-- **Validation**: Unit coverage in `src/tools/reconciliation/__tests__/parser.*` plus `npm run validate-env` to guarantee credentials before file I/O occurs.
-- **Open questions**: Should we persist detected CSV format to `test-exports/` for reuse, or is in-memory derivation sufficient for multi-pass sessions?
-
-### Step 2 — Phase 1 statement pass (newest → oldest)
-- **Rationale**: Mirroring experienced YNAB workflows short-circuits once balances match, avoiding needless mutation of ancient rows.
-- **What happens**: Sort bank rows descending, compute `cleared_delta = ynab.cleared - statement_balance`, and for each row find best YNAB candidate within tolerances + payee similarity. If confidence ≥ `auto_match_threshold` and automation toggles allow, clear/update/auto-create transactions. Recalculate `cleared_delta` after every action; halt once |delta| ≤ tolerance.
-- **Validation**: `findBestMatch` integration tests ensure deterministic candidate ordering; we also assert log completeness (`audit_trail_complete`) in executor tests.
-- **Open questions**: Do we need adaptive confidence thresholds for larger ledgers (>1k rows) to limit runtime, or is the static percentage enough?
-
-### Step 3 — Phase 2 cleared-YNAB sanity pass
-- **Rationale**: Detects stale cleared transactions that never appeared on the bank statement, a common source of lingering deltas.
-- **What happens**: Iterate YNAB transactions with `cleared === 'cleared'` but `reconciled === false` inside the CSV window ±5 days. Attempt to re-match them to leftover bank rows; otherwise flip to `uncleared` when `auto_unclear_missing` is true and recompute `cleared_delta`.
-- **Validation**: Executor tests (`executor.sanity-pass.test.ts`) verify we never un-clear reconciled items, and dry-run mode logs intended actions without mutating YNAB.
-- **Open questions**: Should we surface a preview of would-be un-cleared transactions in dry-run mode to the structured payload for UI display?
-
-### Step 4 — Finalize reconciliation
-- **Rationale**: Once balances align, we need a trusted checkpoint recording statement date/balance plus an auditable list of touched transactions.
-- **What happens**: Prompt the assistant/user to finish reconciliation, set involved transactions to `reconciled`, and call `buildBalanceReconciliation` to persist precision math and `final_verification` booleans.
-- **Validation**: Snapshot tests assert the `execution.account_balance.before/after` objects stay monotonic; manual validation by rerunning `npm test -- --runInBand` ensures no race with parallel Vitest workers.
-- **Open questions**: Should we enforce that `statement_date` is required at this stage, or keep the current fallback to `statement_end_date` if missing?
-
-### Step 5 — Leftover escalation & operator handoff
-- **Rationale**: Keeping humans in the loop for medium/low-confidence matches prevents silent drift when automation can’t safely conclude.
-- **What happens**: Surface structured `recommendations` containing low-confidence suggestions, unmatched bank-only rows, and the list of transactions auto un-cleared during Step 3. The narrative outlines manual review order, while the JSON payload allows clients to build UI cards (see `reference/TROUBLESHOOTING.md#reconciliation`).
-- **Validation**: Adapter tests verify `buildReconciliationPayload` includes each unresolved set with counts, and E2E scripts (`test-reconcile-autodetect.js`) confirm the CLI prints the same inventory of leftovers.
-- **Open questions**: Do we need a SLA timer/escalation hook (e.g., Slack webhook) when leftovers include more than N transactions, or is assistant messaging enough?
-
-### Step 6 — Retriable automation & telemetry feedback
-- **Rationale**: Audit logs inform future tuning (e.g., tolerance adjustments) and enable replays without re-parsing inputs.
-- **What happens**: Persist log streams, emit `execution.summary` stats, and optionally rerun the flow with updated knobs (e.g., `balance_verification_mode = 'GUIDED_RESOLUTION'`) using the same CSV payload. Telemetry consumers watch `audit_trail_complete` and `discrepancy_analysis` to decide whether another automated attempt is viable.
-- **Validation**: `docs/guides/TESTING.md#comprehensive-account-reconciliation` details the manual harness; CI pipelines run `npm run test:comprehensive` to ensure telemetry fields stay backwards compatible.
-- **Open questions**: Should we snapshot anonymized telemetry for regression dashboards, or does that introduce privacy concerns with customer CSVs?
-
-## Testing Hooks & Cross-links
-- Follow the **Comprehensive Account Reconciliation** playbook in `[docs/guides/TESTING.md](guides/TESTING.md#comprehensive-account-reconciliation)` to exercise CSV parsing, matching, and execution paths end-to-end.
-- Tool contract reference lives in `[docs/reference/API.md#reconcile_account](reference/API.md#reconcile_account)` and `[docs/reference/TOOLS.md#reconcile_account](reference/TOOLS.md#reconcile_account)`; keep this doc updated when schemas there change.
-- Troubleshooting steps for stubborn discrepancies are cataloged in `[docs/reference/TROUBLESHOOTING.md#reconciliation](reference/TROUBLESHOOTING.md#reconciliation)`; link to this when raising escalation tickets.
-- Local scripts (`test-reconcile-tool.js`, `test-reconcile-autodetect.js`) double as reproducible demonstrations—capture their JSON output and attach to `.pr-description.md` when documenting reconciliation changes.