@miller-tech/uap 1.39.0 → 1.40.1

package/docs/archive/MODEL_ROUTING_OPTIMIZATION_PLAN.md

@@ -1,320 +0,0 @@
-# Model Routing CLI Selection & UAP Compliance Analysis
-
-## Current Issues Identified
-
-### 1. Missing 'task' Role in Model Routing
-
-**File**: `src/models/types.ts` (line 15)
-
-```typescript
-export type ModelRole = 'planner' | 'executor' | 'reviewer' | 'fallback';
-```
-
-The routing rules support `'task'` as a target role, but the type definition is missing this value.
-
-### 2. Null Issues in Router
-
-**File**: `src/models/router.ts`
-
-- Line 117: `preset` can be undefined when model preset doesn't exist
-- Line 468: No fallback when executor model is not found
-- Line 13: Import uses `ModelPresets` but no null check before access
-
-### 3. Missing CLI Command for Model Selection
-
-**Current**: `uap model status`, `route`, `plan`, `compare` exist
-**Missing**: Interactive CLI to select models per purpose at runtime
-
----
-
-## UAP Compliance Correctness Analysis
-
-### Compliant Features ✅
-
-1. **Multi-model architecture types** - Properly defined in `types.ts`
-2. **Routing rules with priorities** - Implemented in `router.ts`
-3. **Task classification** - Complexity-based routing works correctly
-4. **Planner/Executor separation** - Implemented with validation
-5. **Cost estimation** - Built into router
-6. **Fallback mechanisms** - Present in all critical paths
-
-### Non-Compliant Features ❌
-
-1. **Missing 'task' role** - Type definition incomplete
-2. **No null safety** - Multiple undefined access patterns
-3. **Incomplete CLI** - No interactive model selection
-4. **TypeScript build issues** - May fail on missing presets
-5. **No validation for role assignments** - Can assign non-existent models to roles
-
----
-
-## Performance Analysis
-
-### Current Implementation Performance
-
-| Feature             | Performance | Notes                           |
-| ------------------- | ----------- | ------------------------------- |
-| Task Classification | O(1)        | Keyword matching is fast        |
-| Model Selection     | O(n)        | Iterates through routing rules  |
-| Plan Creation       | O(n\*m)     | n=subtasks, m=complexity levels |
-| Routing Analysis    | O(n)        | Full rule evaluation            |
-
-### Bottlenecks Identified
-
-1. **Routing rules iteration** - Can be optimized with indexing
-2. **Keyword matching** - Linear scan through all keywords
-3. **No caching** - Classification recalculated each time
-4. **Model lookup** - Map is efficient but presets initialization is synchronous
-
----
-
-## Optimization Options
-
-### Option 1: Quick Fixes (Recommended for Immediate Use)
-
-**Priority**: High | **Effort**: Low | **Impact**: Medium
-
-#### A. Fix Missing 'task' Role
-
-```typescript
-// src/models/types.ts line 15
-export type ModelRole = 'planner' | 'executor' | 'reviewer' | 'fallback' | 'task';
-```
-
-#### B. Add Null Safety to Router
-
-```typescript
-// src/models/router.ts line 117-120
-if (preset) {
-  this.models.set(modelDef, preset);
-}
-// Add check before accessing preset throughout
-```
-
-#### C. Add Role Assignment Validation
-
-```typescript
-// In ModelRouter constructor
-private validateRoleAssignments(): void {
-  const roles = this.config.roles || {};
-  for (const [role, modelId] of Object.entries(roles)) {
-    if (!this.models.has(modelId)) {
-      console.warn(`Role ${role} assigned to non-existent model ${modelId}`);
-    }
-  }
-}
-```
-
-### Option 2: CLI Enhancement (User-Friendly Selection)
-
-**Priority**: High | **Effort**: Medium | **Impact**: High
-
-#### A. Add Interactive Model Selector
-
-```typescript
-// src/cli/model.ts - New command
-program
-  .command('model:select')
-  .description('Interactively select models for each role')
-  .option('--planner <id>', 'Model ID for planning role')
-  .option('--executor <id>', 'Model ID for execution role')
-  .option('--reviewer <id>', 'Model ID for review role')
-  .option('--fallback <id>', 'Model ID for fallback role')
-  .option(
-    '--strategy <strategy>',
-    'Routing strategy: balanced|cost-optimized|performance-first|adaptive'
-  )
-  .option('--save', 'Save configuration to .uap.json')
-  .action(async (options) => {
-    // Interactive selection logic
-  });
-```
-
-#### B. Add Preset Browser
-
-```typescript
-// Show available presets with details
-uap model presets --verbose
-```
-
-#### C. Add Configuration Export
-
-```typescript
-// Export current config as JSON/YAML
-uap model export --format json > model-config.json
-```
-
-### Option 3: Performance Optimizations
-
-**Priority**: Medium | **Effort**: Medium | **Impact**: High
-
-#### A. Add Classification Caching
-
-```typescript
-class ModelRouter {
-  private classificationCache = new Map<string, TaskClassificationResult>();
-
-  classifyTask(taskDescription: string): TaskClassificationResult {
-    const cacheKey = taskDescription.toLowerCase().trim();
-    if (this.classificationCache.has(cacheKey)) {
-      return this.classificationCache.get(cacheKey)!;
-    }
-    // ... existing logic ...
-    const result = /* classification logic */;
-    this.classificationCache.set(cacheKey, result);
-    return result;
-  }
-}
-```
-
-#### B. Optimize Keyword Matching
-
-```typescript
-// Pre-compile keyword patterns for faster matching
-private complexityPatterns: Map<TaskComplexity, RegExp[]> = new Map();
-private taskTypePatterns: Map<string, RegExp[]> = new Map();
-
-private buildPatternIndex(): void {
-  for (const [level, keywords] of Object.entries(COMPLEXITY_KEYWORDS)) {
-    this.complexityPatterns.set(level as TaskComplexity,
-      keywords.map(kw => new RegExp(`\\b${kw}\\b`, 'i')));
-  }
-}
-```
-
-#### C. Add Routing Rule Indexing
-
-```typescript
-// Group rules by condition for O(1) lookup
-private complexityIndex: Map<TaskComplexity, RoutingRule[]> = new Map();
-type TaskTypeIndex: Map<string, RoutingRule[]> = new Map();
-
-private buildIndexes(): void {
-  for (const rule of this.routingRules) {
-    if (rule.complexity) {
-      const rules = this.complexityIndex.get(rule.complexity) || [];
-      rules.push(rule);
-      this.complexityIndex.set(rule.complexity, rules);
-    }
-  }
-}
-```
-
-### Option 4: Enhanced Validation & Diagnostics
-
-**Priority**: Medium | **Effort**: Low | **Impact**: Medium
-
-#### A. Add Model Health Check
-
-```typescript
-// src/cli/model.ts
-async function healthCheckCommand(): Promise<void> {
-  const config = loadConfig();
-  const mmConfig = getMultiModelConfig(config);
-  const router = createRouter(mmConfig);
-
-  console.log('=== Model Health Check ===\n');
-
-  // Check all assigned models exist
-  const roles = mmConfig.roles || {};
-  let hasErrors = false;
-  for (const [role, modelId] of Object.entries(roles)) {
-    if (!router.getModel(modelId)) {
-      console.error(`❌ ${role}: Model '${modelId}' not found`);
-      hasErrors = true;
-    } else {
-      console.log(`✓ ${role}: ${modelId} (OK)`);
-    }
-  }
-
-  if (hasErrors) {
-    process.exitCode = 1;
-  }
-}
-```
-
-#### B. Add Configuration Diff
-
-```typescript
-// Compare current config with defaults
-uap model diff
-```
-
-#### C. Add Simulation Mode
-
-```typescript
-// Test routing without execution
-uap model simulate --task "<task description>" --dry-run
-```
-
----
-
-## Recommended Implementation Plan
-
-### Phase 1: Critical Fixes (1-2 hours)
-
-1. ✅ Fix missing 'task' role type definition
-2. ✅ Add null safety checks in router
-3. ✅ Add role assignment validation
-4. ✅ Run build to verify TypeScript compilation
-
-### Phase 2: CLI Enhancement (2-3 hours)
-
-1. ✅ Add `uap model select` interactive command
-2. ✅ Add `uap model presets` listing
-3. ✅ Add `uap model export` for config backup
-4. ✅ Add `uap model health` diagnostic
-
-### Phase 3: Performance (4-6 hours)
-
-1. ✅ Add classification caching
-2. ✅ Optimize keyword matching with precompiled patterns
-3. ✅ Index routing rules for faster lookup
-4. ✅ Benchmark before/after performance
-
-### Phase 4: Validation & Testing (2-3 hours)
-
-1. ✅ Add comprehensive unit tests for router
-2. ✅ Add integration tests for CLI commands
-3. ✅ Create sample configurations for testing
-4. ✅ Document all new commands
-
----
-
-## Implementation Priority Matrix
-
-| Task                     | Priority | Effort | Impact | Phase |
-| ------------------------ | -------- | ------ | ------ | ----- |
-| Fix 'task' role type     | High     | Low    | High   | 1     |
-| Add null safety          | High     | Low    | High   | 1     |
-| CLI interactive selector | High     | Medium | High   | 2     |
-| Role validation          | High     | Low    | Medium | 1     |
-| Classification cache     | Medium   | Low    | Medium | 3     |
-| Keyword optimization     | Medium   | Medium | Low    | 3     |
-| Health check command     | Medium   | Low    | Medium | 2     |
-| Rule indexing            | Medium   | Medium | Medium | 3     |
-
----
-
-## UAP Compliance Checklist
-
-After implementation, verify:
-
-- [ ] All model roles properly typed and validated
-- [ ] No undefined/null access patterns in router
-- [ ] CLI commands for model selection work interactively
-- [ ] Build passes without errors
-- [ ] All existing tests pass
-- [ ] New commands documented in CLI help
-- [ ] Performance improvements verified with benchmarks
-- [ ] Configuration export/import works correctly
-
----
-
-## Next Steps
-
-1. **Start with Phase 1** - Critical fixes to prevent runtime errors
-2. **Run `npm run build`** after each phase to verify compilation
-3. **Test with sample tasks** to verify routing correctness
-4. **Document changes** in CHANGELOG.md
-5. **Create migration guide** if breaking changes are introduced

