forge-server 0.1.0

package/dist/tools/phase-tools.js

@@ -0,0 +1,1215 @@
+// 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 { 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) {
+    return p;
+}
+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, filePath) {
+    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) {
+    // 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 = {
+    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, opts) {
+    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, opts) {
+    if (!opts.vectorStore) {
+        logger.debug('autoExtractKnowledge: vectorStore unavailable, skipping', { phase: opts.phase });
+        return;
+    }
+    const lines = content.split('\n');
+    const extractions = [];
+    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, contextInjector, vectorStore = null, graphStore = null) {
+    // ---------------------------------------------------------------------------
+    // forge.start_interview
+    // ---------------------------------------------------------------------------
+    async function startInterview(input) {
+        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',
+                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) {
+        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',
+                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) {
+        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',
+                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) {
+        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 = 'implementation';
+            const parallelPhases = [];
+            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) {
+        try {
+            const result = engine.startPhase(input.project_id, 'design', 'designer');
+            if ('error' in result) {
+                return result;
+            }
+            // Search for design patterns
+            let relevantPatterns = [];
+            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',
+                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) {
+        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;
+            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) {
+        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 = [];
+            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',
+                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) {
+        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',
+                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) {
+        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',
+                };
+            });
+            // Inject per-module context
+            const moduleContexts = {};
+            let injectedContexts = {};
+            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',
+                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) {
+        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',
+                remaining_claims: remainingCount,
+                all_complete: allComplete,
+                phase: allComplete ? 'inspection' : 'implementation',
+                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) {
+        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 = [];
+            let implementationBroadcasts = [];
+            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',
+                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) {
+        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 = 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 = {
+                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) {
+        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 = [];
+            // 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);
+                    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',
+                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, testPlan) {
+    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, phase) {
+    const items = [];
+    // 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, _engine) {
+    // 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 };
+    }
+}
+//# sourceMappingURL=phase-tools.js.map