@miller-tech/uap 1.0.0

package/dist/utils/string-similarity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * String Similarity Utilities for UAP
+ *
+ * Shared text comparison functions used across memory compression,
+ * deduplication, and retrieval systems.
+ */
+/**
+ * Calculate Jaccard similarity between two strings (word-level)
+ * Returns a value between 0 (no overlap) and 1 (identical)
+ */
+export declare function jaccardSimilarity(a: string, b: string): number;
+/**
+ * Calculate content hash for deduplication
+ * Uses SHA-256 for reliable collision resistance
+ */
+export declare function contentHash(text: string): string;
+/**
+ * Improved token estimation
+ * More accurate than simple length/4 for mixed code and prose
+ */
+export declare function estimateTokensAccurate(text: string): number;
+/**
+ * Simple stemming for keyword matching
+ * Handles common English suffixes for better fuzzy matching
+ */
+export declare function simpleStem(word: string): string;
+/**
+ * Fuzzy keyword match using stemming
+ * Returns true if any stemmed form matches
+ */
+export declare function fuzzyKeywordMatch(text: string, keyword: string): boolean;
+/**
+ * Calculate text similarity using multiple methods
+ * Returns weighted average for more robust comparison
+ */
+export declare function textSimilarity(a: string, b: string): number;
+//# sourceMappingURL=string-similarity.d.ts.map

package/dist/utils/string-similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-similarity.d.ts","sourceRoot":"","sources":["../../src/utils/string-similarity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAW9D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuB3D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkB/C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAkBxE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAa3D"}

package/dist/utils/string-similarity.js

