@miller-tech/uap 1.5.0 → 1.5.2

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.2",
   "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"

package/templates/hooks/session-start.sh

@@ -184,16 +184,37 @@ if docker ps --filter name=qdrant --format "{{.Status}}" 2>/dev/null | grep -q "
   QDRANT_STATUS="ON"
 fi
 
-# Git branch
-GIT_BRANCH=$(git -C "$PROJECT_DIR" branch --show-current 2>/dev/null || echo "?")
-GIT_DIRTY=$(git -C "$PROJECT_DIR" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+# Git branch (safe fallback if not in git repo)
+GIT_BRANCH="?"
+if [ -d "${PROJECT_DIR}/.git" ]; then
+  GIT_BRANCH=$(git -C "$PROJECT_DIR" branch --show-current 2>/dev/null || echo "?")
+fi
+GIT_DIRTY=0
+if [ -d "${PROJECT_DIR}/.git" ]; then
+  GIT_DIRTY=$(git -C "$PROJECT_DIR" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+fi
 
-# Worktree count
+# Worktree count (safe fallback if not in UAP project)
 WORKTREE_COUNT=0
 if [ -d "${PROJECT_DIR}/.worktrees" ]; then
   WORKTREE_COUNT=$(find "${PROJECT_DIR}/.worktrees" -maxdepth 1 -mindepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
 fi
 
+# Check if worktree workflow is enabled in config
+WORKTREE_ENABLED=false
+if [ -f "${PROJECT_DIR}/.uap.json" ]; then
+  WORKTREE_ENABLED=$(node -e "try{const c=JSON.parse(require('fs').readFileSync('${PROJECT_DIR}/.uap.json','utf8'));console.log(c.template?.sections?.worktreeWorkflow ? 'true' : 'false')}catch{console.log('false')}" 2>/dev/null || echo "false")
+fi
+
+# Check if we're inside a worktree directory
+IN_WORKTREE=false
+if [ -d "${PROJECT_DIR}/.worktrees" ]; then
+  CURRENT_DIR=$(pwd)
+  if [[ "$CURRENT_DIR" == *"/.worktrees/"* ]]; then
+    IN_WORKTREE=true
+  fi
+fi
+
 # Pattern count
 PATTERN_COUNT=0
 if [ -f "${PROJECT_DIR}/.factory/patterns/index.json" ]; then
@@ -241,12 +262,21 @@ output+="│ ${MEM_LINE}$(printf ' %.0s' $(seq 1 $((W - 1 - ${#MEM_LINE}))))│"
 INFRA_LINE="Agents: ${AGENT_COUNT}  Patterns: ${PATTERN_COUNT}  Skills: ${SKILL_COUNT}  Droids: ${DROID_COUNT}"
 output+="│ ${INFRA_LINE}$(printf ' %.0s' $(seq 1 $((W - 1 - ${#INFRA_LINE}))))│"$'\n'
 
+
 # Git & worktree line
-GIT_LINE="Git: ${GIT_DIRTY} uncommitted  Worktrees: ${WORKTREE_COUNT}"
+if [ "$WORKTREE_ENABLED" = "true" ]; then
+  if [ "$IN_WORKTREE" = "true" ]; then
+    WORKTREE_STATUS="✅ In worktree"
+  else
+    WORKTREE_STATUS="⚠️ Use worktree (uap worktree create <slug>)"
+  fi
+else
+  WORKTREE_STATUS="Worktrees disabled"
+fi
+GIT_LINE="Git: ${GIT_DIRTY} uncommitted  ${WORKTREE_STATUS}"
 output+="│ ${GIT_LINE}$(printf ' %.0s' $(seq 1 $((W - 1 - ${#GIT_LINE}))))│"$'\n'
 
 output+="├$(printf '─%.0s' $(seq 1 $W))┤"$'\n'
-
 # Active policies
 output+="│ Policies: [ON] IaC Parity  [ON] File Backup$(printf ' %.0s' $(seq 1 $((W - 47))))│"$'\n'