qa360 2.1.7 → 2.2.1

package/docs/ARCHITECTURE.md

@@ -0,0 +1,901 @@
+# QA360 Architecture Documentation
+
+**Version:** 1.4.5
+**Status:** Active (Phases 1-3 AI Integration Complete, F8 Smart Retry Complete)
+**Last Updated:** January 3, 2025
+
+---
+
+## Overview
+
+QA360 is an industrial-grade, **AI-native** testing platform that transforms software quality assurance into **verifiable, signed, and traceable proofs**. The architecture prioritizes:
+
+- **Local-First Execution**: No cloud dependencies, full data sovereignty
+- **Cryptographic Verification**: Ed25519 signatures on all test results
+- **Evidence Preservation**: Immutable audit trails with SQLite WAL
+- **Conversational Testing**: Model Context Protocol (MCP) integration for LLM-native workflows
+- **Framework Agnostic**: Adapter-based design supporting any testing tool
+- **AI-Native**: Local test generation with Ollama (100% free, no API costs)
+
+### Architecture Philosophy
+
+**"Build once, trust forever, share everywhere."**
+
+QA360 follows a monorepo architecture with clear separation of concerns:
+- **Core**: Pure business logic, framework-agnostic
+- **CLI**: Human-friendly command-line interface
+- **MCP**: AI-friendly conversational interface
+- **Adapters**: Framework-specific integrations (Playwright, k6, ZAP, etc.)
+- **UI**: Future web/desktop interfaces (Phase 3)
+
+---
+
+## Version Status
+
+| Component | Version | Status |
+|-----------|---------|--------|
+| **QA360 Platform** | 1.4.5 | Beta (AI Phases 1-3 complete) |
+| **Target Release** | 2.0.0 | Q1 2025 (AI-native) |
+| **CLI** | 1.4.5 | Stable |
+| **Core** | 1.4.5 | Stable |
+| **MCP** | 1.2.0 | Unified |
+
+### Stability Guarantees
+
+- ✅ **Core API**: Stable, breaking changes only in major versions
+- ✅ **CLI Commands**: Stable, backward-compatible additions
+- ✅ **MCP Tools**: 23 tools stable, protocol MCP 0.4.0
+- ⚠️ **Adapters**: Evolving, minor breaking changes possible
+- 🔮 **UI/API**: Future (Phase 3), no stability guarantees yet
+
+---
+
+## Monorepo Structure
+
+```
+QA360/
+├── cli/                      # Command-line interface
+│   ├── src/
+│   │   ├── commands/         # Run, report, verify, serve, etc.
+│   │   └── index.ts          # CLI entrypoint
+│   └── package.json          # @qa360/cli v1.1.0
+│
+├── core/                     # Core business logic
+│   ├── src/
+│   │   ├── adapters/         # Framework adapters (Playwright, k6, ZAP, etc.)
+│   │   ├── ai/               # AI integration (OllamaProvider, TestDiscoverer)
+│   │   ├── auth/             # Authentication providers (9 providers)
+│   │   ├── pack-v2/          # Pack v2 validation & migration
+│   │   ├── proof/            # Proof generation & verification
+│   │   ├── vault/            # Evidence persistence (SQLite)
+│   │   ├── retry/            # F8 Smart Retry Module (Vision 2.0)
+│   │   ├── flakiness/        # Flakiness detection & scoring
+│   │   ├── security/         # Redaction, secrets management
+│   │   └── index.ts          # Public API
+│   └── package.json          # @qa360/core v1.4.5
+│
+├── packages/
+│   └── mcp/                  # Model Context Protocol integration
+│       ├── src/
+│       │   ├── cli/          # MCP CLI (init, up, doctor, fix, etc.)
+│       │   ├── server/       # Full MCP server (23 tools)
+│       │   ├── tools/        # Tool implementations
+│       │   └── security/     # Audit logging, permission system
+│       └── package.json      # @qa360/mcp v1.2.0 (UNIFIED)
+│
+├── adapters/                 # Standalone adapter implementations
+│   ├── playwright/           # Playwright E2E adapter
+│   ├── k6/                   # k6 performance adapter
+│   ├── semgrep/              # Semgrep SAST adapter
+│   ├── zap/                  # OWASP ZAP DAST adapter
+│   ├── trufflehog/           # TruffleHog secrets adapter
+│   └── gitleaks/             # Gitleaks secrets adapter
+│
+├── examples/
+│   ├── packs/                # Example test pack configurations
+│   ├── lovable/              # Lovable.dev integration (Supabase SSE)
+│   └── future-api/           # Phase 3 API placeholder (moved from /api)
+│
+├── ui/                       # Future UI components (Phase 3)
+│   └── web/                  # Web dashboard (planned)
+│
+├── tests/                    # Integration tests
+│   └── e2e/                  # End-to-end test suites
+│
+├── docs/                     # Documentation
+│   ├── ARCHITECTURE.md       # This file
+│   ├── api/                  # API documentation
+│   └── guides/               # User guides
+│
+├── package.json              # Root workspace config
+├── pnpm-workspace.yaml       # pnpm workspace definition
+└── tsconfig.json             # TypeScript configuration
+```
+
+**Total Packages:** 3 core + 6 adapters + 1 UI = **10 packages**
+
+---
+
+## Core Packages
+
+### 1. CLI Package (`@qa360/cli`)
+
+**Version:** 1.1.0  
+**Path:** `/cli`  
+**Purpose:** Human-friendly command-line interface for QA360
+
+#### Key Commands
+
+| Command | Description |
+|---------|-------------|
+| `qa360 run` | Execute test pack with proof generation |
+| `qa360 report` | Generate HTML/PDF reports from proofs |
+| `qa360 verify` | Verify cryptographic signatures |
+| `qa360 history` | Query past test runs |
+| `qa360 serve` | Start observability HTTP server |
+| `qa360 doctor` | Health checks and diagnostics |
+| `qa360 pack` | Pack validation and migration |
+| `qa360 secrets` | Secure secrets management |
+
+#### Features
+
+- **Zero Config**: Auto-detection of project structure
+- **Rich Output**: Chalk-based colored terminal UI
+- **Spinner Feedback**: Ora spinners for long operations
+- **Error Handling**: Structured error codes (RUN###, VRF###, etc.)
+- **CI/CD Ready**: JSON output, exit codes, non-interactive mode
+
+#### Dependencies
+
+```json
+{
+  "commander": "^11.1.0",
+  "chalk": "^5.3.0",
+  "ora": "^8.0.1",
+  "inquirer": "^9.2.12"
+}
+```
+
+---
+
+### 2. Core Package (`@qa360/core`)
+
+**Version:** 0.9.0-core  
+**Path:** `/core`  
+**Purpose:** Framework-agnostic business logic and proof system
+
+#### Architecture
+
+```
+@qa360/core
+├── QA360Core              # Main orchestrator
+├── ProofGenerator         # Proof creation & signing
+├── ProofVerifier          # Signature verification
+├── EvidenceVault          # SQLite persistence (WAL mode)
+├── AdapterRegistry        # Dynamic adapter loading
+└── SecurityRedactor       # PII/credential masking
+```
+
+#### Key Responsibilities
+
+1. **Test Orchestration**: Run packs through adapter pipeline
+2. **Proof Generation**: Ed25519 signatures on test results
+3. **Evidence Persistence**: Immutable SQLite storage with WAL
+4. **Adapter Management**: Dynamic loading of framework adapters
+5. **Security**: Redaction, secrets management, audit logging
+
+#### Public API
+
+```typescript
+import { QA360Core, Proof, PackConfig } from '@qa360/core';
+
+const core = new QA360Core();
+const proof: Proof = await core.run(packConfig, { runId });
+const valid: boolean = await core.verify(proof);
+```
+
+#### Database Schema
+
+- **runs**: Test execution metadata
+- **gates**: Gate results (api, ui, perf, a11y, sast, deps, secrets, dast)
+- **evidence**: Artifacts (screenshots, traces, logs)
+- **signatures**: Ed25519 signatures
+
+---
+
+### AI Integration Modules
+
+#### 1. AI Module (`core/src/ai/`)
+
+**Status:** ✅ Phase 1 Complete (41 tests)
+
+**Components:**
+
+| File | Description | Tests |
+|------|-------------|-------|
+| `index.ts` | OllamaProvider, LLMProvider interface | 41 tests |
+| `OllamaProvider` | Ollama client with retry & timeout | - |
+| `LLMProvider` | Generic LLM provider interface | - |
+| `LLMResponse` | Type definitions for LLM responses | - |
+
+**Features:**
+- Local LLM inference via Ollama (100% free, no API costs)
+- Automatic retry with exponential backoff
+- Configurable timeout and model selection
+- Support for streaming responses
+
+**CLI Commands:**
+```bash
+qa360 ollama test              # Test Ollama connection
+qa360 ollama list              # List installed models
+qa360 ollama pull <model>      # Instructions to download model
+qa360 ollama generate <prompt> # Generate tests (preview)
+qa360 ollama config            # Show configuration
+```
+
+#### 2. Auth Module (`core/src/auth/`)
+
+**Status:** ✅ Phase 2 Complete (92 tests)
+
+**Providers (9 total):**
+
+| Provider | Type | Tests |
+|----------|------|-------|
+| `JwtProvider` | JWT Bearer tokens | 6 tests |
+| `OAuth2Provider` | OAuth2 Client Credentials | 6 tests |
+| `ApiKeyProvider` | API Key in header | 6 tests |
+| `BearerProvider` | Bearer token provider | 6 tests |
+| `BasicAuthProvider` | Basic auth | 5 tests |
+| `TotpProvider` | TOTP-based auth | 6 tests |
+| `UiLoginProvider` | UI form-based login | 5 tests |
+| `GcpAdcProvider` | GCP Application Default Credentials | 6 tests |
+| `AwsIamProvider` | AWS IAM credentials | 5 tests |
+| `AzureAdProvider` | Azure AD authentication | 5 tests |
+
+**Integration Tests:** 36 tests
+
+**Total Tests:** 92
+
+**Features:**
+- Support for standard authentication schemes (JWT, OAuth2, API Key, Bearer, Basic)
+- Support for cloud provider auth (GCP ADC, AWS IAM, Azure AD)
+- TOTP support for two-factor authentication
+- UI login provider for browser-based tests
+
+#### 3. Pack v2 Module (`core/src/pack-v2/`)
+
+**Status:** ✅ Phase 3 Complete (210+ tests)
+
+**Components:**
+
+| File | Description | Tests |
+|------|-------------|-------|
+| `validator.ts` | PackValidatorV2 with 36 error codes | 100+ tests |
+| `migrator.ts` | Migration v1 → v2 | 50+ tests |
+| `loader.ts` | Load with auto-detection | 60+ tests |
+
+**CLI Commands:**
+```bash
+qa360 pack validate [pack] --check-files   # Validate pack
+qa360 pack migrate [pack] --output <file>  # Migrate v1 → v2
+qa360 pack lint [pack]                     # Auto-fix
+```
+
+**Features:**
+- Auto-detection of v1 vs v2 pack format
+- 36 validation error codes with detailed messages
+- Migration of gates array → gates object with adapters
+- Migration of environment → auth profiles + variables
+- Migration of hooks string → typed hook objects
+
+**Total AI Integration Tests:** 343 (41 + 92 + 210)
+
+#### 5. F8 Smart Retry Module (`core/src/retry/`)
+
+**Status:** ✅ Phase 2 Complete (48 tests)
+
+**Components:**
+
+| File | Description | Tests |
+|------|-------------|-------|
+| `types.ts` | RetryStrategy enum, RetryConfig, RetryResult types | - |
+| `retry-engine.ts` | SmartRetryEngine with 6 strategies | 30 tests |
+| `flakiness-integration.ts` | FlakinessAwareRetryEngine for intelligent retry | 18 tests |
+| `vault.ts` | SQLite persistence for retry history | - |
+
+**Retry Strategies:**
+- `NONE` - No retry, fail immediately
+- `FIXED` - Fixed delay between retries
+- `LINEAR` - Linear backoff (delay increases linearly)
+- `EXPONENTIAL` - Exponential backoff (delay doubles each retry)
+- `ADAPTIVE` - Adaptive retry based on flakiness score
+- `INTELLIGENT` - Pattern-based retry (timing, race conditions, selectors)
+
+**Features:**
+- Flakiness-aware retry decisions based on historical test data
+- Non-retriable error detection (OutOfMemoryError, PermissionDenied, SyntaxError, etc.)
+- Configurable jitter to avoid thundering herd problem
+- Pattern-based retry adjustments (timing, external_dependency, race_condition, selector_issue)
+- Retry history tracking in SQLite vault
+
+**Public API:**
+```typescript
+import { SmartRetryEngine, RetryStrategy, createSmartRetryEngine } from '@qa360/core/retry';
+
+const engine = createSmartRetryEngine({
+  maxRetries: 3,
+  initialDelayMs: 1000,
+  strategy: RetryStrategy.ADAPTIVE,
+  jitterFactor: 0.1
+});
+
+const result = await engine.executeWithRetry('test-1', async () => {
+  // Test execution
+});
+// → { success: true, totalAttempts: 2, stopReason: 'success', ... }
+
+// Get retry recommendation based on flakiness
+const rec = engine.getRetryRecommendation({ flakinessScore: 60 });
+// → { shouldRetry: true, strategy: RetryStrategy.ADAPTIVE, maxRetries: 3, ... }
+```
+
+**Total Tests:** 48 (30 + 18)
+
+---
+
+### 4. MCP Package (`@qa360/mcp`)
+
+**Version:** 1.2.0 (Unified)  
+**Path:** `/packages/mcp`  
+**Purpose:** AI-friendly conversational testing interface
+
+#### History & Merge
+
+**December 23, 2024**: Merged two separate packages into one unified package:
+- ❌ `@qa360/mcp-server` (0.9.0-mcp) - Full MCP server, 23 tools
+- ❌ `@qa360/mcp-cli` (1.1.0) - Zero-friction CLI
+- ✅ `@qa360/mcp` (1.2.0) - **Unified package** combining both
+
+**Merge Impact:**
+- Eliminated package conflicts
+- Single binary: `qa360-mcp` (CLI + Server)
+- Reduced complexity: -10,503 lines of duplicate code
+- Improved build speed: +50%
+
+#### MCP Tools (23 Total)
+
+**Core Execution (3 tools):**
+- `qa360.run` - Execute test packs
+- `qa360.verify` - Verify signatures
+- `qa360.report.sign` - Sign reports
+
+**History & Analytics (8 tools):**
+- `qa360.history.list|get|diff|trend|export|gc|pin|unpin`
+
+**Pack Management (4 tools):**
+- `qa360.pack.ask|validate|lint|migrate`
+
+**Secrets Management (2 tools):**
+- `qa360.secrets.add|list` (requires `--allow-secrets`)
+
+**Server & Diagnostics (6 tools):**
+- `qa360.serve.health|diag|metrics`
+- `qa360.vault.get_run|get_artifacts`
+- `qa360.triage.explain_code`
+
+#### CLI Commands (9 Total)
+
+| Command | Description |
+|---------|-------------|
+| `qa360-mcp init` | Auto-configure VS Code +  |
+| `qa360-mcp up` | Start MCP server with auto-recovery |
+| `qa360-mcp doctor` | Health checks (Node, VS Code, Claude) |
+| `qa360-mcp fix` | Auto-repair configuration |
+| `qa360-mcp reset` | Clean slate restart |
+| `qa360-mcp uninstall` | Complete removal |
+| `qa360-mcp test:dx` | DX compliance tests (CI/CD) |
+| `qa360-mcp telemetry` | Opt-in telemetry management |
+
+#### Security Features
+
+- **Permission System**: `--allow-run`, `--allow-secrets` opt-in flags
+- **Rate Limiting**: Configurable requests/second
+- **Audit Logging**: Full trail in `~/.qa360/mcp-audit.log`
+- **Data Redaction**: Automatic PII/credential masking
+- **Concurrency Control**: Limit parallel operations
+
+#### Integration
+
+**Claude Desktop:**
+```json
+{
+  "mcpServers": {
+    "qa360": {
+      "command": "qa360-mcp-server",
+      "args": ["--allow-run", "--allow-secrets"]
+    }
+  }
+}
+```
+
+**VS Code MCP Extension:**
+Auto-configured via `qa360-mcp init` command.
+
+---
+
+## Adapters
+
+QA360 uses an **adapter pattern** to integrate with various testing frameworks. Each adapter implements the `TestAdapter` interface.
+
+### Adapter List
+
+| Adapter | Framework | Gate | Status |
+|---------|-----------|------|--------|
+| **playwright** | Playwright | UI | ✅ Stable |
+| **k6** | k6 | Performance | ✅ Stable |
+| **semgrep** | Semgrep | SAST | ✅ Stable |
+| **zap** | OWASP ZAP | DAST | ⚠️ Beta |
+| **trufflehog** | TruffleHog | Secrets | ✅ Stable |
+| **gitleaks** | Gitleaks | Secrets | ✅ Stable |
+
+### Adapter Interface
+
+```typescript
+interface TestAdapter {
+  name: string;
+  version: string;
+  isAvailable(): Promise<boolean>;
+  run(config: AdapterConfig): Promise<AdapterResult>;
+  cleanup(): Promise<void>;
+}
+```
+
+### Adding Custom Adapters
+
+1. Implement `TestAdapter` interface
+2. Register in `AdapterRegistry`
+3. Configure in pack YAML:
+   ```yaml
+   gates:
+     custom:
+       adapter: my-custom-adapter
+       config: { ... }
+   ```
+
+---
+
+## Architecture Decisions (Week 1 Cleanup)
+
+### Context: December 18-23, 2024
+
+Week 1 focused on **monorepo cleanup and MCP unification** to eliminate technical debt and simplify the architecture.
+
+### Major Changes
+
+#### 1. Empty Package Deletion ✅
+
+**Removed 4 empty/stub packages:**
+- `packages/shared/` - Empty placeholder
+- `packages/types/` - Unused type definitions
+- `packages/utils/` - Duplicate utilities
+- `packages/config/` - Empty config package
+
+**Rationale:**
+- Reduced cognitive overhead (fewer directories to navigate)
+- Eliminated confusion about package responsibilities
+- Simplified dependency graph
+
+**Impact:**
+- -2,156 lines of boilerplate
+- Faster `pnpm install` (fewer workspace links)
+- Clearer project structure
+
+---
+
+#### 2. MCP Package Merge ✅
+
+**Unified 2 MCP packages into 1:**
+
+| Before | After |
+|--------|-------|
+| `@qa360/mcp-server` (0.9.0-mcp) | ✅ `@qa360/mcp` (1.2.0) |
+| `@qa360/mcp-cli` (1.1.0) | ❌ Merged |
+| **2 packages, 1 binary conflict** | **1 package, 1 unified binary** |
+
+**Problem Solved:**
+- Binary name conflict (`qa360-mcp` in both packages)
+- Duplicate code (tools, security, types duplicated)
+- Confusion about which package to use
+- Maintenance burden (updating 2 packages)
+
+**Merge Details:**
+- Copied `tools/` (23 production tools vs 3 stubs)
+- Copied `security/` (audit + manager)
+- Replaced minimal server with full server
+- Merged dependencies (`@qa360/core`, `ajv`)
+- Updated bin entries to point to full server
+
+**Result:**
+- Single source of truth for MCP functionality
+- Eliminated 10,503 lines of duplicate code
+- Unified documentation and examples
+- +50% faster build (no duplicate TypeScript compilation)
+
+**Git History:**
+```bash
+d65d8a1c - refactor(mcp): merge core functionality from mcp-server
+d2ba795e - chore(architecture): finalize monorepo cleanup
+```
+
+---
+
+#### 3. API Directory Relocation ✅
+
+**Moved `/api` to `examples/future-api`**
+
+**Rationale:**
+- `/api` contained placeholder code for Phase 3 REST API
+- Having it at root implied it was production-ready
+- Caused confusion ("Is QA360 a REST API?")
+
+**Action:**
+- Moved 4 placeholder files to `examples/future-api/`
+- Created `README.md` documenting Phase 3 timeline
+- Updated workspace configuration
+
+**Benefit:**
+- Clear signal: API is future work, not current feature
+- Cleaner root directory structure
+- Examples directory as home for future integrations
+
+---
+
+#### 4. Node Requirement Adjustment ✅
+
+**Changed:** `node: ">=20.18.1"` → `">=18.20.0"`
+
+**Rationale:**
+- Original requirement too strict (20.18.1 very recent)
+- Build system works fine on Node 18.x
+- `undici` dependency had strict requirement, downgraded to v6
+- Improves compatibility with existing CI/CD pipelines
+
+**Impact:**
+- Broader Node.js version support
+- Better developer experience (no forced Node upgrade)
+- Still modern (18.20.0 is LTS)
+
+---
+
+### Overall Impact
+
+| Metric | Before | After | Change |
+|--------|--------|-------|--------|
+| **Packages** | 13 | 10 | -23% |
+| **Empty Packages** | 4 | 0 | -100% |
+| **MCP Packages** | 2 | 1 | -50% |
+| **Lines of Code** | ~45,000 | ~34,500 | **-10,503** |
+| **Build Time** | ~12s | ~6s | **+50% faster** |
+| **Workspace Links** | 15 | 10 | -33% |
+| **Binary Conflicts** | 1 | 0 | Resolved |
+
+### Decision Log
+
+All architectural decisions are tracked in:
+- `ARCH-01_MCP_MERGE_ANALYSIS.md` - Detailed merge analysis
+- Git commit messages - Rationale and implementation details
+- This document - High-level summaries
+
+---
+
+## Build System
+
+### Package Manager
+
+**pnpm 9.12.2** - Fast, efficient, strict workspace management
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - cli
+  - core
+  - adapters/*
+  - ui/*
+  - examples/*
+  - packages/*
+  - tests
+```
+
+### TypeScript Configuration
+
+**Version:** TypeScript 5.0+
+
+**tsconfig.json (root):**
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+**Build Commands:**
+```bash
+pnpm install           # Install all workspace dependencies
+pnpm run build         # Compile all TypeScript packages
+pnpm run test          # Run Jest tests
+pnpm run lint          # ESLint checks
+pnpm run type-check    # TypeScript type checking
+```
+
+### CI/CD
+
+**GitHub Actions:**
+- Multi-OS testing (Ubuntu, macOS, Windows)
+- Multi-Node testing (18.x, 20.x, 22.x)
+- Automated build + test + lint
+- Playwright browser installation
+- Artifact collection
+
+**Workflow:** `.github/workflows/qa360-ci.yml`
+
+---
+
+## Security
+
+QA360 implements defense-in-depth security:
+
+### 1. Cryptographic Signatures
+
+**Algorithm:** Ed25519 (Curve25519-based)
+
+- **Key Generation**: Automatic on first run
+- **Storage**: `~/.qa360/keys/` (0600 permissions)
+- **Signing**: All test results signed with private key
+- **Verification**: Public key included in proof for validation
+
+**Proof Structure:**
+```json
+{
+  "proof_version": "1.0.0",
+  "run_id": "uuid-v4",
+  "timestamp": "ISO-8601",
+  "gates": [...],
+  "signature": {
+    "algorithm": "ed25519",
+    "public_key": "base64",
+    "signature": "base64"
+  }
+}
+```
+
+### 2. Evidence Vault
+
+**Technology:** SQLite with WAL (Write-Ahead Logging)
+
+- **Immutability**: Append-only writes
+- **Atomicity**: WAL ensures crash recovery
+- **Performance**: Up to 100x faster than journal mode
+- **Location**: `~/.qa360/vault/evidence.db`
+
+**Integrity Checks:**
+- SHA256 hashes on all artifacts
+- Foreign key constraints
+- CHECK constraints on enums
+- Timestamp validation
+
+### 3. Secrets Management
+
+**Storage:** Encrypted with AES-256
+
+- **Master Key**: Derived from system entropy
+- **Per-Secret Encryption**: Unique IV per secret
+- **Audit Trail**: All access logged
+- **Redaction**: Automatic masking in logs/reports
+
+**Secret Operations:**
+```bash
+qa360 secrets add DB_PASSWORD
+qa360 secrets list --show-values  # Requires confirmation
+qa360 secrets remove DB_PASSWORD
+qa360 secrets doctor             # Audit check
+```
+
+### 4. MCP Security
+
+**Permission System:**
+- `--allow-run`: Explicit opt-in for test execution
+- `--allow-secrets`: Explicit opt-in for secrets access
+- **Default**: Read-only (history, diagnostics, vault queries)
+
+**Rate Limiting:**
+- Configurable requests/second (default: 5 req/s)
+- Per-tool limits
+- DDoS protection
+
+**Audit Logging:**
+- Every MCP tool call logged
+- Timestamp, tool name, arguments (redacted)
+- Success/failure status
+- Log file: `~/.qa360/mcp-audit.log`
+
+### 5. Data Redaction
+
+**Automatic Redaction Patterns:**
+- Bearer tokens
+- Basic auth credentials
+- API keys
+- Database connection strings
+- Private keys / certificates
+- Email addresses (optional)
+
+**Redaction API:**
+```typescript
+import { SecurityRedactor } from '@qa360/core';
+
+const redactor = new SecurityRedactor();
+const safe = redactor.redact(text);
+// "Bearer abc123" → "Bearer [REDACTED]"
+```
+
+---
+
+## Future Phases
+
+QA360 follows a phased roadmap:
+
+### Core Platform Phases
+
+### Phase 1: Core Platform ✅ (Complete)
+- Local-first testing engine
+- Proof generation & verification
+- CLI interface
+- 7 adapters (Playwright, k6, Semgrep, ZAP, Gitleaks, OSV)
+- Evidence vault
+- **Status:** Done (1.4.5)
+
+### Phase 2: MCP Integration ✅ (Complete)
+- Model Context Protocol server
+- 23 conversational tools
+- Claude Desktop / VS Code integration
+- Zero-friction DX CLI
+- **Status:** Done (1.2.0 unified)
+
+### AI Integration Phases (Ollama)
+
+#### AI Phase 1: Ollama Provider ✅ (Complete - Dec 31, 2024)
+- OllamaProvider with retry & timeout
+- TestDiscoverer for auto-detection
+- PackConfigV2 types
+- CLI commands: `ollama test|list|pull|generate|config`
+- **Tests:** 96 passing
+
+#### AI Phase 2: Auth Module ✅ (Complete - Dec 31, 2024)
+- 9 authentication providers
+- JWT, OAuth2, API Key, Bearer, Basic, TOTP
+- Cloud providers: GCP ADC, AWS IAM, Azure AD
+- UI Login provider for browser tests
+- **Tests:** 92 passing
+
+#### AI Phase 3: Pack v2 Validation ✅ (Complete - Dec 31, 2024)
+- PackValidatorV2 (36 error codes)
+- PackMigrator (v1 → v2)
+- PackLoaderV2 (auto-detection)
+- CLI commands: `pack validate|migrate|lint`
+- **Tests:** 210+ passing
+
+#### AI Phase 4: AI Test Generation ⏳ (Planned)
+- CodeGenerator module
+- PromptBuilder for LLM prompts
+- Test generation from OpenAPI/Swagger
+- Interactive test generation CLI
+
+#### AI Phase 5: Integration & Polish ⏳ (Planned)
+- Phase3Runner integration for Pack v2
+- Adapters updated for Auth profiles
+- Complete documentation
+- Example packs v2
+- E2E tests
+
+**Total AI Integration Tests:** 398 (Phases 1-3)
+
+### Vision 2.0 - Flakiness Detection & Smart Retry
+
+#### F1-F7: Flakiness System ✅ (Complete - January 2025)
+- Flakiness Detection Engine
+- Flakiness Scoring (Legendary, Solid, Good, Shaky, Unstable)
+- Quarantine System
+- Self-Healing Module
+- Coverage Analytics
+- SLO/SLI Management
+- Regression Detection
+
+#### F8: Smart Retry Module ✅ (Complete - January 3, 2025)
+- Smart Retry Engine with 6 strategies (NONE, FIXED, LINEAR, EXPONENTIAL, ADAPTIVE, INTELLIGENT)
+- Flakiness-Aware Retry: Integrates with flakiness scoring for intelligent retry decisions
+- Pattern-Based Retry: Adjusts strategy based on failure patterns (timing, race conditions, selectors)
+- Non-Retriable Error Detection: Automatically identifies unrecoverable errors
+- Jitter Support: Avoids thundering herd problem with configurable jitter
+- **Tests:** 48 passing
+
+**Complete Flakiness System:** Detection → Scoring → Quarantine → Smart Retry
+
+### Future Platform Phases
+
+### Phase 3: Cloud & API 🔮 (Q1 2025)
+- REST API for remote execution
+- Web dashboard (real-time)
+- Multi-user authentication
+- Cloud pack registry
+- **Status:** Planned, code in `examples/future-api/`
+
+### Phase 4: Enterprise 🔮 (Q2 2025)
+- SAML/OIDC authentication
+- RBAC (Role-Based Access Control)
+- Compliance reports (SOC2, ISO27001)
+- On-premise deployment
+- **Status:** Planned
+
+---
+
+## References
+
+### Documentation
+
+- **API Reference**: `/docs/api/`
+- **User Guides**: `/docs/guides/`
+- **MCP Server**: `/packages/mcp/README.md`
+- **Core Package**: `/core/README.md`
+- **CLI Package**: `/cli/README.md`
+
+### Key Documents
+
+- **ARCH-01 Analysis**: `ARCH-01_MCP_MERGE_ANALYSIS.md` - Detailed merge analysis
+- **Migration Guide**: `docs/MIGRATION.md` - Upgrade path from pre-1.2.0
+- **Week 1 Summary**: `docs/WEEK1_SUMMARY.md` - Cleanup accomplishments
+- **Ollama Roadmap**: `docs/OLLAMA_REFACTORING_ROADMAP.md` - AI integration roadmap
+- **Status**: `docs/STATUS.md` - Current project status
+
+### External Links
+
+- **Website**: https://qa360.ai
+- **GitHub**: https://github.com/xyqotech/qa360
+- **MCP Protocol**: https://modelcontextprotocol.io
+- **Playwright**: https://playwright.dev
+- **k6**: https://k6.io
+
+---
+
+## Contributing
+
+QA360 follows trunk-based development:
+
+1. **Main Branch**: `develop` (stable, deployable)
+2. **Feature Branches**: Short-lived, merged via PR
+3. **Commit Convention**: Conventional Commits (feat, fix, chore, docs, refactor)
+4. **Testing**: All PRs require passing CI/CD
+
+**Pull Request Checklist:**
+- [ ] Tests pass (`pnpm test`)
+- [ ] Lint passes (`pnpm lint`)
+- [ ] Type check passes (`pnpm type-check`)
+- [ ] Build succeeds (`pnpm build`)
+- [ ] Documentation updated
+- [ ] Commit messages follow convention
+
+---
+
+## License
+
+MIT License - See `LICENSE` file for details.
+
+---
+
+**Architecture Document Version:** 1.1.0
+**Last Review:** January 3, 2025
+**Next Review:** January 2025 (AI Phase 4)