@miller-tech/uap 1.40.0 → 1.41.0

package/docs/AGENTS.md

@@ -1,423 +0,0 @@
-# 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 90,000 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.)
-
-**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
-   - Impact: Breaks IDE 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';
-   - Replace placeholder text in docs/INDEX.md
-   - Create Mermaid diagrams for memory flow
-   - Document data persistence layers
-
-   ```
-
-2. **Complete CLI Reference**
-   - Add all 109 commands with examples
-   - Include exit codes and error messages
-   - Document shell completion setup
-
-3. **Fix Version Mismatch**
-   - Update INDEX.md to v1.20.32
-   - Ensure CHANGELOG.md is current
-   - Sync README version numbers
-
-4. **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:
-
--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:
-
-1. 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

@@ -1,131 +0,0 @@
-# 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