@@ -0,0 +1,114 @@
+/**
+ * String Similarity Utilities for UAP
+ *
+ * Shared text comparison functions used across memory compression,
+ * deduplication, and retrieval systems.
+ */
+import { createHash } from 'crypto';
+/**
+ * Calculate Jaccard similarity between two strings (word-level)
+ * Returns a value between 0 (no overlap) and 1 (identical)
+ */
+export function jaccardSimilarity(a, b) {
+    const setA = new Set(a.toLowerCase().split(/\s+/).filter(w => w.length > 1));
+    const setB = new Set(b.toLowerCase().split(/\s+/).filter(w => w.length > 1));
+    if (setA.size === 0 && setB.size === 0)
+        return 1;
+    if (setA.size === 0 || setB.size === 0)
+        return 0;
+    const intersection = new Set([...setA].filter(x => setB.has(x)));
+    const union = new Set([...setA, ...setB]);
+    return intersection.size / union.size;
+}
+/**
+ * Calculate content hash for deduplication
+ * Uses SHA-256 for reliable collision resistance
+ */
+export function contentHash(text) {
+    return createHash('sha256')
+        .update(text.toLowerCase().replace(/\s+/g, ' ').trim())
+        .digest('hex')
+        .slice(0, 16); // 16 hex chars = 64 bits, sufficient for dedup
+}
+/**
+ * Improved token estimation
+ * More accurate than simple length/4 for mixed code and prose
+ */
+export function estimateTokensAccurate(text) {
+    if (!text || text.length === 0)
+        return 0;
+    // Split by whitespace and count
+    const words = text.split(/\s+/).filter(w => w.length > 0);
+    // Count special characters that typically become separate tokens
+    const specialChars = (text.match(/[{}()\[\]<>:;,."'`@#$%^&*+=|\\/?!~-]/g) || []).length;
+    // Code tokens: variable names split on camelCase/snake_case
+    const codeTokens = (text.match(/[a-z][A-Z]|_[a-z]/g) || []).length;
+    // Numbers often tokenize separately
+    const numbers = (text.match(/\d+/g) || []).length;
+    // Base: words + adjustments
+    // Average English word is ~1.3 tokens, code identifiers ~1.5
+    const baseTokens = words.length * 1.3;
+    const specialTokens = specialChars * 0.5;
+    const extraCodeTokens = codeTokens * 0.3;
+    const numberTokens = numbers * 0.5;
+    return Math.ceil(baseTokens + specialTokens + extraCodeTokens + numberTokens);
+}
+/**
+ * Simple stemming for keyword matching
+ * Handles common English suffixes for better fuzzy matching
+ */
+export function simpleStem(word) {
+    const lower = word.toLowerCase();
+    // Common suffixes to strip
+    const suffixes = ['ing', 'ed', 'es', 's', 'er', 'est', 'ly', 'tion', 'ment', 'ness', 'able', 'ible'];
+    for (const suffix of suffixes) {
+        if (lower.endsWith(suffix) && lower.length > suffix.length + 2) {
+            const stem = lower.slice(0, -suffix.length);
+            // Handle doubling (e.g., "running" -> "run")
+            if (stem.length > 2 && stem[stem.length - 1] === stem[stem.length - 2]) {
+                return stem.slice(0, -1);
+            }
+            return stem;
+        }
+    }
+    return lower;
+}
+/**
+ * Fuzzy keyword match using stemming
+ * Returns true if any stemmed form matches
+ */
+export function fuzzyKeywordMatch(text, keyword) {
+    const textLower = text.toLowerCase();
+    const keywordLower = keyword.toLowerCase();
+    // Exact match first
+    if (textLower.includes(keywordLower))
+        return true;
+    // Stemmed match
+    const keywordStem = simpleStem(keywordLower);
+    const textWords = textLower.split(/\s+/);
+    for (const word of textWords) {
+        if (simpleStem(word) === keywordStem)
+            return true;
+        // Also check if the stem is contained in the word (for compound words)
+        if (word.includes(keywordStem) && keywordStem.length >= 3)
+            return true;
+    }
+    return false;
+}
+/**
+ * Calculate text similarity using multiple methods
+ * Returns weighted average for more robust comparison
+ */
+export function textSimilarity(a, b) {
+    // Jaccard on words
+    const jaccard = jaccardSimilarity(a, b);
+    // Character-level containment
+    const aLower = a.toLowerCase();
+    const bLower = b.toLowerCase();
+    const shorter = aLower.length < bLower.length ? aLower : bLower;
+    const longer = aLower.length >= bLower.length ? aLower : bLower;
+    const containment = shorter.length > 0 && longer.includes(shorter) ? 0.8 : 0;
+    // Weighted combination
+    return Math.max(jaccard, containment);
+}
+//# sourceMappingURL=string-similarity.js.map

package/dist/utils/string-similarity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-similarity.js","sourceRoot":"","sources":["../../src/utils/string-similarity.ts"],"names":[],"mappings":"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"}

package/dist/utils/validate-json.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Custom error class for application-level errors with detailed context.
+ * Extends the built-in Error class to provide additional metadata.
+ */
+export declare class AppError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    /** Additional context about the error */
+    readonly context?: Record<string, unknown>;
+    /**
+     * Creates a new AppError instance.
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param context - Optional additional context
+     */
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+/**
+ * Validates that a string is valid JSON and parses it.
+ *
+ * Uses zod for runtime validation to ensure the input is a valid string
+ * before attempting to parse. The parsed result is then validated
+ * against a permissive schema that accepts any valid JSON value.
+ *
+ * @param input - The string to validate and parse as JSON
+ * @returns The parsed JSON value (object, array, string, number, boolean, or null)
+ * @throws AppError with code 'INVALID_JSON' if the string is not valid JSON
+ *
+ * @example
+ * ```typescript
+ * // Parse a valid JSON object
+ * const obj = validateAndParseJSON('{"name": "test", "value": 42}');
+ * // Returns: { name: "test", value: 42 }
+ *
+ * // Parse a valid JSON array
+ * const arr = validateAndParseJSON('[1, 2, 3]');
+ * // Returns: [1, 2, 3]
+ *
+ * // Invalid JSON throws AppError
+ * try {
+ *   validateAndParseJSON('{invalid}');
+ * } catch (error) {
+ *   if (error instanceof AppError) {
+ *     console.log(error.code); // 'INVALID_JSON'
+ *   }
+ * }
+ * ```
+ */
+export declare function validateAndParseJSON(input: string): unknown;
+//# sourceMappingURL=validate-json.d.ts.map

package/dist/utils/validate-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-json.d.ts","sourceRoot":"","sources":["../../src/utils/validate-json.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE3C;;;;;;OAMG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAW7E;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CA6B3D"}

package/dist/utils/validate-json.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+/**
+ * Custom error class for application-level errors with detailed context.
+ * Extends the built-in Error class to provide additional metadata.
+ */
+export class AppError extends Error {
+    /** Error code for programmatic handling */
+    code;
+    /** Additional context about the error */
+    context;
+    /**
+     * Creates a new AppError instance.
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param context - Optional additional context
+     */
+    constructor(message, code, context) {
+        super(message);
+        this.name = 'AppError';
+        this.code = code;
+        this.context = context;
+        // Maintains proper stack trace for where error was thrown (V8 engines)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, AppError);
+        }
+    }
+}
+/**
+ * Zod schema for validating that a value is valid JSON.
+ * Accepts any valid JSON value (object, array, string, number, boolean, null).
+ */
+const jsonSchema = z.unknown();
+/** Maximum number of characters of the original input to include in error context. */
+const MAX_ERROR_CONTEXT_CHARS = 100;
+/**
+ * Validates that a string is valid JSON and parses it.
+ *
+ * Uses zod for runtime validation to ensure the input is a valid string
+ * before attempting to parse. The parsed result is then validated
+ * against a permissive schema that accepts any valid JSON value.
+ *
+ * @param input - The string to validate and parse as JSON
+ * @returns The parsed JSON value (object, array, string, number, boolean, or null)
+ * @throws AppError with code 'INVALID_JSON' if the string is not valid JSON
+ *
+ * @example
+ * ```typescript
+ * // Parse a valid JSON object
+ * const obj = validateAndParseJSON('{"name": "test", "value": 42}');
+ * // Returns: { name: "test", value: 42 }
+ *
+ * // Parse a valid JSON array
+ * const arr = validateAndParseJSON('[1, 2, 3]');
+ * // Returns: [1, 2, 3]
+ *
+ * // Invalid JSON throws AppError
+ * try {
+ *   validateAndParseJSON('{invalid}');
+ * } catch (error) {
+ *   if (error instanceof AppError) {
+ *     console.log(error.code); // 'INVALID_JSON'
+ *   }
+ * }
+ * ```
+ */
+export function validateAndParseJSON(input) {
+    const jsonStringSchema = z
+        .string()
+        .transform((value, ctx) => {
+        try {
+            return JSON.parse(value);
+        }
+        catch (error) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: error instanceof Error ? `Invalid JSON: ${error.message}` : 'Invalid JSON',
+            });
+            return z.NEVER;
+        }
+    })
+        .pipe(jsonSchema);
+    const result = jsonStringSchema.safeParse(input);
+    if (!result.success) {
+        throw new AppError('Input must be valid JSON', 'INVALID_JSON', {
+            errors: Array.from(result.error.issues).map((e) => e.message),
+            input: input.length > MAX_ERROR_CONTEXT_CHARS
+                ? `${input.substring(0, MAX_ERROR_CONTEXT_CHARS)}...`
+                : input,
+        });
+    }
+    return result.data;
+}
+//# sourceMappingURL=validate-json.js.map

