@dizzlkheinz/ynab-mcpb 0.16.1 → 0.17.1

package/.code/agents/234ff534-2336-4771-a8d9-aa04421a63be/result.txt

@@ -1,747 +0,0 @@
-Based on my analysis of the YNAB MCP Server codebase, I'll create a comprehensive implementation plan for the next iteration. The repo has three pending plans that represent excellent next steps. Let me synthesize these into a cohesive, actionable plan:
-
----
-
-# **YNAB MCP Server v0.14.x Implementation Plan**
-
-**Project:** YNAB MCP Server (Model Context Protocol server for YNAB integration)  
-**Repository:** C:/Users/ksutk/projects/ynab-mcpb  
-**Current Version:** 0.13.4  
-**Target Version:** 0.14.0  
-**Architecture:** TypeScript/Node.js 18+, MCP SDK, Vitest testing  
-
-## **Executive Summary**
-
-This plan consolidates three high-priority improvements identified in `docs/plans/`:
-
-1. **Reloadable Config & Token Validation** - Improve testability and error handling
-2. **Reconciliation Error Handling** - Surface YNAB API errors properly  
-3. **Fix Transaction Cached Property** - Consistency in large response paths (ALREADY COMPLETED per CHANGELOG)
-
-The implementation follows TDD methodology with 2-5 minute task granularity, targeting concrete file paths and test patterns.
-
----
-
-## **Priority 1: Reloadable Config & Token Validation**
-
-**Goal:** Make config parsing reloadable for environment-mutation tests, harden token validation against malformed API responses, and improve CI portability.
-
-**Files Modified:**
-- `src/server/config.ts`
-- `src/server/YNABMCPServer.ts`
-- `src/server/__tests__/config.test.ts`
-- `src/server/__tests__/YNABMCPServer.test.ts`
-- `src/server/__tests__/server-startup.integration.test.ts`
-- `scripts/run-throttled-integration-tests.js`
-
-**Rationale:** Current config is module-scoped, making it difficult to test environment changes without module reloads. Token validation doesn't gracefully handle non-JSON YNAB responses (HTML error pages, etc.).
-
----
-
-### **Task 1.1: Implement Reloadable Config Loader**
-
-**Test-First Approach:**
-
-**Step 1** (2 min): Write failing test for reloadable behavior  
-**File:** `src/server/__tests__/config.test.ts`  
-**Action:** Add test case (already exists at line 18-25 but verify it passes):
-```typescript
-it('reloads environment variables on each loadConfig call', async () => {
-  const { loadConfig } = await import('../config');
-  process.env.YNAB_ACCESS_TOKEN = 'test-token-123';
-  expect(loadConfig().YNAB_ACCESS_TOKEN).toBe('test-token-123');
-  
-  process.env.YNAB_ACCESS_TOKEN = 'updated-token-456';
-  expect(loadConfig().YNAB_ACCESS_TOKEN).toBe('updated-token-456');
-});
-```
-**Verification:** `npx vitest run src/server/__tests__/config.test.ts`  
-**Expected:** Should already pass based on current implementation (line 14-21 in config.ts)
-
-**Step 2** (1 min): Verify singleton behavior is preserved  
-**File:** `src/server/__tests__/config.test.ts`  
-**Action:** Ensure test at line 27-35 passes (singleton `config` uses initial parse, `loadConfig()` re-parses)  
-**Verification:** `npx vitest run src/server/__tests__/config.test.ts`
-
-**Step 3** (2 min): Add test for explicit env override  
-**File:** `src/server/__tests__/config.test.ts`  
-**Action:** Add test case:
-```typescript
-it('accepts explicit env parameter for testing', async () => {
-  const { loadConfig } = await import('../config');
-  const testEnv = { YNAB_ACCESS_TOKEN: 'explicit-token' };
-  expect(loadConfig(testEnv).YNAB_ACCESS_TOKEN).toBe('explicit-token');
-});
-```
-**Verification:** `npx vitest run src/server/__tests__/config.test.ts`  
-**Expected:** Pass (already supported at config.ts:14)
-
-**Step 4** (1 min): Run full config test suite  
-**Command:** `npx vitest run src/server/__tests__/config.test.ts`  
-**Expected:** All tests pass
-
----
-
-### **Task 1.2: Inject Per-Instance Config into YNABMCPServer**
-
-**Implementation Approach:**
-
-**Step 1** (3 min): Add test for per-instance config isolation  
-**File:** `src/server/__tests__/YNABMCPServer.test.ts`  
-**Action:** Add test case:
-```typescript
-it('uses per-instance config instead of module singleton', async () => {
-  process.env.YNAB_ACCESS_TOKEN = 'instance-1-token';
-  const server1 = new YNABMCPServer();
-  
-  process.env.YNAB_ACCESS_TOKEN = 'instance-2-token';
-  const server2 = new YNABMCPServer();
-  
-  // Verify each server uses its instantiation-time config
-  // Implementation detail: check via diagnostic_info or internal state
-  expect(server1).toBeDefined();
-  expect(server2).toBeDefined();
-});
-```
-**Verification:** `npx vitest run src/server/__tests__/YNABMCPServer.test.ts`  
-**Expected:** Fail initially (requires code change)
-
-**Step 2** (4 min): Modify YNABMCPServer constructor  
-**File:** `src/server/YNABMCPServer.ts`  
-**Action:** In constructor (around line 150-200):
-- Change from `import { config }` to using `loadConfig()`
-- Store `private readonly serverConfig: AppConfig`
-- Initialize as: `this.serverConfig = loadConfig();`
-- Use `this.serverConfig.YNAB_ACCESS_TOKEN` for YNAB API instantiation
-- Update all references from `config.YNAB_ACCESS_TOKEN` to `this.serverConfig.YNAB_ACCESS_TOKEN`
-
-**Step 3** (2 min): Re-run tests  
-**Command:** `npx vitest run src/server/__tests__/YNABMCPServer.test.ts`  
-**Expected:** Test from Step 1 now passes
-
-**Step 4** (2 min): Update integration tests  
-**File:** `src/server/__tests__/server-startup.integration.test.ts`  
-**Action:** Ensure tests expect `ValidationError` from `loadConfig()` failures  
-**Verification:** `npx vitest run src/server/__tests__/server-startup.integration.test.ts`
-
----
-
-### **Task 1.3: Token Validation Resilience**
-
-**Goal:** Handle non-JSON YNAB responses gracefully (HTML error pages, malformed JSON).
-
-**Step 1** (3 min): Write failing test for non-JSON response  
-**File:** `src/server/__tests__/server-startup.integration.test.ts`  
-**Action:** Add test case:
-```typescript
-it('throws AuthenticationError for malformed YNAB API responses', async () => {
-  const mockAPI = {
-    user: {
-      getUser: vi.fn().mockRejectedValue(new SyntaxError('Unexpected token < in JSON'))
-    }
-  };
-  
-  await expect(validateToken(mockAPI as any))
-    .rejects.toThrow(AuthenticationError);
-  await expect(validateToken(mockAPI as any))
-    .rejects.toThrow(/Unexpected response from YNAB/);
-});
-```
-**Verification:** `npx vitest run src/server/__tests__/server-startup.integration.test.ts`  
-**Expected:** Fail (no try-catch for SyntaxError yet)
-
-**Step 2** (4 min): Implement graceful error handling  
-**File:** `src/server/YNABMCPServer.ts`  
-**Action:** In `validateToken()` method (locate via search for "validateToken"):
-```typescript
-private async validateToken(api: ynab.API): Promise<void> {
-  try {
-    await api.user.getUser();
-  } catch (error: unknown) {
-    // Handle SyntaxError (malformed JSON), HTML responses, network errors
-    if (error instanceof SyntaxError || 
-        (error instanceof Error && error.message.includes('JSON'))) {
-      throw new AuthenticationError(
-        'Unexpected response from YNAB during token validation. ' +
-        'Please verify your token is valid at https://app.youneedabudget.com/settings/developer'
-      );
-    }
-    
-    // Handle 401/403 as before
-    if (isYNABError(error) && [401, 403].includes(error.status)) {
-      throw new AuthenticationError(
-        'Invalid YNAB access token. Get a new token at: ' +
-        'https://app.youneedabudget.com/settings/developer'
-      );
-    }
-    
-    throw error; // Rethrow other errors
-  }
-}
-```
-
-**Step 3** (2 min): Re-run validation tests  
-**Command:** `npx vitest run src/server/__tests__/server-startup.integration.test.ts`  
-**Expected:** All tests pass
-
----
-
-### **Task 1.4: Windows Portability for Test Runner**
-
-**Step 1** (3 min): Fix throttled integration test runner for Windows  
-**File:** `scripts/run-throttled-integration-tests.js`  
-**Action:** Replace `.cmd` spawning with portable approach:
-```javascript
-const { spawn } = require('child_process');
-const path = require('path');
-
-// Locate vitest binary portably
-const vitestBin = path.resolve(__dirname, '../node_modules/.bin/vitest');
-const vitestCmd = process.platform === 'win32' ? `${vitestBin}.cmd` : vitestBin;
-
-const proc = spawn('node', [vitestCmd, ...args], { 
-  stdio: 'inherit',
-  shell: process.platform === 'win32' 
-});
-```
-**Verification:** `node scripts/run-throttled-integration-tests.js --help` (should not throw EINVAL)
-
-**Step 2** (1 min): Test script execution on Windows  
-**Command:** `node scripts/run-throttled-integration-tests.js --help`  
-**Expected:** Help output without spawn errors
-
----
-
-### **Task 1.5: Full Verification**
-
-**Step 1** (3 min): Run unit test suite  
-**Command:** `npm test`  
-**Expected:** All 1334 tests pass (59 files)
-
-**Step 2** (5 min): Run core integration tests with valid token  
-**Command:** `npm run test:integration:core` (requires `YNAB_ACCESS_TOKEN` in env)  
-**Expected:** Integration tests pass or skip appropriately
-
-**Step 3** (2 min): Type-check codebase  
-**Command:** `npm run type-check`  
-**Expected:** 0 TypeScript errors
-
-**Step 4** (2 min): Commit changes  
-**Commands:**
-```bash
-git add src/server/config.ts src/server/YNABMCPServer.ts src/server/__tests__/*.ts scripts/run-throttled-integration-tests.js
-git commit -m "feat: reloadable config with per-instance isolation and robust token validation
-
-- Config loader now re-parses environment on each call for testability
-- YNABMCPServer uses per-instance config instead of module singleton
-- Token validation gracefully handles non-JSON YNAB responses
-- Throttled test runner portable to Windows (fixes spawn EINVAL)
-- Improves CI reliability and test isolation"
-```
-
----
-
-## **Priority 2: Reconciliation Error Handling**
-
-**Goal:** Propagate YNAB API errors (rate limits, invalid accounts, 404s) properly during reconciliation instead of silently returning zero creations.
-
-**Files Modified:**
-- `src/tools/reconciliation/executor.ts`
-- `src/tools/reconciliation/__tests__/executor.test.ts`
-- `src/tools/reconciliation/__tests__/executor.integration.test.ts`
-
-**Rationale:** Current executor catches all errors during bulk/sequential creation but doesn't distinguish fatal errors (404, 429) from transient ones. Tests expect failures but get silent 0-creation results.
-
----
-
-### **Task 2.1: Add Error Normalization Utilities**
-
-**Step 1** (4 min): Write unit test for error normalization  
-**File:** `src/tools/reconciliation/__tests__/executor.test.ts`  
-**Action:** Add test cases:
-```typescript
-describe('YNAB Error Normalization', () => {
-  it('normalizes YNAB API error objects with status codes', () => {
-    const ynabError = { error: { id: '429', detail: 'Too many requests' } };
-    const normalized = normalizeYnabError(ynabError);
-    expect(normalized.status).toBe(429);
-    expect(normalized.message).toContain('Too many requests');
-  });
-  
-  it('normalizes standard Error objects', () => {
-    const error = new Error('Network failure');
-    const normalized = normalizeYnabError(error);
-    expect(normalized.message).toBe('Network failure');
-  });
-  
-  it('identifies propagation-worthy errors', () => {
-    expect(shouldPropagateYnabError({ status: 429 })).toBe(true);
-    expect(shouldPropagateYnabError({ status: 404 })).toBe(true);
-    expect(shouldPropagateYnabError({ status: 500 })).toBe(true);
-    expect(shouldPropagateYnabError({ status: undefined })).toBe(false);
-  });
-});
-```
-**Verification:** `npx vitest run src/tools/reconciliation/__tests__/executor.test.ts -t "YNAB Error Normalization"`  
-**Expected:** Fail (functions don't exist yet)
-
-**Step 2** (5 min): Implement error normalization functions  
-**File:** `src/tools/reconciliation/executor.ts`  
-**Action:** Add near helper section (before `executeReconciliation`):
-```typescript
-interface NormalizedYnabError {
-  status?: number;
-  name?: string;
-  message: string;
-  detail?: string;
-}
-
-function normalizeYnabError(err: unknown): NormalizedYnabError {
-  // YNAB SDK error format: { error: { id: '429', detail: '...', name: 'rate_limit' } }
-  if (typeof err === 'object' && err !== null && 'error' in err) {
-    const ynabErr = (err as any).error;
-    return {
-      status: parseInt(ynabErr.id) || undefined,
-      name: ynabErr.name,
-      message: ynabErr.detail || ynabErr.name || 'YNAB API error',
-      detail: ynabErr.detail,
-    };
-  }
-  
-  // Standard Error object
-  if (err instanceof Error) {
-    return { message: err.message, name: err.name };
-  }
-  
-  // String error
-  if (typeof err === 'string') {
-    return { message: err };
-  }
-  
-  return { message: 'Unknown error' };
-}
-
-function shouldPropagateYnabError(err: NormalizedYnabError): boolean {
-  // Fatal errors that should bubble up
-  return [401, 403, 404, 429, 500, 503].includes(err.status ?? 0);
-}
-
-function attachStatus(err: NormalizedYnabError): Error {
-  const error = new Error(err.message || err.detail || 'YNAB API error');
-  if (err.status) (error as any).status = err.status;
-  if (err.name) error.name = err.name;
-  return error;
-}
-```
-
-**Step 3** (2 min): Re-run unit tests  
-**Command:** `npx vitest run src/tools/reconciliation/__tests__/executor.test.ts -t "YNAB Error Normalization"`  
-**Expected:** All normalization tests pass
-
----
-
-### **Task 2.2: Update Bulk Creation Error Handling**
-
-**Step 1** (3 min): Add test for bulk creation rate limit propagation  
-**File:** `src/tools/reconciliation/__tests__/executor.integration.test.ts`  
-**Action:** Add test:
-```typescript
-it('propagates rate limit errors during bulk creation', async () => {
-  mockCreateTransactions.rejects({ 
-    error: { id: '429', detail: 'Too many requests', name: 'rate_limit' } 
-  });
-  
-  await expect(executeReconciliation({
-    ynabAPI: mockAPI,
-    analysis: mockAnalysisWithUnmatched,
-    params: mockParams,
-    budgetId: 'test-budget',
-    accountId: 'test-account',
-    initialAccount: mockAccount,
-    currencyCode: 'USD',
-  })).rejects.toMatchObject({ status: 429 });
-});
-```
-**Verification:** `npx vitest run --project integration:core --testNamePattern="propagates rate limit"`  
-**Expected:** Fail (currently catches all errors)
-
-**Step 2** (4 min): Modify bulk chunk error handling  
-**File:** `src/tools/reconciliation/executor.ts`  
-**Action:** In `processBulkChunk` catch block (search for "bulk_chunk_failures"):
-```typescript
-catch (error) {
-  const ynabErr = normalizeYnabError(error);
-  
-  // Propagate fatal errors
-  if (shouldPropagateYnabError(ynabErr)) {
-    throw attachStatus(ynabErr);
-  }
-  
-  // Log non-fatal bulk failures and fall back to sequential
-  const reason = ynabErr.message || 'Unknown error';
-  bulkOperationDetails.bulk_chunk_failures += 1;
-  actions_taken.push({ 
-    type: 'bulk_create_fallback', 
-    reason: `Bulk chunk #${chunkIndex} failed (${reason}). Falling back to sequential creation.`
-  });
-}
-```
-
-**Step 3** (2 min): Re-run integration test  
-**Command:** `npx vitest run --project integration:core --testNamePattern="propagates rate limit"`  
-**Expected:** Test passes
-
----
-
-### **Task 2.3: Update Sequential Creation Error Handling**
-
-**Step 1** (3 min): Add test for invalid account error  
-**File:** `src/tools/reconciliation/__tests__/executor.test.ts`  
-**Action:** Add test:
-```typescript
-it('propagates invalid account errors during sequential creation', async () => {
-  mockCreateTransaction.rejects({ 
-    error: { id: '404', detail: 'Account not found', name: 'not_found' } 
-  });
-  
-  await expect(executeReconciliation({...})).rejects.toMatchObject({ 
-    status: 404,
-    message: expect.stringContaining('Account not found')
-  });
-});
-```
-**Verification:** `npx vitest run src/tools/reconciliation/__tests__/executor.test.ts -t "invalid account"`  
-**Expected:** Fail
-
-**Step 2** (4 min): Modify sequential creation error handling  
-**File:** `src/tools/reconciliation/executor.ts`  
-**Action:** In sequential creation loop catch block (search for "create_transaction_failed"):
-```typescript
-catch (error) {
-  const ynabErr = normalizeYnabError(error);
-  const failureReason = ynabErr.message || 'Unknown error';
-  
-  results.transaction_failures += 1;
-  actions_taken.push({ 
-    type: 'create_transaction_failed',
-    bank_transaction_id: bankTx.id,
-    reason: `Failed to create transaction: ${failureReason}${ynabErr.status ? ` (HTTP ${ynabErr.status})` : ''}`
-  });
-  
-  // Propagate fatal errors after logging
-  if (shouldPropagateYnabError(ynabErr)) {
-    throw attachStatus(ynabErr);
-  }
-}
-```
-
-**Step 3** (2 min): Re-run test  
-**Command:** `npx vitest run src/tools/reconciliation/__tests__/executor.test.ts -t "invalid account"`  
-**Expected:** Pass
-
----
-
-### **Task 2.4: Update Action Reason Logging**
-
-**Step 1** (3 min): Add test for rate limit detection in action log  
-**File:** `src/tools/reconciliation/__tests__/executor.integration.test.ts`  
-**Action:** Add helper and test:
-```typescript
-function containsRateLimitFailure(actions: any[]): boolean {
-  return actions.some(a => 
-    a.reason?.includes('429') || 
-    a.reason?.toLowerCase().includes('rate limit') ||
-    a.reason?.includes('Too many requests')
-  );
-}
-
-it('includes rate limit status in action reasons', async () => {
-  mockCreateTransactions.rejects({ error: { id: '429', detail: 'Too many requests' } });
-  
-  try {
-    await executeReconciliation({...});
-  } catch (err) {
-    // Error should propagate
-    expect((err as any).status).toBe(429);
-  }
-  
-  // If fallback occurred, actions should mention rate limit
-  // (Test expectations depend on whether error propagates before logging)
-});
-```
-
-**Step 2** (2 min): Verify action reasons include status codes  
-**Action:** Review code from Task 2.2 Step 2 and Task 2.3 Step 2 to ensure:
-- Action reasons include HTTP status when available
-- Wording is consistent (`(HTTP 429)` format)
-
-**Step 3** (2 min): Run integration tests  
-**Command:** `npm run test:integration:reconciliation` (if configured) or `npx vitest run --project integration --testPathPattern=reconciliation`  
-**Expected:** Tests pass or skip on rate limits (not silent 0-creations)
-
----
-
-### **Task 2.5: Full Verification**
-
-**Step 1** (3 min): Run reconciliation unit tests  
-**Command:** `npx vitest run src/tools/reconciliation/__tests__/executor.test.ts`  
-**Expected:** All tests pass
-
-**Step 2** (5 min): Run reconciliation integration tests  
-**Command:** `npm run test:integration:reconciliation` (requires YNAB token)  
-**Expected:** Tests pass with proper error propagation
-
-**Step 3** (2 min): Commit changes  
-**Commands:**
-```bash
-git add src/tools/reconciliation/executor.ts src/tools/reconciliation/__tests__/executor*.test.ts
-git commit -m "fix: propagate fatal YNAB API errors during reconciliation
-
-- Add error normalization layer to distinguish fatal vs transient failures
-- Propagate 401/403/404/429/500/503 errors instead of silencing
-- Include HTTP status codes in action failure reasons
-- Improve rate limit detection in integration tests
-- Fixes silent 0-creation failures when account invalid or rate limited"
-```
-
----
-
-## **Priority 3: Fix Transaction Cached Property** ✅
-
-**Status:** ALREADY COMPLETED in v0.13.1 (per CHANGELOG.md line 48-51)
-
-**Evidence:**
-- CHANGELOG entry: "Fixed missing `cached` property in large transaction list responses (>90KB)"
-- Implementation details match plan in `docs/plans/2025-11-21-fix-transaction-cached-property.md`
-
-**No action required.** This can be removed from the planning queue.
-
----
-
-## **Additional Quality Improvements (Optional)**
-
-These tasks can be tackled after Priorities 1-2:
-
-### **Task 3.1: Improve Test Coverage Visibility**
-
-**Step 1** (2 min): Add coverage badge to README  
-**File:** `README.md`  
-**Action:** Add after existing badges:
-```markdown
-[![Coverage](https://img.shields.io/badge/coverage-80%25-green.svg)](https://github.com/dizzlkheinz/ynab-mcpb)
-```
-
-**Step 2** (3 min): Configure coverage thresholds in vitest config  
-**File:** `vitest.config.ts` (search for coverage section)  
-**Action:** Verify thresholds are enforced:
-```typescript
-coverage: {
-  thresholds: {
-    branches: 80,
-    functions: 80,
-    lines: 80,
-    statements: 80,
-  },
-}
-```
-
----
-
-### **Task 3.2: Add Developer Quickstart Script**
-
-**Step 1** (3 min): Create dev setup script  
-**File:** `scripts/dev-setup.sh` (new file)  
-**Action:**
-```bash
-#!/bin/bash
-# Quick setup for new developers
-
-echo "YNAB MCP Server - Developer Setup"
-echo "=================================="
-
-# Check Node version
-node -v | grep -q "v1[89]" || node -v | grep -q "v2[0-9]" || {
-  echo "❌ Node.js 18+ required"
-  exit 1
-}
-
-# Install dependencies
-npm install
-
-# Prompt for YNAB token
-echo ""
-echo "Get your YNAB Access Token from:"
-echo "https://app.youneedabudget.com/settings/developer"
-echo ""
-read -p "Enter YNAB_ACCESS_TOKEN: " token
-
-# Create .env file
-echo "YNAB_ACCESS_TOKEN=$token" > .env
-
-# Run tests
-echo ""
-echo "Running unit tests..."
-npm test
-
-echo ""
-echo "✅ Setup complete! Try: npm run build"
-```
-
-**Step 2** (1 min): Make executable  
-**Command:** `chmod +x scripts/dev-setup.sh` (or Windows equivalent)
-
-**Step 3** (1 min): Document in README  
-**File:** `README.md`  
-**Action:** Add to developer section:
-```markdown
-### Developer Setup
-
-```bash
-npm install
-./scripts/dev-setup.sh  # Guided setup with token prompt
-npm run build
-npm test
-```
-
----
-
-## **Testing Strategy Summary**
-
-### **Unit Tests**
-- **Target:** 80%+ coverage (already achieved: 1334 tests passing)
-- **Fast feedback:** < 15 seconds for full suite
-- **Mocked dependencies:** YNAB API, file system, network
-
-### **Integration Tests**
-- **Core suite:** `test:integration:core` (mocked YNAB API)
-- **Domain suites:** `test:integration:domain` (budgets, accounts, transactions, etc.)
-- **Rate-limited:** Throttled runner prevents 429s in CI
-- **Timeouts:** 90 minutes for full suite (YNAB API 200/hour limit)
-
-### **E2E Tests**
-- **Requires:** Real YNAB_ACCESS_TOKEN
-- **Use case:** Pre-release verification
-- **Frequency:** Manual or release workflow only
-
----
-
-## **Rollout Strategy**
-
-### **Phase 1: Priority 1 (Config & Token Validation)**
-**Duration:** ~45 minutes of focused work  
-**Release:** v0.14.0-alpha.1  
-**Testing:** Unit tests + core integration tests  
-
-### **Phase 2: Priority 2 (Reconciliation Errors)**
-**Duration:** ~40 minutes of focused work  
-**Release:** v0.14.0-alpha.2  
-**Testing:** Reconciliation integration tests (may hit rate limits)
-
-### **Phase 3: Quality Improvements (Optional)**
-**Duration:** ~20 minutes  
-**Release:** v0.14.0-beta.1  
-**Testing:** Full test suite + coverage report
-
-### **Phase 4: Production Release**
-**Duration:** ~10 minutes (docs, CHANGELOG, tagging)  
-**Release:** v0.14.0  
-**Testing:** E2E tests with real YNAB token  
-**Deployment:** npm publish + GitHub release with MCPB file
-
----
-
-## **Success Criteria**
-
-- ✅ All 1334+ unit tests pass
-- ✅ Integration tests pass or skip gracefully (no silent failures)
-- ✅ TypeScript strict mode: 0 errors
-- ✅ Config is reloadable per-instance (enables better testing)
-- ✅ Token validation handles malformed YNAB responses
-- ✅ Reconciliation propagates fatal errors (404, 429, 500)
-- ✅ Windows CI compatibility (no spawn EINVAL)
-- ✅ CHANGELOG updated with breaking changes (if any)
-- ✅ Semantic versioning: v0.14.0 (minor bump for new features)
-
----
-
-## **Breaking Changes Assessment**
-
-**None expected.** All changes are:
-- Internal refactoring (config injection)
-- Improved error handling (stricter but more correct)
-- Bug fixes (reconciliation error propagation)
-
-**API compatibility:** 100% backward compatible with v0.13.x
-
----
-
-## **Documentation Updates Required**
-
-1. **CHANGELOG.md** - Add v0.14.0 section with:
-   - "Reloadable config for improved testability"
-   - "Robust token validation for non-JSON responses"
-   - "Reconciliation error propagation (404/429/500)"
-   - "Windows CI compatibility fix"
-
-2. **docs/guides/TESTING.md** - Add section on:
-   - Per-instance config testing patterns
-   - Error normalization in reconciliation tests
-
-3. **README.md** (optional):
-   - Update badges if coverage changes
-   - Add developer quickstart script reference
-
----
-
-## **Risk Mitigation**
-
-| Risk | Mitigation |
-|------|-----------|
-| **Config changes break production** | Singleton `config` export preserved for backward compatibility |
-| **Token validation too strict** | Only catch SyntaxError/JSON errors, rethrow others |
-| **Reconciliation breaks existing workflows** | Only propagate 401/403/404/429/500/503, other errors still fall back |
-| **Windows test runner fails** | Portable node/vitest spawning, tested on Windows before commit |
-| **Rate limits block CI** | Integration tests already optional with `continue-on-error` |
-
----
-
-## **Post-Implementation Checklist**
-
-- [ ] All unit tests pass (`npm test`)
-- [ ] All integration tests pass or skip (`npm run test:integration:core`)
-- [ ] Type check passes (`npm run type-check`)
-- [ ] Linter passes (`npm run lint`)
-- [ ] Build succeeds (`npm run build`)
-- [ ] CHANGELOG.md updated
-- [ ] Git commit messages follow conventional commits
-- [ ] GitHub Actions CI passes
-- [ ] Manual smoke test with real YNAB token
-- [ ] Version bump to 0.14.0 in package.json
-- [ ] Git tag created: `v0.14.0`
-- [ ] npm publish successful
-- [ ] GitHub release created with MCPB attachment
-
----
-
-## **Next Steps Beyond v0.14.0**
-
-**Future enhancements identified during planning:**
-
-1. **Tool-level timeout configuration** - Allow per-tool timeout overrides for long-running operations
-2. **Reconciliation insights engine** - ML-based payee matching suggestions
-3. **Cached delta optimization** - Reduce redundant fetches for unchanged budgets
-4. **Multi-budget batch operations** - Parallel budget queries with Promise.allSettled
-5. **Output schema versioning** - Support schema evolution without breaking changes
-
----
-
-**End of Implementation Plan**
-
-This plan provides a concrete roadmap for the next iteration with:
-- **Exact file paths** for every change
-- **2-5 minute tasks** following TDD methodology
-- **Verification commands** after each step
-- **Rollback-safe approach** (all changes testable before commit)
-- **Clear success criteria** and risk mitigation
-
-Estimated total implementation time: **2-3 hours** for Priorities 1-2, excluding CI wait times.