@miller-tech/uap 1.40.0 → 1.41.0

package/docs/architecture/EXPERT_STACK.md

@@ -1,137 +0,0 @@
-# Expert Stack: Forward-Design, HALO & Open-Collider
-
-This document covers the expert-system extensions added on top of the v1.23.0
-droid stack: forward-design experts, the activated experts-as-MCP-tools surface,
-HALO trace-based harness optimization, open-collider divergent ideation, and the
-expert-review hard gate.
-
-> Scope note: the base 33-droid roster, `ExpertOrchestrator`, `expert-route`
-> CLI, and `parallel-expert-review` skill already shipped in v1.23.0. This layer
-> closes real gaps in that stack and integrates two external tools.
-
----
-
-## 1. Forward-design droids
-
-The pre-existing roster was review-heavy — the orchestrator's `plan`/`design`
-phases produced no up-front design. Three forward-design experts fill that gap:
-
-| Droid | Phase | Role |
-|---|---|---|
-| `strategic-architect` | plan | North-star architecture, technology selection (OSS-first), multi-quarter evolution, one-way-door decisions. Forward-design counterpart to `architect-reviewer`. |
-| `tactical-architect` | design | Concrete component/module boundaries, interfaces, data shapes, pattern selection, refactor strategy. |
-| `implementation-planner` | design | Executable work breakdown: ordered steps, file-level plan (reuse-first), test plan, risk/rollback. Feeds the `validate-plan-before-build` gate. |
-
-Wiring: `src/coordination/expert-orchestrator.ts` — `PHASE_ROSTER.plan` gains
-`strategic-architect`; `PHASE_ROSTER.design` gains `tactical-architect` and
-`implementation-planner`; `isRelevantForCapability` maps them to the
-`architecture`/`api-design` capabilities so they appear only on relevant tasks.
-
-```bash
-uap expert-route "Design a new billing subsystem" --files src/types/billing.ts --json
-# → plan: strategic-architect … design: tactical-architect, implementation-planner …
-```
-
----
-
-## 2. Experts as MCP tools (activated)
-
-`src/mcp-router/experts/registry.ts` could already convert droids to virtual
-`experts.<name>` tools (`loadExpertTools`) but was never wired in. Now:
-
-- `McpRouter.loadTools()` (`src/mcp-router/server.ts`) calls `loadExpertTools(cwd)`
-  and adds the experts to the fuzzy search index.
-- `handleExecuteTool` (`src/mcp-router/tools/execute.ts`) intercepts
-  `experts.<droid>` paths and dispatches an in-process `consultExpert()` — it
-  loads the droid's instructions and returns them wrapped as a prompt (mirroring
-  `uap_droid_invoke`), instead of routing to an external MCP server.
-
-Result: `discover_tools "architecture review"` surfaces the right expert and
-`execute_tool experts.architect-reviewer` returns a consultation — all within
-the 2-tool token-saving router shape.
-
----
-
-## 3. HALO — trace-based harness optimization
-
-[HALO](https://github.com/context-labs/HALO) analyzes large volumes of execution
-traces to find *systemic* harness/prompt failure modes (not one-off errors). UAP
-integrates it as an exporter + a droid + a CLI.
-
-**Exporter** (`src/observability/halo-exporter.ts`) — opt-in, zero-overhead when
-off. Emits one JSONL span per agent/LLM/tool call in HALO's OTLP/OpenInference
-shape: OTLP identity, `resource.attributes."service.name"`, and the four
-`inference.*` attributes (`project_id`, `observation_kind`, `export.schema_version`,
-`openinference.span.kind`), with nanosecond-precision timestamps.
-
-Tap points: `execute.ts:handleExecuteTool` (TOOL spans) and
-`session-telemetry.ts` `agentComplete`/`agentError` (AGENT spans).
-
-```bash
-export UAP_HALO_TRACE=1                  # enable collection
-export UAP_HALO_TRACE_PATH=.uap/halo/traces.jsonl
-# … run your workflow …
-uap harness status                       # enabled? path? span count?
-uap harness analyze -p "systemic failure modes?"   # wraps `halo <file> -p ...`
-```
-
-**Prerequisite:** `pip install halo-engine` (Python ≥3.10) + an OpenAI-compatible
-endpoint. Each analysis run incurs LLM cost. The `harness-optimizer` droid runs
-the loop: diagnose → **verify each claim against the repo** → route fixes →
-re-measure. Hard rule: *ask HALO about the trace data; never ask it to write code.*
-
----
-
-## 4. Open-Collider — divergent ideation
-
-[open-collider](https://github.com/CL-ML/open-collider) escapes LLM "hivemind"
-clustering by colliding structurally distant knowledge domains (Koestler
-bisociation), then curating non-trivial ideas. Skill mode is free.
-
-- `ideation-expert` droid drives the brief → domains → collide → curate flow.
-- `uap ideate setup <name>` scaffolds the `projects/<name>/` file contract
-  (`brief_validated.json`, `input_bank.yaml`, `prompts/`, `texts/`).
-- `uap ideate run <name>` drives the brainstorm; `uap ideate ideas <name>` reads
-  the newest `curated_ideas.json`.
-- Orchestrator opt-in: `new ExpertOrchestrator({ includeIdeation: true })`
-  prepends an `ideate` phase feeding the plan-phase product/strategy droids.
-  `readCuratedIdeas()` (`src/cli/ideate.ts`) is the consumable artifact.
-
-Use it only when the solution space is wide; skip for convergent tasks.
-
----
-
-## 5. Expert-review hard gate
-
-The `parallel-expert-review` skill claimed "REQUIRED by policy" but nothing
-enforced it. Two policy artifacts close that:
-
-- `expert-review-required` (`src/policies/schemas/policies/expert-review-required.md`
-  + `src/policies/enforcers/expert_review_required.py`): blocks ship actions
-  (`git commit`/`push`, `gh pr create`, merge/pr-ready/signoff) unless
-  `.uap/reviews/<branch-slug>.json` exists and covers `HEAD` (stale → block).
-  Fail-open on detached/non-git; override `UAP_NO_REVIEW=1`.
-- `architecture-review` (`…/policies/architecture-review.md`): the missing
-  backing doc for the previously-orphan `architecture_review.py` enforcer
-  (ADR-or-waiver on architecturally significant diffs).
-
-The review flow writes the artifact on consolidation:
-`{ "head": "<sha>", "verdict": "approve", "reviewers": [...] }`. Install with:
-
-```bash
-uap policy install expert-review-required   # attaches the enforcer to the hook
-```
-
----
-
-## File map
-
-| Concern | Path |
-|---|---|
-| Forward-design droids | `.factory/droids/{strategic-architect,tactical-architect,implementation-planner}.md` |
-| Orchestrator wiring | `src/coordination/expert-orchestrator.ts` |
-| Experts-MCP dispatch | `src/mcp-router/experts/registry.ts`, `server.ts`, `tools/execute.ts` |
-| HALO exporter | `src/observability/halo-exporter.ts` |
-| HALO droid + CLI | `.factory/droids/harness-optimizer.md`, `src/cli/harness.ts` |
-| Ideation droid + CLI | `.factory/droids/ideation-expert.md`, `src/cli/ideate.ts` |
-| Review gate | `src/policies/{schemas/policies/expert-review-required.md,enforcers/expert_review_required.py}` |

package/docs/architecture/MULTI_MODEL.md

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

package/docs/architecture/PLATFORM_GATING.md

@@ -1,68 +0,0 @@
-# Platform Gating
-
-How UAP's policy gate (the DB-driven enforcement that blocks tool calls via
-`policies.db` + `.policy-tools/*.py`) is applied across each supported agent
-harness, and where harness limits make it advisory.
-
-## Install & validate
-
-```bash
-uap hooks install            # all project platforms (Hermes is global → opt-in)
-uap hooks install -t hermes  # Hermes (writes global ~/.hermes/config.yaml)
-uap hooks doctor             # audit coverage; exits non-zero on gaps
-uap setup                    # now also installs hooks (Step 7)
-```
-
-The gate script `templates/hooks/uap-policy-gate.sh` is copied into each
-platform's hooks dir and registered on that platform's pre-tool event. It reads
-the tool payload on stdin, runs the active enforcers, and blocks with `exit 2`
-(Claude convention). Hermes uses a wrapper (`uap-policy-gate-hermes.sh`) that
-translates `exit 2` into a stdout `{"decision":"block"}` JSON.
-
-## Coverage matrix
-
-| Platform | Tier | Pre-tool mechanism | Config |
-|---|---|---|---|
-| claude | ✅ gated | `PreToolUse` hooks (Edit/Write/MultiEdit, Bash, Task/Agent/…) | `.claude/settings.local.json` |
-| vscode | ✅ gated | same (Claude format) | `.claude/settings.local.json` |
-| cursor | ✅ gated | `preToolUse` array | `.cursor/hooks.json` |
-| factory | ✅ gated | `PreToolUse` hooks | `.factory/settings.local.json` |
-| opencode | ✅ gated | `tool.execute.before` plugin hook (throws to abort) | `.opencode/plugin/uap-session-hooks.ts` |
-| omp | ✅ gated | `preToolUsePolicyGate` hook | `.uap/omp/settings.json` |
-| hermes | ✅ gated | `pre_tool_call` shell hook (stdout block JSON) | `~/.hermes/config.yaml` (global) |
-| codex | ⚠️ MCP-gated | no native pre-tool hook event | `.codex/config.toml` `[mcp_servers.uap]` |
-| forgecode | ⚠️ advisory | plugin injects policy context; no block path | `.forge/forgecode.plugin.sh` |
-
-## Harness limits (why two platforms are not hard-gated)
-
-- **Codex** has no pre-tool-use *hook event*, so it can't auto-run the gate
-  before every tool. Gating is **hard** for tools routed through the UAP MCP
-  server (`execute_tool` runs the PolicyGate) and **advisory** for codex-native
-  edit/bash (run `bash .codex/hooks/uap-policy-gate.sh` per AGENTS.md). `hooks
-  doctor` reports codex as MCP-gated.
-- **ForgeCode**'s plugin surfaces session/compaction lifecycle and injects the
-  active-policy list as context, but exposes no pre-tool interception point that
-  can *block*. Reported as advisory.
-
-## Hermes specifics
-
-- Config is **global** (`$HERMES_HOME` or `~/.hermes/config.yaml`), so it is
-  excluded from the default `uap hooks install` loop and installed explicitly
-  with `-t hermes`. `hooks doctor` treats an absent `~/.hermes` as optional, and
-  a present-but-unwired install as a real gap.
-- Hermes hooks are **fail-open** (a crashing/exit-non-zero/bad-JSON hook lets the
-  tool proceed). The UAP Hermes gate therefore always exits 0 and always emits a
-  valid decision JSON, so genuine blocks are enforced.
-- Hermes prompts once to approve each hook command (stored in
-  `~/.hermes/shell-hooks-allowlist.json`); approve the UAP gate, or set
-  `hooks_auto_accept: true`.
-- Hermes has no per-file persona registry, so UAP droids are surfaced via a
-  skills bridge (`~/.hermes/uap-skills/uap-experts/SKILL.md`) that routes to
-  `uap expert-route` and the MCP `experts.<name>` tools.
-
-## Key files
-
-- Installer + doctor: `src/cli/hooks.ts` (`copyHookScripts`, `installHermesHooks`, `auditPlatform`, `hooksDoctor`, `ALL_TARGETS`).
-- Gate scripts: `templates/hooks/uap-policy-gate.sh`, `templates/hooks/uap-policy-gate-hermes.sh`.
-- MCP-router gate (codex path): `src/mcp-router/tools/execute.ts:handleExecuteTool`.
-- Setup wiring: `src/cli/setup.ts`.