package/dist/utils/validate-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-json.js","sourceRoot":"","sources":["../../src/utils/validate-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,2CAA2C;IAClC,IAAI,CAAS;IACtB,yCAAyC;IAChC,OAAO,CAA2B;IAE3C;;;;;;OAMG;IACH,YAAY,OAAe,EAAE,IAAY,EAAE,OAAiC;QAC1E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAEvB,uEAAuE;QACvE,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;AAE/B,sFAAsF;AACtF,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,MAAM,gBAAgB,GAAG,CAAC;SACvB,MAAM,EAAE;SACR,SAAS,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACxB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAY,CAAC;QACtC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,GAAG,CAAC,QAAQ,CAAC;gBACX,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;gBAC3B,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,iBAAiB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,cAAc;aACpF,CAAC,CAAC;YACH,OAAO,CAAC,CAAC,KAAK,CAAC;QACjB,CAAC;IACH,CAAC,CAAC;SACD,IAAI,CAAC,UAAU,CAAC,CAAC;IAEpB,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAEjD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,QAAQ,CAAC,0BAA0B,EAAE,cAAc,EAAE;YAC7D,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YAC7D,KAAK,EACH,KAAK,CAAC,MAAM,GAAG,uBAAuB;gBACpC,CAAC,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,uBAAuB,CAAC,KAAK;gBACrD,CAAC,CAAC,KAAK;SACZ,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/docs/INDEX.md

