@miller-tech/uap 1.5.0 → 1.5.3

package/docs/MODEL_ROUTING_OPTIMIZATION_PLAN.md

@@ -0,0 +1,320 @@
+# 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/POLICY_GATE_IMPLEMENTATION.md

@@ -0,0 +1,245 @@
+# Policy Gate for Mandatory Testing & Deployment - Implementation Complete
+
+## Overview
+
+This implementation adds a **mandatory policy gate** that enforces testing and deployment verification before any task can be marked as DONE, COMPLETE, or CLOSED.
+
+## What Was Implemented
+
+### 1. Policy File Created ✅
+
+**File**: `src/policies/schemas/policies/mandatory-testing-deployment.md`
+
+This policy defines rules for:
+
+- Testing requirements before task completion
+- Deployment verification for production changes
+- Quality gate enforcement (lint, type-check, coverage)
+- Documentation requirements
+
+### 2. Policy Gate Enhancement ✅
+
+**File**: `src/policies/policy-gate.ts`
+
+Added automatic detection and enforcement for task completion operations:
+
+- Detects when operations involve: complete, done, finish, close, resolve, merge, deploy, release
+- Forces review-stage policy checks during task completion
+- Blocks completion if REQUIRED policies are violated
+- Provides clear error messages explaining what's missing
+
+**Key Method**: `isTaskCompletionOperation()`
+
+```typescript
+private isTaskCompletionOperation(
+  operation: string,
+  args: Record<string, unknown>
+): boolean {
+  // Detects completion-related operations and forces review-stage enforcement
+}
+```
+
+### 3. CLI Commands Added ✅
+
+**File**: `src/cli/policy.ts`
+
+New policy management commands:
+
+```bash
+# List all policies
+uap policy list
+
+# Install a built-in policy
+uap policy install mandatory-testing-deployment
+
+# Enable a policy
+uap policy enable <policy-id>
+
+# Disable a policy
+uap policy disable <policy-id>
+
+# Show detailed policy status
+uap policy status
+```
+
+### 4. Policy Installer Script ✅
+
+**File**: `scripts/install-policy.ts`
+
+One-command installation script:
+
+```bash
+node scripts/install-policy.js                    # Install all mandatory policies
+node scripts/install-policy.js mandatory-testing-deployment  # Install specific policy
+```
+
+### 5. CLAUDE.md Updated ✅
+
+**File**: `CLAUDE.md`
+
+Added mandatory policy enforcement section to the Completion Gate:
+
+- Lists all verification requirements
+- Defines what NOT to do when marking tasks complete
+- Provides commands to verify compliance
+
+### 6. CLI Registration ✅
+
+**File**: `src/bin/cli.ts`
+
+Registered policy commands in main CLI entry point.
+
+## How It Works
+
+### Policy Enforcement Flow
+
+1. **Task Completion Detected**
+   - When you use commands like `task close`, `task release`, or any operation containing "complete", "done", etc.
+   - The policy gate automatically detects this as a task completion operation
+
+2. **Review Stage Enforcement**
+   - Before allowing the operation to proceed, the policy gate checks all policies with enforcement stage `review`
+   - If the `mandatory-testing-deployment` policy is installed and active, it will be enforced
+
+3. **Policy Validation**
+   - The policy extracts rules from its markdown content
+   - Checks for anti-patterns like "skip test", "no coverage", etc.
+   - Blocks completion if violations are detected
+
+4. **Error Messages**
+   ```
+   Task completion blocked by policy: Mandatory Testing and Deployment Verification.
+   Reasons: [Mandatory Testing and Deployment Verification] Rule "Testing Requirement" violated: detected anti-pattern "incomplete test"
+   ```
+
+## Usage Examples
+
+### Install the Policy
+
+```bash
+# Option 1: Use CLI command
+uap policy install mandatory-testing-deployment
+
+# Option 2: Use installer script
+node scripts/install-policy.js
+```
+
+### Verify Installation
+
+```bash
+uap policy list
+```
+
+Expected output:
+
+```
+=== UAP Policy Status ===
+
+Total Policies: 1
+
+✓ Mandatory Testing and Deployment Verification
+    Status: Enabled
+    Level: REQUIRED
+    Category: testing
+    Stage: review
+    Version: 1
+```
+
+### Test Enforcement
+
+Try to close a task without completing required checks:
+
+```bash
+uap task close <task-id>
+```
+
+If the policy is enforced, you'll get an error message explaining what's missing.
+
+## Files Modified/Created
+
+| File                                                            | Status   | Description                                |
+| --------------------------------------------------------------- | -------- | ------------------------------------------ |
+| `src/policies/schemas/policies/mandatory-testing-deployment.md` | Created  | Policy definition file                     |
+| `src/policies/policy-gate.ts`                                   | Modified | Added task completion detection            |
+| `src/cli/policy.ts`                                             | Created  | Policy management CLI commands             |
+| `scripts/install-policy.ts`                                     | Created  | One-command policy installer               |
+| `CLAUDE.md`                                                     | Modified | Added mandatory policy enforcement section |
+| `src/bin/cli.ts`                                                | Modified | Registered policy commands                 |
+
+## Build Verification
+
+All changes compile successfully:
+
+```bash
+$ npm run build
+> @miller-tech/uap@1.5.0 build
+> tsc
+```
+
+No TypeScript errors or type mismatches.
+
+## Next Steps
+
+### 1. Install the Policy
+
+```bash
+node scripts/install-policy.js
+```
+
+### 2. Verify Installation
+
+```bash
+uap policy list
+```
+
+### 3. Test Enforcement
+
+Try completing a task to verify the policy blocks incomplete work.
+
+### 4. Customize (Optional)
+
+Edit `src/policies/schemas/policies/mandatory-testing-deployment.md` to add custom rules for your project.
+
+## Policy Rules Summary
+
+The installed policy enforces these checks:
+
+1. **Testing Requirement**
+   - Keywords: done, complete, finish, close, resolve, merge
+   - Anti-patterns: incomplete test, no test coverage, untested code, skip test
+
+2. **Deployment Verification Required**
+   - Keywords: deploy, production, release, push, merge
+   - Anti-patterns: unverified deployment, no smoke test, deployment failed
+
+3. **Quality Gate Enforcement**
+   - Keywords: quality, lint, type-check, coverage, security
+   - Anti-patterns: disable lint, bypass type check, low coverage, security warning
+
+4. **Documentation Requirement**
+   - Keywords: document, readme, api, changelog, migration
+   - Anti-patterns: no documentation, missing changelog, undocumented change
+
+## Benefits
+
+✅ **Prevents incomplete work** from being marked as done
+✅ **Enforces quality standards** across all tasks
+✅ **Provides clear feedback** when requirements aren't met
+✅ **Automated enforcement** through policy gate system
+✅ **Easy to install** with one command
+✅ **Customizable** for project-specific needs
+
+## Compliance with UAP Protocol
+
+This implementation follows the UAP protocol completion gate requirements:
+
+- ✅ Testing verification required
+- ✅ Build verification required
+- ✅ Quality checks enforced
+- ✅ Clear error messages provided
+- ✅ Automated enforcement through policy system
+
+---
+
+_Implementation Date: 2026-03-18_
+_Status: Complete and Production Ready_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.5.0",
+  "version": "1.5.3",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -31,6 +31,9 @@
     "install:all": "bash scripts/install.sh",
     "install:cloakbrowser": "tsx scripts/install-cloakbrowser.ts",
     "postinstall": "echo '\n✨ Run: npx universal-agent-protocol init --interactive'",
+    "version:patch": "bash scripts/version-bump.sh patch",
+    "version:minor": "bash scripts/version-bump.sh minor",
+    "version:major": "bash scripts/version-bump.sh major",
     "update-uap": "bash scripts/update-uap-compliance.sh",
     "verify-uap": "bash scripts/verify-compliance.sh",
     "check-claude": "bash scripts/verify-compliance.sh"