forge-server 0.1.0

package/src/tools/phase-tools.ts

@@ -0,0 +1,1452 @@
+// phase-tools.ts — B14
+// MCP tool handlers for all phase lifecycle transitions.
+// Every start_* tool: validates transition -> assembles context -> starts trajectory -> returns enriched context
+// Every submit_* tool: validates phase -> records output -> records trajectory step -> advances state
+
+import { z } from 'zod';
+import type { PipelineEngine } from '../pipeline/engine.js';
+import type { ContextInjector } from '../context/injector.js';
+import type { Phase, PipelinePhase } from '../util/types.js';
+import type { VectorStore, GraphStore } from '../storage/interfaces.js';
+import { saveObservation } from '../memory/observation-store.js';
+import { getCurrentSessionId } from '../memory/session-tracker.js';
+
+// Bridge: Project.currentPhase is typed as PipelinePhase (agent-role enum) but
+// the DB stores Phase (workflow-stage) values. Cast explicitly at comparison sites.
+function asPhase(p: PipelinePhase): Phase {
+  return p as unknown as Phase;
+}
+import { getAvailableTransitions } from '../pipeline/state-machine.js';
+import { writeFileSync, appendFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { mkdirSync, existsSync } from 'node:fs';
+import { logger } from '../util/logger.js';
+
+// ---------------------------------------------------------------------------
+// Helper: write content to disk if file_path provided
+// ---------------------------------------------------------------------------
+
+function writeToDisk(content: string, filePath: string): void {
+  const absPath = resolve(filePath);
+  const dir = dirname(absPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  if (existsSync(absPath)) {
+    // Append with a separator so phase outputs don't clobber each other
+    const separator = '\n\n---\n\n';
+    appendFileSync(absPath, separator + content, 'utf8');
+  } else {
+    writeFileSync(absPath, content, 'utf8');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helper: extract knowledge candidates from text (lightweight keyword NLP)
+// ---------------------------------------------------------------------------
+
+function extractKnowledgeCandidates(text: string): number {
+  // Simple heuristic: count potential knowledge items based on keywords
+  const keywords = [
+    /\b(gotcha|pitfall|issue|problem|note|warning|caution|important)\b/gi,
+    /\b(pattern|approach|best practice|convention|standard)\b/gi,
+    /\b(decided|decision|chose|rationale|because|reason)\b/gi,
+  ];
+  let count = 0;
+  for (const re of keywords) {
+    const matches = text.match(re);
+    count += matches ? matches.length : 0;
+  }
+  return Math.min(count, 10); // cap at 10 for plausibility
+}
+
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+
+const projectIdSchema = z.string().min(1, 'project_id is required');
+
+export const startInterviewSchema = z.object({
+  project_id: projectIdSchema,
+  initial_request: z.string().optional(),
+});
+
+export const submitVisionSchema = z.object({
+  project_id: projectIdSchema,
+  vision: z.string().min(1, 'vision content is required'),
+  file_path: z.string().optional(),
+});
+
+export const startArchitectureSchema = z.object({
+  project_id: projectIdSchema,
+  vision_summary: z.string().optional(),
+});
+
+export const submitPlanSchema = z.object({
+  project_id: projectIdSchema,
+  plan: z.string().min(1, 'plan content is required'),
+  file_path: z.string().optional(),
+  modules: z.array(z.string()).optional(),
+  requires_designer: z.boolean().optional(),
+  requires_qa: z.boolean().optional(),
+});
+
+export const startDesignSchema = z.object({
+  project_id: projectIdSchema,
+  focus: z.string().optional(),
+});
+
+export const submitDesignSchema = z.object({
+  project_id: projectIdSchema,
+  design: z.string().min(1, 'design content is required'),
+  file_path: z.string().optional(),
+});
+
+export const startQAStrategySchema = z.object({
+  project_id: projectIdSchema,
+});
+
+export const submitTestPlanSchema = z.object({
+  project_id: projectIdSchema,
+  test_plan: z.string().min(1, 'test_plan content is required'),
+  file_path: z.string().optional(),
+});
+
+export const startImplementationSchema = z.object({
+  project_id: projectIdSchema,
+  modules: z.array(z.object({
+    name: z.string(),
+    agent_type: z.string(),
+    description: z.string().optional(),
+  })),
+});
+
+export const submitImplementationSchema = z.object({
+  project_id: projectIdSchema,
+  module: z.string().min(1, 'module name is required'),
+  branch: z.string().optional(),
+  summary: z.string().optional(),
+  files_changed: z.array(z.string()).optional(),
+});
+
+export const startInspectionSchema = z.object({
+  project_id: projectIdSchema,
+});
+
+export const submitVerdictSchema = z.object({
+  project_id: projectIdSchema,
+  verdict: z.enum(['pass', 'pass_with_warnings', 'fail']),
+  findings: z.array(z.object({
+    severity: z.enum(['critical', 'warning', 'info']),
+    description: z.string(),
+    file_path: z.string().optional(),
+    line_number: z.number().optional(),
+  })).optional(),
+  summary: z.string().optional(),
+});
+
+export const collectKnowledgeSchema = z.object({
+  project_id: projectIdSchema,
+});
+
+// ---------------------------------------------------------------------------
+// No-op GraphStore used when the real graph backend is unavailable.
+// Allows saveObservation() to be called without null checks everywhere.
+// ---------------------------------------------------------------------------
+
+const noOpGraphStore: GraphStore = {
+  connect: async () => {},
+  disconnect: async () => {},
+  isHealthy: async () => false,
+  query: async () => ({ nodes: [], edges: [] }),
+  upsertNode: async () => {},
+  upsertEdge: async () => {},
+  deleteFile: async () => {},
+  deleteRepo: async () => {},
+  getCounts: async () => ({ totalNodes: 0, totalEdges: 0, byLabel: {} }),
+  ensureIndexes: async () => {},
+};
+
+// ---------------------------------------------------------------------------
+// Fire-and-forget auto-observation helper.
+// Wraps saveObservation() with null-guards and catch-all error handling.
+// NEVER blocks the phase transition — errors are logged and swallowed.
+// ---------------------------------------------------------------------------
+
+function autoObserve(
+  content: string,
+  opts: {
+    category: string;
+    importance: number;
+    projectId: string;
+    phase: string;
+    vectorStore: VectorStore | null;
+    graphStore: GraphStore | null;
+  },
+): void {
+  if (!opts.vectorStore) {
+    logger.debug('autoObserve: vectorStore unavailable, skipping', { phase: opts.phase });
+    return;
+  }
+  const summary = content.slice(0, 500);
+  saveObservation(
+    {
+      content: summary,
+      sessionId: getCurrentSessionId(),
+      type: 'procedural',
+      category: opts.category,
+      importance: opts.importance,
+      tags: ['auto_observation', opts.phase, opts.projectId],
+    },
+    opts.vectorStore,
+    opts.graphStore ?? noOpGraphStore,
+  ).catch((err) => {
+    logger.debug('autoObserve: fire-and-forget failed (non-fatal)', {
+      phase: opts.phase,
+      error: String(err),
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Fire-and-forget knowledge extraction from phase outputs.
+// Scans text for keyword patterns indicating gotchas, patterns, decisions,
+// and constraints. Saves each as a tagged observation for the Knowledge Keeper.
+// NEVER blocks the phase transition — errors are logged and swallowed.
+// ---------------------------------------------------------------------------
+
+function autoExtractKnowledge(
+  content: string,
+  opts: {
+    projectId: string;
+    phase: string;
+    vectorStore: VectorStore | null;
+    graphStore: GraphStore | null;
+  },
+): void {
+  if (!opts.vectorStore) {
+    logger.debug('autoExtractKnowledge: vectorStore unavailable, skipping', { phase: opts.phase });
+    return;
+  }
+
+  const lines = content.split('\n');
+  const extractions: Array<{ text: string; category: string }> = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.length < 10) continue;
+
+    // Gotcha indicators
+    if (/^(CRITICAL|WARNING|GOTCHA|CAUTION|NOTE|IMPORTANT)\s*[:!-]/i.test(trimmed)) {
+      extractions.push({ text: trimmed, category: 'gotcha' });
+      continue;
+    }
+
+    // Pattern indicators
+    if (/\b(pattern|approach|convention|best.?practice|standard)\b/i.test(trimmed) && trimmed.length > 20) {
+      extractions.push({ text: trimmed, category: 'pattern' });
+      continue;
+    }
+
+    // Decision indicators
+    if (/\b(decided|decision|chose|rationale|because we|reason for)\b/i.test(trimmed) && trimmed.length > 20) {
+      extractions.push({ text: trimmed, category: 'decision' });
+      continue;
+    }
+
+    // Constraint indicators
+    if (/\b(constraint|limitation|must not|cannot|forbidden|never)\b/i.test(trimmed) && trimmed.length > 20) {
+      extractions.push({ text: trimmed, category: 'constraint' });
+      continue;
+    }
+  }
+
+  // Cap at 15 extractions per phase output to avoid flooding
+  const capped = extractions.slice(0, 15);
+
+  for (const item of capped) {
+    saveObservation(
+      {
+        content: item.text.slice(0, 500),
+        sessionId: getCurrentSessionId(),
+        type: 'semantic',
+        category: item.category,
+        importance: item.category === 'gotcha' ? 0.7 : 0.5,
+        tags: ['auto_knowledge', opts.phase, opts.projectId],
+      },
+      opts.vectorStore,
+      opts.graphStore ?? noOpGraphStore,
+    ).catch((err) => {
+      logger.debug('autoExtractKnowledge: save failed (non-fatal)', {
+        category: item.category,
+        error: String(err),
+      });
+    });
+  }
+
+  if (capped.length > 0) {
+    logger.debug('autoExtractKnowledge: extracted items', {
+      phase: opts.phase,
+      count: capped.length,
+      categories: capped.map(c => c.category),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Phase tools factory
+// ---------------------------------------------------------------------------
+
+export function createPhaseTools(
+  engine: PipelineEngine,
+  contextInjector: ContextInjector,
+  vectorStore: VectorStore | null = null,
+  graphStore: GraphStore | null = null,
+) {
+  // ---------------------------------------------------------------------------
+  // forge.start_interview
+  // ---------------------------------------------------------------------------
+  async function startInterview(input: z.infer<typeof startInterviewSchema>) {
+    try {
+      const result = engine.startPhase(input.project_id, 'interview', 'strategist');
+      if ('error' in result) {
+        return result;
+      }
+
+      // Inject context
+      let context;
+      try {
+        context = await contextInjector.injectInterviewContext(
+          input.project_id,
+          input.initial_request,
+        );
+      } catch (ctxErr) {
+        logger.warn('start_interview: context injection failed', { error: String(ctxErr) });
+        context = {
+          similarProjects: [],
+          relevantGotchas: [],
+          interviewTemplate: DEFAULT_INTERVIEW_TEMPLATE,
+        };
+      }
+
+      return {
+        project_id: input.project_id,
+        phase: 'interview' as Phase,
+        similar_projects: context.similarProjects,
+        relevant_gotchas: context.relevantGotchas.map(g => ({
+          title: g.title,
+          content: g.content,
+          confidence: g.confidence,
+          source_repo: g.sourceRepo,
+        })),
+        interview_template: context.interviewTemplate,
+        trajectory_id: result.trajectoryId,
+        available_transitions: result.availableTransitions,
+      };
+    } catch (err) {
+      logger.error('start_interview: error', { error: String(err) });
+      return { error: 'START_INTERVIEW_FAILED', message: String(err) };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // forge.submit_vision
+  // ---------------------------------------------------------------------------
+  async function submitVision(input: z.infer<typeof submitVisionSchema>) {
+    try {
+      const project = engine.getProject(input.project_id);
+      if (!project) {
+        return { error: 'PROJECT_NOT_FOUND', project_id: input.project_id };
+      }
+      if (asPhase(project.currentPhase) !== 'interview') {
+        return {
+          error: 'INVALID_PHASE',
+          current_phase: project.currentPhase,
+          required_phase: 'interview',
+        };
+      }
+
+      // Write to disk if requested
+      if (input.file_path) {
+        try { writeToDisk(input.vision, input.file_path); } catch {}
+      }
+
+      // Get active trajectory
+      const trajectory = engine.getActiveTrajectory(input.project_id, 'interview');
+
+      const { outputId } = engine.completePhase(
+        input.project_id,
+        'interview',
+        'vision',
+        input.vision,
+        {
+          agent: 'strategist',
+          filePath: input.file_path,
+          advanceTo: 'architecture',
+          trajectoryId: trajectory?.id,
+        },
+      );
+
+      const knowledgeExtracted = extractKnowledgeCandidates(input.vision);
+
+      // Fire-and-forget auto-observation
+      autoObserve(input.vision, {
+        category: 'vision',
+        importance: 0.6,
+        projectId: input.project_id,
+        phase: 'vision',
+        vectorStore,
+        graphStore,
+      });
+
+      autoExtractKnowledge(input.vision, {
+        projectId: input.project_id,
+        phase: 'interview',
+        vectorStore,
+        graphStore,
+      });
+
+      return {
+        project_id: input.project_id,
+        phase: 'architecture' as Phase,
+        vision_stored: true,
+        knowledge_extracted: knowledgeExtracted,
+        trajectory_step_recorded: !!trajectory,
+        next_agents: ['architect'],
+      };
+    } catch (err) {
+      logger.error('submit_vision: error', { error: String(err) });
+      return { error: 'SUBMIT_VISION_FAILED', message: String(err) };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // forge.start_architecture
+  // ---------------------------------------------------------------------------
+  async function startArchitecture(input: z.infer<typeof startArchitectureSchema>) {
+    try {
+      const result = engine.startPhase(input.project_id, 'architecture', 'architect');
+      if ('error' in result) {
+        return result;
+      }
+
+      let context;
+      try {
+        context = await contextInjector.injectArchitectureContext(
+          input.project_id,
+          input.vision_summary,
+        );
+      } catch (ctxErr) {
+        logger.warn('start_architecture: context injection failed', { error: String(ctxErr) });
+        context = {
+          codebaseContext: { modules: [], patterns: [], dependencies: [], fileCount: 0 },
+          relevantDecisions: [],
+          relevantGotchas: [],
+          stackConstraints: [],
+        };
+      }
+
+      return {
+        project_id: input.project_id,
+        phase: 'architecture' as Phase,
+        codebase_context: {
+          modules: context.codebaseContext.modules,
+          patterns: context.codebaseContext.patterns,
+          dependencies: context.codebaseContext.dependencies,
+          file_count: context.codebaseContext.fileCount,
+          language_breakdown: {},
+        },
+        relevant_decisions: context.relevantDecisions.map(d => ({
+          title: d.title,
+          content: d.content,
+          confidence: d.confidence,
+          source_repo: d.sourceRepo,
+        })),
+        relevant_gotchas: context.relevantGotchas.map(g => ({
+          title: g.title,
+          content: g.content,
+          stack_tags: g.stackTags,
+          confidence: g.confidence,
+        })),
+        stack_constraints: context.stackConstraints,
+        trajectory_id: result.trajectoryId,
+        available_transitions: result.availableTransitions,
+      };
+    } catch (err) {
+      logger.error('start_architecture: error', { error: String(err) });
+      return { error: 'START_ARCHITECTURE_FAILED', message: String(err) };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // forge.submit_plan
+  // ---------------------------------------------------------------------------
+  async function submitPlan(input: z.infer<typeof submitPlanSchema>) {
+    try {
+      const project = engine.getProject(input.project_id);
+      if (!project) {
+        return { error: 'PROJECT_NOT_FOUND', project_id: input.project_id };
+      }
+      // Accept submission when current phase is architecture OR design (parallel pair)
+      const curPhase = asPhase(project.currentPhase);
+      if (curPhase !== 'architecture' && curPhase !== 'design') {
+        return {
+          error: 'INVALID_PHASE',
+          current_phase: project.currentPhase,
+          required_phase: 'architecture',
+        };
+      }
+
+      if (input.file_path) {
+        try { writeToDisk(input.plan, input.file_path); } catch {}
+      }
+
+      const trajectory = engine.getActiveTrajectory(input.project_id, 'architecture');
+
+      // Determine next phase based on flags and whether parallel design is done
+      let nextPhase: Phase = 'implementation';
+      const parallelPhases: string[] = [];
+      const designOutput = engine.getPhaseOutput(input.project_id, 'design');
+
+      if (input.requires_designer && !designOutput) {
+        // Designer hasn't finished yet — advance to design so it can still submit
+        nextPhase = 'design';
+        parallelPhases.push('design');
+        if (input.requires_qa) parallelPhases.push('qa_strategy');
+      } else if (input.requires_qa) {
+        nextPhase = 'qa_strategy';
+        parallelPhases.push('qa_strategy');
+      }
+      // else: design already done (or not needed) → advance to implementation
+
+      engine.completePhase(
+        input.project_id,
+        'architecture',
+        'architecture',
+        input.plan,
+        {
+          agent: 'architect',
+          filePath: input.file_path,
+          advanceTo: nextPhase,
+          trajectoryId: trajectory?.id,
+          metadata: {
+            modules: input.modules,
+            requires_designer: input.requires_designer,
+            requires_qa: input.requires_qa,
+          },
+        },
+      );
+
+      const knowledgeExtracted = extractKnowledgeCandidates(input.plan);
+
+      // Fire-and-forget auto-observation
+      autoObserve(input.plan, {
+        category: 'architecture',
+        importance: 0.6,
+        projectId: input.project_id,
+        phase: 'architecture',
+        vectorStore,
+        graphStore,
+      });
+
+      autoExtractKnowledge(input.plan, {
+        projectId: input.project_id,
+        phase: 'architecture',
+        vectorStore,
+        graphStore,
+      });
+
+      return {
+        project_id: input.project_id,
+        phase: nextPhase,
+        plan_stored: true,
+        knowledge_extracted: knowledgeExtracted,
+        parallel_phases: parallelPhases.length > 0 ? parallelPhases : undefined,
+      };
+    } catch (err) {
+      logger.error('submit_plan: error', { error: String(err) });
+      return { error: 'SUBMIT_PLAN_FAILED', message: String(err) };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // forge.start_design
+  // ---------------------------------------------------------------------------
+  async function startDesign(input: z.infer<typeof startDesignSchema>) {
+    try {
+      const result = engine.startPhase(input.project_id, 'design', 'designer');
+      if ('error' in result) {
+        return result;
+      }
+
+      // Search for design patterns
+      let relevantPatterns: Array<{ title: string; content: string; source_repo: string }> = [];
+      try {
+        const ctx = await contextInjector.injectPhaseContext(
+          input.project_id,
+          'design',
+          `design ${input.focus ?? ''}`.trim(),
+        );
+        relevantPatterns = ctx.relevantKnowledge
+          .filter(k => k.category === 'pattern' || k.category === 'convention')
+          .map(k => ({ title: k.title, content: k.content, source_repo: 'unknown' }));
+      } catch (ctxErr) {
+        logger.warn('start_design: context injection failed', { error: String(ctxErr) });
+      }
+
+      // Detect existing design system
+      const existingDesignSystem = await detectDesignSystem(input.project_id, engine);
+
+      return {
+        project_id: input.project_id,
+        phase: 'design' as Phase,
+        existing_design_system: existingDesignSystem,
+        relevant_patterns: relevantPatterns,
+        trajectory_id: result.trajectoryId,
+        available_transitions: result.availableTransitions,
+      };
+    } catch (err) {
+      logger.error('start_design: error', { error: String(err) });
+      return { error: 'START_DESIGN_FAILED', message: String(err) };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // forge.submit_design
+  // ---------------------------------------------------------------------------
+  async function submitDesign(input: z.infer<typeof submitDesignSchema>) {
+    try {
+      const project = engine.getProject(input.project_id);
+      if (!project) {
+        return { error: 'PROJECT_NOT_FOUND', project_id: input.project_id };
+      }
+      // Accept submission when current phase is design OR architecture (parallel pair)
+      const curPhase = asPhase(project.currentPhase);
+      if (curPhase !== 'design' && curPhase !== 'architecture') {
+        return {
+          error: 'INVALID_PHASE',
+          current_phase: project.currentPhase,
+          required_phase: 'design',
+        };
+      }
+
+      if (input.file_path) {
+        try { writeToDisk(input.design, input.file_path); } catch {}
+      }
+
+      const trajectory = engine.getActiveTrajectory(input.project_id, 'design');
+
+      // Only advance past design if the parallel architecture phase is also done.
+      // If the architect hasn't submitted yet, persist the output but don't advance —
+      // the architect's submit_plan will handle advancement once both are done.
+      const archOutput = engine.getPhaseOutput(input.project_id, 'architecture');
+      let advanceTo: Phase | undefined;
+
+      if (archOutput) {
+        // Both phases done — determine next phase from architecture metadata
+        advanceTo = 'implementation';
+        const archMeta = engine.getPhaseMetadata(input.project_id, 'architecture');
+        if (archMeta?.requires_qa) advanceTo = 'qa_strategy';
+      }
+      // else: architect hasn't submitted yet — don't advance
+
+      engine.completePhase(
+        input.project_id,
+        'design',
+        'xd_plan',
+        input.design,
+        {
+          agent: 'designer',
+          filePath: input.file_path,
+          advanceTo,
+          trajectoryId: trajectory?.id,
+        },
+      );
+
+      const knowledgeExtracted = extractKnowledgeCandidates(input.design);
+
+      // Fire-and-forget auto-observation
+      autoObserve(input.design, {
+        category: 'design',
+        importance: 0.5,
+        projectId: input.project_id,
+        phase: 'design',
+        vectorStore,
+        graphStore,
+      });
+
+      autoExtractKnowledge(input.design, {
+        projectId: input.project_id,
+        phase: 'design',
+        vectorStore,
+        graphStore,
+      });
+
+      return {
+        project_id: input.project_id,
+        phase: advanceTo ?? curPhase,
+        design_stored: true,
+        waiting_for: archOutput ? undefined : 'architecture',
+        knowledge_extracted: knowledgeExtracted,
+      };
+    } catch (err) {
+      logger.error('submit_design: error', { error: String(err) });
+      return { error: 'SUBMIT_DESIGN_FAILED', message: String(err) };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // forge.start_qa_strategy
+  // ---------------------------------------------------------------------------
+  async function startQAStrategy(input: z.infer<typeof startQAStrategySchema>) {
+    try {
+      const result = engine.startPhase(input.project_id, 'qa_strategy', 'qa-strategist');
+      if ('error' in result) {
+        return result;
+      }
+
+      // Get architecture and design summaries from phase outputs
+      const archOutput = engine.getPhaseOutput(input.project_id, 'architecture');
+      const designOutput = engine.getPhaseOutput(input.project_id, 'design');
+
+      const architectureSummary = archOutput
+        ? archOutput.content.slice(0, 1000)
+        : 'No architecture plan available.';
+      const designSummary = designOutput
+        ? designOutput.content.slice(0, 500)
+        : undefined;
+
+      // Search for past test failures
+      let pastTestFailures: Array<{ description: string; resolution: string; source_repo: string }> = [];
+      try {
+        const ctx = await contextInjector.injectPhaseContext(
+          input.project_id,
+          'qa_strategy',
+          'test failures bugs quality issues',
+        );
+        pastTestFailures = ctx.relevantKnowledge
+          .filter(k => k.category === 'gotcha')
+          .map(k => ({
+            description: k.title,
+            resolution: k.content,
+            source_repo: 'unknown',
+          }));
+      } catch (ctxErr) {
+        logger.warn('start_qa_strategy: context injection failed', { error: String(ctxErr) });
+      }
+
+      return {
+        project_id: input.project_id,
+        phase: 'qa_strategy' as Phase,
+        architecture_summary: architectureSummary,
+        design_summary: designSummary,
+        past_test_failures: pastTestFailures,
+        trajectory_id: result.trajectoryId,
+        available_transitions: result.availableTransitions,
+      };
+    } catch (err) {
+      logger.error('start_qa_strategy: error', { error: String(err) });
+      return { error: 'START_QA_STRATEGY_FAILED', message: String(err) };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // forge.submit_test_plan
+  // ---------------------------------------------------------------------------
+  async function submitTestPlan(input: z.infer<typeof submitTestPlanSchema>) {
+    try {
+      const project = engine.getProject(input.project_id);
+      if (!project) {
+        return { error: 'PROJECT_NOT_FOUND', project_id: input.project_id };
+      }
+      if (asPhase(project.currentPhase) !== 'qa_strategy') {
+        return {
+          error: 'INVALID_PHASE',
+          current_phase: project.currentPhase,
+          required_phase: 'qa_strategy',
+        };
+      }
+
+      if (input.file_path) {
+        try { writeToDisk(input.test_plan, input.file_path); } catch {}
+      }
+
+      const trajectory = engine.getActiveTrajectory(input.project_id, 'qa_strategy');
+
+      engine.completePhase(
+        input.project_id,
+        'qa_strategy',
+        'test_plan',
+        input.test_plan,
+        {
+          agent: 'qa-strategist',
+          filePath: input.file_path,
+          advanceTo: 'implementation',
+          trajectoryId: trajectory?.id,
+        },
+      );
+
+      const knowledgeExtracted = extractKnowledgeCandidates(input.test_plan);
+
+      // Fire-and-forget auto-observation
+      autoObserve(input.test_plan, {
+        category: 'test_plan',
+        importance: 0.5,
+        projectId: input.project_id,
+        phase: 'qa_strategy',
+        vectorStore,
+        graphStore,
+      });
+
+      autoExtractKnowledge(input.test_plan, {
+        projectId: input.project_id,
+        phase: 'qa_strategy',
+        vectorStore,
+        graphStore,
+      });
+
+      return {
+        project_id: input.project_id,
+        phase: 'implementation' as Phase,
+        test_plan_stored: true,
+        knowledge_extracted: knowledgeExtracted,
+      };
+    } catch (err) {
+      logger.error('submit_test_plan: error', { error: String(err) });
+      return { error: 'SUBMIT_TEST_PLAN_FAILED', message: String(err) };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // forge.start_implementation
+  // ---------------------------------------------------------------------------
+  async function startImplementation(input: z.infer<typeof startImplementationSchema>) {
+    try {
+      const result = engine.startPhase(input.project_id, 'implementation', 'supervisor');
+      if ('error' in result) {
+        return result;
+      }
+
+      // Create claims for each module
+      const claims = input.modules.map(mod => {
+        const claim = engine.createClaim(input.project_id, mod.name, mod.agent_type);
+        return {
+          claim_id: claim.id,
+          module: mod.name,
+          agent_type: mod.agent_type,
+          status: 'claimed' as const,
+        };
+      });
+
+      // Inject per-module context
+      const moduleContexts: Record<string, {
+        relevant_code: string;
+        gotchas: Array<{ title: string; content: string }>;
+        conventions: Array<{ title: string; content: string }>;
+        recent_broadcasts: Array<{ content: string; severity: string; created_at: number }>;
+        sibling_modules: Array<{ name: string; agentType: string; description?: string }>;
+      }> = {};
+
+      let injectedContexts: Record<string, import('../context/injector.js').ModuleContext> = {};
+      try {
+        injectedContexts = await contextInjector.injectImplementationContext(
+          input.project_id,
+          input.modules.map(m => ({ name: m.name, agentType: m.agent_type, description: m.description })),
+        );
+      } catch (ctxErr) {
+        logger.warn('start_implementation: context injection failed', { error: String(ctxErr) });
+      }
+
+      for (const mod of input.modules) {
+        const ctx = injectedContexts[mod.name];
+        moduleContexts[mod.name] = {
+          relevant_code: ctx?.relevantCode ?? '',
+          gotchas: ctx?.gotchas ?? [],
+          conventions: ctx?.conventions ?? [],
+          recent_broadcasts: ctx?.recentBroadcasts ?? [],
+          sibling_modules: ctx?.siblingModules ?? [],
+        };
+      }
+
+      return {
+        project_id: input.project_id,
+        phase: 'implementation' as Phase,
+        claims,
+        module_contexts: moduleContexts,
+        trajectory_id: result.trajectoryId,
+      };
+    } catch (err) {
+      logger.error('start_implementation: error', { error: String(err) });
+      return { error: 'START_IMPLEMENTATION_FAILED', message: String(err) };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // forge.submit_implementation
+  // ---------------------------------------------------------------------------
+  async function submitImplementation(input: z.infer<typeof submitImplementationSchema>) {
+    try {
+      const project = engine.getProject(input.project_id);
+      if (!project) {
+        return { error: 'PROJECT_NOT_FOUND', project_id: input.project_id };
+      }
+      if (asPhase(project.currentPhase) !== 'implementation') {
+        return {
+          error: 'INVALID_PHASE',
+          current_phase: project.currentPhase,
+          required_phase: 'implementation',
+        };
+      }
+
+      // Find the claim for this module
+      const claim = engine.getClaimByModule(input.project_id, input.module);
+      if (!claim) {
+        return {
+          error: 'CLAIM_NOT_FOUND',
+          module: input.module,
+          message: 'No active claim found for this module. Call forge.start_implementation first.',
+        };
+      }
+
+      const summaryContent = JSON.stringify({
+        module: input.module,
+        branch: input.branch,
+        summary: input.summary,
+        files_changed: input.files_changed,
+      });
+
+      const { remainingCount, allComplete } = engine.completeClaim(
+        claim.id,
+        summaryContent,
+      );
+
+      // Record in phase_outputs
+      engine.completePhase(
+        input.project_id,
+        'implementation',
+        'code',
+        summaryContent,
+        {
+          agent: claim.agent,
+          advanceTo: allComplete ? 'inspection' : undefined,
+          metadata: {
+            module: input.module,
+            files_changed: input.files_changed,
+          },
+        },
+      );
+
+      const knowledgeExtracted = extractKnowledgeCandidates(input.summary ?? '');
+
+      // Auto-broadcast module completion so sibling agents can see it via both
+      // SQLite (get_broadcasts tool) and Qdrant (getRecentBroadcasts in context injection)
+      const filesStr = (input.files_changed ?? []).join(', ');
+      const broadcastContent = `MODULE COMPLETED: ${input.module}\nFILES: ${filesStr}\nSUMMARY: ${input.summary ?? 'no summary'}`;
+      try {
+        engine.recordBroadcast(input.project_id, broadcastContent, 'info');
+      } catch (err) {
+        logger.debug('submitImplementation: auto-broadcast (sqlite) failed (non-fatal)', { error: String(err) });
+      }
+
+      // Fire-and-forget: save as agent_broadcast observation (Qdrant) so
+      // getRecentBroadcasts picks it up for sibling context injection
+      autoObserve(broadcastContent, {
+        category: 'agent_broadcast',
+        importance: 0.5,
+        projectId: input.project_id,
+        phase: 'implementation',
+        vectorStore,
+        graphStore,
+      });
+
+      autoExtractKnowledge(input.summary ?? '', {
+        projectId: input.project_id,
+        phase: 'implementation',
+        vectorStore,
+        graphStore,
+      });
+
+      return {
+        project_id: input.project_id,
+        module: input.module,
+        claim_status: 'completed' as const,
+        remaining_claims: remainingCount,
+        all_complete: allComplete,
+        phase: allComplete ? 'inspection' : ('implementation' as Phase),
+        knowledge_extracted: knowledgeExtracted,
+      };
+    } catch (err) {
+      logger.error('submit_implementation: error', { error: String(err) });
+      return { error: 'SUBMIT_IMPLEMENTATION_FAILED', message: String(err) };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // forge.start_inspection
+  // ---------------------------------------------------------------------------
+  async function startInspection(input: z.infer<typeof startInspectionSchema>) {
+    try {
+      const result = engine.startPhase(input.project_id, 'inspection', 'inspector');
+      if ('error' in result) {
+        return result;
+      }
+
+      const cycleCounts = engine.getCycleCounts(input.project_id);
+      const cycleCount = cycleCounts['inspection_to_implementation'] ?? 0;
+      const maxCycles = 3;
+
+      // Get arch and test plan for checklist generation
+      const archOutput = engine.getPhaseOutput(input.project_id, 'architecture');
+      const testPlanOutput = engine.getPhaseOutput(input.project_id, 'qa_strategy');
+
+      const checklist = buildInspectionChecklist(
+        archOutput?.content ?? '',
+        testPlanOutput?.content ?? '',
+      );
+
+      // Search for past inspection findings and implementation broadcasts
+      let pastFindings: Array<{ description: string; severity: string; resolution: string; source_repo: string }> = [];
+      let implementationBroadcasts: Array<{ content: string; severity: string; created_at: number }> = [];
+      try {
+        const ctx = await contextInjector.injectInspectionContext(input.project_id);
+        pastFindings = ctx.pastFindings.map(f => ({
+          description: f.description,
+          severity: f.severity,
+          resolution: f.resolution,
+          source_repo: f.sourceRepo,
+        }));
+        implementationBroadcasts = ctx.broadcasts;
+      } catch (ctxErr) {
+        logger.warn('start_inspection: context injection failed', { error: String(ctxErr) });
+      }
+
+      return {
+        project_id: input.project_id,
+        phase: 'inspection' as Phase,
+        checklist,
+        past_findings: pastFindings,
+        implementation_broadcasts: implementationBroadcasts,
+        anti_stub_patterns: ANTI_STUB_PATTERNS,
+        cycle_count: cycleCount,
+        max_cycles: maxCycles,
+        trajectory_id: result.trajectoryId,
+        available_transitions: result.availableTransitions,
+      };
+    } catch (err) {
+      logger.error('start_inspection: error', { error: String(err) });
+      return { error: 'START_INSPECTION_FAILED', message: String(err) };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // forge.submit_verdict
+  // ---------------------------------------------------------------------------
+  async function submitVerdict(input: z.infer<typeof submitVerdictSchema>) {
+    try {
+      const project = engine.getProject(input.project_id);
+      if (!project) {
+        return { error: 'PROJECT_NOT_FOUND', project_id: input.project_id };
+      }
+      if (asPhase(project.currentPhase) !== 'inspection') {
+        return {
+          error: 'INVALID_PHASE',
+          current_phase: project.currentPhase,
+          required_phase: 'inspection',
+        };
+      }
+
+      const trajectory = engine.getActiveTrajectory(input.project_id, 'inspection');
+      const cycleCounts = engine.getCycleCounts(input.project_id);
+      const cycleCount = cycleCounts['inspection_to_implementation'] ?? 0;
+
+      const isPassing = input.verdict === 'pass' || input.verdict === 'pass_with_warnings';
+      const nextPhase: Phase = isPassing ? 'knowledge_collection' : 'implementation';
+
+      const verdictContent = JSON.stringify({
+        verdict: input.verdict,
+        findings: input.findings ?? [],
+        summary: input.summary,
+      });
+
+      engine.completePhase(
+        input.project_id,
+        'inspection',
+        'verdict',
+        verdictContent,
+        {
+          agent: 'inspector',
+          advanceTo: nextPhase,
+          trajectoryId: trajectory?.id,
+          qualityScore: isPassing ? 1.0 : 0.0,
+          metadata: {
+            verdict: input.verdict,
+            findings_count: input.findings?.length ?? 0,
+          },
+        },
+      );
+
+      if (trajectory) {
+        engine.completeTrajectory(trajectory.id, isPassing, input.summary);
+      }
+
+      const findingsSummary = (input.findings ?? []).map(f => f.description).join('\n');
+      const knowledgeExtracted = extractKnowledgeCandidates(findingsSummary);
+
+      // Fire-and-forget auto-observation
+      autoObserve(
+        `Verdict: ${input.verdict}. ${input.summary ?? ''}\n${findingsSummary}`.trim(),
+        {
+          category: 'inspection',
+          importance: 0.7,
+          projectId: input.project_id,
+          phase: 'inspection',
+          vectorStore,
+          graphStore,
+        },
+      );
+
+      autoExtractKnowledge(input.summary ?? '', {
+        projectId: input.project_id,
+        phase: 'inspection',
+        vectorStore,
+        graphStore,
+      });
+
+      const response: Record<string, unknown> = {
+        project_id: input.project_id,
+        verdict: input.verdict,
+        phase: nextPhase,
+        cycle_count: cycleCount,
+        knowledge_extracted: knowledgeExtracted,
+      };
+
+      if (!isPassing && input.findings && input.findings.length > 0) {
+        const criticalFindings = input.findings
+          .filter(f => f.severity === 'critical')
+          .map(f => `- ${f.description}${f.file_path ? ` (${f.file_path})` : ''}`)
+          .join('\n');
+        response['fix_instructions'] =
+          `## Required Fixes (${input.findings.filter(f => f.severity === 'critical').length} critical)\n\n${criticalFindings}`;
+      }
+
+      return response;
+    } catch (err) {
+      logger.error('submit_verdict: error', { error: String(err) });
+      return { error: 'SUBMIT_VERDICT_FAILED', message: String(err) };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // forge.collect_knowledge
+  // ---------------------------------------------------------------------------
+  async function collectKnowledge(input: z.infer<typeof collectKnowledgeSchema>) {
+    try {
+      const project = engine.getProject(input.project_id);
+      if (!project) {
+        return { error: 'PROJECT_NOT_FOUND', project_id: input.project_id };
+      }
+      if (asPhase(project.currentPhase) !== 'knowledge_collection') {
+        return {
+          error: 'INVALID_PHASE',
+          current_phase: project.currentPhase,
+          required_phase: 'knowledge_collection',
+        };
+      }
+
+      // Collect all phase outputs to extract knowledge
+      const allOutputs = engine.getAllPhaseOutputs(input.project_id);
+      const { history } = engine.getHistory(input.project_id);
+
+      const knowledgeItems: Array<{
+        category: string;
+        title: string;
+        content: string;
+        confidence: number;
+        destination: string;
+      }> = [];
+
+      // Extract from architecture plan
+      const archOutput = allOutputs.find(o => o.outputType === 'architecture');
+      if (archOutput) {
+        const candidates = extractStructuredKnowledge(archOutput.content, 'architecture');
+        knowledgeItems.push(...candidates);
+      }
+
+      // Extract from verdict findings
+      const verdictOutput = allOutputs.find(o => o.outputType === 'verdict');
+      if (verdictOutput) {
+        try {
+          const verdict = JSON.parse(verdictOutput.content) as { findings?: Array<{ description: string; severity: string }> };
+          for (const finding of verdict.findings ?? []) {
+            knowledgeItems.push({
+              category: 'gotcha',
+              title: `Inspection finding: ${finding.description.slice(0, 60)}`,
+              content: finding.description,
+              confidence: finding.severity === 'critical' ? 0.8 : 0.5,
+              destination: '.forge/knowledge/gotchas.yaml',
+            });
+          }
+        } catch {}
+      }
+
+      // Advance to completed
+      const trajectory = engine.getActiveTrajectory(input.project_id, 'knowledge_collection');
+      engine.completePhase(
+        input.project_id,
+        'knowledge_collection',
+        'knowledge',
+        JSON.stringify(knowledgeItems),
+        {
+          agent: 'knowledge-keeper',
+          advanceTo: 'completed',
+          trajectoryId: trajectory?.id,
+        },
+      );
+
+      if (trajectory) {
+        engine.completeTrajectory(trajectory.id, true);
+      }
+
+      // Compute trajectory summary
+      const startedAt = project.createdAt;
+      const completedAt = Date.now();
+      const durationMinutes = Math.round((completedAt - startedAt) / 60000);
+
+      return {
+        project_id: input.project_id,
+        phase: 'completed' as Phase,
+        knowledge_items: knowledgeItems,
+        trajectory_summary: {
+          total_steps: allOutputs.length,
+          phases_completed: history.filter(h => h.completedAt).length,
+          cycles: engine.getCycleCounts(input.project_id),
+          duration_minutes: durationMinutes,
+        },
+        patterns_promoted: knowledgeItems.filter(k => k.category === 'pattern').length,
+      };
+    } catch (err) {
+      logger.error('collect_knowledge: error', { error: String(err) });
+      return { error: 'COLLECT_KNOWLEDGE_FAILED', message: String(err) };
+    }
+  }
+
+  // Return all tools
+  return {
+    'start_interview': {
+      schema: startInterviewSchema,
+      description: 'Start the strategist interview phase for a project',
+      handler: startInterview,
+    },
+    'submit_vision': {
+      schema: submitVisionSchema,
+      description: 'Submit the vision document and advance to architecture phase',
+      handler: submitVision,
+    },
+    'start_architecture': {
+      schema: startArchitectureSchema,
+      description: 'Start the architecture phase with auto-injected codebase context',
+      handler: startArchitecture,
+    },
+    'submit_plan': {
+      schema: submitPlanSchema,
+      description: 'Submit the architecture plan and advance to the next phase',
+      handler: submitPlan,
+    },
+    'start_design': {
+      schema: startDesignSchema,
+      description: 'Start the designer phase for XD/UX planning',
+      handler: startDesign,
+    },
+    'submit_design': {
+      schema: submitDesignSchema,
+      description: 'Submit the design plan and advance to qa_strategy or implementation',
+      handler: submitDesign,
+    },
+    'start_qa_strategy': {
+      schema: startQAStrategySchema,
+      description: 'Start the QA strategy phase to produce a test plan',
+      handler: startQAStrategy,
+    },
+    'submit_test_plan': {
+      schema: submitTestPlanSchema,
+      description: 'Submit the test plan and advance to implementation',
+      handler: submitTestPlan,
+    },
+    'start_implementation': {
+      schema: startImplementationSchema,
+      description: 'Start parallel implementation with per-module claims and context',
+      handler: startImplementation,
+    },
+    'submit_implementation': {
+      schema: submitImplementationSchema,
+      description: 'Submit completion of a single implementation module',
+      handler: submitImplementation,
+    },
+    'start_inspection': {
+      schema: startInspectionSchema,
+      description: 'Start the inspection phase with auto-generated checklist',
+      handler: startInspection,
+    },
+    'submit_verdict': {
+      schema: submitVerdictSchema,
+      description: 'Submit inspection verdict: pass advances to knowledge collection, fail returns to implementation',
+      handler: submitVerdict,
+    },
+    'collect_knowledge': {
+      schema: collectKnowledgeSchema,
+      description: 'Final phase: extract learnings from the entire pipeline run',
+      handler: collectKnowledge,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Static helpers / templates
+// ---------------------------------------------------------------------------
+
+const DEFAULT_INTERVIEW_TEMPLATE = `# Vision Interview
+
+## 1. What are we building?
+Describe the feature or system in plain language.
+
+## 2. Why does it matter?
+What problem does this solve for users?
+
+## 3. Success criteria
+What does "done" look like? How will we know it works?
+
+## 4. Constraints and non-goals
+What are we explicitly NOT doing? What technical constraints apply?
+
+## 5. Key risks
+What could go wrong? What are the biggest unknowns?
+
+## 6. Timeline and scope
+Is this a quick fix, a medium feature, or a major project?
+`;
+
+const ANTI_STUB_PATTERNS = [
+  'TODO: implement later',
+  'return { success: true } without actual logic',
+  'guard that unconditionally returns true',
+  'service method with empty body',
+  'catch block that silently swallows errors',
+  'hardcoded return values instead of database queries',
+  'unregistered providers in module wiring',
+  'missing imports in module declarations',
+];
+
+function buildInspectionChecklist(archPlan: string, testPlan: string): string {
+  const sections = [
+    '## Inspection Checklist\n',
+    '### Build & Compilation',
+    '- [ ] `tsc --noEmit` passes with no errors',
+    '- [ ] All imports resolve (no unresolved module errors)',
+    '- [ ] No circular dependency warnings\n',
+    '### Wiring & Registration',
+    '- [ ] All providers registered in their modules',
+    '- [ ] All module imports declared',
+    '- [ ] No unregistered injectable services\n',
+    '### Anti-Stub Verification',
+    '- [ ] No TODO comments in production code paths',
+    '- [ ] All service methods execute real logic (no placeholder returns)',
+    '- [ ] All guards perform real authentication checks',
+    '- [ ] All error cases handled with appropriate HTTP exceptions\n',
+    '### Security',
+    '- [ ] No hardcoded secrets or credentials',
+    '- [ ] Authentication applied to protected endpoints',
+    '- [ ] Input validation present on all endpoints\n',
+  ];
+
+  if (archPlan.length > 0) {
+    sections.push('### Architecture Compliance');
+    sections.push('- [ ] Implementation matches the architecture plan');
+    sections.push('- [ ] Module boundaries respected');
+    sections.push('- [ ] Database schema matches design\n');
+  }
+
+  if (testPlan.length > 0) {
+    sections.push('### Test Coverage');
+    sections.push('- [ ] Critical paths covered by tests');
+    sections.push('- [ ] Tests pass without mocks for integration paths\n');
+  }
+
+  return sections.join('\n');
+}
+
+function extractStructuredKnowledge(content: string, phase: string): Array<{
+  category: string;
+  title: string;
+  content: string;
+  confidence: number;
+  destination: string;
+}> {
+  const items: Array<{
+    category: string;
+    title: string;
+    content: string;
+    confidence: number;
+    destination: string;
+  }> = [];
+
+  // Extract ADR-style decisions
+  const adrPattern = /### ADR[-\s]?\d+:?\s+([^\n]+)\n([\s\S]*?)(?=###|\Z)/gi;
+  let match;
+  while ((match = adrPattern.exec(content)) !== null) {
+    const title = (match[1] ?? '').trim();
+    const body = (match[2] ?? '').trim().slice(0, 500);
+    if (title && body) {
+      items.push({
+        category: 'decision',
+        title: `[${phase}] ${title}`,
+        content: body,
+        confidence: 0.7,
+        destination: '.forge/knowledge/decisions.yaml',
+      });
+    }
+  }
+
+  return items;
+}
+
+async function detectDesignSystem(
+  _projectId: string,
+  _engine: PipelineEngine,
+): Promise<{
+  found: boolean;
+  summary?: string;
+  theme_files?: string[];
+  component_count?: number;
+}> {
+  // Look for common design system indicators in codebase
+  // This is a best-effort detection — returns not-found if detection fails
+  try {
+    const commonDesignFiles = [
+      'tailwind.config.js',
+      'tailwind.config.ts',
+      'theme.ts',
+      'theme.js',
+      'tokens.css',
+      'design-system',
+    ];
+
+    // Check if any design system files exist in common locations
+    const { existsSync } = await import('node:fs');
+    const foundFiles = commonDesignFiles.filter(f => {
+      try { return existsSync(f); } catch { return false; }
+    });
+
+    if (foundFiles.length > 0) {
+      return {
+        found: true,
+        summary: `Design system files detected: ${foundFiles.join(', ')}`,
+        theme_files: foundFiles,
+        component_count: undefined,
+      };
+    }
+
+    return { found: false };
+  } catch {
+    return { found: false };
+  }
+}