@miller-tech/uap 1.20.33 → 1.20.35

package/docs/AGENTS.md</path>CLAUDE.md</path>/home/cogtek/dev/miller-tech/universal-agent-protocol/docs/INDEX.md</path>/home/cogtek/dev/miller-tech/universal-agent-protocol/docs/reference/API_REFERENCE.md</path>/home/cogtek/dev/miller-tech/universal-agent-protocol/docs/reference/UAP_CLI_REFERENCE.md</path>src/index.ts</path>/src/cli/worktree.ts</path>/src/coordination/deploy-batcher.ts</path>/src/policies/policy-gate.ts</path>/src/memory/model-router.ts</path>/src/memory/embeddings.ts</path>/src/models/types.ts</path>/src/types/coordination.ts</path>/src/utils/logger.ts</path>/src/utils/config-loader.ts</path>/src/utils/performance-monitor.ts</path>/src/utils/concurrency.ts</path>/src/utils/concurrency-pool.ts</path>/src/utils/string-similarity.ts</path>/src/utils/rate-limiter.ts</path>/src/utils/system-resources.ts</path>/src/utils/adaptive-cache.ts</path>/src/utils/lazy-imports.ts</path>/src/utils/merge-claude-md.ts</path>/src/utils/stopwords.ts</path>/src/utils/config-loader.ts</path>/src/utils/performance-monitor.ts</path>/src/utils/concurrency.ts</path>/src/utils/concurrency-pool.ts</path>/src/utils/string-similarity.ts</path>/src/utils/rate-limiter.ts</path>/src/utils/system-resources.ts</path>/src/utils/adaptive-cache.ts</path>/src/utils/lazy-imports.ts</path>/src/utils/merge-claude-md.ts</path>/src/utils/stopwords.ts</path>

