forge-server 0.1.0

package/src/pipeline/engine.ts

@@ -0,0 +1,1139 @@
+// PipelineEngine — the core orchestration layer for Forge projects.
+//
+// The engine owns all project + phase lifecycle operations:
+//   - Creating projects
+//   - Phase transition validation and persistence (atomic: event + project update)
+//   - Trajectory recording (start/step/complete)
+//   - Phase output persistence
+//   - Claim lifecycle for parallel implementation dispatch
+//   - History reconstruction from event log
+//   - Cycle count computation from event log
+//
+// All database writes are synchronous (better-sqlite3). External operations
+// (embedding, Qdrant, knowledge extraction) are the responsibility of MCP tool
+// handlers — this engine knows nothing about them.
+
+import { randomUUID } from 'node:crypto';
+import type { PipelineDB } from '../storage/sqlite.js';
+import type {
+  Phase,
+  PipelinePhase,
+  PipelineTier,
+  Project,
+  ProjectMetadata,
+  ProjectRow,
+  Trajectory,
+  TrajectoryStepMetadata,
+  PhaseOutput,
+  Claim,
+  ClaimStatus,
+  ClaimRow,
+  PipelineEvent,
+} from '../util/types.js';
+
+// ---------------------------------------------------------------------------
+// Phase type bridge
+// ---------------------------------------------------------------------------
+
+// The storage layer uses PipelinePhase (agent-role names) in the TypeScript
+// interface types, but the actual DB values are Phase (workflow-stage names).
+// These cast helpers make the boundary explicit without scattering `as unknown`.
+
+/** Cast a workflow-stage Phase to the PipelinePhase expected by event factories. */
+function pp(phase: Phase): PipelinePhase {
+  return phase as unknown as PipelinePhase;
+}
+
+/** Cast a PipelinePhase DB value back to a workflow-stage Phase. */
+function wp(phase: PipelinePhase): Phase {
+  return phase as unknown as Phase;
+}
+
+// ---------------------------------------------------------------------------
+// Parallel phase pairs
+// ---------------------------------------------------------------------------
+// Phases that can run concurrently. When starting a phase whose parallel
+// sibling is (or leads to) the current phase, we allow the start without
+// advancing currentPhase, so both agents can work and submit independently.
+
+const PARALLEL_PAIRS: ReadonlyMap<Phase, Phase> = new Map([
+  ['architecture', 'design'],
+  ['design', 'architecture'],
+]);
+
+/**
+ * Check if `toPhase` can be started as a parallel sibling of the current phase.
+ * Returns true when:
+ *  - `toPhase` has a parallel sibling, AND
+ *  - `fromPhase` is the sibling itself, OR `fromPhase` can validly transition
+ *    to the sibling (so both can start from the same predecessor).
+ */
+function isParallelStart(fromPhase: Phase, toPhase: Phase, tier: PipelineTier): boolean {
+  const sibling = PARALLEL_PAIRS.get(toPhase);
+  if (!sibling) return false;
+  return fromPhase === sibling || isValidTransition(fromPhase, sibling, tier);
+}
+import {
+  isValidTransition,
+  getAvailableTransitions,
+  isCycleTransition,
+  getCycleKey,
+  canCycle,
+  getForcedAdvancePhase,
+} from './state-machine.js';
+import {
+  phaseTransitionEvent,
+  agentStartedEvent,
+  agentCompletedEvent,
+  projectCreatedEvent,
+  projectCompletedEvent,
+  claimCreatedEvent,
+  claimCompletedEvent,
+  claimFailedEvent,
+  eventToParams,
+  rowToEvent,
+} from './events.js';
+import { logger } from '../util/logger.js';
+
+// ---------------------------------------------------------------------------
+// Public interfaces
+// ---------------------------------------------------------------------------
+
+export interface CreateProjectOptions {
+  name: string;
+  description?: string;
+  repoId: string;
+  tier?: PipelineTier;
+  metadata?: ProjectMetadata;
+}
+
+export interface TransitionResult {
+  projectId: string;
+  fromPhase: Phase;
+  toPhase: Phase;
+  trajectoryId: string;
+  cycleCounts: Record<string, number>;
+  availableTransitions: Phase[];
+}
+
+/** Full project state snapshot — returned by getState(). */
+export interface EngineState {
+  project: Project;
+  history: PipelineEvent[];
+  activeClaims: Claim[];
+  cycleCounts: Record<string, number>;
+  availableTransitions: Phase[];
+}
+
+export interface ProjectState {
+  project: Project;
+  activeTrajectory: Trajectory | null;
+  cycleCounts: Record<string, number>;
+  availableTransitions: Phase[];
+  activeClaims: Claim[];
+}
+
+export interface PhaseHistory {
+  phase: Phase;
+  agent: string;
+  startedAt: string;
+  completedAt?: string;
+  success?: boolean;
+}
+
+export interface ProjectHistory {
+  projectId: string;
+  events: PipelineEvent[];
+  outputs: PhaseOutput[];
+  history: PhaseHistory[];
+}
+
+// Typed error class so callers can distinguish engine errors from generic ones.
+export type PipelineEngineErrorCode =
+  | 'PROJECT_NOT_FOUND'
+  | 'PROJECT_NOT_ACTIVE'
+  | 'INVALID_TRANSITION'
+  | 'CYCLE_LIMIT_EXCEEDED';
+
+export class PipelineEngineError extends Error {
+  readonly code: PipelineEngineErrorCode;
+  readonly details: Record<string, unknown>;
+
+  constructor(
+    code: PipelineEngineErrorCode,
+    message: string,
+    details: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = 'PipelineEngineError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// PipelineEngine
+// ---------------------------------------------------------------------------
+
+export class PipelineEngine {
+  constructor(private readonly db: PipelineDB) {}
+
+  // ---------------------------------------------------------------------------
+  // Project lifecycle
+  // ---------------------------------------------------------------------------
+
+  createProject(opts: CreateProjectOptions): Project {
+    const id = randomUUID();
+    const now = Date.now();
+    const tier: PipelineTier = opts.tier ?? 'full';
+
+    this.db.run(
+      `INSERT INTO projects (id, repo_id, name, description, current_phase, tier, status, created_at, updated_at, metadata)
+       VALUES (?, ?, ?, ?, 'idle', ?, 'active', ?, ?, ?)`,
+      [
+        id,
+        opts.repoId,
+        opts.name,
+        opts.description ?? null,
+        tier,
+        now,
+        now,
+        JSON.stringify(opts.metadata ?? {}),
+      ],
+    );
+
+    // Emit project_created event
+    const event = projectCreatedEvent(id, {
+      name: opts.name,
+      tier,
+      repo_id: opts.repoId,
+    });
+    this.db.run(
+      `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      Object.values(eventToParams(event)),
+    );
+
+    logger.info('PipelineEngine: project created', { id, name: opts.name, tier });
+
+    return this.getProject(id)!;
+  }
+
+  getProject(projectId: string): Project | null {
+    const row = this.db.get<ProjectRow>(
+      `SELECT * FROM projects WHERE id = ?`,
+      [projectId],
+    );
+    if (!row) return null;
+    return this._rowToProject(row);
+  }
+
+  /**
+   * Lists projects with optional repo and status filters.
+   * Ordered by updated_at DESC (most recently modified first).
+   */
+  listProjects(repoId?: string, status?: string): Project[] {
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (repoId !== undefined) {
+      conditions.push('repo_id = ?');
+      params.push(repoId);
+    }
+    if (status !== undefined) {
+      conditions.push('status = ?');
+      params.push(status);
+    }
+
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    const rows = this.db.all<ProjectRow>(
+      `SELECT * FROM projects ${where} ORDER BY updated_at DESC`,
+      params,
+    );
+    return rows.map((r) => this._rowToProject(r));
+  }
+
+  /**
+   * Returns the most recently updated active project for a repo, or null when
+   * there is no active project for that repo.
+   */
+  getActiveProject(repoId: string): Project | null {
+    const row = this.db.get<ProjectRow>(
+      `SELECT * FROM projects WHERE repo_id = ? AND status = 'active' ORDER BY updated_at DESC LIMIT 1`,
+      [repoId],
+    );
+    return row ? this._rowToProject(row) : null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Task-spec core API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns the full current state of a project: project data, full event
+   * history, active claims, derived cycle counts, and available transitions.
+   *
+   * Throws PipelineEngineError with code PROJECT_NOT_FOUND when the project
+   * does not exist.
+   */
+  getState(projectId: string): EngineState {
+    const project = this._requireProject(projectId);
+    const history = this.getEventHistory(projectId);
+    const activeClaims = this.getActiveClaims(projectId);
+    const cycleCounts = this._getCycleCounts(projectId);
+    const currentPhase = wp(project.currentPhase);
+    const availableTransitions = getAvailableTransitions(currentPhase, project.tier);
+    return { project, history, activeClaims, cycleCounts, availableTransitions };
+  }
+
+  /**
+   * Atomically advances a project to `toPhase` in a single SQLite transaction:
+   *   1. Validates the transition (throws on illegal transitions).
+   *   2. Checks cycle limits (throws CYCLE_LIMIT_EXCEEDED; details include the
+   *      forced advance phase so callers can decide how to proceed).
+   *   3. Inserts a phase_transition event.
+   *   4. Updates projects.current_phase and updated_at.
+   *   5. If toPhase === 'completed', marks the project status 'complete' and
+   *      emits an additional project_completed event.
+   *
+   * Throws PipelineEngineError for invalid transitions and cycle limit exceeded.
+   * All writes are in a single better-sqlite3 transaction.
+   */
+  advancePhase(
+    projectId: string,
+    toPhase: Phase,
+    agent?: string,
+    payload?: Record<string, unknown>,
+  ): void {
+    const project = this._requireProject(projectId);
+
+    if (project.status !== 'active') {
+      throw new PipelineEngineError(
+        'PROJECT_NOT_ACTIVE',
+        `Project '${projectId}' has status '${project.status}' and cannot be advanced`,
+        { currentPhase: project.currentPhase, status: project.status },
+      );
+    }
+
+    const fromPhase = wp(project.currentPhase);
+
+    if (!isValidTransition(fromPhase, toPhase, project.tier)) {
+      const available = getAvailableTransitions(fromPhase, project.tier);
+      throw new PipelineEngineError(
+        'INVALID_TRANSITION',
+        `Cannot transition from '${fromPhase}' to '${toPhase}' for tier '${project.tier}'`,
+        { currentPhase: fromPhase, attempted: toPhase, legalTransitions: available },
+      );
+    }
+
+    // Cycle limit check for backward edges.
+    if (isCycleTransition(fromPhase, toPhase)) {
+      const key = getCycleKey(fromPhase, toPhase)!;
+      const cycleCounts = this._getCycleCounts(projectId);
+      const count = cycleCounts[key] ?? 0;
+      if (!canCycle(fromPhase, toPhase, count)) {
+        const forcedPhase = getForcedAdvancePhase(fromPhase, toPhase);
+        throw new PipelineEngineError(
+          'CYCLE_LIMIT_EXCEEDED',
+          `Cycle '${key}' has reached the maximum of ${count} iterations. Force advance to '${forcedPhase ?? 'next'}'`,
+          { cycleKey: key, cycleCount: count, forcedAdvanceTo: forcedPhase },
+        );
+      }
+    }
+
+    const now = Date.now();
+    const isTerminal = toPhase === 'completed';
+    const newStatus: Project['status'] = isTerminal ? 'complete' : 'active';
+
+    const transEvent = phaseTransitionEvent(projectId, pp(fromPhase), pp(toPhase), agent ?? null, payload ?? {});
+
+    this.db.db.transaction(() => {
+      // 1. Insert phase_transition event
+      this.db.run(
+        `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+        Object.values(eventToParams(transEvent)),
+      );
+
+      // 2. Update project
+      this.db.run(
+        `UPDATE projects SET current_phase = ?, updated_at = ?, status = ? WHERE id = ?`,
+        [toPhase, now, newStatus, projectId],
+      );
+
+      // 3. Emit project_completed if terminal
+      if (isTerminal) {
+        const completedEvent = projectCompletedEvent(projectId, { agent: agent ?? null });
+        this.db.run(
+          `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`,
+          Object.values(eventToParams(completedEvent)),
+        );
+      }
+    })();
+
+    logger.info('PipelineEngine: advancePhase', { projectId, from: fromPhase, to: toPhase, agent });
+  }
+
+  /**
+   * Persists a phase output to phase_outputs. Multiple outputs per phase are
+   * allowed (e.g., vision doc, refined vision doc, etc.).
+   *
+   * Throws PipelineEngineError with code PROJECT_NOT_FOUND when the project
+   * does not exist.
+   */
+  recordOutput(
+    projectId: string,
+    phase: Phase,
+    outputType: string,
+    content: string,
+    filePath?: string,
+  ): void {
+    this._requireProject(projectId);
+    this.db.run(
+      `INSERT INTO phase_outputs (project_id, phase, output_type, content, file_path, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [projectId, phase, outputType, content, filePath ?? null, Date.now()],
+    );
+  }
+
+  /**
+   * Returns phase outputs for a project, optionally filtered to a specific
+   * phase. Ordered by created_at ASC.
+   */
+  getOutputs(projectId: string, phase?: Phase): PhaseOutput[] {
+    this._requireProject(projectId);
+    if (phase !== undefined) {
+      return this.db.all<{
+        id: number;
+        project_id: string;
+        phase: string;
+        output_type: string;
+        content: string;
+        file_path: string | null;
+        created_at: number;
+      }>(
+        `SELECT * FROM phase_outputs WHERE project_id = ? AND phase = ? ORDER BY created_at ASC`,
+        [projectId, phase],
+      ).map((r) => this._rowToPhaseOutput(r));
+    }
+    return this.getAllPhaseOutputs(projectId);
+  }
+
+  /**
+   * Returns all events for a project ordered by created_at ASC.
+   * This is the raw event sourcing log used for history reconstruction.
+   */
+  getEventHistory(projectId: string): PipelineEvent[] {
+    return this.db.all<{
+      id: number;
+      project_id: string;
+      event_type: string;
+      from_phase: string | null;
+      to_phase: string | null;
+      agent: string | null;
+      payload: string;
+      created_at: number;
+    }>(
+      `SELECT * FROM pipeline_events WHERE project_id = ? ORDER BY created_at ASC`,
+      [projectId],
+    ).map(rowToEvent);
+  }
+
+  /**
+   * Marks a project as 'archived'. Emits a project_completed event with an
+   * 'abandoned' flag. Idempotent if already archived.
+   *
+   * Throws PipelineEngineError with code PROJECT_NOT_FOUND when the project
+   * does not exist.
+   */
+  abandonProject(projectId: string): void {
+    const project = this._requireProject(projectId);
+
+    if (project.status === 'archived') {
+      return; // Idempotent.
+    }
+
+    const now = Date.now();
+    const completedEvent = projectCompletedEvent(projectId, { abandoned: true });
+
+    this.db.db.transaction(() => {
+      this.db.run(
+        `UPDATE projects SET status = 'archived', updated_at = ? WHERE id = ?`,
+        [now, projectId],
+      );
+      this.db.run(
+        `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+        Object.values(eventToParams(completedEvent)),
+      );
+    })();
+
+    logger.info('PipelineEngine: project abandoned', { projectId });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Phase transitions (extended API — used by MCP tools)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Transition a project to a new phase.
+   * Validates the transition against the state machine, emits events,
+   * starts a trajectory, and returns the result.
+   */
+  startPhase(
+    projectId: string,
+    toPhase: Phase,
+    agent: string,
+    extra?: Record<string, unknown>,
+  ): TransitionResult | { error: string; current_phase: Phase; legal_transitions: Phase[] } {
+    const project = this.getProject(projectId);
+    if (!project) {
+      return { error: 'PROJECT_NOT_FOUND', current_phase: 'idle', legal_transitions: [] };
+    }
+
+    // Cast from PipelinePhase (domain type) to Phase (state-machine type) — the
+    // DB stores Phase values in the current_phase column; the Project interface
+    // types it as PipelinePhase for legacy compatibility.
+    const fromPhase = project.currentPhase as unknown as Phase;
+    const tier = project.tier;
+    const cycleCounts = this._getCycleCounts(projectId);
+
+    // Validate transition
+    const validTransition = isValidTransition(fromPhase, toPhase, tier);
+    const parallelStart = !validTransition && isParallelStart(fromPhase, toPhase, tier);
+
+    if (!validTransition && !parallelStart) {
+      const legal = getAvailableTransitions(fromPhase, tier);
+      return {
+        error: 'INVALID_TRANSITION',
+        current_phase: fromPhase,
+        legal_transitions: legal,
+      };
+    }
+
+    // For parallel siblings (architecture + design), don't change currentPhase —
+    // both agents run concurrently and the submit handlers coordinate advancement.
+    // Skip only when the current phase IS the sibling (both are running from the
+    // same starting point) or when we allowed a parallelStart.
+    const sibling = PARALLEL_PAIRS.get(toPhase);
+    const skipPhaseUpdate = parallelStart || (validTransition && sibling !== undefined && fromPhase === sibling);
+
+    // Check cycle limits (only for non-parallel forward transitions)
+    if (!skipPhaseUpdate && isCycleTransition(fromPhase, toPhase)) {
+      const key = getCycleKey(fromPhase, toPhase)!;
+      const count = cycleCounts[key] ?? 0;
+      if (!canCycle(fromPhase, toPhase, count)) {
+        const forcedPhase = getForcedAdvancePhase(fromPhase, toPhase);
+        logger.warn('PipelineEngine: cycle limit exceeded, forcing advance', {
+          projectId,
+          from: fromPhase,
+          to: toPhase,
+          forced: forcedPhase,
+          count,
+        });
+        // Force advance to the prescribed phase instead
+        if (forcedPhase) {
+          return this.startPhase(projectId, forcedPhase, agent, {
+            ...extra,
+            forced: true,
+            reason: 'cycle_limit_exceeded',
+          });
+        }
+      }
+      // Increment cycle counter
+      cycleCounts[key] = (cycleCounts[key] ?? 0) + 1;
+    }
+
+    const now = Date.now();
+
+    // Update project phase (skip for parallel siblings)
+    if (!skipPhaseUpdate) {
+      this.db.run(
+        `UPDATE projects SET current_phase = ?, updated_at = ? WHERE id = ?`,
+        [toPhase, now, projectId],
+      );
+    }
+
+    // Emit transition event (bridge Phase -> PipelinePhase for event factory)
+    const transEvent = phaseTransitionEvent(projectId, pp(fromPhase), pp(toPhase), agent, extra ?? {});
+    this.db.run(
+      `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      Object.values(eventToParams(transEvent)),
+    );
+
+    // Emit agent_started event
+    const startedEvent = agentStartedEvent(projectId, pp(toPhase), agent, extra ?? {});
+    this.db.run(
+      `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      Object.values(eventToParams(startedEvent)),
+    );
+
+    // Start trajectory
+    const trajectoryId = randomUUID();
+    this.db.run(
+      `INSERT INTO trajectories (id, project_id, phase, agent, status, started_at)
+       VALUES (?, ?, ?, ?, 'active', ?)`,
+      [trajectoryId, projectId, toPhase, agent, now],
+    );
+
+    logger.info('PipelineEngine: phase started', { projectId, from: fromPhase, to: toPhase, agent, parallel: skipPhaseUpdate });
+
+    return {
+      projectId,
+      fromPhase,
+      toPhase,
+      trajectoryId,
+      cycleCounts,
+      availableTransitions: getAvailableTransitions(toPhase, tier),
+    };
+  }
+
+  /**
+   * Record completion of a phase: persist output, complete the trajectory,
+   * and optionally advance the state machine.
+   */
+  completePhase(
+    projectId: string,
+    phase: Phase,
+    outputType: string,
+    content: string,
+    opts: {
+      agent: string;
+      filePath?: string;
+      advanceTo?: Phase;
+      trajectoryId?: string;
+      qualityScore?: number;
+      metadata?: Record<string, unknown>;
+    },
+  ): { outputId: number; nextPhase: Phase | null } {
+    const project = this.getProject(projectId);
+    if (!project) {
+      throw new Error(`Project not found: ${projectId}`);
+    }
+
+    const now = Date.now();
+
+    // Persist phase output
+    const result = this.db.run(
+      `INSERT INTO phase_outputs (project_id, phase, output_type, content, file_path, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [projectId, phase, outputType, content, opts.filePath ?? null, now],
+    );
+
+    // Complete active trajectory for this phase
+    if (opts.trajectoryId) {
+      this.db.run(
+        `UPDATE trajectories SET status = 'complete', completed_at = ?, success = 1 WHERE id = ?`,
+        [now, opts.trajectoryId],
+      );
+
+      // Record trajectory step for the output
+      this.db.run(
+        `INSERT INTO trajectory_steps (trajectory_id, action, result, quality_score, metadata, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)`,
+        [
+          opts.trajectoryId,
+          `submit_${phase}`,
+          content.slice(0, 500),
+          opts.qualityScore ?? null,
+          JSON.stringify(opts.metadata ?? {}),
+          now,
+        ],
+      );
+    }
+
+    // Emit agent_completed event
+    const completedEvent = agentCompletedEvent(projectId, pp(phase), opts.agent, {
+      output_type: outputType,
+      content_length: content.length,
+      ...opts.metadata,
+    });
+    this.db.run(
+      `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      Object.values(eventToParams(completedEvent)),
+    );
+
+    // Advance state if requested
+    if (opts.advanceTo) {
+      this.db.run(
+        `UPDATE projects SET current_phase = ?, updated_at = ? WHERE id = ?`,
+        [opts.advanceTo, now, projectId],
+      );
+
+      const transEvent = phaseTransitionEvent(projectId, pp(phase), pp(opts.advanceTo), opts.agent, {});
+      this.db.run(
+        `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+        Object.values(eventToParams(transEvent)),
+      );
+
+      logger.info('PipelineEngine: phase completed, advanced', {
+        projectId,
+        from: phase,
+        to: opts.advanceTo,
+      });
+    }
+
+    return {
+      outputId: Number(result.lastInsertRowid),
+      nextPhase: opts.advanceTo ?? null,
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Trajectory helpers
+  // ---------------------------------------------------------------------------
+
+  startTrajectory(projectId: string, phase: Phase, agent: string): string {
+    const id = randomUUID();
+    this.db.run(
+      `INSERT INTO trajectories (id, project_id, phase, agent, status, started_at)
+       VALUES (?, ?, ?, ?, 'active', ?)`,
+      [id, projectId, phase, agent, Date.now()],
+    );
+    return id;
+  }
+
+  recordTrajectoryStep(
+    trajectoryId: string,
+    action: string,
+    result?: string,
+    qualityScore?: number,
+    metadata?: TrajectoryStepMetadata,
+  ): void {
+    this.db.run(
+      `INSERT INTO trajectory_steps (trajectory_id, action, result, quality_score, metadata, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [
+        trajectoryId,
+        action,
+        result ?? null,
+        qualityScore ?? null,
+        JSON.stringify(metadata ?? {}),
+        Date.now(),
+      ],
+    );
+  }
+
+  completeTrajectory(
+    trajectoryId: string,
+    success: boolean,
+    feedback?: string,
+  ): void {
+    this.db.run(
+      `UPDATE trajectories SET status = ?, completed_at = ?, success = ?, feedback = ? WHERE id = ?`,
+      [success ? 'complete' : 'failed', Date.now(), success ? 1 : 0, feedback ?? null, trajectoryId],
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Claims (parallel implementation dispatch)
+  // ---------------------------------------------------------------------------
+
+  createClaim(projectId: string, moduleName: string, agent: string): Claim {
+    const id = randomUUID();
+    const now = Date.now();
+    this.db.run(
+      `INSERT INTO claims (id, project_id, module_name, agent, status, claimed_at)
+       VALUES (?, ?, ?, ?, 'claimed', ?)`,
+      [id, projectId, moduleName, agent, now],
+    );
+
+    const event = claimCreatedEvent(projectId, id, moduleName, agent);
+    this.db.run(
+      `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      Object.values(eventToParams(event)),
+    );
+
+    return {
+      id,
+      projectId,
+      moduleName,
+      agent,
+      branch: null,
+      status: 'claimed',
+      claimedAt: now,
+      completedAt: null,
+      result: null,
+    };
+  }
+
+  completeClaim(
+    claimId: string,
+    result?: string,
+  ): { remainingCount: number; allComplete: boolean } {
+    const row = this.db.get<ClaimRow>(`SELECT * FROM claims WHERE id = ?`, [claimId]);
+    if (!row) throw new Error(`Claim not found: ${claimId}`);
+
+    const now = Date.now();
+    this.db.run(
+      `UPDATE claims SET status = 'complete', completed_at = ?, result = ? WHERE id = ?`,
+      [now, result ?? null, claimId],
+    );
+
+    const event = claimCompletedEvent(row.project_id, claimId, row.module_name, row.agent, result);
+    this.db.run(
+      `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      Object.values(eventToParams(event)),
+    );
+
+    const remaining = this.db.all<{ id: string }>(
+      `SELECT id FROM claims WHERE project_id = ? AND status NOT IN ('complete', 'failed')`,
+      [row.project_id],
+    );
+
+    return {
+      remainingCount: remaining.length,
+      allComplete: remaining.length === 0,
+    };
+  }
+
+  failClaim(claimId: string, reason: string): void {
+    const row = this.db.get<ClaimRow>(`SELECT * FROM claims WHERE id = ?`, [claimId]);
+    if (!row) throw new Error(`Claim not found: ${claimId}`);
+
+    this.db.run(
+      `UPDATE claims SET status = 'failed', completed_at = ? WHERE id = ?`,
+      [Date.now(), claimId],
+    );
+
+    const event = claimFailedEvent(row.project_id, claimId, row.module_name, row.agent, reason);
+    this.db.run(
+      `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      Object.values(eventToParams(event)),
+    );
+  }
+
+  getActiveClaims(projectId: string): Claim[] {
+    const rows = this.db.all<ClaimRow>(
+      `SELECT * FROM claims WHERE project_id = ? AND status NOT IN ('complete', 'failed')`,
+      [projectId],
+    );
+    return rows.map((r) => this._rowToClaim(r));
+  }
+
+  getClaims(projectId: string, status?: ClaimStatus): Claim[] {
+    if (status !== undefined) {
+      const rows = this.db.all<ClaimRow>(
+        `SELECT * FROM claims WHERE project_id = ? AND status = ? ORDER BY claimed_at ASC`,
+        [projectId, status],
+      );
+      return rows.map((r) => this._rowToClaim(r));
+    }
+    const rows = this.db.all<ClaimRow>(
+      `SELECT * FROM claims WHERE project_id = ? ORDER BY claimed_at ASC`,
+      [projectId],
+    );
+    return rows.map((r) => this._rowToClaim(r));
+  }
+
+  getClaim(claimId: string): Claim | null {
+    const row = this.db.get<ClaimRow>(`SELECT * FROM claims WHERE id = ?`, [claimId]);
+    return row ? this._rowToClaim(row) : null;
+  }
+
+  getClaimByModule(projectId: string, moduleName: string): Claim | null {
+    const row = this.db.get<ClaimRow>(
+      `SELECT * FROM claims WHERE project_id = ? AND module_name = ? ORDER BY claimed_at DESC LIMIT 1`,
+      [projectId, moduleName],
+    );
+    return row ? this._rowToClaim(row) : null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Phase outputs
+  // ---------------------------------------------------------------------------
+
+  getPhaseOutput(projectId: string, phase: Phase, outputType?: string): PhaseOutput | null {
+    const sql = outputType
+      ? `SELECT * FROM phase_outputs WHERE project_id = ? AND phase = ? AND output_type = ? ORDER BY created_at DESC LIMIT 1`
+      : `SELECT * FROM phase_outputs WHERE project_id = ? AND phase = ? ORDER BY created_at DESC LIMIT 1`;
+    const params = outputType ? [projectId, phase, outputType] : [projectId, phase];
+    const row = this.db.get<{
+      id: number;
+      project_id: string;
+      phase: string;
+      output_type: string;
+      content: string;
+      file_path: string | null;
+      created_at: number;
+    }>(sql, params);
+    if (!row) return null;
+    return this._rowToPhaseOutput(row);
+  }
+
+  /**
+   * Retrieve metadata stored in the agent_completed event for a phase.
+   * This includes flags like requires_qa, requires_designer, modules, etc.
+   * that are passed via opts.metadata in completePhase().
+   */
+  getPhaseMetadata(projectId: string, phase: Phase): Record<string, unknown> | null {
+    const row = this.db.get<{ payload: string }>(
+      `SELECT payload FROM pipeline_events
+       WHERE project_id = ? AND event_type = 'agent_completed' AND from_phase = ?
+       ORDER BY created_at DESC LIMIT 1`,
+      [projectId, phase],
+    );
+    if (!row) return null;
+    try {
+      return JSON.parse(row.payload) as Record<string, unknown>;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Record a broadcast event in the pipeline_events table.
+   * Used by phase tools to auto-broadcast module completions for swarm coordination.
+   */
+  recordBroadcast(
+    projectId: string,
+    content: string,
+    severity: 'info' | 'warning' | 'critical' = 'info',
+  ): void {
+    this.db.run(
+      `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+       VALUES (?, ?, NULL, NULL, NULL, ?, ?)`,
+      [
+        projectId,
+        'agent_broadcast',
+        JSON.stringify({ content, severity }),
+        Date.now(),
+      ],
+    );
+  }
+
+  getAllPhaseOutputs(projectId: string): PhaseOutput[] {
+    const rows = this.db.all<{
+      id: number;
+      project_id: string;
+      phase: string;
+      output_type: string;
+      content: string;
+      file_path: string | null;
+      created_at: number;
+    }>(`SELECT * FROM phase_outputs WHERE project_id = ? ORDER BY created_at ASC`, [projectId]);
+    return rows.map((r) => this._rowToPhaseOutput(r));
+  }
+
+  // ---------------------------------------------------------------------------
+  // History
+  // ---------------------------------------------------------------------------
+
+  getHistory(projectId: string): ProjectHistory {
+    const events = this.db.all<{
+      id: number;
+      project_id: string;
+      event_type: string;
+      from_phase: string | null;
+      to_phase: string | null;
+      agent: string | null;
+      payload: string;
+      created_at: number;
+    }>(`SELECT * FROM pipeline_events WHERE project_id = ? ORDER BY created_at ASC`, [projectId]);
+
+    const outputs = this.getAllPhaseOutputs(projectId);
+
+    // Build phase history from agent_started / agent_completed pairs.
+    // ev.fromPhase is PipelinePhase (domain type), PhaseHistory.phase is Phase.
+    const history: PhaseHistory[] = [];
+    const startedMap = new Map<string, { phase: Phase; agent: string; startedAt: number }>();
+
+    for (const row of events) {
+      const ev = rowToEvent(row);
+      if (ev.eventType === 'agent_started' && ev.fromPhase) {
+        startedMap.set(`${ev.fromPhase}-${ev.agent}`, {
+          phase: wp(ev.fromPhase),
+          agent: ev.agent ?? 'unknown',
+          startedAt: ev.createdAt,
+        });
+      } else if (ev.eventType === 'agent_completed' && ev.fromPhase) {
+        const key = `${ev.fromPhase}-${ev.agent}`;
+        const started = startedMap.get(key);
+        if (started) {
+          history.push({
+            phase: started.phase,
+            agent: started.agent,
+            startedAt: new Date(started.startedAt).toISOString(),
+            completedAt: new Date(ev.createdAt).toISOString(),
+            success: true,
+          });
+          startedMap.delete(key);
+        }
+      }
+    }
+
+    // Flush any in-progress phases
+    for (const [, started] of startedMap) {
+      history.push({
+        phase: started.phase,
+        agent: started.agent,
+        startedAt: new Date(started.startedAt).toISOString(),
+      });
+    }
+
+    return {
+      projectId,
+      events: events.map(rowToEvent),
+      outputs,
+      history,
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Cycle tracking
+  // ---------------------------------------------------------------------------
+
+  getCycleCounts(projectId: string): Record<string, number> {
+    return this._getCycleCounts(projectId);
+  }
+
+  private _getCycleCounts(projectId: string): Record<string, number> {
+    const rows = this.db.all<{
+      from_phase: string;
+      to_phase: string;
+      count: number;
+    }>(
+      `SELECT from_phase, to_phase, COUNT(*) as count
+       FROM pipeline_events
+       WHERE project_id = ? AND event_type = 'phase_transition' AND from_phase IS NOT NULL AND to_phase IS NOT NULL
+       GROUP BY from_phase, to_phase`,
+      [projectId],
+    );
+
+    const counts: Record<string, number> = {};
+    for (const row of rows) {
+      const key = `${row.from_phase}_to_${row.to_phase}`;
+      // Only include recognised cycle keys
+      if (getCycleKey(row.from_phase as Phase, row.to_phase as Phase)) {
+        counts[key] = row.count;
+      }
+    }
+    return counts;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Retrieves a project by id and throws a typed PipelineEngineError when not
+   * found. Used by every method that requires an existing project.
+   */
+  private _requireProject(projectId: string): Project {
+    const row = this.db.get<ProjectRow>(
+      `SELECT * FROM projects WHERE id = ?`,
+      [projectId],
+    );
+    if (!row) {
+      throw new PipelineEngineError(
+        'PROJECT_NOT_FOUND',
+        `Project '${projectId}' does not exist`,
+        { projectId },
+      );
+    }
+    return this._rowToProject(row);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Row mappers
+  // ---------------------------------------------------------------------------
+
+  private _rowToProject(row: ProjectRow): Project {
+    let metadata: ProjectMetadata;
+    try {
+      metadata = JSON.parse(row.metadata) as ProjectMetadata;
+    } catch {
+      metadata = {};
+    }
+
+    return {
+      id: row.id,
+      repoId: row.repo_id,
+      name: row.name,
+      description: row.description,
+      // The DB stores Phase (workflow-stage) values in current_phase, but
+      // Project.currentPhase is typed as PipelinePhase. We bridge here so
+      // callers use wp() to get back to Phase when needed.
+      currentPhase: row.current_phase as unknown as PipelinePhase,
+      tier: row.tier,
+      status: row.status,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+      metadata,
+    };
+  }
+
+  private _rowToClaim(row: ClaimRow): Claim {
+    return {
+      id: row.id,
+      projectId: row.project_id,
+      moduleName: row.module_name,
+      agent: row.agent,
+      branch: row.branch,
+      status: row.status,
+      claimedAt: row.claimed_at,
+      completedAt: row.completed_at,
+      result: row.result,
+    };
+  }
+
+  private _rowToPhaseOutput(row: {
+    id: number;
+    project_id: string;
+    phase: string;
+    output_type: string;
+    content: string;
+    file_path: string | null;
+    created_at: number;
+  }): PhaseOutput {
+    return {
+      id: row.id,
+      projectId: row.project_id,
+      // Bridge: Phase values stored in DB, PhaseOutput.phase typed as PipelinePhase.
+      phase: row.phase as unknown as PipelinePhase,
+      outputType: row.output_type,
+      content: row.content,
+      filePath: row.file_path,
+      createdAt: row.created_at,
+    };
+  }
+
+  // Expose getTrajectory for phase tools
+  getActiveTrajectory(projectId: string, phase: Phase): Trajectory | null {
+    const row = this.db.get<{
+      id: string;
+      project_id: string;
+      phase: string;
+      agent: string;
+      status: string;
+      started_at: number;
+      completed_at: number | null;
+      success: number | null;
+      feedback: string | null;
+    }>(
+      `SELECT * FROM trajectories WHERE project_id = ? AND phase = ? AND status = 'active' ORDER BY started_at DESC LIMIT 1`,
+      [projectId, phase],
+    );
+    if (!row) return null;
+    return {
+      id: row.id,
+      projectId: row.project_id,
+      // Bridge: Phase stored in DB, Trajectory.phase typed as PipelinePhase.
+      phase: row.phase as unknown as PipelinePhase,
+      agent: row.agent,
+      status: row.status as 'active' | 'complete' | 'failed' | 'abandoned',
+      startedAt: row.started_at,
+      completedAt: row.completed_at,
+      success: row.success === null ? null : row.success === 1,
+      feedback: row.feedback,
+    };
+  }
+}