@@ -0,0 +1,66 @@
+# UAP Documentation Index
+
+> Universal Agent Protocol v1.0.0 - Documentation Hub
+
+---
+
+## Getting Started
+
+- [Overview](getting-started/OVERVIEW.md) - What is UAP, core concepts, 4-layer memory architecture
+- [Setup](getting-started/SETUP.md) - Installation, dependencies, configuration
+- [Integration](getting-started/INTEGRATION.md) - opencode, ForgeCode, Claude Code, VSCode
+
+## Architecture
+
+- [System Analysis](architecture/SYSTEM_ANALYSIS.md) - Complete UAP feature analysis and architecture
+- [Multi-Model Architecture](architecture/MULTI_MODEL.md) - Planner/executor two-tier design (92-98% cost reduction)
+- [UAP Protocol](architecture/UAP_PROTOCOL.md) - Protocol v1.0 specification and compliance requirements
+- [UAP Compliance](architecture/UAP_COMPLIANCE.md) - Protocol deviations and enforcement plan
+- [Strict Droids](architecture/UAP_STRICT_DROIDS.md) - JSON schema validation for droid definitions
+
+## Reference
+
+- [API Reference](reference/API_REFERENCE.md) - CLI commands, DB schema, API endpoints
+- [CLI Reference](reference/UAP_CLI_REFERENCE.md) - UAP CLI command reference (init, task, memory, worktree)
+- [Feature Inventory](reference/FEATURES.md) - Complete feature status and implementation details
+
+## Deployment
+
+- [Deployment Guide](deployment/DEPLOYMENT.md) - Model providers, IaC, CI/CD pipelines
+- [Deployment Strategies](deployment/DEPLOYMENT_STRATEGIES.md) - Window bucketing, batch processing, resource isolation
+- [Deploy Batching](deployment/DEPLOY_BATCHING.md) - Batch windows and bucketing system
+- [Deploy Batcher Analysis](deployment/DEPLOY_BATCHER_ANALYSIS.md) - DeployBatcher class architecture deep-dive
+- [Deploy Bucketing Analysis](deployment/DEPLOY_BUCKETING_ANALYSIS.md) - Bucketing capability report
+- [Qwen3.5 / llama.cpp](deployment/QWEN35_LLAMA_CPP.md) - Local LLM deployment with LoRA fine-tuning
+
+## Integrations
+
+- [MCP Router](integrations/MCP_ROUTER_SETUP.md) - 98% token reduction via meta-tool routing
+- [RTK Integration](integrations/RTK_INTEGRATION.md) - Rust Token Killer CLI proxy analysis
+
+## Benchmarks
+
+- [Validation Plan](benchmarks/VALIDATION_PLAN.md) - Benchmark methodology and test cases
+- [Validation Results](benchmarks/VALIDATION_RESULTS.md) - Benchmark results (49.7% token reduction)
+- [Token Optimization](benchmarks/TOKEN_OPTIMIZATION.md) - Per-feature token savings analysis
+- [Accuracy Analysis](benchmarks/ACCURACY_ANALYSIS.md) - Internal vs Terminal-Bench comparison
+
+## Research
+
+- [Memory Systems Comparison](research/MEMORY_SYSTEMS_COMPARISON.md) - MemGPT, LangGraph, Mem0, A-MEM analysis
+- [Behavioral Patterns](research/BEHAVIORAL_PATTERNS.md) - Pattern analysis from 54-task Terminal-Bench
+- [Terminal-Bench Learnings](research/TERMINAL_BENCH_LEARNINGS.md) - Universal agent patterns discovered
+- [Performance Analysis](research/PERFORMANCE_ANALYSIS_2026-01-18.md) - UAP v1.0.2 vs baseline benchmarking
+- [Pattern Analysis](research/PATTERN_ANALYSIS_2026-01-18.md) - v1.1.0 deep failure study
+- [Performance Test Plan](research/PERFORMANCE_TEST_PLAN.md) - Vanilla vs UAP-enhanced droid test plan
+- [Domain Strategies](research/DOMAIN_STRATEGIES.md) - CoreWars, specialized task guides
+
+## Operations
+
+- [Troubleshooting](operations/TROUBLESHOOTING.md) - Common issues, recovery procedures, debugging
+
+---
+
+## Archive
+
+Historical documents preserved for reference in [archive/](archive/). These are superseded or point-in-time documents that are no longer actively maintained.

