feat: add quality-review dispatch hook to intercept agent:stopped events

When an execute-mode agent stops with task_complete and the initiative has
qualityReview=true, the orchestrator now spawns a fresh execute-mode agent
to run /simplify on changed .ts/.tsx/.js files before marking the task
completed. The task transitions through quality_review status as a recursion
guard so the review agent's stop event is handled normally.

- Add apps/server/execution/quality-review.ts with three exported functions:
  computeQualifyingFiles, shouldRunQualityReview, runQualityReview
- Add apps/server/execution/quality-review.test.ts (28 tests)
- Update ExecutionOrchestrator to accept agentManager, replace
  handleAgentStopped with quality-review-aware logic, add getRepoPathForTask
- Update orchestrator.test.ts with 3 quality-review integration tests
- Update container.ts to pass agentManager to ExecutionOrchestrator
- Update docs/dispatch-events.md to reflect new agent:stopped behavior

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

apps/server/execution/orchestrator.test.ts

@@ -8,10 +8,17 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { ExecutionOrchestrator } from './orchestrator.js';
 import { ensureProjectClone } from '../git/project-clones.js';
 import type { BranchManager } from '../git/branch-manager.js';
+import { shouldRunQualityReview, runQualityReview } from './quality-review.js';
 
 vi.mock('../git/project-clones.js', () => ({
   ensureProjectClone: vi.fn().mockResolvedValue('/tmp/test-workspace/clones/test'),
 }));
+
+vi.mock('./quality-review.js', () => ({
+  shouldRunQualityReview: vi.fn(),
+  runQualityReview: vi.fn(),
+  computeQualifyingFiles: vi.fn(),
+}));
 import type { PhaseRepository } from '../db/repositories/phase-repository.js';
 import type { TaskRepository } from '../db/repositories/task-repository.js';
 import type { InitiativeRepository } from '../db/repositories/initiative-repository.js';
@@ -110,6 +117,23 @@ function createMocks() {
 
   const eventBus = createMockEventBus();
 
+  const agentManager = {
+    spawn: vi.fn().mockResolvedValue({ id: 'review-agent-1' }),
+    stop: vi.fn(),
+    list: vi.fn(),
+    resume: vi.fn(),
+    delete: vi.fn(),
+  };
+
+  const agentRepository = {
+    findById: vi.fn().mockResolvedValue({ id: 'a1', mode: 'execute' }),
+    findByTaskId: vi.fn().mockResolvedValue(null),
+    findAll: vi.fn().mockResolvedValue([]),
+    create: vi.fn(),
+    update: vi.fn(),
+    delete: vi.fn(),
+  };
+
   return {
     branchManager,
     phaseRepository,
@@ -120,6 +144,8 @@ function createMocks() {
     dispatchManager,
     conflictResolutionService,
     eventBus,
+    agentManager,
+    agentRepository,
   };
 }
 
@@ -135,6 +161,8 @@ function createOrchestrator(mocks: ReturnType<typeof createMocks>) {
     mocks.conflictResolutionService,
     mocks.eventBus,
     '/tmp/test-workspace',
+    mocks.agentManager as any,
+    mocks.agentRepository as any,
   );
   orchestrator.start();
   return orchestrator;
@@ -370,3 +398,87 @@ describe('ExecutionOrchestrator', () => {
     });
   });
 });
+
+describe('handleAgentStopped — quality review integration', () => {
+  let mocks: ReturnType<typeof createMocks>;
+
+  beforeEach(() => {
+    mocks = createMocks();
+    vi.mocked(shouldRunQualityReview).mockReset();
+    vi.mocked(runQualityReview).mockReset();
+  });
+
+  it('calls runQualityReview and skips completeTask when shouldRunQualityReview returns run:true', async () => {
+    vi.mocked(shouldRunQualityReview).mockResolvedValue({
+      run: true,
+      qualifyingFiles: ['src/foo.ts'],
+    });
+    vi.mocked(runQualityReview).mockResolvedValue(undefined);
+
+    // Provide task data for re-fetch inside runQualityReview branch
+    vi.mocked(mocks.taskRepository.findById).mockResolvedValue({
+      id: 't1',
+      status: 'in_progress',
+      initiativeId: 'i1',
+      phaseId: 'p1',
+    } as any);
+    vi.mocked(mocks.initiativeRepository.findById).mockResolvedValue({
+      id: 'i1',
+      branch: 'cw/test',
+      qualityReview: true,
+    } as any);
+    vi.mocked(mocks.phaseRepository.findById).mockResolvedValue({
+      id: 'p1',
+      name: 'impl',
+      initiativeId: 'i1',
+    } as any);
+
+    createOrchestrator(mocks);
+
+    mocks.eventBus.emit({
+      type: 'agent:stopped',
+      timestamp: new Date(),
+      payload: { taskId: 't1', reason: 'task_complete', agentId: 'a1' },
+    });
+
+    await vi.waitFor(() => {
+      expect(runQualityReview).toHaveBeenCalledWith(
+        expect.objectContaining({ taskId: 't1', qualifyingFiles: ['src/foo.ts'] }),
+      );
+    });
+    expect(mocks.dispatchManager.completeTask).not.toHaveBeenCalled();
+  });
+
+  it('calls completeTask and skips runQualityReview when shouldRunQualityReview returns run:false', async () => {
+    vi.mocked(shouldRunQualityReview).mockResolvedValue({ run: false, qualifyingFiles: [] });
+    vi.mocked(runQualityReview).mockResolvedValue(undefined);
+
+    createOrchestrator(mocks);
+
+    mocks.eventBus.emit({
+      type: 'agent:stopped',
+      timestamp: new Date(),
+      payload: { taskId: 't1', reason: 'task_complete', agentId: 'a1' },
+    });
+
+    await vi.waitFor(() => {
+      expect(mocks.dispatchManager.completeTask).toHaveBeenCalledWith('t1', 'a1');
+    });
+    expect(runQualityReview).not.toHaveBeenCalled();
+  });
+
+  it('skips both paths for user_requested reason', async () => {
+    createOrchestrator(mocks);
+
+    mocks.eventBus.emit({
+      type: 'agent:stopped',
+      timestamp: new Date(),
+      payload: { taskId: 't1', reason: 'user_requested', agentId: 'a1' },
+    });
+
+    // Wait for scheduleDispatch to be triggered (dispatchNext is called in the cycle)
+    await vi.waitFor(() => expect(mocks.dispatchManager.dispatchNext).toHaveBeenCalled());
+    expect(shouldRunQualityReview).not.toHaveBeenCalled();
+    expect(mocks.dispatchManager.completeTask).not.toHaveBeenCalled();
+  });
+});