package/docs/archive/NPM-PUBLISH-V0.9.1.md

@@ -1,240 +0,0 @@
-# 🚀 UAP v0.9.1 NPM Publish - Complete Success!
-
-**Date**: March 11, 2026  
-**Version**: 0.9.1  
-**Status**: ✅ **PUBLISHED TO NPM**
-
----
-
-## ✅ Deployment Complete!
-
-### Package Published
-
-| Package | Version | Status | URL |
-|---------|---------|--------|-----|
-| `universal-agent-protocol` | **0.9.1** | ✅ Published | [npmjs.com](https://www.npmjs.com/package/universal-agent-protocol) |
-
-### Package Details
-
-```
-universal-agent-protocol@0.9.1 | MIT | deps: 13 | versions: 7
-Autonomous AI agent memory system with CLAUDE.md protocol enforcement
-https://github.com/DammianMiller/universal-agent-protocol#readme
-
-bin: universal-agent-protocol, uap, uap-tool-calls
-```
-
-### Installation
-
-```bash
-# Install the latest version
-npm install universal-agent-protocol@latest
-
-# Or install specific version
-npm install universal-agent-protocol@0.9.1
-
-# Use globally
-npm install -g universal-agent-protocol
-
-# Create UAP instance
-uap setup -p all
-```
-
----
-
-## 🎯 What's in v0.9.1
-
-### Key Features
-
-1. **OpenCode as Primary Harness** 🎉
-   - Full feature parity with Claude Code
-   - 6 plugins fully operational
-   - MCP Router integration
-
-2. **Pattern RAG Enabled by Default** ✅
-   - Saves ~12,000 tokens per query
-   - On-demand pattern retrieval from CLAUDE.md
-   - 397 patterns indexed in Qdrant
-
-3. **Jinja2 Template Fix** 🔧
-   - Resolved system message validation error
-   - Fixed chat template for Qwen3.5
-   - Improved error messages
-
-4. **Full UAP Compliance** ✅
-   - Task management system
-   - Worktree isolation
-   - Memory persistence
-   - Agent coordination
-
----
-
-## 📊 NPM Package Statistics
-
-| Metric | Value |
-|--------|-------|
-| **Name** | universal-agent-protocol |
-| **Version** | 0.9.1 |
-| **License** | MIT |
-| **Dependencies** | 13 packages |
-| **Total Versions** | 7 releases |
-| **Tarball Size** | ~2.6 MB (unpacked) |
-| **Binaries** | `uap`, `universal-agent-protocol`, `uap-tool-calls` |
-
-### Dependencies
-
-```json
-{
-  "@octokit/rest": "^20.0.2",
-  "@qdrant/js-client-rest": "^1.11.0",
-  "better-sqlite3": "^11.0.0",
-  "chalk": "^5.3.0",
-  "commander": "^11.1.0",
-  "ora": "^8.0.1"
-}
-```
-
----
-
-## 🚀 GitHub Actions Workflow
-
-### Workflow Status
-
-| Job | Status | Duration |
-|-----|--------|----------|
-| **Build & Test** | ✅ Success | 1m31s |
-| **Publish to npm** | ✅ Success | 1m29s |
-| **Create Release** | ✅ Success | 12s |
-| **Deploy Documentation** | ⚠️ Skipped | — |
-
-### Workflow Run
-
-- **Run ID**: `22905773861`
-- **Trigger**: Push to master branch
-- **Commit**: `b82b1e60` - "chore: bump version to 0.9.1 for npm publish"
-- **URL**: https://github.com/DammianMiller/universal-agent-protocol/actions/runs/22905773861
-
----
-
-## 📦 What's Changed (v0.9.1)
-
-### Bug Fixes
-
-- **Jinja2 Template System Message Error**
-  - Fixed validation error in `chat_template.jinja` line 103
-  - Added `has_system_message` variable for consistent checks
-  - Improved error messages for missing system messages
-
-### Improvements
-
-- **Default Pattern RAG**
-  - Enabled by default when Qdrant is available
-  - Automatic pattern retrieval on task queries
-  - Token savings: ~12K per query
-
-### Infrastructure
-
-- **OpenCode Primary Harness**
-  - All 6 plugins active and tested
-  - MCP Router configured for opencode
-  - Full feature parity achieved
-
----
-
-## 🔧 Installation & Usage
-
-### Quick Start
-
-```bash
-# Install globally
-npm install -g universal-agent-protocol@latest
-
-# Initialize in your project
-cd /path/to/project
-uap setup -p all
-
-# That's it! OpenCode is now your primary harness with:
-# ✅ Pattern RAG (~12K tokens saved/query)
-# ✅ Task management active
-# ✅ Worktree isolation ready
-```
-
-### Available Commands
-
-```bash
-# Task Management
-uap task create -t "Your task" --type feature --priority 2
-uap task ready              # List tasks ready to work on
-uap task claim <id>         # Claim + create worktree
-
-# Worktree Isolation
-uap worktree create <slug>  # Create isolated branch
-uap worktree list           # List active worktrees
-uap worktree pr <id>        # Create PR from worktree
-
-# Memory & Patterns
-uap memory status           # Show memory health
-uap patterns query "search" --top 3  # Query patterns
-
-# Compliance
-uap compliance check -v     # Check UAP compliance
-```
-
----
-
-## 📚 Documentation
-
-### Quick Links
-
-- **README**: https://github.com/DammianMiller/universal-agent-protocol#readme
-- **NPM Package**: https://www.npmjs.com/package/universal-agent-protocol
-- **GitHub Actions**: https://github.com/DammianMiller/universal-agent-protocol/actions
-- **Issues**: https://github.com/DammianMiller/universal-agent-protocol/issues
-
-### Full Documentation
-
-All documentation is available in the `docs/` folder of the repository:
-- `/docs/deployment/` - Deployment guides and summaries
-- `/docs/fixes/` - Bug fix documentation
-- `/README.md` - Complete usage guide
-
----
-
-## ✅ Deployment Checklist
-
-- [x] Version bumped to 0.9.1
-- [x] Build & Test passed (1m31s)
-- [x] Published to npm registry
-- [x] GitHub Release created
-- [x] Package verified on npmjs.com
-- [ ] Documentation deployment (skipped due to protection rules)
-
----
-
-## 📊 Previous Versions
-
-| Version | Date | Status | Notes |
-|---------|------|--------|-------|
-| 0.9.1 | Mar 11, 2026 | ✅ Published | OpenCode primary harness |
-| 0.9.0 | Mar 10, 2026 | ✅ Published | OpenCode enabled |
-| 0.8.1 | Mar 10, 2026 | ✅ Published | Full compliance enforcement |
-
----
-
-## 🎉 Summary
-
-**UAP v0.9.1 is now live on npm!**
-
-This release brings:
-- ✅ OpenCode as the primary AI coding harness
-- ✅ Pattern RAG enabled by default (~12K tokens saved/query)
-- ✅ Fixed Jinja2 template system message validation error
-- ✅ Full feature parity across all platforms
-- ✅ 100% UAP compliance enforcement
-
-**Install now**: `npm install universal-agent-protocol@latest`
-
----
-
-*Published via GitHub Actions workflow `deploy-publish.yml`*  
-*Workflow Run: https://github.com/DammianMiller/universal-agent-protocol/actions/runs/22905773861*