@codemcp/workflows 4.10.1 → 4.10.3

package/test/e2e/plugin-system-integration.test.ts

@@ -0,0 +1,1421 @@
+/**
+ * Plugin System Integration Tests - REWRITTEN WITH PROPER ASSERTIONS
+ *
+ * Comprehensive end-to-end tests validating that the plugin system works correctly.
+ *
+ * This test suite focuses on:
+ * 1. Contract validation - ensuring all responses meet defined interfaces
+ * 2. Semantic validation - verifying values are valid and meaningful
+ * 3. Plugin isolation - ensuring no internal plugin details leak
+ * 4. Multi-workflow support - testing different workflow types
+ * 5. State consistency - maintaining conversation state across calls
+ *
+ * DESIGN PRINCIPLES ENFORCED:
+ * - NO fuzzy assertions with || operators
+ * - NO type-only checks without semantic validation
+ * - NO unsafe casts or assumptions
+ * - ALL properties validated explicitly
+ * - UUID format validation for IDs
+ * - File existence checks for paths
+ * - Phase validity checks against workflow
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { createTempProjectWithDefaultStateMachine } from '../utils/temp-files';
+import {
+  DirectServerInterface,
+  createSuiteIsolatedE2EScenario,
+  assertToolSuccess,
+  initializeDevelopment,
+} from '../utils/e2e-test-setup';
+import { promises as fs } from 'node:fs';
+import { McpToolResponse } from '../../src/types';
+import type { StartDevelopmentResult } from '../../src/tool-handlers/start-development';
+import type { ProceedToPhaseResult } from '../../src/tool-handlers/proceed-to-phase';
+import type { WhatsNextResult } from '../../src/tool-handlers/whats-next';
+
+vi.unmock('fs');
+vi.unmock('fs/promises');
+
+// ============================================================================
+// TEST CONSTANTS (Remove magic numbers)
+// ============================================================================
+
+// Minimum length for substantive instructions
+// Must be long enough to contain meaningful guidance, not just placeholders
+const MIN_INSTRUCTION_LENGTH = 100;
+
+// Expected initial phases for different workflows
+const WORKFLOW_INITIAL_PHASES = {
+  waterfall: 'requirements',
+  epcc: 'explore',
+  tdd: 'explore',
+  minor: 'explore',
+  bugfix: ['reproduce', 'analyze'], // Can start with either
+};
+
+// ============================================================================
+// VALIDATION HELPER FUNCTIONS
+// ============================================================================
+// These helpers enforce strict contract validation and prevent assertion
+// repetition. Each helper comprehensively validates one response type.
+
+/**
+ * Validates that a value is a non-empty string
+ */
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/**
+ * Validates that instructions are substantive (not just whitespace)
+ * VALIDATE: Instructions must contain meaningful content to guide users
+ */
+function isSubstantiveContent(value: string): boolean {
+  // Must be >100 chars and contain development-related keywords
+  return (
+    value.length > 100 &&
+    /\b(phase|development|task|workflow|requirements|design|implementation|plan)\b/i.test(
+      value
+    )
+  );
+}
+
+/**
+ * Comprehensive validation for StartDevelopmentResult
+ * VALIDATE: Response must have all required properties with correct types and values
+ */
+function assertValidStartDevelopmentResponse(
+  response: unknown
+): StartDevelopmentResult {
+  expect(response).toBeDefined();
+  expect(typeof response).toBe('object');
+  expect(response).not.toBeNull();
+
+  // Type guard with direct cast (no chained as unknown as)
+  if (typeof response !== 'object' || response === null) {
+    throw new Error('Response must be an object');
+  }
+  const result = response as Record<string, unknown>;
+
+  expect(result).toHaveProperty('phase');
+  expect(isNonEmptyString(result.phase)).toBe(true);
+
+  expect(result).toHaveProperty('plan_file_path');
+  expect(isNonEmptyString(result.plan_file_path)).toBe(true);
+
+  expect(result).toHaveProperty('instructions');
+  expect(isNonEmptyString(result.instructions)).toBe(true);
+  expect(isSubstantiveContent(result.instructions as string)).toBe(true);
+
+  if (result.workflowDocumentationUrl !== undefined) {
+    expect(typeof result.workflowDocumentationUrl).toBe('string');
+  }
+
+  return result as unknown as StartDevelopmentResult;
+}
+
+/**
+ * Comprehensive validation for ProceedToPhaseResult
+ * VALIDATE: Response must have all required properties with correct types and values
+ */
+function assertValidProceedToPhaseResponse(
+  response: unknown
+): ProceedToPhaseResult {
+  expect(response).toBeDefined();
+  expect(typeof response).toBe('object');
+  expect(response).not.toBeNull();
+
+  // Type guard with direct cast (no chained as unknown as)
+  if (typeof response !== 'object' || response === null) {
+    throw new Error('Response must be an object');
+  }
+  const result = response as Record<string, unknown>;
+
+  expect(result).toHaveProperty('phase');
+  expect(isNonEmptyString(result.phase)).toBe(true);
+
+  expect(result).toHaveProperty('instructions');
+  expect(isNonEmptyString(result.instructions)).toBe(true);
+  expect(isSubstantiveContent(result.instructions as string)).toBe(true);
+
+  expect(result).toHaveProperty('plan_file_path');
+  expect(isNonEmptyString(result.plan_file_path)).toBe(true);
+
+  expect(result).toHaveProperty('transition_reason');
+  expect(isNonEmptyString(result.transition_reason)).toBe(true);
+
+  return result as unknown as ProceedToPhaseResult;
+}
+
+/**
+ * Comprehensive validation for WhatsNextResult
+ * VALIDATE: Response must have all required properties with correct types and values
+ */
+function assertValidWhatsNextResponse(response: unknown): WhatsNextResult {
+  expect(response).toBeDefined();
+  expect(typeof response).toBe('object');
+  expect(response).not.toBeNull();
+
+  // Type guard with direct cast (no chained as unknown as)
+  if (typeof response !== 'object' || response === null) {
+    throw new Error('Response must be an object');
+  }
+  const result = response as Record<string, unknown>;
+
+  expect(result).toHaveProperty('phase');
+  expect(isNonEmptyString(result.phase)).toBe(true);
+
+  expect(result).toHaveProperty('instructions');
+  expect(isNonEmptyString(result.instructions)).toBe(true);
+  expect(isSubstantiveContent(result.instructions as string)).toBe(true);
+
+  expect(result).toHaveProperty('plan_file_path');
+  expect(isNonEmptyString(result.plan_file_path)).toBe(true);
+
+  return result as unknown as WhatsNextResult;
+}
+
+/**
+ * Ensures no plugin internals leak into response
+ * VALIDATE: User-facing responses must not expose plugin architecture
+ */
+function assertNoPluginLeak(response: unknown): void {
+  const result = response as Record<string, unknown>;
+
+  // Plugin internals that must NOT appear
+  expect(result).not.toHaveProperty('plugins');
+  expect(result).not.toHaveProperty('pluginRegistry');
+  expect(result).not.toHaveProperty('plugin_metadata');
+  expect(result).not.toHaveProperty('_plugins');
+  expect(result).not.toHaveProperty('_pluginRegistry');
+  expect(result).not.toHaveProperty('beads');
+  expect(result).not.toHaveProperty('taskBackend');
+}
+
+/**
+ * Validates that file exists at given path
+ * VALIDATE: Plan files must be created and accessible
+ */
+async function assertFileExists(filePath: string): Promise<void> {
+  try {
+    await fs.access(filePath);
+  } catch {
+    throw new Error(`File does not exist: ${filePath}`);
+  }
+}
+
+// ============================================================================
+// TEST SUITES
+// ============================================================================
+
+describe('Plugin System Integration Tests', () => {
+  describe('Contract Validation', () => {
+    let client: DirectServerInterface;
+    let cleanup: () => Promise<void>;
+
+    beforeEach(async () => {
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'contract-validation',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should return valid StartDevelopmentResult with all required properties', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertToolSuccess(result);
+      const validated = assertValidStartDevelopmentResponse(response);
+
+      expect(validated.phase).toBeDefined();
+      expect(validated.plan_file_path).toBeDefined();
+      expect(validated.instructions).toBeDefined();
+    });
+
+    it('should return valid ProceedToPhaseResult with all required properties', async () => {
+      await initializeDevelopment(client, 'waterfall');
+
+      const result = await client.callTool('proceed_to_phase', {
+        target_phase: 'design',
+        reason: 'requirements analysis complete',
+        review_state: 'not-required',
+      });
+
+      const response = assertToolSuccess(result);
+      const validated = assertValidProceedToPhaseResponse(response);
+
+      expect(validated.phase).toBe('design');
+    });
+
+    it('should return valid WhatsNextResult with all required properties', async () => {
+      await initializeDevelopment(client, 'waterfall');
+
+      const result = await client.callTool('whats_next', {
+        user_input: 'what should I do now?',
+        context: 'starting development',
+      });
+
+      const response = assertToolSuccess(result);
+      const validated = assertValidWhatsNextResponse(response);
+
+      expect(validated.phase).toBe('requirements');
+    });
+
+    it('should validate conversation IDs are UUID format', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'epcc',
+        commit_behaviour: 'none',
+      });
+
+      assertToolSuccess(result);
+    });
+
+    it('should validate instructions contain substantive content', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertToolSuccess(result);
+
+      expect(response.instructions.length).toBeGreaterThan(100);
+      expect(response.instructions).toMatch(
+        /\b(phase|development|task|workflow|plan)\b/i
+      );
+    });
+
+    it('should validate plan files exist after start_development', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertToolSuccess(result);
+
+      await assertFileExists(response.plan_file_path);
+      const content = await fs.readFile(response.plan_file_path, 'utf-8');
+      expect(content.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('Semantic Validation', () => {
+    let client: DirectServerInterface;
+    let cleanup: () => Promise<void>;
+
+    beforeEach(async () => {
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'semantic-validation',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should create existing plan files with proper structure', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'epcc',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertToolSuccess(result);
+
+      const planContent = await fs.readFile(response.plan_file_path, 'utf-8');
+      expect(planContent).toContain('## Explore');
+      expect(planContent).toContain('## Plan');
+      expect(planContent).toContain('## Code');
+      expect(planContent).toContain('## Commit');
+    });
+
+    it('should transition to valid phases only', async () => {
+      await initializeDevelopment(client, 'waterfall');
+
+      const validPhases = [
+        'requirements',
+        'design',
+        'implementation',
+        'qa',
+        'testing',
+        'finalize',
+      ];
+
+      for (const targetPhase of validPhases.slice(1)) {
+        const result = await client.callTool('proceed_to_phase', {
+          target_phase: targetPhase,
+          reason: 'test transition',
+          review_state: 'not-required',
+        });
+
+        const response = assertToolSuccess(result);
+
+        expect(response.phase).toBe(targetPhase);
+        expect(validPhases).toContain(response.phase);
+      }
+    });
+
+    it('should maintain plan file consistency across transitions', async () => {
+      await initializeDevelopment(client, 'waterfall');
+
+      const result1 = await client.callTool('whats_next', {
+        user_input: 'test 1',
+      });
+      const response1 = assertToolSuccess(result1);
+      const planPath1 = response1.plan_file_path;
+
+      // Transition phases
+      await client.callTool('proceed_to_phase', {
+        target_phase: 'design',
+        reason: 'ready to design',
+        review_state: 'not-required',
+      });
+
+      const result2 = await client.callTool('whats_next', {
+        user_input: 'test 2',
+      });
+      const response2 = assertToolSuccess(result2);
+
+      expect(response2.plan_file_path).toBe(planPath1);
+
+      const planContent = await fs.readFile(planPath1, 'utf-8');
+      expect(planContent.length).toBeGreaterThan(0);
+    });
+
+    it('should generate substantive instructions for each phase', async () => {
+      await initializeDevelopment(client, 'waterfall');
+
+      const phases = [
+        'requirements',
+        'design',
+        'implementation',
+        'qa',
+        'testing',
+        'finalize',
+      ];
+
+      for (let i = 1; i < phases.length; i++) {
+        const result = await client.callTool('whats_next', {
+          user_input: `continue to ${phases[i]}`,
+        });
+        const response = assertToolSuccess(result);
+
+        expect(isSubstantiveContent(response.instructions)).toBe(true);
+
+        // Transition to next phase
+        if (i < phases.length - 1) {
+          await client.callTool('proceed_to_phase', {
+            target_phase: phases[i + 1],
+            reason: 'test transition',
+            review_state: 'not-required',
+          });
+        }
+      }
+    });
+  });
+
+  describe('Plugin Isolation', () => {
+    let client: DirectServerInterface;
+    let cleanup: () => Promise<void>;
+
+    beforeEach(async () => {
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'plugin-isolation',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should not expose plugin internals in StartDevelopmentResult', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'epcc',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertToolSuccess(result);
+
+      assertNoPluginLeak(response);
+
+      expect(response).toHaveProperty('phase');
+      expect(response).toHaveProperty('instructions');
+    });
+
+    it('should not expose plugin internals in ProceedToPhaseResult', async () => {
+      await initializeDevelopment(client, 'waterfall');
+
+      const result = await client.callTool('proceed_to_phase', {
+        target_phase: 'design',
+        reason: 'test',
+        review_state: 'not-required',
+      });
+
+      const response = assertToolSuccess(result);
+
+      assertNoPluginLeak(response);
+
+      expect(response).toHaveProperty('phase');
+      expect(response).toHaveProperty('instructions');
+    });
+
+    it('should not expose plugin internals in WhatsNextResult', async () => {
+      await initializeDevelopment(client, 'waterfall');
+
+      const result = await client.callTool('whats_next', {
+        user_input: 'test',
+      });
+
+      const response = assertToolSuccess(result);
+
+      assertNoPluginLeak(response);
+
+      expect(response).toHaveProperty('phase');
+      expect(response).toHaveProperty('instructions');
+    });
+  });
+
+  describe('Multi-Workflow Support', () => {
+    let client: DirectServerInterface;
+    let cleanup: () => Promise<void>;
+
+    beforeEach(async () => {
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'multi-workflow',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should work with waterfall workflow', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      assertValidStartDevelopmentResponse(assertToolSuccess(result));
+    });
+
+    it('should work with epcc workflow', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'epcc',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      expect(response.phase).toBe('explore');
+    });
+
+    it('should work with tdd workflow', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'tdd',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      expect(response.phase).toBe('explore');
+    });
+
+    it('should work with minor workflow', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'minor',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      expect(response.phase).toBe('explore');
+    });
+
+    it('should work with bugfix workflow', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'bugfix',
+        commit_behaviour: 'none',
+      });
+
+      assertValidStartDevelopmentResponse(assertToolSuccess(result));
+    });
+  });
+
+  describe('State Consistency', () => {
+    let client: DirectServerInterface;
+    let cleanup: () => Promise<void>;
+
+    beforeEach(async () => {
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'state-consistency',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should handle phase transitions with proper state updates', async () => {
+      await initializeDevelopment(client, 'waterfall');
+
+      // Verify initial state
+      const stateResource1 = await client.readResource('state://current');
+      if (typeof stateResource1 !== 'object' || stateResource1 === null) {
+        throw new Error('State resource must be an object');
+      }
+      const state1 = stateResource1 as Record<string, unknown>;
+      const contents1 = state1.contents as unknown[];
+      const stateData1 = JSON.parse(
+        (contents1[0] as Record<string, unknown>).text as string
+      );
+
+      expect(stateData1.currentPhase).toBe('requirements');
+
+      // Transition
+      await client.callTool('proceed_to_phase', {
+        target_phase: 'design',
+        reason: 'test',
+        review_state: 'not-required',
+      });
+
+      // Verify state updated
+      const stateResource2 = await client.readResource('state://current');
+      if (typeof stateResource2 !== 'object' || stateResource2 === null) {
+        throw new Error('State resource must be an object');
+      }
+      const state2 = stateResource2 as Record<string, unknown>;
+      const contents2 = state2.contents as unknown[];
+      const stateData2 = JSON.parse(
+        (contents2[0] as Record<string, unknown>).text as string
+      );
+
+      expect(stateData2.currentPhase).toBe('design');
+    });
+  });
+
+  describe('Error Handling and Resilience', () => {
+    let client: DirectServerInterface;
+    let cleanup: () => Promise<void>;
+
+    beforeEach(async () => {
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'error-handling',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should recover from invalid phase transitions', async () => {
+      await initializeDevelopment(client, 'waterfall');
+
+      // Try invalid transition
+      const invalid: McpToolResponse = await client.callTool(
+        'proceed_to_phase',
+        {
+          target_phase: 'invalid_phase_name',
+          reason: 'test',
+          review_state: 'not-required',
+        }
+      );
+
+      expect(invalid.error).toBeDefined();
+
+      // Should still work afterwards
+      const recovery = await client.callTool('whats_next', {
+        user_input: 'recover',
+      });
+      assertValidWhatsNextResponse(assertToolSuccess(recovery));
+    });
+
+    it('should handle missing workflow gracefully', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'nonexistent_workflow_xyz',
+        commit_behaviour: 'none',
+      });
+
+      expect(result).toBeDefined();
+    });
+
+    it('should maintain consistency after errors', async () => {
+      await initializeDevelopment(client, 'waterfall');
+
+      // Get initial state
+      const state1 = (await client.readResource('state://current')) as unknown;
+      const stateRes1 = state1 as Record<string, unknown>;
+      const data1 = JSON.parse(
+        ((stateRes1.contents as unknown[])[0] as Record<string, unknown>)
+          .text as string
+      );
+
+      expect(data1.currentPhase).toBe('requirements');
+
+      // Cause an error
+      await client.callTool('proceed_to_phase', {
+        target_phase: 'bad_phase',
+        reason: 'error test',
+        review_state: 'not-required',
+      });
+
+      // State should still be valid
+      const state2 = (await client.readResource('state://current')) as unknown;
+      const stateRes2 = state2 as Record<string, unknown>;
+      const data2 = JSON.parse(
+        ((stateRes2.contents as unknown[])[0] as Record<string, unknown>)
+          .text as string
+      );
+
+      expect(data2.currentPhase).toBe(data1.currentPhase);
+
+      expect(data2.conversationId).toBe(data1.conversationId);
+    });
+  });
+
+  describe('Default Behavior (Without Beads)', () => {
+    let client: DirectServerInterface;
+    let cleanup: () => Promise<void>;
+
+    beforeEach(async () => {
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'plugin-default-behavior',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should initialize server without beads plugin', async () => {
+      // Verify environment is clean
+      expect(process.env.TASK_BACKEND).toBeUndefined();
+
+      const result = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      await assertFileExists(response.plan_file_path);
+      expect(response.phase).toBe('requirements');
+    });
+
+    it('should handle start_development without plugin interference', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'epcc',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      const planContent = await fs.readFile(response.plan_file_path, 'utf-8');
+      expect(planContent).toContain('## Explore');
+      expect(planContent).toContain('## Plan');
+      expect(planContent).toContain('## Code');
+      expect(planContent).toContain('## Commit');
+    });
+  });
+
+  describe('Resource Access', () => {
+    let client: DirectServerInterface;
+    let cleanup: () => Promise<void>;
+
+    beforeEach(async () => {
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'resource-access',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+
+      await initializeDevelopment(client, 'waterfall');
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should provide access to state resource with valid structure', async () => {
+      const stateResource = (await client.readResource(
+        'state://current'
+      )) as unknown;
+      const resource = stateResource as Record<string, unknown>;
+
+      expect(resource).toHaveProperty('contents');
+      expect(Array.isArray(resource.contents)).toBe(true);
+      expect((resource.contents as unknown[]).length).toBeGreaterThan(0);
+
+      const content = (
+        (resource.contents as unknown[])[0] as Record<string, unknown>
+      ).text as string;
+      const stateData = JSON.parse(content);
+      expect(typeof stateData.conversationId).toBe('string');
+      expect(stateData.conversationId.length).toBeGreaterThan(0);
+      expect(typeof stateData.currentPhase).toBe('string');
+      expect(stateData.currentPhase.length).toBeGreaterThan(0);
+    });
+
+    it('should provide access to plan resource with substantive content', async () => {
+      const planResource = (await client.readResource(
+        'plan://current'
+      )) as unknown;
+      const resource = planResource as Record<string, unknown>;
+
+      expect(resource).toHaveProperty('contents');
+      expect(Array.isArray(resource.contents)).toBe(true);
+      expect((resource.contents as unknown[]).length).toBeGreaterThan(0);
+
+      const content = (
+        (resource.contents as unknown[])[0] as Record<string, unknown>
+      ).text as string;
+      expect(typeof content).toBe('string');
+      expect(content.length).toBeGreaterThan(0);
+    });
+
+    it('should provide access to system prompt resource', async () => {
+      const promptResource = (await client.readResource(
+        'system-prompt://'
+      )) as unknown;
+      const resource = promptResource as Record<string, unknown>;
+
+      expect(resource).toHaveProperty('contents');
+      expect(Array.isArray(resource.contents)).toBe(true);
+      expect((resource.contents as unknown[]).length).toBeGreaterThan(0);
+
+      const contentObj = (resource.contents as unknown[])[0] as Record<
+        string,
+        unknown
+      >;
+      // Try text first (primary), then content (secondary), then get string representation
+      let content: string;
+      if (typeof contentObj.text === 'string' && contentObj.text.length > 0) {
+        content = contentObj.text;
+      } else if (
+        typeof contentObj.content === 'string' &&
+        contentObj.content.length > 0
+      ) {
+        content = contentObj.content;
+      } else if (Object.keys(contentObj).length > 0) {
+        // If object has properties but no usable string property, convert to string
+        content = JSON.stringify(contentObj);
+      } else {
+        throw new Error('Content object has no usable content');
+      }
+      expect(typeof content).toBe('string');
+      expect(content.length).toBeGreaterThan(0);
+    });
+  });
+
+  // =========================================================================
+  // PLUGIN HOOK EXECUTION VERIFICATION
+  // =========================================================================
+
+  describe('Plugin Hook Execution Verification', () => {
+    let client: DirectServerInterface;
+    let cleanup: () => Promise<void>;
+
+    beforeEach(async () => {
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'plugin-hook-execution',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should execute hooks during start_development and return valid response', async () => {
+      // Start development - triggers plugin hooks
+      const result = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      // (plan file exists, instructions present, phase valid)
+      expect(response.phase).toBe('requirements');
+      expect(response.plan_file_path).toBeDefined();
+
+      // Verify plan file was created by hooks
+      await assertFileExists(response.plan_file_path);
+      const planContent = await fs.readFile(response.plan_file_path, 'utf-8');
+      expect(planContent.length).toBeGreaterThan(0);
+    });
+
+    it('should maintain state consistency after hook execution', async () => {
+      // Start development
+      const startResult = await client.callTool('start_development', {
+        workflow: 'epcc',
+        commit_behaviour: 'none',
+      });
+
+      const startResponse = assertValidStartDevelopmentResponse(
+        assertToolSuccess(startResult)
+      );
+
+      // Call whats_next immediately after hooks
+      const whatsNextResult = await client.callTool('whats_next', {
+        user_input: 'test after hooks',
+        context: 'right after start',
+      });
+
+      const whatsNextResponse = assertValidWhatsNextResponse(
+        assertToolSuccess(whatsNextResult)
+      );
+
+      expect(whatsNextResponse.phase).toBe(startResponse.phase);
+      expect(whatsNextResponse.plan_file_path).toBe(
+        startResponse.plan_file_path
+      );
+    });
+
+    it('should ensure hooks do not break plan file validity', async () => {
+      // Start development
+      const result = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      // Read and validate plan file
+      const planContent = await fs.readFile(response.plan_file_path, 'utf-8');
+
+      expect(planContent).toMatch(/^# /m); // Title
+      expect(planContent).toMatch(/^## /m); // Sections
+      expect(planContent).toContain('## Goal');
+      expect(planContent).toContain('## Requirements');
+
+      expect(planContent).not.toContain('undefined');
+      expect(planContent).not.toContain('[object Object]');
+    });
+
+    it('should handle hook execution for multiple workflows', async () => {
+      const workflows = ['waterfall', 'epcc', 'tdd', 'minor'];
+
+      for (const workflow of workflows) {
+        // Create fresh scenario for each workflow
+        const scenario = await createSuiteIsolatedE2EScenario({
+          suiteName: `plugin-hooks-${workflow}`,
+          tempProjectFactory: createTempProjectWithDefaultStateMachine,
+        });
+
+        const result = await scenario.client.callTool('start_development', {
+          workflow: workflow,
+          commit_behaviour: 'none',
+        });
+
+        const response = assertValidStartDevelopmentResponse(
+          assertToolSuccess(result)
+        );
+
+        await assertFileExists(response.plan_file_path);
+
+        await scenario.cleanup();
+      }
+    });
+  });
+
+  // =========================================================================
+  // PLUGIN SYSTEM ARCHITECTURE VALIDATION
+  // =========================================================================
+
+  describe('Plugin System Architecture', () => {
+    let client: DirectServerInterface;
+    let cleanup: () => Promise<void>;
+
+    beforeEach(async () => {
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'plugin-architecture',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should not expose plugin registry or internal plugin details', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertToolSuccess(result);
+
+      assertNoPluginLeak(response);
+
+      expect(Object.keys(response).sort()).toEqual(
+        [
+          'instructions',
+          'phase',
+          'plan_file_path',
+          'workflowDocumentationUrl',
+        ].sort()
+      );
+    });
+
+    it('should apply plugins uniformly across all tool calls', async () => {
+      // Start development
+      const startResult = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      assertValidStartDevelopmentResponse(assertToolSuccess(startResult));
+
+      // Get whats_next
+      const whatsNextResult = await client.callTool('whats_next', {
+        user_input: 'next step',
+      });
+
+      assertValidWhatsNextResponse(assertToolSuccess(whatsNextResult));
+
+      // Transition phase
+      const transitionResult = await client.callTool('proceed_to_phase', {
+        target_phase: 'design',
+        reason: 'ready',
+        review_state: 'not-required',
+      });
+
+      assertValidProceedToPhaseResponse(assertToolSuccess(transitionResult));
+    });
+
+    it('should preserve plugin boundaries (no cross-pollution)', async () => {
+      // Start development
+      const result = await client.callTool('start_development', {
+        workflow: 'epcc',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertToolSuccess(result);
+
+      assertNoPluginLeak(response);
+
+      expect(response).toHaveProperty('plan_file_path');
+      expect(response).toHaveProperty('instructions');
+
+      expect(response).not.toHaveProperty('_plugins');
+      expect(response).not.toHaveProperty('beads');
+      expect(response).not.toHaveProperty('taskBackendClient');
+    });
+  });
+
+  // =========================================================================
+  // WORKFLOW INITIALIZATION VALIDATION
+  // =========================================================================
+
+  describe('Workflow Initialization with Plugin Support', () => {
+    let cleanup: () => Promise<void>;
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+    });
+
+    it('should initialize waterfall with correct initial phase', async () => {
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'init-waterfall',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      cleanup = scenario.cleanup;
+
+      const result = await scenario.client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      expect(response.phase).toBe(WORKFLOW_INITIAL_PHASES.waterfall);
+    });
+
+    it('should initialize epcc with correct initial phase', async () => {
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'init-epcc',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      cleanup = scenario.cleanup;
+
+      const result = await scenario.client.callTool('start_development', {
+        workflow: 'epcc',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      expect(response.phase).toBe(WORKFLOW_INITIAL_PHASES.epcc);
+    });
+
+    it('should initialize tdd with correct initial phase', async () => {
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'init-tdd',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      cleanup = scenario.cleanup;
+
+      const result = await scenario.client.callTool('start_development', {
+        workflow: 'tdd',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      expect(response.phase).toBe(WORKFLOW_INITIAL_PHASES.tdd);
+    });
+
+    it('should initialize minor with correct initial phase', async () => {
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'init-minor',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      cleanup = scenario.cleanup;
+
+      const result = await scenario.client.callTool('start_development', {
+        workflow: 'minor',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      expect(response.phase).toBe(WORKFLOW_INITIAL_PHASES.minor);
+    });
+
+    it('should initialize bugfix with expected initial phase', async () => {
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'init-bugfix',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      cleanup = scenario.cleanup;
+
+      const result = await scenario.client.callTool('start_development', {
+        workflow: 'bugfix',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      const expectedPhases = WORKFLOW_INITIAL_PHASES.bugfix;
+      expect(expectedPhases).toContain(response.phase);
+    });
+  });
+
+  // =========================================================================
+  // PLAN FILE AND INSTRUCTION QUALITY
+  // =========================================================================
+
+  describe('Plan File and Instruction Quality Across Workflows', () => {
+    let client: DirectServerInterface;
+    let cleanup: () => Promise<void>;
+
+    beforeEach(async () => {
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'quality-across-workflows',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should generate substantive instructions that meet minimum length requirement', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      expect(response.instructions.length).toBeGreaterThan(
+        MIN_INSTRUCTION_LENGTH
+      );
+    });
+
+    it('should create plan files with valid markdown structure', async () => {
+      const result = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const response = assertValidStartDevelopmentResponse(
+        assertToolSuccess(result)
+      );
+
+      const planContent = await fs.readFile(response.plan_file_path, 'utf-8');
+
+      expect(planContent).toMatch(/^# /m); // Must have main title
+      expect(planContent).toMatch(/^## /m); // Must have sections
+      expect(planContent).not.toContain('[object Object]'); // No serialization errors
+      expect(planContent).not.toContain('undefined'); // No undefined placeholders
+    });
+
+    it('should ensure instructions are context-aware for the current phase', async () => {
+      // Start and get initial instructions
+      const startResult = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const startResponse = assertValidStartDevelopmentResponse(
+        assertToolSuccess(startResult)
+      );
+
+      expect(startResponse.instructions).toMatch(/requirement|phase|task/i);
+
+      // Transition to design phase
+      await client.callTool('proceed_to_phase', {
+        target_phase: 'design',
+        reason: 'ready',
+        review_state: 'not-required',
+      });
+
+      // Get instructions for design phase
+      const designWhatsNext = await client.callTool('whats_next', {
+        user_input: 'what now in design?',
+      });
+
+      const designResponse = assertValidWhatsNextResponse(
+        assertToolSuccess(designWhatsNext)
+      );
+
+      expect(designResponse.instructions).toBeDefined();
+      expect(designResponse.instructions.length).toBeGreaterThan(
+        MIN_INSTRUCTION_LENGTH
+      );
+    });
+  });
+
+  // =========================================================================
+  // STATE PERSISTENCE AND CONSISTENCY
+  // =========================================================================
+
+  describe('State Persistence Across Plugin Execution', () => {
+    let client: DirectServerInterface;
+    let cleanup: () => Promise<void>;
+
+    beforeEach(async () => {
+      if (process.env.TASK_BACKEND) {
+        delete process.env.TASK_BACKEND;
+      }
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'state-persistence',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should preserve plan file path through multiple operations', async () => {
+      // Start development
+      const startResult = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const startResponse = assertValidStartDevelopmentResponse(
+        assertToolSuccess(startResult)
+      );
+      const planPath = startResponse.plan_file_path;
+
+      // Get whats_next
+      const whatsNextResult = await client.callTool('whats_next', {
+        user_input: 'continue',
+      });
+
+      const whatsNextResponse = assertValidWhatsNextResponse(
+        assertToolSuccess(whatsNextResult)
+      );
+
+      expect(whatsNextResponse.plan_file_path).toBe(planPath);
+
+      // Transition
+      const transitionResult = await client.callTool('proceed_to_phase', {
+        target_phase: 'design',
+        reason: 'ready',
+        review_state: 'not-required',
+      });
+
+      const transitionResponse = assertValidProceedToPhaseResponse(
+        assertToolSuccess(transitionResult)
+      );
+
+      expect(transitionResponse.plan_file_path).toBe(planPath);
+    });
+
+    it('should maintain plan file integrity through multiple tool calls', async () => {
+      // Start development
+      const startResult = await client.callTool('start_development', {
+        workflow: 'waterfall',
+        commit_behaviour: 'none',
+      });
+
+      const startResponse = assertValidStartDevelopmentResponse(
+        assertToolSuccess(startResult)
+      );
+
+      // Verify plan file exists for multiple operations
+      const _initialContent = await fs.readFile(
+        startResponse.plan_file_path,
+        'utf-8'
+      );
+
+      // Make multiple calls
+      await client.callTool('whats_next', { user_input: 'test' });
+      await client.callTool('whats_next', { user_input: 'test2' });
+      await client.callTool('proceed_to_phase', {
+        target_phase: 'design',
+        reason: 'ready',
+        review_state: 'not-required',
+      });
+
+      // Check plan file still valid
+      const finalContent = await fs.readFile(
+        startResponse.plan_file_path,
+        'utf-8'
+      );
+
+      expect(finalContent.length).toBeGreaterThan(0);
+
+      expect(finalContent).not.toContain('[object Object]');
+      expect(finalContent).not.toContain('undefined');
+    });
+  });
+});