@@ -0,0 +1,433 @@
+# UAP Project Code Analysis and Documentation Audit Report
+
+## Executive Summary
+
+The Universal Agent Protocol (UAP) is a comprehensive AI agent framework with extensive functionality for persistent memory, multi-agent coordination, pattern-based workflows, and policy enforcement. The project contains approximately 143 TypeScript source files, 74 test files, and over 9 total files (including benchmark results and agent sessions).
+
+## Documentation Quality Assessment
+
+### Current State: GOOD TO VERY GOOD
+
+**Strengths:**
+- Comprehensive README.md (542 lines) with feature overview, CLI reference, and architecture diagrams
+- Extensive CLI reference documentation (620 lines in UAP_CLI_REFERENCE.md)
+- Architecture documentation covering system design and components
+- Benchmark results and validation plans documented
+- Integration guides for multiple platforms (Claude, Factory, OpenCode, etc.)
+- Documentation version mismatch (README shows v1.20.32, INDEX.md shows v1.18.0)
+- Some CLI commands in code don't match documentation
+- Limited inline JSDoc comments in source files
+- Outdated architecture diagrams with placeholder text
+- Missing documentation for several internal modules
+
+## Feature Inventory
+
+### 1. Memory System (27+ modules)
+**Well-documented:**
+- Hierarchical memory (Hot/Warm/Cold tiers)
+- Embedding service with multiple providers
+- Knowledge graph implementation
+- Semantic compression
+- Write gate quality filtering
+- Daily log staging area
+
+**Under-documented:**
+- Predictive memory service
+- Context pruner (token-budget-aware)
+- Ambiguity detector (P37 pattern)
+- Prepopulation from docs/git history
+- Memory maintenance routines
+- Correction propagator for cross-tier updates
+
+### 2. Multi-Agent Coordination (8 modules)
+**Well-documented:**
+- Coordination service and database
+- Agent lifecycle management
+- Work claims and announcements
+- Messaging system with channels
+- Deploy batching with configurable windows
+
+**Under-documented:**
+- Capability router (18 capability types)
+- Auto-agent registration
+- Pattern router implementation
+- Adaptive patterns with success tracking
+
+### 3. Policy Enforcement (8 modules)
+**Well-documented:**
+- Policy schema and database manager
+- Policy memory CRUD operations
+- Enforcement levels (REQUIRED/RECOMMENDED/OPTIONAL)
+- Audit trail functionality
+
+**Under-documented:**
+- Policy gate middleware implementation
+- Enforced tool router
+- Python enforcement tools
+- Policy converter to CLAUDE.md format
+
+### 4. Pattern System (23+ patterns)
+**Well-documented:**
+- Pattern list with descriptions
+- Critical patterns (P12, P35) always active
+- Pattern RAG management
+
+**Under-documented:**
+- Pattern matching algorithm
+- Pattern library storage format
+- Pattern success tracking metrics
+- Custom pattern creation guide
+
+### 5. Worktree System
+**Well-documented:**
+- CLI commands (create, list, pr, cleanup, finish)
+- Git workflow integration
+- Exempt paths documentation
+
+**Under-documented:**
+- Worktree file guard enforcement mechanism
+- Branch naming conventions
+- Conflict resolution strategies
+- Prune functionality details
+
+### 6. Hooks System
+**Well-documented:**
+- Session start hook (5 steps)
+- Pre-compact hook (4 steps)
+- Platform-specific installations
+- Hook status checking
+
+**Under-documented:**
+- Pre-tool-use hooks (mentioned but not detailed)
+- Post-tool-use hooks
+- Custom hook creation guide
+- Hook failure recovery
+
+### 7. MCP Router
+**Well-documented:**
+- 98% token reduction claim
+- Meta-tool routing concept
+- Config parser and fuzzy search
+
+**Under-documented:**
+- Client pool management
+- Output compression algorithm
+- Session statistics tracking
+- Tool discover/execute definitions
+
+### 8. Multi-Model Architecture
+**Well-documented:**
+- 3-tier execution model
+- 13 model profiles
+- Dynamic temperature and rate limiting
+- Model analytics
+
+**Under-documented:**
+- Task planner decomposition algorithm
+- Plan validator cycle detection
+- Unified router logic
+- Execution profile loading
+
+### 9. Browser Automation
+**Well-documented:**
+- CloakBrowser integration
+- Playwright drop-in compatibility
+- Basic usage example
+
+**Under-documented:**
+- Stealth techniques
+- Humanize mode details
+- Error handling
+- Performance characteristics
+
+### 10. Task Management
+**Well-documented:**
+- Task types and statuses
+- Priority levels (P0-P4)
+- Dependencies and claims
+- JSONL sync format
+
+**Under-documented:**
+- Event bus implementation
+- Decoder gate mechanism
+- Task classifier (9 categories)
+- Compaction/archive logic
+
+### 11. Droids & Skills
+**Well-documented:**
+- 8 expert droids listed
+- 33 skills categorized
+- Skill documentation command
+
+**Under-documented:**
+- Droid creation process
+- Skill loading mechanism
+- Custom droid development
+- Skill composition patterns
+
+## Documentation Gaps by Priority
+
+### CRITICAL (Must-Have)
+
+1. **Inline JSDoc for Public APIs**
+   - Missing from src/index.ts exports (340 lines of exports)
+   - Affects: Memory system, coordination, policies, models, MCP router
+   - autocomplete and API documentation generation
+
+2. **CLI Command Completeness**
+   - Dashboard has 11 views but only partially documented
+   - Model commands (8 subcommands) under-documented
+   - Policy commands (15 subcommands) need examples
+   - Worktree finish command behavior not explained
+
+3. **Configuration Schema Documentation**
+   - .uap.json schema incomplete
+   - Missing validation rules
+   - Environment variables not fully listed
+
+4. **Database Schema Accuracy**
+   - API_REFERENCE.md shows outdated table structures
+   - Missing tables: deploy_queue, pattern_index, task_events
+   - Qdrant collection schemas not documented
+
+5. **Hook System Implementation Details**
+   - Pre-edit build gate enforcement mechanism
+   - Worktree file guard blocking logic
+   - Completion gate verification steps
+
+### HIGH PRIORITY (Should-Have)
+
+6. **Memory System Architecture Diagram**
+   - Current diagram has placeholder text
+   - 4-layer architecture needs visual representation
+   - Data flow between tiers unclear
+
+7. **Pattern Library Reference**
+   - All 23+ patterns need detailed descriptions
+   - Pattern selection criteria missing
+   - Pattern composition examples
+
+8. **Multi-Agent Coordination Flow**
+   - Heartbeat mechanism details
+   - Overlap detection algorithm
+   - Message priority handling
+   - Deadlock prevention
+
+9. **Policy Enforcement Workflow**
+   - Policy evaluation order
+   - Violation handling procedures
+   - Audit trail query examples
+
+10. **Testing and Quality Gates**
+    - Test coverage requirements (50% threshold)
+    - Build gate enforcement
+    - Completion gate verification steps
+
+### MEDIUM PRIORITY (Nice-to-Have)
+
+11. **Benchmark Methodology**
+    - Terminal-Bench adapter details
+    - Harbor integration workflow
+    - A/B comparison methodology
+
+12. **Deployment Guides**
+    - Production Qdrant setup
+    - CI/CD pipeline configuration
+    - Horizontal scaling patterns
+
+13. **Troubleshooting Matrix**
+    - Error code reference
+    - Common failure modes
+    - Recovery procedures
+
+14. **Integration Patterns**
+    - RTK token compression details
+    - Platform-specific optimizations
+    - Custom adapter development
+
+15. **Performance Optimization Guide**
+    - Token budget management
+    - Cache warm strategies
+    - Memory pruning thresholds
+
+## Specific Recommendations
+
+### Immediate Actions (Week 1-2)
+
+1. **Add JSDoc to src/index.ts**
+   ```typescript
+   /**
+    * Hierarchical memory manager with hot/warm/cold tiering
+    * @see src/memory/hierarchical-memory.ts for implementation details
+    */
+   export { HierarchicalMemoryManager } from './memory/hierarchical-memory.js';
+documentation/architecture diagrams**
+   - Replace placeholder text in docs/INDEX.md
+   - Create Mermaid diagrams for memory flow
+   - Document data persistence layers
+
+3. **Complete CLI Reference**
+   - Add all 109 commands with examples
+   - Include exit codes and error messages
+   - Document shell completion setup
+
+4. **Fix Version Mismatch**
+   - Update INDEX.md to v1.20.32
+   - Ensure CHANGELOG.md is current
+   - Sync README version numbers
+
+5. **Document Database Schemas**
+   - Update API_REFERENCE.md with actual tables
+   - Add Qdrant collection schemas
+   - Include migration guides
+
+### Short-Term Actions (Week 3-4)
+
+6. **Create Module-Level Documentation**
+   - Add README.md to each src/ subdirectory
+   - Document module responsibilities and dependencies
+   - Include usage examples
+
+7. **Build Pattern Library Reference**
+   - Document all 23+ patterns with use cases
+   - Add pattern selection decision tree
+   - Create pattern composition examples
+
+8. **Enhance Hook Documentation**
+   - Document all hook types (pre/post tool-use)
+   - Add hook failure recovery guide
+   - Include custom hook templates
+
+9. **Complete Configuration Guide**
+   - Full .uap.json schema with validation
+   - Environment variable reference
+   - Platform-specific configs
+
+10. **Add Testing Documentation**
+    - Test coverage requirements
+    - Build gate enforcement
+    - Completion gate checklist
+
+### Long-Term Actions (Month 2+)
+
+11. **Generate API Documentation**
+    - Use TypeDoc for TypeScript APIs
+    - Integrate with GitHub Pages
+    - Keep in sync with code changes
+
+12. **Create Video Tutorials**
+    - Quick start walkthrough
+    - Advanced feature demonstrations
+    - Troubleshooting guides
+
+13. **Develop Interactive Examples**
+    - Code sandbox for CLI commands
+    - Memory system visualization
+    - Multi-agent simulation
+
+14. **Establish Documentation Review Process**
+    - Require docs updates with PRs
+    - Add docs linting to CI
+    - Schedule quarterly reviews
+
+15. **Create Contribution Guide**
+    - Documentation standards
+    - Template examples
+    - Review process
+
+## Proposed Documentation Structure
+
+### Current Structure (Adequate)
+```
+docs/
+├── getting-started/      ✓ Good coverage
+├── architecture/         ⚠ Needs updates
+├── reference/            ✓ CLI ref good, API ref outdated
+├── deployment/           ⚠ Incomplete
+├── benchmarks/           ✓ Comprehensive
+├── operations/           ⚠ Minimal
+├── integrations/         ✓ Good coverage
+├── research/             ⚠ Academic focus
+└── archive/              ℹ Historical reference
+```
+
+### Proposed Enhanced Structure
+```
+docs/
+├── getting-started/
+│   ├── QUICKSTART.md     ← New: 5-minute setup
+│   ├── INSTALLATION.md   ← Updated: Platform-specific
+│   └── TROUBLESHOOTING.md ← Merged from operations/
+│   ├── memory-system.md
+│   ├── coordination.md
+│   ├── patterns.md
+│   └── policies.md
+├── architecture/
+│   ├── OVERVIEW.md       ← Updated with diagrams
+│   ├── COMPONENTS.md     ← New: Module details
+│   ├── DATA_FLOW.md      ← New: Data persistence
+│   └── SCHEMAS.md        ← Updated: Database specs
+├── reference/
+│   ├── CLI_REFERENCE.md  ✓ Complete
+│   ├── API_REFERENCE.md  ← Updated with JSDoc
+│   ├── CONFIG_SCHEMA.md  ← New: Full schema
+│   └── ERROR_CODES.md    ← New: Error reference
+├── guides/               ← New: Practical tutorials
+│   ├── memory-best-practices.md
+│   ├── multi-agent-setup.md
+│   ├── policy-enforcement.md
+│   ├── pattern-library.md
+│   └── worktree-workflow.md
+├── deployment/
+│   ├── PRODUCTION.md     ← Updated
+│   ├── CI_CD.md          ← Updated
+│   ├── SCALING.md        ← New: Horizontal scaling
+│   └── MONITORING.md     ← New: Observability
+├── benchmarks/           ✓ Comprehensive
+├── operations/
+│   ├── MAINTENANCE.md    ← New: Routine tasks
+│   ├── BACKUP_RESTORE.md ← New: Disaster recovery
+│   └── DEBUGGING.md      ← Updated: Debug modes
+├── integrations/         ✓ Good coverage
+├── contributed/          ← New: Community content
+└── archive/              ℹ Historical reference
+```
+
+## Test Coverage Analysis
+
+### Current State
+- 74 test files covering major components
+- Tests for: policies, memory, coordination, models, benchmarks, CLI
+- Vitest configuration with coverage thresholds (50%)
+
+### Gaps
+1. **Browser module** - Minimal test coverage
+2. **MCP router** - Only output-compressor tested
+3. **Dashboard** - Server and event-stream not tested
+4. **Telemetry** - Session telemetry untested
+5. **Benchmarks** - Agent implementations not tested
+
+### Recommendations
+1. Add JSDoc to test files for clarity
+2. Create integration test suite
+3. Document test coverage requirements
+4. Add performance test benchmarks
+
+## Conclusion
+
+The UAP project has **solid foundational documentation** with comprehensive CLI references and good architectural overviews. However, there are significant gaps in:
+   - Inline code documentation (JSDoc)
+2. Module-level documentation for internal components
+3. Accurate database schemas
+4. Configuration schema completeness
+5. Hook system implementation details
+
+**Priority Ranking:**
+- **Must-Have**: JSDoc, CLI completeness, config schema, DB schemas, hook docs
+   - Architecture diagrams, pattern library, coordination flows, policy workflows, testing docs
+- **Nice-to-Have**: Video tutorials, interactive examples, contribution guide, API generation
+- Critical fixes: 2-3 weeks
+- High priority: 4-6 weeks
+- Medium priority: 8-12 weeks
+
+The documentation quality is sufficient for current users but needs improvement to support new contributors and maintain long-term project health.

package/docs/DOCUMENTATION_AUDIT_REPORT.md

@@ -0,0 +1,131 @@
+# UAP Documentation Audit Report
+
+The Universal Agent Protocol (UAP) project has comprehensive foundational documentation but needs improvements in:
+
+- Inline JSDoc comments (140+ exports missing docs)
+- Module-level README files
+- Database schema accuracy
+- CLI command completeness
+
+## Current State Assessment:
+
+- Comprehensive README.md (542 lines) with feature overview
+- Extensive CLI reference documentation (620 lines)
+- Architecture documentation with Mermaid diagrams
+- Benchmark results thoroughly documented
+
+## Documentation Gaps by Priority:
+
+### CRITICAL (Must-Have):
+
+1. **Inline JSDoc for Public APIs** - Missing from src/index.ts exports
+2. **CLI Command Completeness** - Dashboard (13 views), model commands (8 subcommands), policy commands (15 subcommands) under-documented
+3. **Configuration Schema Documentation** - .uap.json schema incomplete, missing validation rules
+4. **Database Schema Accuracy** - API_REFERENCE.md shows outdated table structures
+5. **Hook System Implementation Details** - Pre-edit build gate enforcement mechanism not explained
+
+### HIGH PRIORITY (Should-Have):
+
+6. **Memory System Architecture Diagram** - Current diagram has placeholder text
+7. **Pattern Library Reference** - All 23+ patterns need detailed descriptions
+8. **Multi-Agent Coordination Flow** - Heartbeat mechanism details missing
+9. **Policy Enforcement Workflow** - Policy evaluation order not documented
+10. **Testing and Quality Gates** - Test coverage requirements (50% threshold) undocumented
+
+### MEDIUM PRIORITY (Nice-to-Have):
+
+11. **Benchmark Methodology** - Terminal-Bench adapter details
+12. **Deployment Guides** - Production Qdrant setup
+13. **Troubleshooting Matrix** - Error code reference
+14. **Integration Patterns** - RTK token compression details
+15. **Performance Optimization Guide** - Token budget management
+
+## Recommended Documentation Strategy: Hybrid Approach
+
+**Combine comprehensive README with inline JSDoc:**
+
+**Pros:**
+
+- Single source of truth in README for quick onboarding
+- IDE autocomplete via JSDoc for developers
+- Lower maintenance burden than separate docs site
+
+**Cons:**
+
+- README can become unwieldy (542+ lines)
+- Inline docs can drift from code if not maintained
+
+## Implementation Roadmap:
+
+### Phase 1: Critical Fixes (Weeks 1-2)
+
+| Task                               | Files                               | Effort  | Priority |
+| ---------------------------------- | ----------------------------------- | ------- | -------- |
+| Add JSDoc to src/index.ts exports  | src/index.ts                        | 8 hours | CRITICAL |
+| Update database schemas            | docs/reference/API_REFERENCE.md     | 4 hours | CRITICAL |
+| Update configuration schema        | README.md, docs/INDEX.md            | 3 hours | CRITICAL |
+| Complete CLI command documentation | docs/reference/UAP_CLI_REFERENCE.md | 6 hours | HIGH     |
+
+### Phase 2: Module Documentation (Weeks 3-4)
+
+| Task                              | Files                      | Effort  | Priority |
+| --------------------------------- | -------------------------- | ------- | -------- |
+| Create memory module README       | src/memory/README.md       | 4 hours | HIGH     |
+| Create coordination module README | src/coordination/README.md | 3 hours | HIGH     |
+| Create policies module README     | src/policies/README.md     | 3 hours | HIGH     |
+| Create models module README       | src/models/README.md       | 3 hours | MEDIUM   |
+
+### Phase 3: Advanced Documentation (Months 2-3)
+
+| Task                                   | Files                             | Effort  | Priority |
+| -------------------------------------- | --------------------------------- | ------- | -------- |
+| Generate API docs with TypeDoc         | docs/api/                         | 8 hours | MEDIUM   |
+| Create pattern library reference       | docs/reference/PATTERN_LIBRARY.md | 6 hours | HIGH     |
+| Add memory architecture diagram        | docs/INDEX.md                     | 2 hours | HIGH     |
+| Establish documentation review process | CONTRIBUTING.md                   | 3 hours | MEDIUM   |
+
+## Module-Level Documentation Analysis:
+
+### Source Code Structure (143 files):
+
+| Directory         | Files    | Documentation Status | Gaps                                                  |
+| ----------------- | -------- | -------------------- | ----------------------------------------------------- |
+| src/memory/       | 22 files | ⚠️ PARTIAL           | Predictive memory, context pruner, ambiguity detector |
+| src/models/       | 10 files | ⚠️ PARTIAL           | Unified router logic, execution profile loading       |
+| src/coordination/ | 6 files  | ⚠️ PARTIAL           | Capability router (18 types), adaptive patterns       |
+| src/cli/          | 27 files | ✅ GOOD              | Dashboard views, model commands need examples         |
+| src/utils/        | 10 files | ✅ GOOD              | Well-documented utilities                             |
+| src/policies/     | 8 files  | ⚠️ PARTIAL           | Policy gate middleware, Python enforcement tools      |
+| src/mcp-router/   | 10 files | ⚠️ PARTIAL           | Client pool management, session stats tracking        |
+| src/tasks/        | 7 files  | ⚠️ PARTIAL           | Event bus implementation, decoder gate mechanism      |
+| src/browser/      | 2 files  | ❌ MINIMAL           | Stealth techniques, error handling                    |
+| src/dashboard/    | 2 files  | ❌ MINIMAL           | Server and event-stream not tested                    |
+| src/telemetry/    | 0 tests  | ❌ MISSING           | Session telemetry untested                            |
+
+## Test Coverage Gaps:
+
+| Module              | Test Files | Tests | Coverage Status | Missing                                         |
+| ------------------- | ---------- | ----- | --------------- | ----------------------------------------------- |
+| Browser             | 1 file     | 4     | ❌ MINIMAL      | Stealth techniques, error handling, performance |
+| MCP Router          | 3 files    | 40+   | ⚠️ PARTIAL      | Client pool, session stats, tool execution      |
+| Dashboard           | 2 files    | ~10   | ❌ MINIMAL      | Server, event-stream, real-time updates         |
+| Telemetry           | 0 files    | 0     | ❌ MISSING      | Session tracking, model usage metrics           |
+| Benchmarks (agents) | 0 files    | 0     | ❌ MISSING      | Agent implementation tests                      |
+
+## Conclusion:
+
+The UAP project has **solid foundational documentation** with comprehensive CLI references and good architectural overviews. However, there are significant gaps that need addressing.
+
+### Top 5 Priorities:
+
+1. **Add JSDoc to src/index.ts** (2-3 hours) - Affects IDE autocomplete for all users
+2. **Update database schemas in API_REFERENCE.md** (4 hours) - Critical for developers
+3. **Create module-level READMEs** (12 hours total) - Improves code navigation
+4. **Complete CLI command documentation** (6 hours) - Helps power users
+5. **Document configuration schema** (3 hours) - Essential for setup
+
+### Recommended Strategy: Hybrid Approach
+
+Best balance of developer experience and maintenance burden.
+
+**Total Effort:** ~52 hours over 3 months