docs(F003): add comprehensive testing documentation and guides

Added complete testing documentation to support the 338-test suite
with 84.97% coverage.

Documentation Added:
1. README.md Testing Section
   - Coverage badge (84.97%)
   - Quick start commands
   - Coverage thresholds table
   - Test organization diagram
   - Example test snippet

2. TESTING.md Comprehensive Guide (docs/guides/)
   - Test organization and structure
   - Testing patterns (Tool, State, Integration, Resource)
   - Coverage requirements and current metrics
   - Best practices and anti-patterns
   - Common patterns and helpers
   - CI integration details
   - Troubleshooting guide

3. Test Fixture Documentation (src/__tests__/fixtures/)
   - Purpose and usage of each fixture
   - valid-state.json - Standard state structure
   - complete-state.json - All gears completed
   - corrupted-state.json - Error handling
   - proto-pollution.json - Security testing
   - Best practices for fixtures
   - Dynamic vs static test data

Test Quality Verification:
- ✅ Ran tests 3+ times - no flaky tests detected
- ✅ Test execution time: ~4.7s (target: <60s)
- ✅ All 338 tests passing consistently
- ✅ Coverage stable at 84.97%

CI Integration:
- Existing .github/workflows/ci.yml already configured
- Coverage runs on Node 20.x
- Automatic Codecov upload
- Threshold enforcement via vitest.config.ts

Coverage Breakdown:
- Overall: 84.97% (lines/statements), 90.25% branches, 93.33% functions
- Tools: 98.49% coverage
- Resources: 94.21% coverage
- Utils: 95.55% coverage
- index.ts: 0% (expected - heavy MCP SDK mocking)

Addresses: F003-test-coverage US4 (CI/CD), Phase 7 (Polish)
Related: production-readiness-specs/F003-test-coverage/tasks.md (T090-T106)

Author: claude

mcp-server/README.md

@@ -380,6 +380,76 @@ npx stackshift-mcp
 
 ---
 
+## Testing
+
+[![Coverage](https://img.shields.io/badge/coverage-84.97%25-yellow)](https://github.com/jschulte/stackshift/actions)
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run specific test file
+npm test -- src/tools/__tests__/analyze.test.ts
+```
+
+### Coverage Thresholds
+
+The project enforces strict coverage thresholds:
+- **Lines**: 85%
+- **Functions**: 85%
+- **Branches**: 80%
+- **Statements**: 85%
+
+CI builds will fail if coverage drops below these thresholds.
+
+### Test Organization
+
+```
+src/
+├── __tests__/              # Main server & integration tests
+│   ├── index.test.ts       # MCP server initialization
+│   ├── integration.test.ts # E2E workflows
+│   └── fixtures/           # Test data
+├── tools/__tests__/        # Tool handler tests (6 gears)
+├── resources/__tests__/    # Resource handler tests
+└── utils/__tests__/        # Utility tests
+    ├── state-manager.test.ts
+    ├── state-recovery.test.ts
+    └── security.test.ts
+```
+
+### Writing Tests
+
+See [docs/guides/TESTING.md](./docs/guides/TESTING.md) for detailed testing patterns and examples.
+
+**Quick example:**
+```typescript
+import { describe, it, expect } from 'vitest';
+import { analyzeToolHandler } from '../analyze.js';
+
+describe('analyzeToolHandler', () => {
+  it('should analyze project directory', async () => {
+    const result = await analyzeToolHandler({
+      directory: '/test/path',
+      route: 'greenfield'
+    });
+
+    expect(result.content).toBeDefined();
+    expect(result.content[0].text).toContain('Analysis Complete');
+  });
+});
+```
+
+---
+
 ## Troubleshooting
 
 ### Server Not Starting