cognitive-core 0.1.2 → 0.2.0

package/docs/PLAN-agentic-workspace-implementation.md

@@ -1,717 +0,0 @@
-# Implementation Plan: Agentic Workspace
-
-## Overview
-
-This plan implements the agentic workspace infrastructure described in `DESIGN-agentic-workspace.md`. The system standardizes how cognitive-core spawns analysis agents with filesystem-based workspaces, structured I/O, and meta-learning capture.
-
-**Goal**: Replace ad-hoc heuristic analyzers with a reusable workspace pattern that routes complex inputs to full agentic analysis while keeping simple cases on fast heuristic paths.
-
-**Key constraint**: All existing heuristics are preserved as `heuristicFallback` — no functionality is lost, and simple cases stay fast.
-
----
-
-## Phase 1: Core Infrastructure
-
-**Objective**: Implement the three foundational components — types, `WorkspaceManager`, and `AgenticTaskRunner` — and wire them into `Atlas`.
-
-### 1.1 — Types & Interfaces
-
-**File**: `src/workspace/types.ts` (new)
-
-Define all workspace-related types and interfaces:
-
-- `AgenticTaskTemplate<TInput, TOutput>` — the declarative recipe interface
-- `OutputConfig`, `OutputFileSpec` — output shape definition
-- `AgentSkillSpec` — skill to load into workspace
-- `ResourceSpec` — supplementary resource definition
-- `AnalysisComplexity` — complexity assessment enum (`'heuristic' | 'lightweight' | 'standard' | 'thorough'`)
-- `ProcessingContext` — context passed to `processOutput`
-- `WorkspaceHandle` — handle to a created workspace directory
-- `AgenticTaskResult<TOutput>` — result from running a task
-- `AgenticTaskRunnerConfig` — runner configuration
-- `AgenticTaskOutputError` — custom error class for output validation failures
-
-All types are directly derived from the design doc (lines 107-283 of `DESIGN-agentic-workspace.md`).
-
-**Zod schemas**: Add `AgenticTaskRunnerConfigSchema` to `src/types/config.ts` as a new section in `AtlasConfigSchema`:
-
-```typescript
-export const AgenticTaskRunnerConfigSchema = z.object({
-  cleanupWorkspaces: z.boolean().default(true),
-  keepFailedWorkspaces: z.boolean().default(true),
-  maxConcurrentAgents: z.number().default(3),
-  staleWorkspaceMaxAgeMs: z.number().default(3600_000),
-  workspaceBaseDir: z.string().optional(), // defaults to os.tmpdir()
-});
-```
-
-Add `agenticTasks: AgenticTaskRunnerConfigSchema.default({})` to `AtlasConfigSchema`.
-
-**Dependencies**: None — pure type definitions.
-
-### 1.2 — WorkspaceManager
-
-**File**: `src/workspace/manager.ts` (new)
-
-Implement the `WorkspaceManager` class with all methods from the design doc (lines 291-596):
-
-- **Creation**: `create(taskType)` — creates `{baseDir}/atlas-workspaces/{taskType}-{timestamp}-{randomId}/` with subdirectories `input/`, `resources/`, `skills/`, `workspace/`, `output/`
-- **Input writers**:
-  - `writeInputJson(handle, filename, data)` — JSON files
-  - `writeInputJsonl(handle, filename, items)` — JSONL files (one item per line)
-  - `writeInputMarkdown(handle, filename, frontmatter, body)` — Markdown with YAML frontmatter
-  - `writeInputRaw(handle, filename, content)` — arbitrary files
-- **Skill writers**:
-  - `writeSkill(handle, skill)` — writes `skills/{name}/SKILL.md`
-  - `writeSkills(handle, skills)` — writes multiple skills in parallel
-- **Resource writers**:
-  - `writeResource(handle, resource)` — handles `file`, `symlink`, and `directory` resource types
-  - `writeResources(handle, resources)` — writes multiple resources in parallel
-- **Output readers**:
-  - `readOutputJson<T>(handle, filename, schema?)` — reads and optionally validates JSON
-  - `readOutputJsonl<T>(handle, filename, schema?)` — reads JSONL as array
-  - `readOutputMarkdown(handle, filename)` — reads raw markdown
-  - `readOutputDir<T>(handle, dirName, schema?)` — reads all JSON files in a directory
-- **Validation**: `validateOutput(handle, config)` — checks required output files exist
-- **Lifecycle**:
-  - `cleanup(handle)` — removes workspace directory
-  - `listActive()` — scans for active workspaces
-  - `pruneStale(maxAgeMs)` — removes old workspaces
-- **Helpers**: `toYamlFrontmatter(data)` — simple YAML serializer for frontmatter
-
-**Implementation notes**:
-- Uses `node:fs/promises` (`mkdir`, `writeFile`, `readFile`, `readdir`, `rm`, `symlink`, `cp`, `access`)
-- Uses `node:path` (`join`, `dirname`)
-- Uses `node:crypto` (`randomUUID`) for workspace IDs
-- `baseDir` defaults to `os.tmpdir()`
-
-**Tests**: `tests/workspace/manager.test.ts`
-- Test workspace creation and directory structure
-- Test each input writer (JSON, JSONL, markdown, raw)
-- Test skill writing
-- Test resource writing (file, symlink, directory)
-- Test output reading with and without schema validation
-- Test output validation (required vs optional files)
-- Test cleanup and stale pruning
-- Test YAML frontmatter generation with different data types
-
-### 1.3 — Playbook-Skill Converter
-
-**File**: `src/workspace/skill-converter.ts` (new)
-
-Implement bidirectional conversion between Playbooks and Agent Skills (SKILL.md format):
-
-- `convertPlaybooksToSkills(playbooks: Playbook[]): AgentSkillSpec[]`
-- `generateSkillMd(playbook: Playbook): string` — renders Playbook as SKILL.md with sections: When to Use, Triggers, Strategy, Tactics, Steps, Example, Verification
-- `parseSkillMdToPlaybook(skillMd: string, skillName: string): Playbook` — parses SKILL.md sections back into Playbook fields
-
-This is directly from the design doc (lines 1792-1849).
-
-**Tests**: `tests/workspace/skill-converter.test.ts`
-- Test round-trip conversion (Playbook → SKILL.md → Playbook)
-- Test that generated SKILL.md is valid markdown with expected sections
-- Test parsing handles optional sections gracefully
-- Test edge cases: empty tactics, no steps, no code example
-
-### 1.4 — AgenticTaskRunner
-
-**File**: `src/workspace/runner.ts` (new)
-
-Implement the `AgenticTaskRunner` class (design doc lines 604-821):
-
-- **Constructor**: Takes `WorkspaceManager`, `AgentManager`, `MemorySystem`, `LearningPipeline`, `AgenticTaskRunnerConfig`
-- **Main method** `run<TInput, TOutput>(template, input)`:
-  1. `assessComplexity()` — check if heuristic suffices
-  2. If `'heuristic'` + `heuristicFallback` exists → run fallback, return immediately
-  3. `workspaceManager.create()` — create workspace
-  4. `template.prepareWorkspace()` — populate input files
-  5. `workspaceManager.writeSkills()` — load skills
-  6. `workspaceManager.writeResources()` — load resources
-  7. `getKnowledge()` — query memory for domain + additional knowledge
-  8. `agentManager.spawn()` — spawn agent with workspace as cwd
-  9. `workspaceManager.validateOutput()` — check required files exist
-  10. `collectWithRetry()` — read and validate output
-  11. `template.processOutput()` — store/accumulate results
-  12. `learningPipeline.processTrajectory()` — meta-learning on analysis agent
-  13. Cleanup workspace (in `finally` block)
-- **Private helpers**:
-  - `getKnowledge()` — combines domain-scoped query + template-specific additional knowledge via `mergeKnowledge`
-  - `collectWithRetry()` — retries output collection on validation failure
-  - `getTimeout()` — adjusts timeout based on complexity level
-
-**Implementation notes**:
-- The `mergeKnowledge` helper deduplicates playbooks by ID when merging domain + additional knowledge results
-- When `config.keepFailedWorkspaces` is true and the task fails, skip cleanup
-- The runner does NOT manage concurrency in Phase 1 (single-threaded execution). Concurrency limiting (`maxConcurrentAgents`) is deferred to Phase 4.
-
-**Tests**: `tests/workspace/runner.test.ts`
-- Test heuristic fallback path (complexity = 'heuristic')
-- Test full agentic path with mock backend and mock template
-- Test workspace lifecycle (created, populated, cleaned up)
-- Test output validation failure handling
-- Test meta-learning (analysis agent trajectory processed)
-- Test knowledge injection (domain + additional merged)
-- Test timeout adjustment by complexity
-- Test failed workspace preservation when `keepFailedWorkspaces` is true
-
-### 1.5 — Module Exports & Index
-
-**File**: `src/workspace/index.ts` (new)
-
-Export all workspace types, classes, and factory functions:
-- `WorkspaceManager`, `createWorkspaceManager`
-- `AgenticTaskRunner`, `createAgenticTaskRunner`
-- `convertPlaybooksToSkills`, `generateSkillMd`, `parseSkillMdToPlaybook`
-- All type exports
-
-**File**: `src/index.ts` (modified)
-
-Add workspace exports section.
-
-### 1.6 — Atlas Integration
-
-**File**: `src/atlas.ts` (modified)
-
-- Add `private taskRunner: AgenticTaskRunner | null = null` field
-- In constructor or `init()`: if `agentManager` is set, create `AgenticTaskRunner` with workspace manager, agent manager, memory, and learning pipeline
-- Add `getTaskRunner(): AgenticTaskRunner | null` accessor
-- Wire into `AtlasConfig` via the new `agenticTasks` config section
-
-**File**: `src/types/config.ts` (modified)
-
-- Add `AgenticTaskRunnerConfigSchema` as defined in 1.1
-- Add to `AtlasConfigSchema`
-
-No changes to existing `solve()` flow in Phase 1 — the runner is available but not yet used by any templates.
-
-### Phase 1 Deliverables
-
-| File | Action | Description |
-|------|--------|-------------|
-| `src/workspace/types.ts` | NEW | All workspace type definitions |
-| `src/workspace/manager.ts` | NEW | WorkspaceManager implementation |
-| `src/workspace/skill-converter.ts` | NEW | Playbook ↔ SKILL.md converter |
-| `src/workspace/runner.ts` | NEW | AgenticTaskRunner implementation |
-| `src/workspace/index.ts` | NEW | Module exports |
-| `src/types/config.ts` | MODIFY | Add AgenticTaskRunnerConfig |
-| `src/atlas.ts` | MODIFY | Wire in AgenticTaskRunner |
-| `src/index.ts` | MODIFY | Export workspace module |
-| `tests/workspace/manager.test.ts` | NEW | WorkspaceManager tests |
-| `tests/workspace/skill-converter.test.ts` | NEW | Converter tests |
-| `tests/workspace/runner.test.ts` | NEW | AgenticTaskRunner tests |
-
----
-
-## Phase 2: First Templates (Team Analysis)
-
-**Objective**: Implement the team analysis and team playbook extraction templates as the first concrete uses of the workspace infrastructure. These are new functionality (no existing code to replace), which makes them ideal for validating the infrastructure end-to-end.
-
-### 2.1 — Team Types
-
-**File**: `src/types/team-trajectory.ts` (new)
-
-Define team trajectory types from `PROPOSAL-team-aware-learning.md`:
-- `TeamEvent`, `TeamEventType`
-- `InteractionEdge`
-- `CoordinationMetrics`
-- `MemberOutcome`
-- `TeamTrajectory`
-- `TeamOutcome`
-
-**File**: `src/types/team-playbook.ts` (new)
-
-Define team playbook types:
-- `TeamPlaybook`, `TeamPlaybookApplicability`
-- `TeamCompositionGuidance`, `TeamRoleSpec`
-- `TeamCoordinationGuidance`, `TeamChannelSpec`, `InteractionPattern`
-- `TeamPlaybookVerification`, `TeamPlaybookEvolution`, `TeamRefinement`
-- `RolePlaybook`, `RoleInteractionGuidance` (from `DESIGN-team-extraction-pipeline.md`)
-
-**File**: `src/types/team-meta.ts` (new)
-
-Define team meta-learning types:
-- `TeamMetaObservation`, `FormationObservation`
-- `CompositionObservation`, `CoordinationObservation`
-- `TeamOutcomeObservation`, `TeamLessonsLearned`
-- `TeamMetaStrategy`, `TeamMetaCondition`, `TeamMetaAdjustment`
-
-**File**: `src/types/index.ts` (modified)
-
-Export all new team types.
-
-**File**: `src/types/config.ts` (modified)
-
-Add `TeamLearningConfigSchema` from the proposal:
-```typescript
-export const TeamLearningConfigSchema = z.object({
-  enabled: z.boolean().default(false),
-  minTrajectories: z.number().default(5),
-  deduplicationThreshold: z.number().min(0).max(1).default(0.85),
-  metricsWeight: z.number().min(0).max(1).default(0.3),
-  maxExperiences: z.number().default(200),
-  maxPlaybooks: z.number().default(50),
-  maxRolePlaybooks: z.number().default(100),
-  analysisTimeout: z.number().default(300_000),
-  extractionTimeout: z.number().default(600_000),
-});
-```
-
-Add `teamLearning: TeamLearningConfigSchema.default({})` to `AtlasConfigSchema`.
-
-### 2.2 — Team Analysis Output Schemas
-
-**File**: `src/workspace/templates/team-analysis-schemas.ts` (new)
-
-Zod schemas for the team analysis agent's output files (from `DESIGN-team-extraction-pipeline.md` lines 518-667):
-- `AgentCreditOutputSchema` — `output/agent-credits.json`
-- `InteractionCreditOutputSchema` — `output/interaction-credits.json`
-- `CoordinationAssessmentOutputSchema` — `output/coordination-assessment.json`
-- `RoleLessonOutputSchema` — `output/role-lessons/{role}.json`
-- `TeamLessonsOutputSchema` — `output/team-lessons.json`
-- `TeamMetaObservationOutputSchema` — `output/meta-observations.json`
-
-These schemas validate that the analysis agent produced correctly shaped output.
-
-### 2.3 — Team Trajectory Ingester
-
-**File**: `src/workspace/templates/team-ingester.ts` (new)
-
-Implement `TeamTrajectoryIngester` — the computational preprocessing step (no LLM calls) from `DESIGN-team-extraction-pipeline.md`:
-
-```typescript
-class TeamTrajectoryIngester {
-  async ingest(input: TeamTrajectoryInput): Promise<IngestResult>
-}
-```
-
-The `ingest()` method:
-1. **Build interaction graph** — extract interaction tags from step metadata, group by `interactionId`, link source→target, validate edges, flag expected vs emergent
-2. **Compute structural metrics** — per-agent stats, per-interaction stats, graph-level metrics (density, degree, bottlenecks, parallelism)
-3. **Compress trajectories** — preserve interaction boundary steps at full fidelity, fold internal steps between boundaries, strip verbose output
-4. **Score steps and interactions** — promise + progress + interaction bonus scoring, mark top ~20% as critical
-5. Return `IngestResult` with `TeamTrajectory`, `compressionStats`, `criticalMoments`
-
-This is purely computational — no workspace or agent involved yet.
-
-**Configuration**: `CompressionConfig` with defaults:
-- `maxTokensPerAgent`: 5000
-- `preserveInteractionBoundaries`: true
-- `foldThreshold`: 5
-- `maxCriticalRatio`: 0.25
-- `criticalStepThreshold`: 0.3
-- `criticalInteractionThreshold`: 0.3
-
-**Tests**: `tests/workspace/templates/team-ingester.test.ts`
-- Test interaction graph building from tagged steps
-- Test structural metrics computation
-- Test compression preserves boundary steps
-- Test critical step/interaction scoring
-- Test with minimal (2-agent) and larger (5+ agent) teams
-
-### 2.4 — Team Analysis Template
-
-**File**: `src/workspace/templates/team-analysis.ts` (new)
-
-Implement `teamAnalysisTemplate: AgenticTaskTemplate<TeamAnalysisInput, TeamAnalysisResult>` (design doc lines 1475-1619):
-
-- `taskType`: `'team-analysis'`
-- `domain`: `'team-analysis'`
-- `assessComplexity()`: ≤2 members → lightweight, >5 or failed → thorough, else standard
-- No `heuristicFallback` — team analysis always needs semantic understanding
-- `prepareWorkspace()`:
-  - Uses the ingester (2.3) to preprocess, then writes compressed trajectories, interaction graph, metrics, context
-  - Writes JSONL for per-agent trajectories
-  - Writes JSON for interaction graph, timeline, structural metrics
-  - Writes markdown context doc with YAML frontmatter
-- `buildTaskPrompt()`: natural language instructions for the analysis agent
-- `getSkills()`: converts team analysis playbooks to SKILL.md
-- `getResources()`: optional codebase snapshot symlink
-- `outputConfig`: defines required output files (agent-credits.json, interaction-credits.json, coordination-assessment.md, lessons.json)
-- `collectOutput()`: reads and validates all output files against Zod schemas
-- `processOutput()`: stores results in team memory (deferred to Phase 2.6), accumulates for batch extraction
-
-**Tests**: `tests/workspace/templates/team-analysis.test.ts`
-- Test complexity assessment for different team sizes/outcomes
-- Test workspace preparation produces expected file structure
-- Test task prompt includes workspace file paths
-- Test output collection with valid and invalid outputs
-
-### 2.5 — Team Playbook Extraction Template
-
-**File**: `src/workspace/templates/team-playbook-extraction.ts` (new)
-
-Implement `teamPlaybookExtractionTemplate: AgenticTaskTemplate<TeamPlaybookExtractionInput, ExtractedTeamPlaybooks>` (design doc lines 1625-1783):
-
-- `taskType`: `'team-playbook-extraction'`
-- `domain`: `'team-playbook-extraction'`
-- `timeout`: 600_000 (10 minutes)
-- `assessComplexity()`: always agentic, >10 batches → thorough, else standard
-- `prepareWorkspace()`:
-  - Writes batch summary markdown with frontmatter
-  - Writes each lesson batch as markdown
-  - Writes existing team/role playbooks for deduplication
-- `buildTaskPrompt()`: instructions for extracting role, team coordination, and meta-strategy playbooks
-- `outputConfig`: team-playbooks/, role-playbooks/, team-skills/, role-skills/, updates/, meta-strategies/, extraction-summary.json
-- `collectOutput()`: reads all output directories
-- `processOutput()`: stores new playbooks and meta-strategies
-
-**Tests**: `tests/workspace/templates/team-playbook-extraction.test.ts`
-- Test complexity assessment
-- Test workspace preparation
-- Test output collection from multiple output directories
-
-### 2.6 — Team Memory System
-
-**File**: `src/memory/team-experience.ts` (new)
-
-Implement `TeamExperienceMemory` — stores team trajectories and analysis results. Mirrors `ExperienceMemory` but for team data.
-
-- JSON file-based persistence under `{baseDir}/team-experiences/`
-- `store(teamTrajectory, analysis)` — save team experience
-- `findSimilar(query, options)` — BM25 search over team experiences
-- `getByDomain(domain)` — domain-scoped retrieval
-- `count()`, `getAll()`, `prune()` — standard memory operations
-
-**File**: `src/memory/team-playbook.ts` (new)
-
-Implement `TeamPlaybookLibrary` and `RolePlaybookLibrary`:
-
-- `TeamPlaybookLibrary` — stores/retrieves `TeamPlaybook` objects
-  - JSON file-based persistence under `{baseDir}/team-playbooks/`
-  - `findMatching(query)` — find team playbooks matching a task
-  - `add()`, `get()`, `getAll()`, `delete()`, `count()`
-  - `recordSuccess()`, `recordFailure()` — evolution tracking
-
-- `RolePlaybookLibrary` — stores/retrieves `RolePlaybook` objects
-  - JSON file-based persistence under `{baseDir}/role-playbooks/`
-  - `findForRole(role, topology, domain)` — find role guidance
-  - `add()`, `get()`, `getAll()`, `delete()`, `count()`
-
-**File**: `src/memory/team-meta.ts` (new)
-
-Implement `TeamMetaMemory`:
-- Stores `TeamMetaObservation` and `TeamMetaStrategy`
-- JSON file-based persistence under `{baseDir}/team-meta-observations/` and `{baseDir}/team-meta-strategies/`
-- `recordObservation()`, `getObservations()`
-- `storeMetaStrategy()`, `getStrategies()`
-
-**File**: `src/memory/system.ts` (modified)
-
-Extend `MemorySystem` with optional team memory fields:
-```typescript
-public readonly teamExperiences?: TeamExperienceMemory;
-public readonly teamPlaybooks?: TeamPlaybookLibrary;
-public readonly rolePlaybooks?: RolePlaybookLibrary;
-public readonly teamMeta?: TeamMetaMemory;
-```
-
-Initialize these when `teamLearning.enabled` is true in config.
-
-**Tests**: `tests/memory/team-experience.test.ts`, `tests/memory/team-playbook.test.ts`, `tests/memory/team-meta.test.ts`
-
-### 2.7 — Team Learning Pipeline
-
-**File**: `src/learning/team-pipeline.ts` (new)
-
-Implement `TeamLearningPipeline` (from `DESIGN-team-extraction-pipeline.md` lines 1144-1213):
-
-```typescript
-class TeamLearningPipeline {
-  async processTeamTrajectory(input: TeamTrajectoryInput): Promise<TeamProcessResult>
-  async runBatchLearning(): Promise<TeamBatchResult>
-  isBatchReady(): boolean
-  getAccumulatedCount(): number
-}
-```
-
-- `processTeamTrajectory()`:
-  1. Ingest via `TeamTrajectoryIngester` (preprocess + compress)
-  2. Run `teamAnalysisTemplate` through `AgenticTaskRunner`
-  3. Store results, accumulate for batch extraction
-  4. Analysis agent's trajectory is automatically processed for meta-learning (done by the runner)
-
-- `runBatchLearning()`:
-  1. Check `accumulated.length >= config.minTeamTrajectories`
-  2. Run `teamPlaybookExtractionTemplate` through `AgenticTaskRunner`
-  3. Store extracted team/role playbooks
-  4. Clear accumulated
-
-**Tests**: `tests/learning/team-pipeline.test.ts`
-
-### 2.8 — Atlas Team Methods
-
-**File**: `src/atlas.ts` (modified)
-
-Add team-aware methods:
-- `processTeamTrajectory(input)` — delegates to `TeamLearningPipeline`
-- `runTeamBatchLearning()` — delegates to pipeline
-- Wire `TeamLearningPipeline` into constructor when team learning is enabled
-- Update `getStats()` to include team memory stats
-
-**File**: `src/index.ts` (modified)
-
-Export team types and pipeline.
-
-### Phase 2 Deliverables
-
-| File | Action | Description |
-|------|--------|-------------|
-| `src/types/team-trajectory.ts` | NEW | Team trajectory types |
-| `src/types/team-playbook.ts` | NEW | Team/role playbook types |
-| `src/types/team-meta.ts` | NEW | Team meta-learning types |
-| `src/types/config.ts` | MODIFY | Add TeamLearningConfig |
-| `src/types/index.ts` | MODIFY | Export team types |
-| `src/workspace/templates/team-analysis-schemas.ts` | NEW | Output Zod schemas |
-| `src/workspace/templates/team-ingester.ts` | NEW | Computational preprocessor |
-| `src/workspace/templates/team-analysis.ts` | NEW | Team analysis template |
-| `src/workspace/templates/team-playbook-extraction.ts` | NEW | Team playbook extraction template |
-| `src/memory/team-experience.ts` | NEW | Team experience memory |
-| `src/memory/team-playbook.ts` | NEW | Team/role playbook libraries |
-| `src/memory/team-meta.ts` | NEW | Team meta-observation memory |
-| `src/memory/system.ts` | MODIFY | Add optional team fields |
-| `src/learning/team-pipeline.ts` | NEW | Team learning pipeline |
-| `src/atlas.ts` | MODIFY | Add team methods |
-| `src/index.ts` | MODIFY | Export team modules |
-| `tests/workspace/templates/team-ingester.test.ts` | NEW | Ingester tests |
-| `tests/workspace/templates/team-analysis.test.ts` | NEW | Analysis template tests |
-| `tests/workspace/templates/team-playbook-extraction.test.ts` | NEW | Extraction template tests |
-| `tests/memory/team-experience.test.ts` | NEW | Team memory tests |
-| `tests/memory/team-playbook.test.ts` | NEW | Team playbook tests |
-| `tests/memory/team-meta.test.ts` | NEW | Team meta tests |
-| `tests/learning/team-pipeline.test.ts` | NEW | Pipeline tests |
-
----
-
-## Phase 3: Migrate Existing Analysis
-
-**Objective**: Create templates for existing analysis points, preserving current heuristics as fallbacks. Each migration follows the same pattern: wrap the existing analyzer as `heuristicFallback`, implement `prepareWorkspace` + `buildTaskPrompt` + `collectOutput` for the agentic path.
-
-### 3.1 — Trajectory Analysis Template
-
-**File**: `src/workspace/templates/trajectory-analysis.ts` (new)
-
-Wraps existing `TrajectoryAnalyzer` (from `src/learning/analyzer.ts`):
-
-- `heuristicFallback`: delegates to existing `TrajectoryAnalyzer.analyze()`
-- `assessComplexity`: ≤5 steps + success → heuristic; failed or >20 steps → standard; else lightweight
-- `prepareWorkspace`: writes trajectory as JSONL, context as markdown with frontmatter
-- `outputConfig`: `analysis.json` (required)
-- `collectOutput`: reads and validates against `AnalysisResultSchema`
-
-**File**: `src/learning/pipeline.ts` (modified)
-
-Update `processTrajectory()` to optionally route through `AgenticTaskRunner` when available:
-```typescript
-if (this.taskRunner) {
-  const { output: analysis } = await this.taskRunner.run(
-    trajectoryAnalysisTemplate, { trajectory, creditStrategy }
-  );
-} else {
-  const analysis = await this.analyzer.analyze(trajectory);
-}
-```
-
-Add `setTaskRunner(runner)` method to accept the runner reference.
-
-### 3.2 — Playbook Extraction Template
-
-**File**: `src/workspace/templates/playbook-extraction.ts` (new)
-
-Wraps existing `PlaybookExtractor` + `LLMPlaybookExtractor`:
-
-- `heuristicFallback`: delegates to existing `PlaybookExtractor.extract()`
-- `assessComplexity`: ≤3 trajectories → heuristic; >10 → thorough; else standard
-- `prepareWorkspace`: writes batch summary, trajectories as JSONL, analyses as JSON, existing playbooks for dedup
-- `timeout`: 300_000 (5 min)
-- `outputConfig`: playbooks/ (optional), skills/ (optional), updates/ (optional), extraction-summary.json (required)
-- `collectOutput`: reads playbooks, skills, updates directories
-
-**File**: `src/learning/pipeline.ts` (modified)
-
-Update `runBatchLearning()` to optionally route through runner.
-
-### 3.3 — Meta-Learning Reflection Template
-
-**File**: `src/workspace/templates/meta-reflection.ts` (new)
-
-Wraps existing `MetaLearner.generateReflection()`:
-
-- `heuristicFallback`: existing `MetaLearner` logic
-- `assessComplexity`: success + high confidence → heuristic; else lightweight
-- `prepareWorkspace`: trajectory as JSONL, context with routing decision + injected playbooks as markdown
-- `outputConfig`: `meta-observation.json` (required)
-
-### 3.4 — Usage Inference Template
-
-**File**: `src/workspace/templates/usage-inference.ts` (new)
-
-Wraps existing `PlaybookUsageInference`:
-
-- `heuristicFallback`: existing word-overlap matching
-- `assessComplexity`: no playbooks → heuristic; ≤2 playbooks + short trajectory → heuristic; else lightweight
-- `prepareWorkspace`: trajectory as JSONL, each playbook as markdown
-- `outputConfig`: `usage-results.json` (required)
-
-### 3.5 — Solution Evaluation Template
-
-**File**: `src/workspace/templates/solution-evaluation.ts` (new)
-
-Enhances existing `SolutionEvaluator` Tier 2:
-
-- `heuristicFallback`: existing Tier 1 (verification) + Tier 3 (heuristic) logic
-- `assessComplexity`: has programmatic verification → heuristic; short success → lightweight; else standard
-- `getResources`: optional codebase symlink for verification
-- `outputConfig`: `evaluation.json` (required)
-
-### Phase 3 Deliverables
-
-| File | Action | Description |
-|------|--------|-------------|
-| `src/workspace/templates/trajectory-analysis.ts` | NEW | Trajectory analysis template |
-| `src/workspace/templates/playbook-extraction.ts` | NEW | Playbook extraction template |
-| `src/workspace/templates/meta-reflection.ts` | NEW | Meta-reflection template |
-| `src/workspace/templates/usage-inference.ts` | NEW | Usage inference template |
-| `src/workspace/templates/solution-evaluation.ts` | NEW | Solution evaluation template |
-| `src/learning/pipeline.ts` | MODIFY | Route through runner when available |
-| `tests/workspace/templates/trajectory-analysis.test.ts` | NEW | Tests |
-| `tests/workspace/templates/playbook-extraction.test.ts` | NEW | Tests |
-| `tests/workspace/templates/meta-reflection.test.ts` | NEW | Tests |
-| `tests/workspace/templates/usage-inference.test.ts` | NEW | Tests |
-| `tests/workspace/templates/solution-evaluation.test.ts` | NEW | Tests |
-
----
-
-## Phase 4: Tuning & Robustness
-
-**Objective**: Add production-readiness features — concurrency control, monitoring, and cost optimization.
-
-### 4.1 — Concurrency Limiting
-
-Add a semaphore to `AgenticTaskRunner` that limits concurrent agent spawns to `config.maxConcurrentAgents`. Use a simple queue-based approach:
-
-```typescript
-class AgenticTaskRunner {
-  private activeCount = 0;
-  private queue: Array<() => void> = [];
-
-  private async acquireSlot(): Promise<void> { ... }
-  private releaseSlot(): void { ... }
-}
-```
-
-### 4.2 — Workspace Monitoring
-
-Add `AgenticTaskRunner.getActiveWorkspaces()` for debugging/monitoring. Include metrics: task type, start time, elapsed time, agent status.
-
-Add periodic stale workspace cleanup (driven by the runner config `staleWorkspaceMaxAgeMs`).
-
-### 4.3 — Cost Tracking
-
-Add per-template cost tracking to `AgenticTaskResult`:
-- Estimated token usage (from agent metrics)
-- Whether heuristic or agentic path was used
-- Complexity assessment
-
-Aggregate statistics available via `Atlas.getStats()`.
-
-### 4.4 — Complexity Threshold Calibration
-
-After accumulating real usage data, refine `assessComplexity` thresholds:
-- Track quality difference between heuristic and agentic paths
-- Identify cases where heuristic is sufficient (save cost)
-- Identify cases where agentic adds clear value (justify cost)
-
-This is data-driven tuning, not code changes per se.
-
----
-
-## Implementation Order & Dependencies
-
-```
-Phase 1.1 (types) ──────────────────────────────────────────┐
-Phase 1.2 (WorkspaceManager) ──────┐                        │
-Phase 1.3 (skill converter) ───────┤                        │
-                                   ▼                        ▼
-Phase 1.4 (AgenticTaskRunner) ──── needs 1.1, 1.2, 1.3 ───►│
-Phase 1.5 (exports) ──────────────────────────────────────── │
-Phase 1.6 (Atlas integration) ──── needs 1.4 ──────────────►│
-                                                             │
-Phase 2.1 (team types) ────────────────────────────────────┐ │
-Phase 2.2 (output schemas) ───────────────────────────────┐│ │
-Phase 2.3 (ingester) ──────────── needs 2.1 ─────────────►││ │
-Phase 2.4 (team analysis template) needs 1.4, 2.1-2.3 ───►│└►│
-Phase 2.5 (team extraction template) needs 1.4, 2.1-2.2 ──┘  │
-Phase 2.6 (team memory) ──────── needs 2.1 ──────────────────►│
-Phase 2.7 (team pipeline) ────── needs 2.3-2.6 ──────────────►│
-Phase 2.8 (Atlas team methods) ── needs 2.7 ──────────────────►│
-                                                               │
-Phase 3.1-3.5 (existing templates) needs Phase 1 ─────────────►
-Phase 4 (tuning) ──────────────── needs Phase 1-3 ─────────────►
-```
-
-**Recommended implementation sequence within each phase**:
-- Phase 1: 1.1 → 1.2 + 1.3 (parallel) → 1.4 → 1.5 + 1.6 (parallel)
-- Phase 2: 2.1 + 2.2 (parallel) → 2.3 + 2.6 (parallel) → 2.4 + 2.5 (parallel) → 2.7 → 2.8
-- Phase 3: 3.1 → 3.2 → 3.3 + 3.4 + 3.5 (parallel, independent)
-- Phase 4: 4.1 → 4.2 + 4.3 (parallel) → 4.4
-
----
-
-## Testing Strategy
-
-### Unit Tests
-
-Each new file gets a corresponding test file. Tests use:
-- **Vitest** (existing test framework)
-- **MockBackend** (existing `src/runtime/backends/mock.ts`) for agent spawning
-- **In-memory filesystem** or temp directories for workspace tests
-- **Zod schemas** for output validation
-
-### Integration Tests
-
-**File**: `tests/integration/workspace-e2e.test.ts` (new)
-
-End-to-end test that:
-1. Creates an `Atlas` instance with mock backend
-2. Runs a template through `AgenticTaskRunner`
-3. Verifies workspace was created, populated, and cleaned up
-4. Verifies output was collected and processed
-5. Verifies meta-learning captured the analysis agent's trajectory
-
-**File**: `tests/integration/team-learning-e2e.test.ts` (new)
-
-End-to-end test for team learning:
-1. Creates team trajectory input with multiple members
-2. Processes through `TeamLearningPipeline`
-3. Verifies team experience stored
-4. Accumulates multiple executions
-5. Triggers batch extraction
-6. Verifies team playbooks created
-
-### Test Approach
-
-- Tests for templates use mock templates with simple input/output types to test the runner independently from any specific analysis logic
-- Tests for the ingester use synthetic team trajectory data with known patterns
-- All tests are designed to run without network access or LLM calls
-
----
-
-## Risk Mitigation
-
-| Risk | Mitigation |
-|------|-----------|
-| Agent doesn't produce valid output | `collectWithRetry` + `outputConfig` validation + graceful fallback to heuristic |
-| Workspace cleanup fails | `finally` block + periodic stale pruning |
-| Cost explosion from excessive agentic analysis | `assessComplexity` gates most inputs to heuristic path |
-| Team types conflict with existing types | Team types are in separate files, no naming conflicts |
-| `AgentManager.spawn()` API mismatch | Runner wraps spawn, adapter layer isolates changes |
-| Circular dependency (runner → pipeline → runner) | Pipeline receives runner via `setTaskRunner()` setter, not constructor |
-
----
-
-## Open Questions for Later
-
-1. **Concurrency model**: Should the runner use a work-stealing queue or simple semaphore? (Start simple in Phase 4.1)
-2. **Workspace persistence**: Should successful analysis workspaces be archived for debugging? (Default: no, but `keepFailedWorkspaces` covers failure cases)
-3. **Cross-template knowledge**: Should playbooks from one analysis domain inform another? (The domain-scoped memory query handles this automatically)
-4. **Streaming output**: Should the runner support streaming partial results from long-running analysis agents? (Not in scope for initial implementation)