cognitive-core 0.0.2 → 0.1.2

package/docs/DESIGN-workspace-migration.md

@@ -0,0 +1,1079 @@
+# Design: Workspace Migration & Modular Compute
+
+**Status:** Draft
+**Supersedes:** Portions of `DESIGN-agentic-workspace.md` (Phase 3–4: migration path)
+**Builds on:** `DESIGN-agentic-workspace.md` (infrastructure), `DESIGN-team-extraction-pipeline.md` (team analysis)
+
+---
+
+## Problem
+
+cognitive-core has three structural issues:
+
+1. **~10 analysis tasks use brittle heuristics** (word overlap, regex, exponential decay) for work that requires semantic understanding. The `AgenticTaskTemplate` + `AgenticTaskRunner` infrastructure now exists but no tasks have been migrated to use it.
+
+2. **Three major subsystems are implemented but disconnected from the core flow.** `MetaLearner`, `LearningEffectivenessTracker`, and `LLMPlaybookExtractor` are never called from `Atlas.solve()` or `LearningPipeline`. Their outputs are lost.
+
+3. **Compute is tightly coupled.** `AgentManager` maps agent types to backends via name matching. `ACPBackend` conflates the ACP wire protocol with local process spawning. There is no way to route the same agent type to different compute sources based on cost, availability, or requirements.
+
+This document specifies the concrete migration of all analysis tasks to workspace-based execution, the wiring of disconnected subsystems, and a modular compute provider abstraction.
+
+---
+
+## Scope
+
+| In Scope | Out of Scope |
+|----------|-------------|
+| Migrating existing heuristic analysis tasks to `AgenticTaskTemplate` | New team trajectory types (covered by `DESIGN-team-extraction-pipeline.md`) |
+| Wiring disconnected subsystems into `Atlas.solve()` | Changes to the memory system internals |
+| `ComputeProvider` abstraction for modular backend selection | Implementing specific remote compute backends |
+| Updated `LearningPipeline` orchestration | Changes to the `agent-workspace` package itself |
+| Configuration schema additions | UI/CLI changes |
+
+---
+
+## Part 1: Task Inventory and Migration Plan
+
+### 1.1 Complete Task Map
+
+Every analysis point, its current implementation, and its migration target:
+
+| # | Task | File | Current Impl | Migration | Priority |
+|---|------|------|-------------|-----------|----------|
+| 1 | Credit assignment | `learning/analyzer.ts:70-84` | Exponential decay / outcome-based | Template: `trajectory-analysis` | A |
+| 2 | Key step identification | `learning/analyzer.ts:154-157` | Attribution threshold (≥ 0.15) | Merged into `trajectory-analysis` | A |
+| 3 | Error pattern detection | `learning/analyzer.ts:188-237` | Regex matching + repetition counting | Merged into `trajectory-analysis` | A |
+| 4 | Abstractability assessment | `learning/analyzer.ts:242-263` | Heuristic (success + key steps ≥ 2) | Merged into `trajectory-analysis` | A |
+| 5 | Playbook extraction | `learning/playbook-extractor.ts:68-108` | Action normalization + frequency + text similarity | Template: `playbook-extraction` | A |
+| 6 | LLM playbook extraction | `learning/llm-extractor.ts:67-135` | Single LLM call, JSON parsing | Absorbed into `playbook-extraction` template | A |
+| 7 | Usage inference | `learning/usage-inference.ts:71-107` | Keyword extraction + word overlap | Template: `usage-inference` | A |
+| 8 | Meta-learning reflection | `learning/meta-learner.ts:68-130` | Word overlap, heuristic outcome quality | Template: `meta-reflection` | B |
+| 9 | Solution evaluation | `search/evaluator.ts` | Tiered: agent + heuristic | Template: `solution-evaluation` | B |
+| 10 | Refinement strategy | `search/refinement-loop.ts:112-217` | Issue listing + retry with same config | Template: `refinement-analysis` | B |
+| 11 | Routing decision | `search/router.ts:106-161` | Threshold-based rules on similarity scores | Template: `routing-decision` | C |
+| 12 | Effectiveness tracking | `learning/effectiveness.ts` | Counting / aggregation | **No migration** — pure metrics, heuristic is correct | — |
+| 13 | Team trajectory analysis | *new* | N/A | Template: `team-analysis` | D |
+| 14 | Team playbook extraction | *new* | N/A | Template: `team-playbook-extraction` | D |
+
+**Priority key:**
+- **A** — High-value migrations. Heuristics doing semantic work. Migrate first.
+- **B** — Medium-value. Current implementations work but are limited.
+- **C** — Lower value. Threshold-based routing is adequate for now.
+- **D** — New capabilities. Depend on team trajectory types from separate design.
+
+### 1.2 Template Consolidation
+
+Tasks 1–4 (`TrajectoryAnalyzer`) are currently a single method (`analyze()`). Rather than four separate templates, they become **one template** (`trajectory-analysis`) where the agent performs all four analyses in a single workspace session. This matches the current call pattern and avoids spawning four agents per trajectory.
+
+Tasks 5–6 (`PlaybookExtractor` + `LLMPlaybookExtractor`) consolidate into a **single template** (`playbook-extraction`). The LLM extractor currently exists but is never called from `LearningPipeline` — the template replaces both.
+
+### 1.3 Templates to Implement
+
+Seven templates total (plus two from team design):
+
+```
+workspace/templates/
+├── trajectory-analysis.ts      # Replaces TrajectoryAnalyzer (tasks 1-4)
+├── playbook-extraction.ts      # Replaces PlaybookExtractor + LLMPlaybookExtractor (tasks 5-6)
+├── usage-inference.ts          # Replaces PlaybookUsageInference (task 7)
+├── meta-reflection.ts          # Replaces MetaLearner.generateReflection() (task 8)
+├── solution-evaluation.ts      # Enhances evaluator.ts (task 9)
+├── refinement-analysis.ts      # Enhances refinement-loop.ts (task 10)
+├── routing-decision.ts         # Enhances router.ts (task 11)
+├── team-analysis.ts            # New (task 13, from team design)
+└── team-playbook-extraction.ts # New (task 14, from team design)
+```
+
+Each template file exports an `AgenticTaskTemplate<TInput, TOutput>` conforming to the interface defined in `workspace/types.ts`.
+
+---
+
+## Part 2: Core Flow Adjustments
+
+### 2.1 Current Flow (with disconnections marked)
+
+```
+Atlas.solve(task)
+  ├─ TaskRouter.route(task)                          # threshold heuristic
+  ├─ SkillLibrary.getSkillsForAgent(task)            # tier-based injection
+  ├─ AgentManager.spawn(config)                      # execute task
+  │
+  │  ╌╌╌ POST-EXECUTION ╌╌╌
+  │
+  ├─ PlaybookUsageInference.inferUsage(traj, pbs)    # word overlap
+  ├─ SkillLibrary.recordOutcome(...)                  # update tiers
+  │
+  │  ✗ MetaLearner.generateReflection() ← NEVER CALLED
+  │  ✗ EffectivenessTracker.annotate()  ← NEVER CALLED
+  │
+  ├─ LearningPipeline.processTrajectory(traj)
+  │    ├─ MemorySystem.storeTrajectory(traj)
+  │    ├─ TrajectoryAnalyzer.analyze(traj)            # exp decay + regex
+  │    └─ accumulate for batch
+  │
+  └─ [batch threshold] → LearningPipeline.runBatchLearning()
+       ├─ PlaybookExtractor.extract(trajs, analyses)  # frequency counting
+       │
+       │  ✗ LLMPlaybookExtractor ← EXISTS BUT NEVER CALLED
+       │
+       └─ Memory.playbooks.add/update
+```
+
+### 2.2 Updated Flow
+
+```
+Atlas.solve(task)
+  ├─ TaskRouter.route(task)
+  ├─ SkillLibrary.getSkillsForAgent(task)
+  ├─ AgentManager.spawn(config)                       # execute task
+  │
+  │  ╌╌╌ POST-EXECUTION (workspace-based) ╌╌╌
+  │
+  ├─ taskRunner.run(usageInferenceTemplate, {...})     # MIGRATED: semantic matching
+  ├─ SkillLibrary.recordOutcome(...)
+  ├─ taskRunner.run(metaReflectionTemplate, {...})     # WIRED UP: was disconnected
+  ├─ EffectivenessTracker.annotate(...)                # WIRED UP: was disconnected
+  │
+  ├─ LearningPipeline.processTrajectory(traj)
+  │    ├─ MemorySystem.storeTrajectory(traj)
+  │    ├─ taskRunner.run(trajectoryAnalysisTemplate, {...})  # MIGRATED
+  │    └─ accumulate for batch
+  │
+  └─ [batch threshold] → LearningPipeline.runBatchLearning()
+       ├─ taskRunner.run(playbookExtractionTemplate, {...})  # MIGRATED (unifies both extractors)
+       └─ Memory.playbooks.add/update
+```
+
+### 2.3 Specific Wiring Changes
+
+#### 2.3.1 Wire MetaLearner into Atlas
+
+`Atlas` currently never creates a `MetaLearner`. Add:
+
+```typescript
+// In Atlas constructor or init()
+this.metaLearner = createMetaLearner(this.memory.meta);
+this.router.setMetaLearner(this.metaLearner);
+```
+
+In `Atlas.solve()`, after usage inference:
+
+```typescript
+// Generate meta-reflection (workspace-based for complex cases, heuristic for simple)
+const metaResult = await this.taskRunner.run(metaReflectionTemplate, {
+  trajectory: result.trajectory,
+  routingDecision: routing,
+  playbooksUsed: injectedPlaybooks,
+});
+
+// Feed reflection back to meta-learner for strategy generation
+await this.metaLearner.recordObservation(metaResult.output);
+```
+
+#### 2.3.2 Wire EffectivenessTracker into Atlas
+
+`Atlas` currently never calls `annotate()`. Add after usage inference:
+
+```typescript
+// In Atlas.solve(), after usage inference completes
+const appliedPlaybookIds = (result.playbookUsage ?? [])
+  .filter(u => u.wasUsed)
+  .map(u => u.playbookId);
+
+await this.effectivenessTracker.annotate(
+  result.trajectory,
+  routing.memoryContext.playbooks,    // surfaced
+  routing.memoryContext.experiences.map(e => e.experience.id),  // surfaced experiences
+  appliedPlaybookIds,                 // applied
+);
+```
+
+#### 2.3.3 LearningPipeline Accepts AgenticTaskRunner
+
+`LearningPipeline` currently instantiates `TrajectoryAnalyzer` and `PlaybookExtractor` directly. Change to accept and use `AgenticTaskRunner`:
+
+```typescript
+class LearningPipeline {
+  private taskRunner: AgenticTaskRunner | null = null;
+
+  // Existing analyzer/extractor kept as heuristic fallbacks
+  private analyzer: TrajectoryAnalyzer;
+  private playbookExtractor: PlaybookExtractor;
+
+  setTaskRunner(runner: AgenticTaskRunner): void {
+    this.taskRunner = runner;
+  }
+
+  async processTrajectory(trajectory: Trajectory): Promise<ProcessResult> {
+    await this.memory.storeTrajectory(trajectory);
+
+    let analysis: AnalysisResult;
+    if (this.taskRunner) {
+      // Workspace-based analysis (with built-in heuristic fallback)
+      const result = await this.taskRunner.run(trajectoryAnalysisTemplate, {
+        trajectory,
+        creditStrategy: this.config.creditStrategy,
+      });
+      analysis = result.output;
+    } else {
+      // Direct heuristic (no runner configured)
+      analysis = await this.analyzer.analyze(trajectory);
+    }
+
+    this.accumulated.push(trajectory);
+    this.accumulatedAnalyses.push(analysis);
+
+    return {
+      trajectoryId: trajectory.id,
+      stored: true,
+      analysis,
+      abstractable: analysis.abstractable,
+      playbookExtracted: false,
+    };
+  }
+
+  async runBatchLearning(): Promise<BatchResult> {
+    // ... existing guard clauses ...
+
+    let playbookExtraction: ExtractedPlaybooks;
+    if (this.taskRunner) {
+      const result = await this.taskRunner.run(playbookExtractionTemplate, {
+        trajectories: this.accumulated,
+        analyses: this.accumulatedAnalyses,
+        existingPlaybooks: await this.memory.playbooks.getAll(),
+      });
+      playbookExtraction = result.output;
+    } else {
+      playbookExtraction = await this.playbookExtractor.extract(
+        this.accumulated,
+        this.accumulatedAnalyses,
+        await this.memory.playbooks.getAll(),
+      );
+    }
+
+    // ... rest of method (add playbooks, prune, etc.) unchanged ...
+  }
+}
+```
+
+### 2.4 Heuristic Fallback Guarantee
+
+Every template's `assessComplexity()` routes simple cases to the `heuristicFallback()` which calls the **existing implementation unchanged**. This means:
+
+- No functionality is lost during migration
+- Simple cases (short successful trajectories, few playbooks, clear outcomes) stay fast and free
+- Agent analysis is reserved for cases where semantic understanding provides value
+- The system can run in "heuristic-only" mode if no `AgenticTaskRunner` is configured
+
+---
+
+## Part 3: Modular Compute Provider
+
+### 3.1 Problem
+
+The current `AgentManager.findBackend()` at `runtime/manager.ts:471-480` does this:
+
+```typescript
+private findBackend(agentType: string): AgentBackend | undefined {
+  for (const backend of this.backends.values()) {
+    if (backend.supportedTypes.includes(agentType)) {
+      return backend;  // First match wins
+    }
+  }
+  return this.backends.get(agentType);
+}
+```
+
+This has three limitations:
+1. **First-match wins.** If two backends support `claude-code`, the first registered one always wins.
+2. **No cost/requirements routing.** A lightweight analysis task and a thorough team analysis both get the same backend.
+3. **`ACPBackend` conflates protocol and compute.** The class at `runtime/backends/acp.ts` handles ACP update processing (`processUpdate`, session management) AND local process lifecycle (`AgentFactory.spawn`). Adding a remote ACP endpoint means duplicating the protocol handling code.
+
+### 3.2 Design
+
+Introduce a `ComputeProvider` that sits between `AgentManager` and the backend registry:
+
+```
+AgenticTaskRunner
+  → AgentManager.spawn(config)
+      → ComputeProvider.resolve(agentType, requirements)
+          → returns ComputeTarget { backend, overrides }
+      → backend.spawn(mergedConfig)
+```
+
+#### 3.2.1 New Types
+
+```typescript
+// src/runtime/compute-provider.ts
+
+/**
+ * Requirements for compute resolution.
+ * Templates express preferences; the provider resolves them to concrete backends.
+ */
+export interface ComputeRequirements {
+  /** Preferred execution location */
+  mode?: 'local' | 'remote' | 'any';
+  /** Maximum cost budget in cents (for cost-aware routing) */
+  maxCostCents?: number;
+  /** Required agent capabilities */
+  capabilities?: string[];
+  /** Timeout hint (provider may select faster backends for short timeouts) */
+  timeout?: number;
+  /** Complexity hint from template */
+  complexity?: AnalysisComplexity;
+}
+
+/**
+ * Resolution result: which backend to use and any config overrides.
+ */
+export interface ComputeTarget {
+  /** The resolved backend */
+  backend: AgentBackend;
+  /** Config overrides for this resolution (e.g., different timeout, env vars) */
+  overrides?: Partial<AgentSpawnConfig>;
+  /** Source identifier for logging/metrics */
+  source: string;
+}
+
+/**
+ * Registered compute source with metadata.
+ */
+export interface ComputeSource {
+  /** Unique name for this source */
+  name: string;
+  /** Underlying backend */
+  backend: AgentBackend;
+  /** Cost tier for routing decisions */
+  costTier: 'free' | 'low' | 'medium' | 'high';
+  /** Execution location */
+  location: 'local' | 'remote';
+  /** Priority (lower = preferred, for tie-breaking) */
+  priority: number;
+}
+
+/**
+ * Resolves agent type + requirements to a concrete compute target.
+ */
+export interface ComputeProvider {
+  /** Resolve an agent execution request to a backend */
+  resolve(
+    agentType: string,
+    requirements?: ComputeRequirements
+  ): Promise<ComputeTarget>;
+
+  /** Register a compute source */
+  register(source: ComputeSource): void;
+
+  /** List available compute sources */
+  listSources(): ComputeSource[];
+
+  /** Check if any source supports the given agent type */
+  supports(agentType: string): boolean;
+}
+```
+
+#### 3.2.2 Default Implementation
+
+```typescript
+// src/runtime/compute-provider.ts
+
+/**
+ * Default compute provider.
+ * Replicates current first-match behavior, with optional cost/location routing.
+ */
+export class DefaultComputeProvider implements ComputeProvider {
+  private sources: ComputeSource[] = [];
+
+  register(source: ComputeSource): void {
+    this.sources.push(source);
+    // Keep sorted by priority
+    this.sources.sort((a, b) => a.priority - b.priority);
+  }
+
+  listSources(): ComputeSource[] {
+    return [...this.sources];
+  }
+
+  supports(agentType: string): boolean {
+    return this.sources.some(s => s.backend.supportedTypes.includes(agentType));
+  }
+
+  async resolve(
+    agentType: string,
+    requirements?: ComputeRequirements
+  ): Promise<ComputeTarget> {
+    // Filter to sources that support this agent type
+    let candidates = this.sources.filter(
+      s => s.backend.supportedTypes.includes(agentType)
+    );
+
+    if (candidates.length === 0) {
+      throw new Error(
+        `No compute source supports agent type '${agentType}'. ` +
+        `Available sources: ${this.sources.map(s => s.name).join(', ')}`
+      );
+    }
+
+    // Apply requirements filters
+    if (requirements?.mode && requirements.mode !== 'any') {
+      const locationFiltered = candidates.filter(
+        s => s.location === requirements.mode
+      );
+      if (locationFiltered.length > 0) {
+        candidates = locationFiltered;
+      }
+      // If no match for preferred mode, fall back to all candidates
+    }
+
+    if (requirements?.maxCostCents !== undefined) {
+      const costOrder: Record<string, number> = {
+        free: 0, low: 1, medium: 5, high: 20,
+      };
+      const budgetFiltered = candidates.filter(
+        s => costOrder[s.costTier] <= (requirements.maxCostCents ?? Infinity)
+      );
+      if (budgetFiltered.length > 0) {
+        candidates = budgetFiltered;
+      }
+    }
+
+    // Check availability (first available wins, respecting priority order)
+    for (const source of candidates) {
+      if (await source.backend.isAvailable()) {
+        return {
+          backend: source.backend,
+          source: source.name,
+        };
+      }
+    }
+
+    // Fallback: return first candidate regardless of availability
+    return {
+      backend: candidates[0].backend,
+      source: candidates[0].name,
+    };
+  }
+}
+```
+
+#### 3.2.3 AgentManager Integration
+
+Modify `AgentManager` to use `ComputeProvider` instead of direct backend lookup:
+
+```typescript
+// src/runtime/manager.ts
+
+export class AgentManager {
+  private computeProvider: ComputeProvider;
+  // ... existing fields ...
+
+  constructor(
+    memory: MemorySystem,
+    options?: {
+      injector?: KnowledgeInjector;
+      extractor?: TrajectoryExtractor;
+      computeProvider?: ComputeProvider;
+    }
+  ) {
+    this.memory = memory;
+    this.injector = options?.injector ?? new DefaultKnowledgeInjector();
+    this.extractor = options?.extractor ?? new DefaultTrajectoryExtractor();
+    this.computeProvider = options?.computeProvider ?? new DefaultComputeProvider();
+  }
+
+  /**
+   * Register a backend as a compute source.
+   * Wraps the backend in a ComputeSource with defaults.
+   */
+  registerBackend(backend: AgentBackend, options?: {
+    costTier?: ComputeSource['costTier'];
+    location?: ComputeSource['location'];
+    priority?: number;
+  }): void {
+    this.computeProvider.register({
+      name: backend.name,
+      backend,
+      costTier: options?.costTier ?? 'low',
+      location: options?.location ?? 'local',
+      priority: options?.priority ?? 10,
+    });
+    // Keep backwards-compatible backends map
+    this.backends.set(backend.name, backend);
+  }
+
+  async spawn(config: AgentSpawnConfig): Promise<AgentResult> {
+    // Resolve compute target
+    const target = await this.computeProvider.resolve(
+      config.agentType,
+      config.computeRequirements,
+    );
+
+    // Merge overrides from compute resolution
+    const resolvedConfig = target.overrides
+      ? { ...config, ...target.overrides }
+      : config;
+
+    // ... rest of spawn logic uses target.backend instead of findBackend() ...
+  }
+}
+```
+
+#### 3.2.4 AgenticTaskTemplate Gets ComputeRequirements
+
+Add an optional field to the template interface:
+
+```typescript
+// src/workspace/types.ts (addition to AgenticTaskTemplate)
+
+export interface AgenticTaskTemplate<TInput, TOutput> {
+  // ... existing fields ...
+
+  /**
+   * Compute requirements for this template.
+   * Used by ComputeProvider to select appropriate backend.
+   * If not specified, defaults are used.
+   */
+  computeRequirements?: ComputeRequirements;
+
+  /**
+   * Dynamic compute requirements based on input and complexity.
+   * Overrides static computeRequirements when provided.
+   */
+  getComputeRequirements?(
+    input: TInput,
+    complexity: AnalysisComplexity
+  ): ComputeRequirements;
+}
+```
+
+The `AgenticTaskRunner` passes these through when spawning:
+
+```typescript
+// In AgenticTaskRunner.run(), when building spawn config:
+const requirements = template.getComputeRequirements
+  ? template.getComputeRequirements(input, complexity)
+  : template.computeRequirements;
+
+const agentResult = await this.agentManager.spawn({
+  agentType: template.agentType ?? 'claude-code',
+  task,
+  cwd: handle.path,
+  injectedKnowledge: knowledge,
+  computeRequirements: requirements,
+  // ...
+});
+```
+
+#### 3.2.5 ACPBackend Split
+
+Split the current monolithic `ACPBackend` into two concerns:
+
+```
+Current:
+  ACPBackend
+    ├─ ACP wire protocol (processUpdate, session streaming)
+    └─ Local process lifecycle (AgentFactory.spawn, close)
+
+After:
+  ACPProtocolMixin (or base class)
+    └─ processUpdate(), runPrompt(), session state management
+
+  LocalACPBackend extends ACPProtocolMixin
+    └─ AgentFactory.spawn() for local processes
+
+  RemoteACPBackend extends ACPProtocolMixin  (future)
+    └─ HTTP/WebSocket connection to remote ACP endpoint
+```
+
+The `ACPProtocolMixin` extracts the `processUpdate()` method at `acp.ts:169-270` and `runPrompt()` at `acp.ts:138-163` into a reusable piece. Backend implementations only need to provide `spawn()` and `terminate()` for their specific compute environment.
+
+### 3.3 AgentSpawnConfig Addition
+
+```typescript
+// src/runtime/types.ts (addition to AgentSpawnConfig)
+
+export interface AgentSpawnConfig {
+  // ... existing fields ...
+
+  /** Compute requirements for provider-based resolution */
+  computeRequirements?: ComputeRequirements;
+}
+```
+
+### 3.4 Configuration Addition
+
+```typescript
+// src/types/config.ts (additions)
+
+export const ComputeProviderConfigSchema = z.object({
+  /** Default cost tier preference */
+  defaultCostTier: z.enum(['free', 'low', 'medium', 'high']).default('low'),
+  /** Default location preference */
+  defaultLocation: z.enum(['local', 'remote', 'any']).default('local'),
+  /** Fallback to any available source if preferred not available */
+  allowFallback: z.boolean().default(true),
+});
+
+export type ComputeProviderConfig = z.infer<typeof ComputeProviderConfigSchema>;
+
+// Add to AtlasConfigSchema:
+// compute: ComputeProviderConfigSchema.default({}),
+```
+
+---
+
+## Part 4: Template Specifications
+
+Each template follows the `AgenticTaskTemplate<TInput, TOutput>` interface from `workspace/types.ts`. Below are the input/output types and complexity rules for each.
+
+### 4.1 Trajectory Analysis Template
+
+**Replaces:** `TrajectoryAnalyzer` (tasks 1–4)
+
+```typescript
+// workspace/templates/trajectory-analysis.ts
+
+interface TrajectoryAnalysisInput {
+  trajectory: Trajectory;
+  creditStrategy: CreditStrategy;
+}
+
+// Output reuses the existing AnalysisResult type from learning/analyzer.ts
+// No schema changes needed — the agent produces the same shape.
+
+const trajectoryAnalysisTemplate: AgenticTaskTemplate<
+  TrajectoryAnalysisInput,
+  AnalysisResult
+> = {
+  taskType: 'trajectory-analysis',
+  domain: 'trajectory-analysis',
+  description: 'Analyze agent trajectory for credit assignment, key steps, and error patterns',
+
+  assessComplexity(input) {
+    const { trajectory } = input;
+    // Short successful trajectories → heuristic (existing analyzer is fine)
+    if (trajectory.steps.length <= 5 && trajectory.outcome.success) {
+      return 'heuristic';
+    }
+    // Failed trajectories benefit most from semantic analysis
+    if (!trajectory.outcome.success) return 'standard';
+    // Long trajectories need agent to identify what actually mattered
+    if (trajectory.steps.length > 20) return 'standard';
+    return 'lightweight';
+  },
+
+  async heuristicFallback(input) {
+    // Delegates to existing TrajectoryAnalyzer — zero cost path
+    const analyzer = createAnalyzer(input.creditStrategy);
+    return analyzer.analyze(input.trajectory);
+  },
+
+  // Workspace: input/context.md + input/trajectories/execution.jsonl
+  // Output: output/analysis.json (AnalysisResult schema)
+
+  computeRequirements: { mode: 'local', complexity: 'lightweight' },
+};
+```
+
+**Workspace layout:**
+```
+input/
+  context.md             # YAML frontmatter: taskId, domain, outcome, stepCount, wallTime
+  trajectories/
+    execution.jsonl      # One step per line (thought, action, observation, metadata)
+skills/                  # Analysis playbooks converted to SKILL.md
+output/
+  analysis.json          # AnalysisResult (validated against existing schema)
+```
+
+### 4.2 Playbook Extraction Template
+
+**Replaces:** `PlaybookExtractor` + `LLMPlaybookExtractor` (tasks 5–6)
+
+```typescript
+// workspace/templates/playbook-extraction.ts
+
+interface PlaybookExtractionInput {
+  trajectories: Trajectory[];
+  analyses: AnalysisResult[];
+  existingPlaybooks: Playbook[];
+}
+
+// Output reuses ExtractedPlaybooks from learning/playbook-extractor.ts
+
+const playbookExtractionTemplate: AgenticTaskTemplate<
+  PlaybookExtractionInput,
+  ExtractedPlaybooks
+> = {
+  taskType: 'playbook-extraction',
+  domain: 'playbook-extraction',
+  description: 'Extract reusable playbooks from trajectory batch',
+  timeout: 300_000,
+
+  assessComplexity(input) {
+    if (input.trajectories.length <= 3) return 'heuristic';
+    if (input.trajectories.length > 10) return 'thorough';
+    return 'standard';
+  },
+
+  async heuristicFallback(input) {
+    const extractor = createPlaybookExtractor();
+    return extractor.extract(input.trajectories, input.analyses, input.existingPlaybooks);
+  },
+
+  computeRequirements: { mode: 'local', complexity: 'standard' },
+};
+```
+
+**Workspace layout:**
+```
+input/
+  summary.md                     # YAML: batchSize, domains[], successRate
+  trajectories/
+    {trajectoryId}.jsonl         # One per trajectory, one step per line
+  analyses/
+    {trajectoryId}.json          # Pre-computed analysis from template 4.1
+  existing-playbooks/
+    {playbookName}.json          # For deduplication
+skills/                          # Extraction playbooks → SKILL.md
+output/
+  playbooks/                     # New playbooks (JSON)
+  updates/                       # Updates to existing playbooks (JSON)
+  extraction-summary.json        # Required: counts, patterns found, confidence
+```
+
+### 4.3 Usage Inference Template
+
+**Replaces:** `PlaybookUsageInference` (task 7)
+
+```typescript
+// workspace/templates/usage-inference.ts
+
+interface UsageInferenceInput {
+  trajectory: Trajectory;
+  injectedPlaybooks: Playbook[];
+}
+
+// Output: PlaybookUsageResult[] from learning/usage-inference.ts
+
+const usageInferenceTemplate: AgenticTaskTemplate<
+  UsageInferenceInput,
+  PlaybookUsageResult[]
+> = {
+  taskType: 'usage-inference',
+  domain: 'usage-inference',
+  description: 'Determine which injected playbooks were actually followed',
+
+  assessComplexity(input) {
+    if (input.injectedPlaybooks.length === 0) return 'heuristic';
+    if (input.injectedPlaybooks.length <= 2 && input.trajectory.steps.length <= 10) {
+      return 'heuristic';
+    }
+    return 'lightweight';
+  },
+
+  async heuristicFallback(input) {
+    const inference = createUsageInference();
+    return inference.inferUsage(input.trajectory, input.injectedPlaybooks);
+  },
+
+  computeRequirements: { mode: 'local', complexity: 'lightweight' },
+};
+```
+
+### 4.4 Meta-Reflection Template
+
+**Replaces:** `MetaLearner.generateReflection()` (task 8)
+
+```typescript
+// workspace/templates/meta-reflection.ts
+
+interface MetaReflectionInput {
+  trajectory: Trajectory;
+  routingDecision: RoutingDecision;
+  playbooksUsed: Playbook[];
+}
+
+// Output: MetaObservation from types/meta.ts
+
+const metaReflectionTemplate: AgenticTaskTemplate<
+  MetaReflectionInput,
+  MetaObservation
+> = {
+  taskType: 'meta-reflection',
+  domain: 'meta-reflection',
+  description: 'Reflect on task execution to generate meta-learning observations',
+
+  assessComplexity(input) {
+    // Clear success with high confidence routing → heuristic
+    if (input.trajectory.outcome.success && input.routingDecision.confidence > 0.8) {
+      return 'heuristic';
+    }
+    return 'lightweight';
+  },
+
+  async heuristicFallback(input) {
+    // Existing MetaLearner logic (word overlap, outcome quality heuristics)
+    // Extract from MetaLearner.generateReflection() into standalone function
+  },
+
+  computeRequirements: { mode: 'local', complexity: 'lightweight' },
+};
+```
+
+### 4.5 Solution Evaluation Template
+
+**Replaces:** `SolutionEvaluator` Tier 2 (task 9)
+
+```typescript
+// workspace/templates/solution-evaluation.ts
+
+interface SolutionEvaluationInput {
+  trajectory: Trajectory;
+  task: Task;
+  solution?: unknown;
+  codebasePath?: string;
+}
+
+// Output: EvaluationResult from search/refinement-types.ts
+
+const solutionEvaluationTemplate: AgenticTaskTemplate<
+  SolutionEvaluationInput,
+  EvaluationResult
+> = {
+  taskType: 'solution-evaluation',
+  domain: 'solution-evaluation',
+  description: 'Evaluate solution quality from trajectory',
+
+  assessComplexity(input) {
+    // Programmatic verification available → use that (Tier 1)
+    if (input.task.verification) return 'heuristic';
+    if (input.trajectory.outcome.success && input.trajectory.steps.length <= 10) {
+      return 'lightweight';
+    }
+    return 'standard';
+  },
+
+  getResources(input) {
+    // Symlink codebase for verification if available
+    if (input.codebasePath) {
+      return [{ path: 'codebase', type: 'symlink', source: input.codebasePath }];
+    }
+    return [];
+  },
+
+  computeRequirements: { mode: 'local', complexity: 'standard' },
+};
+```
+
+### 4.6 Refinement Analysis Template
+
+**Replaces:** inline refinement prompt building in `RefinementLoop` (task 10)
+
+```typescript
+// workspace/templates/refinement-analysis.ts
+
+interface RefinementAnalysisInput {
+  trajectory: Trajectory;
+  task: Task;
+  evaluation: EvaluationResult;
+  previousAttempts: number;
+}
+
+interface RefinementPlan {
+  rootCauses: string[];
+  strategy: string;
+  steps: string[];
+  avoidPatterns: string[];
+}
+
+const refinementAnalysisTemplate: AgenticTaskTemplate<
+  RefinementAnalysisInput,
+  RefinementPlan
+> = {
+  taskType: 'refinement-analysis',
+  domain: 'refinement-analysis',
+  description: 'Analyze failure and plan refinement strategy',
+
+  assessComplexity(input) {
+    // First failure → lightweight analysis
+    if (input.previousAttempts <= 1) return 'lightweight';
+    // Repeated failures → deeper analysis
+    return 'standard';
+  },
+
+  // No heuristic fallback — refinement analysis always benefits from semantic reasoning
+
+  computeRequirements: { mode: 'local', complexity: 'lightweight' },
+};
+```
+
+---
+
+## Part 5: File Changes
+
+### 5.1 New Files
+
+| File | Purpose |
+|------|---------|
+| `src/runtime/compute-provider.ts` | `ComputeProvider` interface + `DefaultComputeProvider` |
+| `src/workspace/templates/trajectory-analysis.ts` | Template for tasks 1–4 |
+| `src/workspace/templates/playbook-extraction.ts` | Template for tasks 5–6 |
+| `src/workspace/templates/usage-inference.ts` | Template for task 7 |
+| `src/workspace/templates/meta-reflection.ts` | Template for task 8 |
+| `src/workspace/templates/solution-evaluation.ts` | Template for task 9 |
+| `src/workspace/templates/refinement-analysis.ts` | Template for task 10 |
+| `src/workspace/templates/index.ts` | Barrel export |
+
+### 5.2 Modified Files
+
+| File | Change |
+|------|--------|
+| `src/runtime/manager.ts` | Accept `ComputeProvider`, use in `spawn()` instead of `findBackend()` |
+| `src/runtime/types.ts` | Add `computeRequirements` to `AgentSpawnConfig` |
+| `src/runtime/backends/acp.ts` | Extract protocol handling into `ACPProtocolMixin` |
+| `src/workspace/types.ts` | Add `computeRequirements` and `getComputeRequirements` to template interface |
+| `src/workspace/runner.ts` | Pass compute requirements through to `AgentManager.spawn()` |
+| `src/learning/pipeline.ts` | Accept `AgenticTaskRunner`, delegate to templates when available |
+| `src/atlas.ts` | Wire `MetaLearner`, `EffectivenessTracker`, use templates in post-execution |
+| `src/types/config.ts` | Add `ComputeProviderConfigSchema` to `AtlasConfigSchema` |
+
+### 5.3 Unchanged Files
+
+| File | Reason |
+|------|--------|
+| `src/learning/analyzer.ts` | Kept as heuristic fallback, called by `trajectoryAnalysisTemplate.heuristicFallback()` |
+| `src/learning/playbook-extractor.ts` | Kept as heuristic fallback, called by `playbookExtractionTemplate.heuristicFallback()` |
+| `src/learning/usage-inference.ts` | Kept as heuristic fallback |
+| `src/learning/meta-learner.ts` | Kept as heuristic fallback + strategy generation logic |
+| `src/learning/effectiveness.ts` | No migration needed (pure metrics) |
+| `src/search/router.ts` | Low priority migration (C), functional as-is |
+| `src/search/evaluator.ts` | Kept as heuristic fallback for Tier 1/3 |
+| `src/search/refinement-loop.ts` | Structure preserved, inner analysis delegated to template |
+
+---
+
+## Part 6: Implementation Order
+
+### Phase 1: Compute Provider (no behavior change)
+
+1. Create `src/runtime/compute-provider.ts` with `DefaultComputeProvider`
+2. Add `computeRequirements` to `AgentSpawnConfig`
+3. Update `AgentManager` to use `ComputeProvider` (default provider replicates current behavior exactly)
+4. Update `registerBackend()` to wrap backends in `ComputeSource`
+
+**Verification:** All existing tests pass unchanged. No behavioral difference.
+
+### Phase 2: Wire Disconnected Subsystems
+
+1. Create `MetaLearner` in `Atlas.init()`, connect to `TaskRouter`
+2. Call `EffectivenessTracker.annotate()` in `Atlas.solve()` post-execution
+3. Ensure `LearningEffectivenessTracker` is initialized in `Atlas.init()`
+
+**Verification:** New integration tests confirm meta-observations are recorded and effectiveness annotations are created.
+
+### Phase 3: First Template Migration (trajectory analysis)
+
+1. Create `workspace/templates/trajectory-analysis.ts`
+2. Add `setTaskRunner()` to `LearningPipeline`
+3. Update `LearningPipeline.processTrajectory()` to delegate when runner is available
+4. Wire `taskRunner` into `LearningPipeline` via `Atlas.setAgentManager()`
+
+**Verification:** Existing `LearningPipeline` tests pass. New tests confirm:
+- Simple trajectories hit `heuristicFallback()` (fast, free)
+- Complex trajectories spawn an agent in a workspace
+- Output validates against `AnalysisResult` schema
+
+### Phase 4: Remaining Priority-A Templates
+
+1. `playbook-extraction.ts` — update `LearningPipeline.runBatchLearning()`
+2. `usage-inference.ts` — update `Atlas.solve()` post-execution
+3. Delete `LLMPlaybookExtractor` (absorbed into playbook extraction template)
+
+**Verification:** Each template has its own test suite. Integration tests confirm the full `solve() → learn → extract` flow.
+
+### Phase 5: Priority-B Templates
+
+1. `meta-reflection.ts` — update `Atlas.solve()` to use template instead of direct `MetaLearner`
+2. `solution-evaluation.ts` — update `SolutionEvaluator` to delegate when runner available
+3. `refinement-analysis.ts` — update `RefinementLoop` to use template for failure analysis
+
+### Phase 6: ACPBackend Split
+
+1. Extract `ACPProtocolMixin` from `ACPBackend`
+2. Create `LocalACPBackend extends ACPProtocolMixin`
+3. (Future) `RemoteACPBackend extends ACPProtocolMixin`
+
+**This phase is independent** and can happen in parallel with template migrations.
+
+---
+
+## Part 7: Cost Model
+
+### 7.1 Per-Template Estimates
+
+| Template | Heuristic Path | Lightweight | Standard | Thorough |
+|----------|---------------|-------------|----------|----------|
+| trajectory-analysis | ~0 tokens | ~2K | ~5K | — |
+| playbook-extraction | ~0 tokens | — | ~8K | ~15K |
+| usage-inference | ~0 tokens | ~1K | — | — |
+| meta-reflection | ~0 tokens | ~2K | — | — |
+| solution-evaluation | ~0 tokens | ~2K | ~5K | — |
+| refinement-analysis | — | ~2K | ~4K | — |
+
+### 7.2 Typical Flow Cost
+
+For a single `Atlas.solve()` call on a moderate task:
+
+| Step | Complexity Hit | Cost |
+|------|---------------|------|
+| Task execution (the actual agent work) | — | ~10-50K tokens |
+| Usage inference (2 playbooks, 8 steps) | heuristic | 0 |
+| Meta-reflection (clear success, high confidence) | heuristic | 0 |
+| Trajectory analysis (8 steps, success) | heuristic | 0 |
+| **Total overhead from learning** | | **~0 tokens** |
+
+For a complex failed task:
+
+| Step | Complexity Hit | Cost |
+|------|---------------|------|
+| Task execution | — | ~30-100K tokens |
+| Usage inference (5 playbooks, 25 steps) | lightweight | ~1K |
+| Meta-reflection (failure, low confidence) | lightweight | ~2K |
+| Trajectory analysis (25 steps, failure) | standard | ~5K |
+| **Total overhead from learning** | | **~8K tokens** |
+
+Batch learning (triggered every ~10 trajectories):
+
+| Step | Complexity Hit | Cost |
+|------|---------------|------|
+| Playbook extraction (10 trajectories) | standard | ~8K |
+| **Total batch cost** | | **~8K tokens** |
+
+The heuristic fallback path ensures that the common case (simple successful tasks) adds zero cost. Semantic analysis is reserved for the ~20% of cases where it matters: failures, complex trajectories, batch extraction.
+
+---
+
+## Appendix A: Existing Code to Preserve as Heuristic Fallbacks
+
+These implementations remain in the codebase, called by `heuristicFallback()` on their respective templates:
+
+| Implementation | Call Path |
+|----------------|-----------|
+| `TrajectoryAnalyzer.analyze()` | `trajectoryAnalysisTemplate.heuristicFallback()` |
+| `PlaybookExtractor.extract()` | `playbookExtractionTemplate.heuristicFallback()` |
+| `PlaybookUsageInference.inferUsage()` | `usageInferenceTemplate.heuristicFallback()` |
+| `MetaLearner.generateReflection()` logic | `metaReflectionTemplate.heuristicFallback()` |
+| `SolutionEvaluator` Tier 1+3 | `solutionEvaluationTemplate.heuristicFallback()` |
+
+No existing code is deleted during migration. The heuristic implementations are the fallback path and continue to be tested independently.
+
+## Appendix B: Backwards Compatibility
+
+| Scenario | Behavior |
+|----------|----------|
+| `Atlas` with no `AgentManager` | `LearningPipeline` uses heuristic analyzers directly (no `taskRunner`) |
+| `Atlas` with `AgentManager` but no workspace templates registered | `LearningPipeline` uses heuristic analyzers (taskRunner exists but templates not wired) |
+| `AgentManager` with single backend | `DefaultComputeProvider` resolves to that backend (current behavior) |
+| `registerBackend()` called without `ComputeSource` options | Backend wrapped with default cost/location/priority |
+| Template with no `computeRequirements` | `ComputeProvider.resolve()` called with no requirements (returns highest-priority available) |