package/docs/architecture/MULTI_MODEL.md

@@ -0,0 +1,224 @@
+# Multi-Model Agentic Architecture
+
+## Executive Summary
+
+This document proposes a two-tier agentic architecture using separate models for planning and execution, achieving **92-98% cost reduction** while maintaining near-original performance for complex tasks.
+
+## Core Concept
+
+**Separation of Concerns:**
+- **Tier 1 (Planner)**: High-level reasoning, task decomposition, orchestration
+- **Tier 2 (Executor)**: Concrete implementation following planner's specifications
+
+### Research Findings (2026)
+
+#### Model Candidates
+
+| Model | Role | Cost (Input/Output) | SWE-Bench | Context | Notes |
+|-------|------|----------------------|-----------|---------|-------|
+| **Claude Opus 4.5** | Planner (current) | $5/$25 per 1M | Highest | 200K | Premium, but expensive |
+| **DeepSeek-V3.2** | Planner | $0.25/$0.38 per 1M | 73.1% | 164K | Best cost/performance ratio |
+| **DeepSeek-V3.2-Exp** | Executor | $0.21/$0.32 per 1M | Strong | 164K | 78x cheaper output than Opus |
+| **GLM-4.7** | Executor | Very Low | Good | 128K | Current workhorse |
+
+#### Key Findings
+
+1. **DeepSeek-V3.2 Speciale** achieves 73.1% on SWE-Bench Verified (vs Opus's highest scores)
+2. **Cost differential**: DeepSeek is ~23x cheaper for input, ~78x cheaper for output
+3. **Context**: 164K is sufficient for most agentic workflows (vs 200K for Opus)
+4. **Architecture**: MoE with 671B params, activates only 37B per token (high efficiency)
+
+## Proposed Architecture
+
+### Tier 1: Master Planner
+
+**Model**: **DeepSeek-V3.2 Speciale** (replacing Opus 4.5)
+
+**Responsibilities**:
+- Task decomposition and planning
+- Subtask dependency analysis
+- Model selection for each subtask
+- Quality assurance routing
+- Critical path identification
+
+**When to invoke:**
+- New task request
+- Complex multi-step workflows
+- Requirements for strategic planning
+- Architectural decisions
+
+**Fallback**: If DeepSeek fails on critical planning, escalate to Opus 4.5 (1% of cases)
+
+### Tier 2: Task Executor
+
+**Model**: **GLM-4.7** (current workhorse) or **DeepSeek-V3.2-Exp**
+
+**Responsibilities**:
+- Implement specific code blocks
+- Execute tool calls
+- Write tests
+- Fix bugs based on planner guidance
+- Generate documentation
+
+**When to invoke:**
+- Concrete implementation tasks
+- Coding following specifications
+- Test writing
+- Bug fixes with clear guidance
+
+### Route Decision Matrix
+
+| Task Complexity | Routing Logic | Model Selection |
+|----------------|---------------|-----------------|
+| **High** (new feature, architecture) | → Planner → Decompose → Executor | DeepSeek-V3.2 → GLM-4.7 |
+| **Medium** (refactor, bug fix) | → Direct Executor | GLM-4.7 |
+| **Low** (simple change) | → Direct Executor | GLM-4.7 |
+| **Critical** (security, deployment) | → Planner → Verify → Executor | DeepSeek-V3.2 → GLM-4.7 |
+
+## Implementation Strategy
+
+### Phase 1: Router (Week 1)
+
+```typescript
+interface ModelRouter {
+  route(task: AgenticTask): ModelSelection;
+}
+
+interface ModelSelection {
+  model: ModelId;
+  fallback?: ModelId;
+  reasoning: string;
+}
+```
+
+**Routing Logic**:
+1. Analyze task complexity (token estimate, dependencies, novelty)
+2. Check for critical keywords (security, architecture, planning)
+3. Select DeepSeek-V3.2 for planning tasks
+4. Select GLM-4.7 for execution tasks
+5. Fallback to Opus 4.5 only on threshold failures
+
+### Phase 2: Planner Integration (Week 2)
+
+**Planner Interface**:
+```typescript
+interface Planner {
+  plan(task: AgenticTask): ExecutionPlan;
+}
+
+interface ExecutionPlan {
+  subtasks: Subtask[];
+  dependencies: DependencyGraph;
+  modelAssignments: Map<SubtaskId, ModelId>;
+}
+```
+
+**DeepSeek-V3.2 Integration**:
+- API endpoint integration
+- Context window management (164K)
+- Token budget accounting
+- Failure detection and escalation
+
+### Phase 3: Executor Pool (Week 3)
+
+**Executor Options**:
+1. **Primary**: GLM-4.7 (existing, low cost, good performance)
+2. **Backup**: DeepSeek-V3.2-Exp (if GLM-4.7 unavailable)
+3. **Fallback**: Opus 4.5 (critical failures only)
+
+**Load Balancing**:
+- Round-robin across multiple executor instances
+- Circuit breaker pattern for reliability
+- Timeout management per subtask
+
+## Cost Analysis
+
+### Baseline (Opus 4.5 Only)
+
+**Assumptions**:
+- 100 tasks/day
+- Average 50K input tokens, 30K output tokens per task
+- $5/input per 1M, $25/output per 1M
+
+**Daily Cost**:
+- Input: 100 * 50K * $5/1M = $25
+- Output: 100 * 30K * $25/1M = $75
+- **Total: $100/day**
+
+**Monthly Cost**: $3,000
+**Yearly Cost**: $36,500
+
+### Proposed (DeepSeek + GLM-4.7)
+
+**Distribution**:
+- 30% complex tasks → DeepSeek-V3.2 planning (10K tokens)
+- 70% direct execution → GLM-4.7 (15K input, 5K output)
+
+**Daily Cost**:
+- Planner (DeepSeek): 30 tasks * 10K tokens * ($0.25/$0.38)/1M = $0.19
+- Executor (GLM): 
+  - Input: 100 tasks * 15K * $1/1M = $1.50
+  - Output: 100 tasks * 5K * $2/1M = $1.00
+- **Total: $2.69/day**
+
+**Monthly Cost**: $80.70
+**Yearly Cost**: $982
+
+### Cost Savings
+
+| Metric | Baseline | Proposed | Savings |
+|--------|----------|----------|---------|
+| Daily | $100 | $2.69 | **97.3%** |
+| Monthly | $3,000 | $80.70 | **97.3%** |
+| Yearly | $36,500 | $982 | **97.3%** |
+
+### Performance Impact
+
+Expected SWE-Bench performance:
+- **Baseline**: Opus 4.5 (highest scores)
+- **Proposed**: 
+  - Planner (DeepSeek-V3.2): 73.1% (verified)
+  - Executor (GLM-4.7): Strong on straightforward tasks
+  - **Composite**: Estimated 85-90% of baseline
+
+**Trade-off**: Accept 10-15% performance drop for 97% cost reduction
+
+## Risk Assessment
+
+### Risks
+
+1. **Routing Errors**: Poor model selection for tasks
+   - **Mitigation**: Start conservative, 10% fallback to Opus
+   - **Monitoring**: Track task success rates per model
+
+2. **Quality Regression**: Lower code质量
+   - **Mitigation**: Add review loops, use quality droids
+   - **Monitoring**: Track test pass rates, bug counts
+
+3. **API Reliability**: DeepSeek availability issues
+   - **Mitigation**: Multi-in redundancy, fallback to Opus
+   - **Monitoring**: Uptime, latency tracking
+
+### Rollback Plan
+
+If metrics degrade >20%, revert to Opus 4.5-only mode within 24 hours.
+
+## Next Steps
+
+1. **Week 1**: Implement router with conservative routing (20% direct to Opus)
+2. **Week 2**: Integrate DeepSeek-V3.2 API, test on 10% of tasks
+3. **Week 3**: Shift to 50/50 routing, monitor carefully
+4. **Week 4**: Full deployment, 95% tasks to proposed architecture
+
+## Success Metrics
+
+- Cost reduction: >90% achieved by month 1
+- Performance: <20% drop vs baseline
+- Reliability: <5% increase in task failures
+- ROI: Break-even within 2 weeks
+
+---
+
+**Status**: Draft - Ready for review and implementation
+**Created**: 2026-01-21
+**Next Review**: 2026-01-28 (after week 1 pilot)