cognitive-core 0.1.0 → 0.1.2

package/tests/workspace/full-flow.test.ts

@@ -0,0 +1,839 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readFile, readdir, access } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { WorkspaceManager } from 'agent-workspace';
+import type { WorkspaceHandle } from 'agent-workspace';
+import { AgenticTaskRunner } from '../../src/workspace/runner.js';
+import { AgenticTaskOutputError } from '../../src/workspace/types.js';
+import type {
+  AgenticTaskTemplate,
+  AgentSkillSpec,
+  ResourceSpec,
+  ProcessingContext,
+} from '../../src/workspace/types.js';
+import type { AgenticTaskRunnerConfig } from '../../src/types/config.js';
+import { createMockBackend } from '../../src/runtime/backends/mock.js';
+import { AgentManager, createAgentManager } from '../../src/runtime/manager.js';
+import { MemorySystem, createMemorySystem } from '../../src/memory/system.js';
+import type { MemoryQueryResultV2 } from '../../src/memory/system.js';
+import { LearningPipeline, createLearningPipeline } from '../../src/learning/pipeline.js';
+import { createPlaybook } from '../../src/types/playbook.js';
+import { convertPlaybooksToSkills, generateSkillMd } from '../../src/workspace/skill-converter.js';
+
+// --------------------------------------------------------------------------
+// Test types
+// --------------------------------------------------------------------------
+interface AnalysisInput {
+  code: string;
+  language: string;
+  complexity?: 'simple' | 'complex';
+}
+
+interface AnalysisOutput {
+  issues: Array<{ line: number; message: string; severity: string }>;
+  summary: string;
+  score: number;
+}
+
+// --------------------------------------------------------------------------
+// Helpers
+// --------------------------------------------------------------------------
+
+function makePlaybook(name: string, domain: string) {
+  return createPlaybook({
+    name,
+    applicability: {
+      situations: [`Analyzing ${domain} code for issues`],
+      triggers: [`${domain}-analysis`, 'code-review'],
+      antiPatterns: ['Runtime profiling (not static analysis)'],
+      domains: [domain, 'analysis'],
+    },
+    guidance: {
+      strategy: `Parse the ${domain} code and identify issues by category.`,
+      tactics: [
+        'Check for type errors first',
+        'Look for unused variables',
+        'Identify potential null dereferences',
+      ],
+      steps: [
+        'Read the source file',
+        'Run static analysis',
+        'Categorize findings by severity',
+        'Produce output/result.json',
+      ],
+      codeExample: `analyze(source, { language: '${domain}' })`,
+    },
+    verification: {
+      successIndicators: ['Output file is valid JSON', 'All issues have line numbers'],
+      failureIndicators: ['Empty output', 'Invalid JSON'],
+    },
+    confidence: 0.9,
+    complexity: 'moderate',
+    evolution: {
+      version: '2.0.0',
+      createdFrom: ['traj-100', 'traj-101'],
+      failures: [],
+      refinements: [
+        {
+          context: 'monorepo',
+          addition: 'Resolve workspace paths before analysis',
+          source: 'failure' as const,
+          addedAt: new Date('2025-06-01'),
+        },
+      ],
+      successCount: 12,
+      failureCount: 1,
+    },
+  });
+}
+
+function createFullTemplate(options?: {
+  skills?: AgentSkillSpec[];
+  resources?: ResourceSpec[];
+  additionalKnowledge?: boolean;
+  outputData?: AnalysisOutput;
+  failOnCollect?: boolean;
+  failOnCollectOnce?: boolean;
+  processOutputSpy?: (output: AnalysisOutput, input: AnalysisInput, ctx: ProcessingContext) => Promise<void>;
+}): AgenticTaskTemplate<AnalysisInput, AnalysisOutput> {
+  const defaultOutput: AnalysisOutput = options?.outputData ?? {
+    issues: [
+      { line: 10, message: 'Unused variable "x"', severity: 'warning' },
+      { line: 25, message: 'Possible null dereference', severity: 'error' },
+    ],
+    summary: 'Found 2 issues: 1 error, 1 warning',
+    score: 0.7,
+  };
+
+  let collectAttempts = 0;
+
+  return {
+    taskType: 'code-analysis',
+    domain: 'static-analysis',
+    description: 'Analyze source code for issues and produce a structured report',
+
+    assessComplexity(input: AnalysisInput) {
+      if (input.complexity === 'simple') return 'heuristic';
+      if (input.complexity === 'complex') return 'thorough';
+      return 'standard';
+    },
+
+    agentType: 'mock',
+
+    heuristicFallback: async (input: AnalysisInput) => ({
+      issues: [],
+      summary: `Heuristic: ${input.language} code looks fine`,
+      score: 1.0,
+    }),
+
+    async prepareWorkspace(input: AnalysisInput, handle: WorkspaceHandle) {
+      await handle.writeRaw('input', `source.${input.language === 'typescript' ? 'ts' : 'py'}`, input.code);
+      await handle.writeJson('input', 'config.json', {
+        language: input.language,
+        rules: ['no-unused-vars', 'no-null-deref'],
+      });
+      // Pre-write output (simulating what a real agent would produce)
+      if (!options?.failOnCollect && !options?.failOnCollectOnce) {
+        await handle.writeJson('output', 'result.json', defaultOutput);
+      }
+      if (options?.failOnCollectOnce) {
+        // Write output so it's there for the retry
+        await handle.writeJson('output', 'result.json', defaultOutput);
+      }
+    },
+
+    buildTaskPrompt(input: AnalysisInput) {
+      return `Analyze the ${input.language} source code in input/ for issues. ` +
+        `Write a JSON report to output/result.json with fields: issues (array), summary (string), score (number).`;
+    },
+
+    getSkills(_input: AnalysisInput) {
+      return options?.skills ?? [];
+    },
+
+    getResources(_input: AnalysisInput) {
+      return options?.resources ?? [];
+    },
+
+    getAdditionalKnowledge: options?.additionalKnowledge
+      ? async (_input: AnalysisInput, memory: MemorySystem) => {
+          return memory.queryV2('code quality patterns', { domains: ['quality'] });
+        }
+      : undefined,
+
+    outputConfig: {
+      files: [
+        {
+          path: 'result.json',
+          format: 'json' as const,
+          required: true,
+          description: 'Analysis result with issues, summary, and score',
+        },
+      ],
+    },
+
+    async collectOutput(handle: WorkspaceHandle) {
+      collectAttempts++;
+      if (options?.failOnCollect) {
+        throw new Error('Output malformed');
+      }
+      if (options?.failOnCollectOnce && collectAttempts === 1) {
+        throw new Error('Transient parse error');
+      }
+      return handle.readJson<AnalysisOutput>('output', 'result.json');
+    },
+
+    async processOutput(
+      output: AnalysisOutput,
+      input: AnalysisInput,
+      context: ProcessingContext
+    ) {
+      if (options?.processOutputSpy) {
+        await options.processOutputSpy(output, input, context);
+      }
+    },
+
+    timeout: 60_000,
+    captureToolCalls: true,
+  };
+}
+
+// --------------------------------------------------------------------------
+// Test suite
+// --------------------------------------------------------------------------
+describe('Full Flow: AgenticTaskRunner end-to-end', () => {
+  let testBaseDir: string;
+  let workspaceManager: WorkspaceManager;
+  let agentManager: AgentManager;
+  let memory: MemorySystem;
+  let learning: LearningPipeline;
+  let runner: AgenticTaskRunner;
+  let config: AgenticTaskRunnerConfig;
+
+  beforeEach(async () => {
+    testBaseDir = join(tmpdir(), `atlas-full-flow-${randomUUID().slice(0, 8)}`);
+
+    workspaceManager = new WorkspaceManager({
+      baseDir: testBaseDir,
+      prefix: 'atlas-workspaces',
+    });
+    memory = createMemorySystem(join(testBaseDir, '.atlas'));
+    await memory.init();
+    learning = createLearningPipeline(memory);
+    agentManager = createAgentManager(memory);
+
+    const mockBackend = createMockBackend({
+      success: true,
+      result: 'Analysis complete — output written to output/result.json',
+      durationMs: 50,
+      toolCalls: [
+        { name: 'read_file', input: { path: 'input/source.ts' }, output: 'code content' },
+        { name: 'write_file', input: { path: 'output/result.json' }, output: 'written' },
+      ],
+    });
+    agentManager.registerBackend(mockBackend);
+
+    config = {
+      cleanupWorkspaces: false, // keep workspaces so tests can inspect
+      keepFailedWorkspaces: true,
+      maxConcurrentAgents: 3,
+      staleWorkspaceMaxAgeMs: 3600_000,
+    };
+
+    runner = new AgenticTaskRunner(
+      workspaceManager,
+      agentManager,
+      memory,
+      learning,
+      config,
+    );
+  });
+
+  afterEach(async () => {
+    const active = await workspaceManager.list();
+    for (const ws of active) {
+      await workspaceManager.cleanup(ws);
+    }
+    await memory.close();
+  });
+
+  // ========================================================================
+  // 1. Complete lifecycle — every step verified
+  // ========================================================================
+  describe('complete lifecycle', () => {
+    it('should execute all 12 runner steps from workspace creation through meta-learning', async () => {
+      const processOutputSpy = vi.fn();
+      const processTrajectory = vi.spyOn(learning, 'processTrajectory');
+      const queryV2 = vi.spyOn(memory, 'queryV2');
+
+      const playbook = makePlaybook('typescript-analysis', 'typescript');
+      const skills = convertPlaybooksToSkills([playbook]);
+
+      const template = createFullTemplate({
+        skills,
+        processOutputSpy,
+      });
+
+      const input: AnalysisInput = {
+        code: 'const x = 1;\nconst y: string | null = null;\ny.length;',
+        language: 'typescript',
+      };
+
+      const result = await runner.run(template, input);
+
+      // Result shape
+      expect(result.method).toBe('agentic');
+      expect(result.agentTrajectoryId).toBeDefined();
+      expect(result.metrics.totalTimeMs).toBeGreaterThan(0);
+      expect(result.metrics.toolCalls).toBeGreaterThanOrEqual(0);
+
+      // Output is correct
+      expect(result.output.issues).toHaveLength(2);
+      expect(result.output.summary).toContain('2 issues');
+      expect(result.output.score).toBe(0.7);
+
+      // Knowledge was queried (domain-scoped)
+      expect(queryV2).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({ domains: ['static-analysis'] }),
+      );
+
+      // processOutput was called with correct args
+      expect(processOutputSpy).toHaveBeenCalledTimes(1);
+      expect(processOutputSpy).toHaveBeenCalledWith(
+        result.output,
+        input,
+        expect.objectContaining({
+          memory: expect.anything(),
+          learningPipeline: expect.anything(),
+        }),
+      );
+
+      // Meta-learning processed the trajectory
+      expect(processTrajectory).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // ========================================================================
+  // 2. Skills injection through runner
+  // ========================================================================
+  describe('skills injection', () => {
+    it('should write playbook-converted skills as SKILL.md files into workspace', async () => {
+      let capturedHandle: WorkspaceHandle | null = null;
+
+      const playbooks = [
+        makePlaybook('typescript-analysis', 'typescript'),
+        makePlaybook('null-safety-check', 'safety'),
+      ];
+      const skills = convertPlaybooksToSkills(playbooks);
+
+      const template = createFullTemplate({ skills });
+      const origPrepare = template.prepareWorkspace.bind(template);
+      template.prepareWorkspace = async (input, handle) => {
+        capturedHandle = handle;
+        await origPrepare(input, handle);
+      };
+
+      await runner.run(template, { code: 'x', language: 'typescript' });
+
+      expect(capturedHandle).not.toBeNull();
+      const skillsDir = capturedHandle!.dir('skills');
+
+      // Both skills should have SKILL.md files
+      const entries = await readdir(skillsDir);
+      expect(entries).toContain('typescript-analysis');
+      expect(entries).toContain('null-safety-check');
+
+      // Content should be valid SKILL.md
+      const tsSkillMd = await readFile(
+        join(skillsDir, 'typescript-analysis', 'SKILL.md'),
+        'utf-8',
+      );
+      expect(tsSkillMd).toContain('# Typescript Analysis');
+      expect(tsSkillMd).toContain('## When to Use');
+      expect(tsSkillMd).toContain('## Strategy');
+      expect(tsSkillMd).toContain('Confidence: 90%');
+
+      const safetySkillMd = await readFile(
+        join(skillsDir, 'null-safety-check', 'SKILL.md'),
+        'utf-8',
+      );
+      expect(safetySkillMd).toContain('# Null Safety Check');
+    });
+  });
+
+  // ========================================================================
+  // 3. Resources injection through runner
+  // ========================================================================
+  describe('resources injection', () => {
+    it('should populate file resources into workspace resources/ directory', async () => {
+      let capturedHandle: WorkspaceHandle | null = null;
+
+      const resources: ResourceSpec[] = [
+        {
+          path: 'rules/no-unused-vars.md',
+          type: 'file',
+          source: '# No Unused Variables\n\nFlag variables that are declared but never read.',
+          description: 'Linting rule documentation',
+        },
+        {
+          path: 'rules/no-null-deref.md',
+          type: 'file',
+          source: '# No Null Dereference\n\nFlag accesses on potentially null values.',
+          description: 'Null safety rule documentation',
+        },
+      ];
+
+      const template = createFullTemplate({ resources });
+      const origPrepare = template.prepareWorkspace.bind(template);
+      template.prepareWorkspace = async (input, handle) => {
+        capturedHandle = handle;
+        await origPrepare(input, handle);
+      };
+
+      await runner.run(template, { code: 'x', language: 'typescript' });
+
+      expect(capturedHandle).not.toBeNull();
+
+      const rule1 = await readFile(
+        join(capturedHandle!.resourcesDir, 'rules', 'no-unused-vars.md'),
+        'utf-8',
+      );
+      expect(rule1).toContain('No Unused Variables');
+
+      const rule2 = await readFile(
+        join(capturedHandle!.resourcesDir, 'rules', 'no-null-deref.md'),
+        'utf-8',
+      );
+      expect(rule2).toContain('No Null Dereference');
+    });
+  });
+
+  // ========================================================================
+  // 4. Knowledge injection and merging
+  // ========================================================================
+  describe('knowledge injection with additional queries', () => {
+    it('should merge domain knowledge with additional knowledge queries', async () => {
+      const queryV2 = vi.spyOn(memory, 'queryV2');
+
+      const template = createFullTemplate({ additionalKnowledge: true });
+
+      await runner.run(template, { code: 'x', language: 'typescript' });
+
+      // Should have been called twice: once for domain, once for additional
+      expect(queryV2).toHaveBeenCalledTimes(2);
+
+      // First call: domain-scoped
+      expect(queryV2).toHaveBeenCalledWith(
+        expect.stringContaining('Analyze source code'),
+        expect.objectContaining({ domains: ['static-analysis'] }),
+      );
+
+      // Second call: additional knowledge
+      expect(queryV2).toHaveBeenCalledWith(
+        'code quality patterns',
+        expect.objectContaining({ domains: ['quality'] }),
+      );
+    });
+  });
+
+  // ========================================================================
+  // 5. Heuristic fallback for simple inputs
+  // ========================================================================
+  describe('heuristic fallback', () => {
+    it('should bypass workspace entirely for simple inputs', async () => {
+      const processTrajectory = vi.spyOn(learning, 'processTrajectory');
+
+      const template = createFullTemplate();
+      const result = await runner.run(template, {
+        code: 'console.log("hi")',
+        language: 'typescript',
+        complexity: 'simple',
+      });
+
+      expect(result.method).toBe('heuristic');
+      expect(result.output.score).toBe(1.0);
+      expect(result.output.summary).toContain('Heuristic');
+      expect(result.metrics.tokensUsed).toBe(0);
+      expect(result.metrics.toolCalls).toBe(0);
+      expect(result.agentTrajectoryId).toBeUndefined();
+
+      // No workspace activity, no meta-learning
+      expect(processTrajectory).not.toHaveBeenCalled();
+      const active = await workspaceManager.list();
+      expect(active).toHaveLength(0);
+    });
+  });
+
+  // ========================================================================
+  // 6. Thorough complexity doubles timeout
+  // ========================================================================
+  describe('thorough complexity', () => {
+    it('should double the timeout for complex inputs and still complete', async () => {
+      let capturedTimeout = 0;
+      const origSpawn = agentManager.spawn.bind(agentManager);
+      agentManager.spawn = async (spawnConfig) => {
+        capturedTimeout = spawnConfig.timeout ?? 0;
+        return origSpawn(spawnConfig);
+      };
+
+      const template = createFullTemplate();
+
+      const result = await runner.run(template, {
+        code: 'complex code...',
+        language: 'typescript',
+        complexity: 'complex',
+      });
+
+      expect(result.method).toBe('agentic');
+      expect(capturedTimeout).toBe(120_000); // 60_000 * 2
+    });
+  });
+
+  // ========================================================================
+  // 7. Output validation and collection with retry
+  // ========================================================================
+  describe('output collection retry', () => {
+    it('should retry collectOutput on transient failure and succeed', async () => {
+      const template = createFullTemplate({ failOnCollectOnce: true });
+
+      const result = await runner.run(template, {
+        code: 'x',
+        language: 'typescript',
+      });
+
+      // Should succeed on retry
+      expect(result.method).toBe('agentic');
+      expect(result.output.issues).toHaveLength(2);
+    });
+
+    it('should throw AgenticTaskOutputError when collection permanently fails', async () => {
+      const template = createFullTemplate({ failOnCollect: true });
+
+      await expect(
+        runner.run(template, { code: 'x', language: 'typescript' }),
+      ).rejects.toThrow(AgenticTaskOutputError);
+    });
+  });
+
+  // ========================================================================
+  // 8. processOutput receives correct context
+  // ========================================================================
+  describe('processOutput integration', () => {
+    it('should pass memory and learningPipeline in ProcessingContext', async () => {
+      let receivedContext: ProcessingContext | null = null;
+
+      const template = createFullTemplate({
+        processOutputSpy: async (_output, _input, ctx) => {
+          receivedContext = ctx;
+        },
+      });
+
+      await runner.run(template, { code: 'x', language: 'typescript' });
+
+      expect(receivedContext).not.toBeNull();
+      expect(receivedContext!.memory).toBe(memory);
+      expect(receivedContext!.learningPipeline).toBe(learning);
+    });
+
+    it('should allow processOutput to store results back into memory', async () => {
+      const template = createFullTemplate({
+        processOutputSpy: async (output, input, ctx) => {
+          await ctx.memory.experiences.add({
+            id: `analysis-${randomUUID().slice(0, 8)}`,
+            taskInput: `Analyze ${input.language} code`,
+            solutionOutput: output.summary,
+            feedback: output.score > 0.5 ? 'acceptable' : 'needs-improvement',
+            success: output.score > 0.5,
+            domain: 'static-analysis',
+            trajectoryId: 'test',
+            usageCount: 0,
+            createdAt: new Date(),
+            metadata: { issueCount: output.issues.length },
+          });
+        },
+      });
+
+      await runner.run(template, { code: 'x', language: 'typescript' });
+
+      // Verify experience was stored
+      const results = await memory.queryV2('static analysis', {
+        domains: ['static-analysis'],
+      });
+      expect(results.experiences.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  // ========================================================================
+  // 9. Workspace filesystem structure
+  // ========================================================================
+  describe('workspace filesystem', () => {
+    it('should produce correct directory structure with all populated dirs', async () => {
+      let capturedHandle: WorkspaceHandle | null = null;
+
+      const playbooks = [makePlaybook('ts-analysis', 'typescript')];
+      const skills = convertPlaybooksToSkills(playbooks);
+      const resources: ResourceSpec[] = [
+        { path: 'docs/guide.md', type: 'file', source: '# Guide\n\nAnalysis guide.' },
+      ];
+
+      const template = createFullTemplate({ skills, resources });
+      const origPrepare = template.prepareWorkspace.bind(template);
+      template.prepareWorkspace = async (input, handle) => {
+        capturedHandle = handle;
+        await origPrepare(input, handle);
+      };
+
+      await runner.run(template, { code: 'const a = 1;', language: 'typescript' });
+
+      expect(capturedHandle).not.toBeNull();
+      const wsPath = capturedHandle!.path;
+
+      // All expected directories exist
+      for (const dir of ['input', 'output', 'resources', 'scratch', 'skills']) {
+        await expect(access(join(wsPath, dir))).resolves.toBeUndefined();
+      }
+
+      // Input files
+      const inputJson = JSON.parse(
+        await readFile(join(wsPath, 'input', 'config.json'), 'utf-8'),
+      );
+      expect(inputJson.language).toBe('typescript');
+
+      const sourceContent = await readFile(join(wsPath, 'input', 'source.ts'), 'utf-8');
+      expect(sourceContent).toBe('const a = 1;');
+
+      // Output files
+      const outputJson = JSON.parse(
+        await readFile(join(wsPath, 'output', 'result.json'), 'utf-8'),
+      );
+      expect(outputJson.issues).toHaveLength(2);
+
+      // Skills
+      await expect(
+        access(join(wsPath, 'skills', 'ts-analysis', 'SKILL.md')),
+      ).resolves.toBeUndefined();
+
+      // Resources
+      const guide = await readFile(join(wsPath, 'resources', 'docs', 'guide.md'), 'utf-8');
+      expect(guide).toContain('Analysis guide');
+    });
+  });
+
+  // ========================================================================
+  // 10. Workspace cleanup on success
+  // ========================================================================
+  describe('workspace cleanup', () => {
+    it('should cleanup workspace on success when cleanupWorkspaces is true', async () => {
+      const cleanupRunner = new AgenticTaskRunner(
+        workspaceManager,
+        agentManager,
+        memory,
+        learning,
+        { ...config, cleanupWorkspaces: true },
+      );
+
+      let capturedPath = '';
+      const template = createFullTemplate();
+      const origPrepare = template.prepareWorkspace.bind(template);
+      template.prepareWorkspace = async (input, handle) => {
+        capturedPath = handle.path;
+        await origPrepare(input, handle);
+      };
+
+      await cleanupRunner.run(template, { code: 'x', language: 'typescript' });
+
+      await expect(access(capturedPath)).rejects.toThrow();
+    });
+
+    it('should keep failed workspace when keepFailedWorkspaces is true', async () => {
+      const template = createFullTemplate({ failOnCollect: true });
+
+      try {
+        await runner.run(template, { code: 'x', language: 'typescript' });
+      } catch {
+        // Expected
+      }
+
+      const active = await workspaceManager.list();
+      expect(active.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  // ========================================================================
+  // 11. Agent spawn receives correct configuration
+  // ========================================================================
+  describe('agent spawn configuration', () => {
+    it('should pass workspace path as cwd, task prompt, and agent type to agent', async () => {
+      let capturedCwd = '';
+      let capturedTask: { description?: string; domain?: string } = {};
+      let capturedAgentType = '';
+
+      const origSpawn = agentManager.spawn.bind(agentManager);
+      agentManager.spawn = async (spawnConfig) => {
+        capturedCwd = spawnConfig.cwd ?? '';
+        capturedTask = { description: spawnConfig.task.description, domain: spawnConfig.task.domain };
+        capturedAgentType = spawnConfig.agentType;
+        return origSpawn(spawnConfig);
+      };
+
+      const template = createFullTemplate();
+
+      await runner.run(template, { code: 'x', language: 'typescript' });
+
+      expect(capturedCwd).toContain('atlas-workspaces');
+      expect(capturedTask.description).toContain('Analyze the typescript source code');
+      expect(capturedTask.domain).toBe('static-analysis');
+      expect(capturedAgentType).toBe('mock');
+    });
+
+    it('should inject knowledge into the agent spawn config', async () => {
+      let capturedKnowledge: MemoryQueryResultV2 | undefined;
+
+      const origSpawn = agentManager.spawn.bind(agentManager);
+      agentManager.spawn = async (spawnConfig) => {
+        capturedKnowledge = spawnConfig.injectedKnowledge as MemoryQueryResultV2 | undefined;
+        return origSpawn(spawnConfig);
+      };
+
+      const template = createFullTemplate();
+      await runner.run(template, { code: 'x', language: 'typescript' });
+
+      expect(capturedKnowledge).toBeDefined();
+      expect(capturedKnowledge).toHaveProperty('playbooks');
+      expect(capturedKnowledge).toHaveProperty('experiences');
+    });
+  });
+
+  // ========================================================================
+  // 12. Playbook → Skill → Workspace round-trip
+  // ========================================================================
+  describe('playbook to workspace round-trip', () => {
+    it('should convert playbook to skill, write to workspace, and verify content integrity', async () => {
+      let capturedHandle: WorkspaceHandle | null = null;
+
+      const playbook = makePlaybook('null-safety-check', 'typescript');
+      const skills = convertPlaybooksToSkills([playbook]);
+
+      expect(skills).toHaveLength(1);
+      expect(skills[0].name).toBe('null-safety-check');
+      expect(skills[0].source).toBe('playbook-conversion');
+
+      const template = createFullTemplate({ skills });
+      const origPrepare = template.prepareWorkspace.bind(template);
+      template.prepareWorkspace = async (input, handle) => {
+        capturedHandle = handle;
+        await origPrepare(input, handle);
+      };
+
+      await runner.run(template, { code: 'x', language: 'typescript' });
+
+      // Read the SKILL.md that was written to workspace
+      const skillMd = await readFile(
+        join(capturedHandle!.dir('skills'), 'null-safety-check', 'SKILL.md'),
+        'utf-8',
+      );
+
+      // Verify all key sections from the playbook survived the conversion
+      expect(skillMd).toContain('# Null Safety Check');
+      expect(skillMd).toContain('## When to Use');
+      expect(skillMd).toContain('Analyzing typescript code for issues');
+      expect(skillMd).toContain('## Triggers');
+      expect(skillMd).toContain('typescript-analysis');
+      expect(skillMd).toContain('## When NOT to Use');
+      expect(skillMd).toContain('Runtime profiling');
+      expect(skillMd).toContain('## Strategy');
+      expect(skillMd).toContain('Parse the typescript code');
+      expect(skillMd).toContain('## Tactics');
+      expect(skillMd).toContain('Check for type errors first');
+      expect(skillMd).toContain('## Steps');
+      expect(skillMd).toContain('1. Read the source file');
+      expect(skillMd).toContain('## Example');
+      expect(skillMd).toContain("analyze(source, { language: 'typescript' })");
+      expect(skillMd).toContain('## Verification');
+      expect(skillMd).toContain('Output file is valid JSON');
+      expect(skillMd).toContain('## Context Notes');
+      expect(skillMd).toContain('monorepo');
+      expect(skillMd).toContain('Confidence: 90%');
+    });
+  });
+
+  // ========================================================================
+  // 13. Multiple sequential runs don't interfere
+  // ========================================================================
+  describe('sequential run isolation', () => {
+    it('should produce independent results across multiple runs', async () => {
+      const template1 = createFullTemplate({
+        outputData: {
+          issues: [{ line: 1, message: 'Issue A', severity: 'error' }],
+          summary: 'Run 1',
+          score: 0.5,
+        },
+      });
+
+      const template2 = createFullTemplate({
+        outputData: {
+          issues: [
+            { line: 2, message: 'Issue B', severity: 'warning' },
+            { line: 3, message: 'Issue C', severity: 'info' },
+          ],
+          summary: 'Run 2',
+          score: 0.9,
+        },
+      });
+
+      const result1 = await runner.run(template1, { code: 'a', language: 'typescript' });
+      const result2 = await runner.run(template2, { code: 'b', language: 'typescript' });
+
+      expect(result1.output.summary).toBe('Run 1');
+      expect(result1.output.issues).toHaveLength(1);
+      expect(result1.output.score).toBe(0.5);
+
+      expect(result2.output.summary).toBe('Run 2');
+      expect(result2.output.issues).toHaveLength(2);
+      expect(result2.output.score).toBe(0.9);
+
+      // Both should have unique trajectory IDs
+      expect(result1.agentTrajectoryId).not.toBe(result2.agentTrajectoryId);
+    });
+  });
+
+  // ========================================================================
+  // 14. Error propagation and workspace retention
+  // ========================================================================
+  describe('error propagation', () => {
+    it('should include taskType in AgenticTaskOutputError', async () => {
+      const template = createFullTemplate({ failOnCollect: true });
+
+      try {
+        await runner.run(template, { code: 'x', language: 'typescript' });
+        expect.fail('Should have thrown');
+      } catch (error) {
+        expect(error).toBeInstanceOf(AgenticTaskOutputError);
+        expect((error as AgenticTaskOutputError).taskType).toBe('code-analysis');
+        expect((error as AgenticTaskOutputError).message).toContain('code-analysis');
+      }
+    });
+  });
+
+  // ========================================================================
+  // 15. Meta-learning receives the correct trajectory
+  // ========================================================================
+  describe('meta-learning integration', () => {
+    it('should feed the analysis agent trajectory to the learning pipeline', async () => {
+      const processTrajectory = vi.spyOn(learning, 'processTrajectory');
+
+      const template = createFullTemplate();
+      const result = await runner.run(template, { code: 'x', language: 'typescript' });
+
+      expect(processTrajectory).toHaveBeenCalledTimes(1);
+
+      const trajectory = processTrajectory.mock.calls[0][0];
+      expect(trajectory.id).toBe(result.agentTrajectoryId);
+      expect(trajectory.task.domain).toBe('static-analysis');
+      expect(trajectory.task.description).toContain('Analyze the typescript source code');
+    });
+  });
+});