@miller-tech/uap 1.40.0 → 1.41.0

package/docs/reference/FEATURES.md

@@ -1,472 +1,176 @@
-# Universal Agent Protocol (UAP) - Feature Inventory & Status
-
-**npm Version:** 7.0.2
-**Last Updated:** 2026-03-14
-**Tests:** 267 passing (23 files)
-
----
-
-## Feature Status Legend
-
-| Status  | Meaning                              |
-| ------- | ------------------------------------ |
-| ENABLED | Fully implemented, tested, optimized |
-| PARTIAL | Implemented but with known gaps      |
-| STUB    | Interface exists but no real logic   |
-| PLANNED | Not yet implemented                  |
-
----
-
-## 1. Memory System
-
-### 1.1 Working Memory (L1) — ENABLED
-
-**Source:** `src/memory/` (SQLite via better-sqlite3)
-**Storage:** `agents/data/memory/short_term.db`
-**Tables:** `memories` with FTS5 index (`memories_fts`)
-
-| Setting        | Value                        |
-| -------------- | ---------------------------- |
-| Max entries    | 50                           |
-| Access latency | <1ms (in-memory)             |
-| Write gate     | 5-criteria scoring (min 0.3) |
-
-**Write Gate** (`src/memory/write-gate.ts:94`): Evaluates 5 criteria before storing:
-
-- `behavioral_change`, `commitment`, `decision_rationale`, `stable_fact`, `explicit_request`
-- Noise pattern rejection (greetings, acknowledgments, status updates)
-- Score: 0.4 first match + 0.15 per additional + length bonus
-
-**CLI:** `uap memory store`, `uap memory query`, `uap memory status`
-
-### 1.2 Session Memories (L2) — ENABLED
-
-**Source:** Same SQLite DB, `session_memories` table
-**Threshold:** importance >= 7
-**Promotion:** Via `uap memory promote` or automatic from daily log
-
-### 1.3 Semantic Memory (L3) — ENABLED
-
-**Source:** Qdrant vector database (`src/memory/backends/`)
-**Backends:** Qdrant Cloud (`qdrant-cloud.test.ts`), GitHub (`github.ts`)
-**Embedding:** Deterministic SHA-256 hash vectors (CLI) or sentence-transformers (Python)
-**Cache:** LRU eviction policy (`src/memory/embeddings.ts:598`)
-
-| Setting         | Value                   |
-| --------------- | ----------------------- |
-| Vector size     | 384                     |
-| Score threshold | 0.35                    |
-| Embedding cache | LRU, max 10,000 entries |
-
-**Note:** CLI uses deterministic hash-based pseudo-random vectors. For real semantic search, use the Python sentence-transformers pipeline (`uap patterns index`).
-
-### 1.4 Knowledge Graph (L4) — ENABLED
-
-**Source:** SQLite `entities` and `relationships` tables
-**Algorithm:** Dijkstra shortest path (`src/utils/dijkstra.ts:17`)
-
-### 1.5 Memory Tiering — ENABLED
-
-**Tiers:** HOT (10) / WARM (50) / COLD (500)
-**Adaptive Context:** `src/memory/adaptive-context.ts`
-**DB Pool:** 5 SQLite connections, round-robin selection, WAL mode
-
-| Setting      | Value         |
-| ------------ | ------------- |
-| Pool size    | 5 connections |
-| Journal mode | WAL           |
-| Synchronous  | NORMAL        |
-| Busy timeout | 10,000ms      |
-
-### 1.6 Daily Log — ENABLED
-
-**Source:** `src/memory/daily-log.ts:47`
-**Purpose:** Staging area for memories before promotion
-**Promotion threshold:** score >= 0.6
-
-### 1.7 Correction Propagator — ENABLED
-
-**Source:** `src/memory/correction-propagator.ts:59`
-**Purpose:** Cross-tier correction propagation with superseded history tracking
-**Corrected entry importance:** 8
-
-### 1.8 Agent-Scoped Memory — ENABLED
-
-**Source:** `src/memory/agent-scoped-memory.ts:52`
-**Purpose:** Per-agent memory isolation with sharing capability
-**Indexed on:** agent_id, shared, importance
-
-### 1.9 Memory Consolidator — ENABLED
-
-**Source:** `src/memory/memory-consolidator.ts`
-**Security:** Parameterized SQL queries (SQL injection fixed in v4.8.1)
-
----
-
-## 2. Multi-Model Architecture
-
-### 2.1 Model Router — ENABLED
-
-**Source:** `src/models/router.ts:89`
-**Purpose:** Classifies tasks by complexity/type, selects optimal model via priority-sorted routing rules
-
-| Setting          | Default                                                                 |
-| ---------------- | ----------------------------------------------------------------------- |
-| Strategy         | `balanced` (3 of 4 strategies differentiated; `adaptive` == `balanced`) |
-| Default planner  | `opus-4.5`                                                              |
-| Default executor | `glm-4.7`                                                               |
-| Default fallback | `opus-4.5`                                                              |
-| Routing rules    | 11 default rules, priority 30-100                                       |
-
-**Model Presets** (6): `opus-4.5`, `deepseek-v3.2`, `deepseek-v3.2-exp`, `glm-4.7`, `gpt-5.2`, `qwen35-a3b`
-
-**Known Gap:** `routingStrategy` `adaptive` is accepted but behaves identically to `balanced`. The other 3 strategies (`cost-optimized`, `performance-first`, `balanced`) are differentiated.
-
-### 2.2 Task Planner — ENABLED
-
-**Source:** `src/models/planner.ts:42`
-**Purpose:** Decomposes tasks into dependency-aware subtasks with model assignment
-
-| Setting         | Default                         |
-| --------------- | ------------------------------- |
-| Max subtasks    | 10                              |
-| Max depth       | 3                               |
-| Parallelization | enabled                         |
-| Auto-validation | always (mandatory since v4.8.0) |
-
-**Decomposition:** Keyword-based heuristic (not LLM-driven). Phases: Analysis, Design, Implementation, Testing, Security Review, Documentation.
-
-### 2.3 Task Executor — ENABLED
-
-**Source:** `src/models/executor.ts:69`
-**Purpose:** Executes plans with retry logic, fallback, and parallel batching
-
-| Setting      | Default                                  |
-| ------------ | ---------------------------------------- |
-| Max retries  | 2                                        |
-| Retry delay  | Exponential backoff (1s, 2s, 4s)         |
-| Step timeout | 120,000ms (2 min)                        |
-| Fallback     | enabled                                  |
-| Max parallel | 3                                        |
-| Token limits | low=2K, medium=4K, high=8K, critical=12K |
-
-**Improvements in v4.8.1:**
-
-- `previousAttempts` now populated between retries (enables retry-context prompts)
-- Exponential backoff replaces fixed 1s delay
-
-**Known Gap:** No real `ModelClient` implementation — only `MockModelClient` for testing. CLI execution prints "not implemented yet."
-
-### 2.4 Plan Validator — ENABLED
-
-**Source:** `src/models/plan-validator.ts:24`
-**Purpose:** Validates every plan for structural integrity
-
-| Check             | What it validates                                         |
-| ----------------- | --------------------------------------------------------- |
-| Subtasks          | Titles, descriptions, complexity, types, duplicates       |
-| Dependencies      | Cycle detection (DFS), non-existent references            |
-| Model assignments | Every subtask has a model                                 |
-| Constraints       | Security/performance-sensitive tasks flagged              |
-| Cost estimates    | Negative values (error), >$1000 (warning), >24h (warning) |
-
-| Setting      | Default                                        |
-| ------------ | ---------------------------------------------- |
-| Timeout      | 300,000ms (5 min), enforced via Promise.race() |
-| Strict mode  | false                                          |
-| Skip trivial | false (mandatory validation since v4.8.0)      |
-
-### 2.5 Benchmark-Data Model Router — ENABLED
-
-**Source:** `src/memory/model-router.ts:68`
-**Purpose:** Separate routing system using real Terminal-Bench benchmark data with SQLite-persisted fingerprints and adaptive learning (EMA)
-
-| Setting             | Value                       |
-| ------------------- | --------------------------- |
-| DB pool             | 5 connections, WAL mode     |
-| EMA alpha (success) | 0.1                         |
-| EMA alpha (latency) | 0.2                         |
-| Fingerprint blend   | 70% persisted / 30% default |
-| Max cost/task       | $0.05                       |
-| Max latency         | 120s                        |
-
-**Note:** This is independent from `src/models/router.ts`. The two routing systems are not yet integrated.
-
----
-
-## 3. Multi-Agent Coordination
-
-### 3.1 Coordination Database — ENABLED
-
-**Source:** `src/coordination/database.ts:5`
-**Storage:** `./agents/data/coordination/coordination.db`
-**Tables:** 6 (agent_registry, agent_messages, work_announcements, work_claims, deploy_queue, deploy_batches)
-
-| Setting      | Value                   |
-| ------------ | ----------------------- |
-| Journal mode | WAL (added v4.8.1)      |
-| Synchronous  | NORMAL (added v4.8.1)   |
-| Busy timeout | 10,000ms (added v4.8.1) |
-
-### 3.2 Coordination Service — ENABLED
-
-**Source:** `src/coordination/service.ts:31`
-**Purpose:** Agent lifecycle, resource claiming, work announcements, messaging, deploy queue, overlap detection, conflict risk assessment
-
-| Setting              | Default                     |
-| -------------------- | --------------------------- |
-| Heartbeat interval   | 30,000ms (30s)              |
-| Claim expiry         | 300,000ms (5 min)           |
-| Stale agent cutoff   | 3x heartbeat interval (90s) |
-| Message retention    | 24 hours                    |
-| Deploy default delay | 30,000ms (30s)              |
-
-**Overlap Detection:** Same-file, same-directory, overlapping-files conflicts
-**Conflict Risk:** `none` / `low` / `medium` / `high` / `critical`
-
-### 3.3 Auto Agent Coordinator — ENABLED
-
-**Source:** `src/coordination/auto-agent.ts:22`
-**Purpose:** Automatic agent registration, heartbeat, graceful exit cleanup
-
-| Setting            | Default                                              |
-| ------------------ | ---------------------------------------------------- |
-| Heartbeat interval | 30,000ms                                             |
-| Exit handlers      | SIGINT, SIGTERM, exit (tracked + removed on cleanup) |
-
-**Improvements in v4.8.1:**
-
-- Idempotent cleanup (safe to call multiple times)
-- Exit handlers tracked and removed to prevent listener leaks
-
-### 3.4 Capability Router — ENABLED
-
-**Source:** `src/coordination/capability-router.ts:159`
-**Purpose:** Routes tasks to droids/skills by file patterns, task types, keywords
-
-| Setting                   | Value                                                                            |
-| ------------------------- | -------------------------------------------------------------------------------- |
-| Default mappings          | 12 (TS, JS, CLI, security, perf, docs, review, testing, infra, Python, Rust, Go) |
-| Max recommended droids    | 3                                                                                |
-| Max recommended skills    | 2                                                                                |
-| Always-included reviewers | code-quality-guardian, security-auditor                                          |
-
-### 3.5 Pattern Router — ENABLED (restored in v4.8.1)
-
-**Source:** `src/coordination/pattern-router.ts`
-**Purpose:** Loads Terminal-Bench patterns from `.factory/patterns/index.json`, keyword matching, enforcement checklists
-
-**Was a no-op stub prior to v4.8.1.** Now fully implemented with:
-
-- Pattern loading from project directory
-- Keyword-based matching
-- Always-included critical patterns (P12 Output Existence, P35 Decoder-First)
-- Singleton with lazy initialization
-
-### 3.6 Deploy Batcher — ENABLED
-
-**Source:** `src/coordination/deploy-batcher.ts:47`
-**Purpose:** Intelligent deployment batching with squashing, deduplication, parallel execution
-
-| Action   | Normal Window | Urgent Window |
-| -------- | ------------- | ------------- |
-| commit   | 30s           | 2s            |
-| push     | 5s            | 1s            |
-| merge    | 10s           | 2s            |
-| workflow | 5s            | 1s            |
-| deploy   | 60s           | 5s            |
-
-| Setting              | Default |
-| -------------------- | ------- |
-| Max batch size       | 20      |
-| Parallel execution   | enabled |
-| Max parallel actions | 5       |
-
-**Fixed in v5.0.0:** Replaced `execSync` with async `execFile` using argument arrays. Eliminates shell injection risk and event loop blocking.
-
----
-
-## 4. Task Management
-
-### 4.1 Task Database — ENABLED
-
-**Source:** `src/tasks/database.ts:5`
-**Storage:** `./.uap/tasks/tasks.db`
-**Tables:** 5 (tasks, task_dependencies, task_history, task_activity, task_summaries)
-
-| Setting      | Value                   |
-| ------------ | ----------------------- |
-| Journal mode | WAL (added v4.8.1)      |
-| Synchronous  | NORMAL (added v4.8.1)   |
-| Busy timeout | 10,000ms (added v4.8.1) |
-
-### 4.2 Task Service — ENABLED
-
-**Source:** `src/tasks/service.ts:31`
-**Purpose:** Full CRUD, dependency DAG with cycle detection (BFS), history/audit trail, JSONL sync, compaction
-
-| Setting        | Default                    |
-| -------------- | -------------------------- |
-| JSONL path     | `./.uap/tasks/tasks.jsonl` |
-| Compact cutoff | 90 days                    |
-
-**Fixed in v5.0.0:** Added `due_date` column with migration for existing DBs. `overdue` stats now query tasks past due date that aren't closed.
-
-### 4.3 Task Coordinator — ENABLED
-
-**Source:** `src/tasks/coordination.ts:31`
-**Purpose:** Bridge between task system and coordination system
-
-**Scoring for `suggestNextTask()`:**
-
-- Priority weight: `(4 - priority) * 10` (P0=40, P4=0)
-- No-overlap bonus: +20
-- No-dependencies bonus: +5
-- Unblocks-others bonus: +3 per blocked task
-
----
-
-## 5. CLI Commands
-
-### Fully Implemented (20+)
-
-| Command          | Source                             | Purpose                                |
-| ---------------- | ---------------------------------- | -------------------------------------- |
-| `uap init`       | `src/cli/init.ts`                  | Project initialization                 |
-| `uap setup`      | `src/cli/setup.ts`                 | Full setup chain                       |
-| `uap memory`     | `src/cli/memory.ts`                | Memory management (10 subcommands)     |
-| `uap task`       | `src/cli/task.ts`                  | Task CRUD + workflow (14 subcommands)  |
-| `uap agent`      | `src/cli/agent.ts`                 | Agent lifecycle (11 subcommands)       |
-| `uap deploy`     | `src/cli/deploy.ts`                | Deploy batching (8 subcommands)        |
-| `uap worktree`   | `src/cli/worktree.ts`              | Git worktree management                |
-| `uap droids`     | `src/cli/droids.ts`                | Droid management                       |
-| `uap coord`      | `src/cli/coord.ts`                 | Coordination status/flush/cleanup      |
-| `uap model`      | `src/cli/model.ts`                 | Model routing/planning (4 subcommands) |
-| `uap dashboard`  | `src/cli/dashboard.ts`             | Rich visualization (6 sub-dashboards)  |
-| `uap patterns`   | `src/cli/patterns.ts`              | Pattern RAG management                 |
-| `uap hooks`      | `src/cli/hooks.ts`                 | Hook installer (6 platforms)           |
-| `uap compliance` | `src/cli/compliance.ts`            | Protocol compliance (12 gates)         |
-| `uap generate`   | `src/cli/generate.ts`              | CLAUDE.md generation                   |
-| `uap analyze`    | `src/cli/analyze.ts`               | Project structure analysis             |
-| `uap mcp-router` | `src/cli/mcp-router.ts`            | MCP Router management                  |
-| `uap update`     | `src/cli/update.ts`                | System update                          |
-| `uap rtk`        | `src/cli/rtk.ts`                   | RTK integration                        |
-| `llama-optimize` | `src/bin/llama-server-optimize.ts` | llama.cpp parameter optimization       |
-
-### Stubs
-
-| Command           | Source                   | Status                            |
-| ----------------- | ------------------------ | --------------------------------- |
-| `uap schema-diff` | `src/cli/schema-diff.ts` | Prints "disabled in this version" |
-
-### Implemented in v5.0.0
-
-| Command               | Source             | Status                                                                |
-| --------------------- | ------------------ | --------------------------------------------------------------------- |
-| `uap sync`            | `src/cli/sync.ts`  | Syncs droids, skills, commands between claude/factory/opencode/vscode |
-| `uap model --execute` | `src/cli/model.ts` | Executes plans via MockModelClient (dry-run mode)                     |
-
----
-
-## 6. Hooks System
-
-| Hook         | Source                             | Status                                      |
-| ------------ | ---------------------------------- | ------------------------------------------- |
-| SessionStart | `templates/hooks/session-start.sh` | ENABLED — Injects compliance checklist      |
-| PreCompact   | `templates/hooks/pre-compact.sh`   | ENABLED — DB optimization before compaction |
-| PreToolUse   | Pattern injection                  | ENABLED — Via hook system                   |
-| PostToolUse  | Memory persistence                 | ENABLED — Via hook system                   |
-
-**Platforms:** Claude Code, Factory.AI, VSCode, Cursor, OpenCode, ForgeCode
-
----
-
-## 7. Droid System
-
-**Source:** `src/uap-droids-strict.ts:35` (schema), `:183` (plugin entry)
-**Storage:** `.factory/droids/*.md` (JSON frontmatter + markdown body)
-**Validation:** Zod schema (`DROID_SCHEMA`), decoder-first gate
-
-**Built-in Templates:** code-reviewer, security-reviewer, performance-reviewer, test-writer
-
----
-
-## 8. Utilities
-
-| Utility           | Source                             | Status                                   |
-| ----------------- | ---------------------------------- | ---------------------------------------- |
-| CLAUDE.md Merger  | `src/utils/merge-claude-md.ts:325` | ENABLED                                  |
-| JSON Validator    | `src/utils/validate-json.ts:73`    | ENABLED                                  |
-| String Similarity | `src/utils/string-similarity.ts`   | ENABLED                                  |
-| Config Manager    | `src/utils/config-manager.ts:4`    | ENABLED                                  |
-| Fetch with Retry  | `src/utils/fetch-with-retry.ts:1`  | ENABLED (3 retries, exponential backoff) |
-| Rate Limiter      | `src/utils/rate-limiter.ts:16`     | ENABLED (sliding window, Zod validated)  |
-| Dijkstra          | `src/utils/dijkstra.ts:17`         | ENABLED                                  |
-
----
-
-## 9. Test Coverage
-
-| Test File                                           | Tests   | What's Covered                        |
-| --------------------------------------------------- | ------- | ------------------------------------- |
-| `test/tasks.test.ts`                                | 30      | Task CRUD, dependencies, sync, stats  |
-| `test/models.test.ts`                               | 26      | Router, planner, executor, presets    |
-| `src/memory/optimization.test.ts`                   | 21      | Memory optimization                   |
-| `test/coordination.test.ts`                         | 20      | Agent lifecycle, claims, messaging    |
-| `test/deploy-batcher.test.ts`                       | 16      | Deploy batching, squashing, execution |
-| `test/write-gate.test.ts`                           | 14      | Write gate criteria and scoring       |
-| `benchmark-env/src/utils/__tests__/helpers.test.ts` | 13      | Benchmark helpers                     |
-| `src/tests/uap-strict-droids.test.ts`               | 12      | Droid schema validation, decoder gate |
-| `test/agent-scoped-memory.test.ts`                  | 8       | Agent memory isolation                |
-| `test/session-stats.test.ts`                        | 8       | Session statistics                    |
-| `src/memory/short-term/indexeddb.test.ts`           | 8       | IndexedDB short-term memory           |
-| `test/hooks.test.ts`                                | 7       | Hook system                           |
-| `test/mcp-router-output-compressor.test.ts`         | 7       | Output compression                    |
-| `test/daily-log.test.ts`                            | 6       | Daily log staging                     |
-| `src/memory/backends/github.test.ts`                | 6       | GitHub backend                        |
-| `test/memory-maintenance.test.ts`                   | 6       | Memory maintenance                    |
-| `test/correction-propagator.test.ts`                | 5       | Correction propagation                |
-| `test/mcp-router-filter.test.ts`                    | 5       | MCP router filtering                  |
-| `src/memory/backends/qdrant-cloud.test.ts`          | 5       | Qdrant backend                        |
-| `src/utils/merge-claude-md.test.ts`                 | 4       | CLAUDE.md merging                     |
-| `src/tests/droids-parallel.test.ts`                 | 1       | Parallel droid execution              |
-| **Total**                                           | **228** | **21 files, 100% pass rate**          |
-
----
-
-## 10. Known Gaps & Future Work
-
-| Gap                                        | Impact                                                                           | Effort | Status           |
-| ------------------------------------------ | -------------------------------------------------------------------------------- | ------ | ---------------- |
-| No real `ModelClient` implementation       | High — executor only works with mock                                             | High   | Fixed in v1.0.0 |
-| Two routing systems not integrated         | Medium — `src/models/router.ts` and `src/memory/model-router.ts` are independent | Medium | Fixed in v1.0.0 |
-| `task_sync_meta` table unused              | Low — created but never populated                                                | Low    | Fixed in v1.0.0 |
-| `routingStrategy` `adaptive` == `balanced` | Low — 3 of 4 strategies differentiated                                           | Low    | Fixed in v1.0.0 |
-| `routingStrategy` 3/4 differentiated       | Medium — `cost-optimized`, `performance-first`, `balanced` work                  | N/A    | Fixed in v8.0.0  |
-| `execSync` in DeployBatcher                | Medium — blocks event loop, shell injection risk                                 | Medium | Fixed in v5.0.0  |
-| Shell injection in embeddings/prepopulate  | High — user text in shell commands                                               | Medium | Fixed in v8.0.0  |
-| Race condition in exclusive claims         | High — concurrent agents could both acquire exclusive lock                       | Low    | Fixed in v8.0.0  |
-| L4 schema missing columns                  | Medium — `description` and `strength` columns missing from base schema           | Low    | Fixed in v8.0.0  |
-| Embedding cache key collisions             | Low — `text.slice(0,500)` caused collisions for long texts                       | Low    | Fixed in v8.0.0  |
-| No tests for coordination/task subsystems  | High — ~2,600 lines untested                                                     | High   | Fixed in v5.0.0  |
-| `uap sync` not implemented                 | Low — planned for v0.9.0                                                         | Medium | Fixed in v5.0.0  |
-| `uap model --execute` not implemented      | Medium — plan execution only via API                                             | Medium | Fixed in v5.0.0  |
-| Task `overdue` stats unimplemented         | Low — no due_date column                                                         | Low    | Fixed in v5.0.0  |
-| MCP Router CLI setup placeholder           | Medium — CLI setup not functional                                                | Low    | Fixed in v1.0.0 |
-| `uap uninstall` not implemented            | Low — no cleanup command                                                         | Low    | Fixed in v1.0.0 |
-| Plugin install only for 2 harnesses        | Medium — 13+ harnesses unsupported                                               | Medium | Fixed in v1.0.0 |
-| Deploy batch config not persistent         | Medium — settings lost on restart                                                | Low    | Fixed in v1.0.0 |
-| No droid schema validation                 | Medium — invalid droids not caught                                               | Medium | Fixed in v1.0.0 |
-| No decoder gate                            | Medium — no input/output validation                                              | Medium | Fixed in v1.0.0 |
-| No dynamic compression                     | Low — static compression only                                                    | Medium | Fixed in v1.0.0 |
-| No context pruning                         | Low — no intelligent context removal                                             | Medium | Fixed in v1.0.0 |
-| No adaptive patterns                       | Low — patterns don't self-tune                                                   | Medium | Fixed in v1.0.0 |
-| No predictive memory                       | Low — no context prefetching                                                     | High   | Fixed in v1.0.0 |
-| No multi-turn agent loop                   | Medium — no error recovery loop                                                  | High   | Fixed in v1.0.0 |
-| PATH_MIGRATIONS TODO in code               | Low — dead TODO comment                                                          | Low    | Fixed in v1.0.0 |
-
----
-
-**Last Updated:** 2026-03-17
-**npm Package:** @miller-tech/uap v1.0.0
-**Build:** 0 errors | **Tests:** 258 passing (23 files) | **Lint:** 0 errors
+# Feature Catalog
+
+> Universal Agent Protocol (UAP) v1.40.0
+
+UAP is a universal AI-agent memory, coordination, and enforcement system. This
+catalog groups its features by source subsystem under `src/`. Each entry is a
+code-grounded summary of what the subsystem provides.
+
+## Memory (`src/memory/`)
+
+Hierarchical, tiered memory with semantic recall — the largest subsystem.
+
+| Feature | Description |
+|---------|-------------|
+| Embedding service (`embeddings.ts`) | Multi-provider embeddings with priority order llama.cpp → Ollama → OpenAI → sentence-transformers → TF-IDF. Default nomic-embed-text (768-dim); MiniLM/TF-IDF fallback at 384. |
+| Hierarchical memory (`hierarchical-memory.ts`) | Hot/warm/cold tiered memory with SQLite persistence and embeddings. |
+| Short-term store (`short-term/`) | SQLite L1/L2 memory: memories, sessions, FTS5 search, knowledge-graph entities. |
+| Model router w/ feedback (`model-router.ts`) | Routes to models using latency/success fingerprints. |
+| Task classifier (`task-classifier.ts`) | Classifies task type/complexity to drive retrieval and routing. |
+| Dynamic retrieval (`dynamic-retrieval.ts`) | Context-aware retrieval of relevant memories. |
+| Adaptive context (`adaptive-context.ts`) | Context optimizations driven by historical task outcomes + semantic cache. |
+| Semantic/context compression (`semantic-compression.ts`, `context-compressor.ts`, `context-pruner.ts`) | Compress/prune context to fit token budgets. |
+| Speculative cache (`speculative-cache.ts`) | Pre-fetches likely-needed memory. |
+| Consolidator / maintenance (`memory-consolidator.ts`, `memory-maintenance.ts`) | Consolidate and garbage-collect memory over time. |
+| Write gate (`write-gate.ts`) | Quality filter for what gets written to memory. |
+| Daily log (`daily-log.ts`) | Staging log with promotion (`gate_score`) to long-term memory. |
+| Correction propagation (`correction-propagator.ts`) | Supersedes stale entries when corrections are made. |
+| Predictive memory (`predictive-memory.ts`) | Learns query patterns to predict needed context. |
+| Knowledge graph (`knowledge-graph.ts`) | L4 entity/relationship graph. |
+| Ambiguity detector (`ambiguity-detector.ts`) | Implements P37 ambiguity detection. |
+| Serverless Qdrant (`serverless-qdrant.ts`) | Lazy-local Docker Qdrant (`qdrant/qdrant:latest`, port 6333) or cloud. |
+| Backends (`backends/`) | Pluggable long-term stores: Qdrant cloud, GitHub, factory selector. |
+| Prepopulate (`prepopulate.ts`) | Seeds memory and discovers skills for CLAUDE.md generation. |
+| Terminal-bench knowledge (`terminal-bench-knowledge.ts`) | Curated benchmark knowledge. |
+
+## Models (`src/models/`)
+
+Multi-model, two-tier (planner/executor) architecture.
+
+| Feature | Description |
+|---------|-------------|
+| Router (`router.ts`, `unified-router.ts`) | Classifies tasks and selects models. |
+| Planner (`planner.ts`) | Decomposes tasks into subtasks (`TaskPlanner`). |
+| Executor (`executor.ts`) | Runs subtasks with retry/fallback (`TaskExecutor`, `MockModelClient`). |
+| Plan validator (`plan-validator.ts`) | Validates plans before build. |
+| Execution profiles (`execution-profiles.ts`, `profile-loader.ts`) | Named model profiles (`UAP_MODEL_PROFILE`). |
+| Analytics (`analytics.ts`) | Per-task token/cost/outcome metrics (`model_analytics.db`). |
+| OpenAI-compat client (`openai-compat-client.ts`) | OpenAI `/v1`-compatible client (default endpoint `http://localhost:4000/v1`). |
+
+## Coordination (`src/coordination/`)
+
+Multi-agent coordination layer.
+
+| Feature | Description |
+|---------|-------------|
+| Database/service (`database.ts`, `service.ts`) | Agent registry, heartbeats, messages, work announcements/claims. |
+| Deploy batcher (`deploy-batcher.ts`) | Batches commit/push/merge/deploy actions into windows. |
+| Capability router (`capability-router.ts`) | Routes tasks to droids by capability. |
+| Auto-agent (`auto-agent.ts`) | Auto-agent driver. |
+| Pattern router (`pattern-router.ts`) | Matches tasks to execution patterns; always includes P12/P35. |
+| Adaptive patterns (`adaptive-patterns.ts`) | Tracks pattern success outcomes to adapt selection. |
+| Expert orchestrator (`expert-orchestrator.ts`) | Orchestrates parallel expert/droid review. |
+
+## Tasks (`src/tasks/`)
+
+Task management system (positioned as an alternative to Beads).
+
+| Feature | Description |
+|---------|-------------|
+| Service (`service.ts`) | CRUD, dependencies, claim/release, board, stats. |
+| Database (`database.ts`) | SQLite store (`.uap/tasks/tasks.db`) + JSONL mirror. |
+| Coordination (`coordination.ts`) | Task ↔ agent coordination. |
+| Decoder gate (`decoder-gate.ts`) | Full decoder-first (P35) validator. |
+| Event bus (`event-bus.ts`) | `TaskEventBus` for task lifecycle events. |
+
+## Policies (`src/policies/`)
+
+DB-driven policy enforcement engine.
+
+| Feature | Description |
+|---------|-------------|
+| Policy gate (`policy-gate.ts`) | `PolicyGate` + `PolicyViolationError` — the enforcement core. |
+| Tool registry (`policy-tools.ts`) | `PolicyToolRegistry` of executable policy tools. |
+| Policy memory (`policy-memory.ts`) | Persists policies (`policies.db`). |
+| Enforced tool router (`enforced-tool-router.ts`) | Routes tool calls through the gate. |
+| CLAUDE.md conversion (`convert-policy-to-claude.ts`) | Renders policies into CLAUDE.md. |
+| Enforcers (`enforcers/`) | ~20 Python enforcers (worktree_required, test_gate, schema_diff_gate, memory_before_plan, coord_overlap, mcp_router_first, rtk_wrap, iac_parity, expert_review_required, etc.). |
+
+## Delivery (`src/delivery/`)
+
+Convergence loop that drives a model through execute → apply → verify → feedback
+against real completion gates until "delivered".
+
+| Feature | Description |
+|---------|-------------|
+| Convergence loop (`convergence-loop.ts`) | The main delivery loop. |
+| Run coordinator (`run-coordinator.ts`) | Coordinates a delivery run. |
+| Explorer (`explorer.ts`) | Best-of-N candidate generation. |
+| Applier (`applier.ts`) | Applies file changes. |
+| Verifier ladder (`verifier-ladder.ts`) | Build/typecheck/test/lint gate ladder. |
+| Judge / critic (`judge.ts`, `critic.ts`) | Evaluate and critique turns. |
+| Escalation (`escalation.ts`) | Stagnation escalation ladder. |
+| Auto-optimizer (`auto-optimizer.ts`) | Dynamically enables aids. |
+| Ideation / practice / spec-imports | Divergent strategy seeds, best-practice cards, curated project seeds. |
+| HALO trace (`halo-trace.ts`) | Emits HALO spans. |
+| Integrity (`integrity.ts`) | Test-protection / integrity guard. |
+
+## MCP Router (`src/mcp-router/`)
+
+Hierarchical MCP router that collapses 150+ MCP tools to 2
+(`discover_tools`, `execute_tool`) for ~98% token reduction.
+
+| Feature | Description |
+|---------|-------------|
+| Server (`server.ts`) | `McpRouter` + stdio server. |
+| Output compressor (`output-compressor.ts`) | Compresses tool output. |
+| Session stats (`session-stats.ts`) | Token-savings statistics. |
+| Config parser (`config/parser.ts`) | Loads/merges `mcp.json` with path expansion. |
+| Executor (`executor/client.ts`) | `McpClient` / `McpClientPool`. |
+| Fuzzy search (`search/fuzzy.ts`) | `ToolSearchIndex`. |
+| Experts (`experts/registry.ts`) | Expert-consult registry. |
+| Tools (`tools/`) | `discover`, `execute`, `deliver` handlers. |
+
+## Dashboard (`src/dashboard/`)
+
+| Feature | Description |
+|---------|-------------|
+| Data service (`data-service.ts`) | Aggregates task/agent/memory/model/system data. |
+| Event stream (`event-stream.ts`) | Real-time dashboard events. |
+| Server (`server.ts`) | Web dashboard server (default port 3847). |
+| Data seeder (`data-seeder.ts`) | Seeds demo/initial dashboard data. |
+
+## Analyzers & Generators
+
+| Subsystem | Description |
+|-----------|-------------|
+| Analyzers (`analyzers/`) | `analyzeProject(cwd)` builds a `ProjectAnalysis` (languages, frameworks, dirs) from `.uap.json`, git, package files. |
+| Generators (`generators/claude-md.ts`) | Handlebars-based CLAUDE.md / web AGENT.md generation from analysis + discovered skills. |
+
+## Observability & Telemetry
+
+| Subsystem | Description |
+|-----------|-------------|
+| Observability (`observability/halo-exporter.ts`) | Emits agent/LLM/tool spans as OTLP/OpenInference JSONL for the HALO engine. Opt-in via `UAP_HALO_TRACE`; zero-overhead when off. |
+| Telemetry (`telemetry/session-telemetry.ts`) | Session-level telemetry capture. |
+
+## Browser & Benchmarks
+
+| Subsystem | Description |
+|-----------|-------------|
+| Browser (`browser/web-browser.ts`) | `WebBrowser` automation wrapper for agents. |
+| Benchmarks (`benchmarks/`) | Benchmark harness comparing a naive agent vs UAP-augmented agent; multi-turn loops, token throughput, speculative autotune. |
+
+## Droids
+
+The expert-droid roster lives as markdown-with-JSON-frontmatter files under
+`.factory/droids/*.md`, discovered at runtime by `discoverDroids()` in
+`src/uap-droids-strict.ts`. The strict plugin validates droids against a Zod
+schema and exposes `uap_droid_list` / `uap_droid_invoke`, plus the
+decoder-first (P35) and worktree gates. See `docs/reference/EXPERT_DROIDS.md`.
+
+## Utilities (`src/utils/`)
+
+Shared helpers: adaptive cache, concurrency pools (retry/timeout/fallback),
+config loader, lazy imports, structured logger, CLAUDE.md merge, performance
+monitor, query-complexity scoring, rate limiter, string similarity, and system
+resource detection.
+
+## CLI surface (`src/bin/cli.ts`)
+
+The `uap` CLI exposes (top-level commands): `init`, `setup`, `analyze`,
+`generate`, `memory`, `patterns`, `worktree`, `sync`, `droids`, `expert-route`,
+`deliver`, `harness` (HALO), `ideate`, `coord`, `agent`, `deploy`, `task`,
+`compliance`, `coordination`, `skill`, `update`, `dashboard` (alias `dash`),
+`model`, `mcp-router`, `hooks`, `tool-calls`, `rtk`, `mcp-setup`, `schema-diff`,
+`policy`, `uap-omp`.