vibn-frontend/lib/types/phase-handoff.ts

/**
 * Phase Handoff Protocol
 * 
 * Defines the structured handoff between phases in the Vibn workflow.
 * Each phase (extraction, vision, mvp, marketing) produces a handoff that:
 * - Declares confidence and readiness for next phase
 * - Separates confirmed facts from uncertain/missing items
 * - Provides questions to resolve ambiguity
 * - References source evidence
 */

/**
 * Phase identifier for handoffs
 */
export type PhaseType = 'collector' | 'extraction' | 'vision' | 'mvp' | 'marketing';

/**
 * Structured handoff between phases
 * 
 * Produced by each phase agent to communicate confidence, gaps, and questions
 * to the next phase or back to the user.
 */
export interface PhaseHandoff {
  /** Which phase produced this handoff */
  phase: PhaseType;
  
  /** Is this phase ready to hand off to the next one? */
  readyForNextPhase: boolean;
  
  /** Overall confidence score (0-1) for this phase's outputs */
  confidence: number;
  
  /** Items that are confirmed and high-confidence */
  confirmed: Record<string, any>;
  
  /** Items that are uncertain or low-confidence */
  uncertain: Record<string, any>;
  
  /** Items that are completely missing or unknown */
  missing: string[];
  
  /** Questions for the user to resolve gaps or ambiguity */
  questionsForUser: string[];
  
  /** References to source knowledge items or extractions that support this handoff */
  sourceEvidence: string[];
  
  /** Version of the handoff schema (for future evolution) */
  version: string;
  
  /** When this handoff was created */
  timestamp: string;
  
  /** Optional metadata specific to this phase */
  metadata?: Record<string, any>;
}

/**
 * Handoff from the Collector phase
 * 
 * After gathering project materials, confirm readiness for extraction.
 */
export interface CollectorPhaseHandoff extends PhaseHandoff {
  phase: 'collector';
  
  /** Checklist status */
  confirmed: {
    /** Has user uploaded documents? */
    hasDocuments?: boolean;
    
    /** Number of documents uploaded */
    documentCount?: number;
    
    /** Has user connected GitHub repo? */
    githubConnected?: boolean;
    
    /** GitHub repo full name (e.g., 'user/repo') */
    githubRepo?: string;
    
    /** Has user installed browser extension and linked to project? */
    extensionLinked?: boolean;
  };
  
  /** Items the user said "no" or "not yet" to */
  uncertain: {
    /** User declined or hasn't set up extension */
    extensionDeclined?: boolean;
    
    /** User doesn't have a GitHub repo yet */
    noGithubYet?: boolean;
  };
  
  /** What's missing before moving to extraction */
  missing: string[]; // e.g., ["documents", "github repo", "extension"]
}

/**
 * Handoff from the Extraction phase
 * 
 * After analyzing all chat_extractions, summarize what's known about the product.
 */
export interface ExtractionPhaseHandoff extends PhaseHandoff {
  phase: 'extraction';
  
  /** High-confidence product signals */
  confirmed: {
    /** Product one-liner (if clear) */
    oneLiner?: string;
    
    /** Core problem statement */
    problemStatement?: string;
    
    /** Target user personas */
    targetUsers?: string[];
    
    /** Confirmed features */
    features?: string[];
    
    /** Known tech stack */
    techStack?: string[];
  };
  
  /** Low-confidence or conflicting signals */
  uncertain: {
    /** Ambiguous or conflicting features */
    features?: string[];
    
    /** Unclear business model */
    businessModel?: string;
  };
  
  /** What's missing to build a solid product model */
  missing: string[]; // e.g., ["target market size", "pricing strategy"]
}

/**
 * Handoff from the Vision phase
 * 
 * After creating canonicalProductModel, declare what's locked vs tentative.
 */
export interface VisionPhaseHandoff extends PhaseHandoff {
  phase: 'vision';
  
  confirmed: {
    /** Core value proposition (locked) */
    valueProposition?: string;
    
    /** Primary user persona (locked) */
    primaryPersona?: string;
    
    /** Must-have features for MVP */
    mustHaveFeatures?: string[];
  };
  
  uncertain: {
    /** Nice-to-have features (not decided for MVP) */
    niceToHaveFeatures?: string[];
    
    /** Unclear scope decisions */
    scopeDecisions?: string[];
  };
  
  missing: string[]; // e.g., ["competitive analysis", "pricing model"]
}

/**
 * Handoff from the MVP phase
 * 
 * After creating mvpPlan, declare what's ready to build vs needs clarification.
 */
export interface MVPPhaseHandoff extends PhaseHandoff {
  phase: 'mvp';
  
  confirmed: {
    /** Locked feature scope */
    featureScope?: string[];
    
    /** Tech stack decisions */
    techStack?: string[];
    
    /** Build timeline estimate */
    timelineEstimate?: string;
  };
  
  uncertain: {
    /** Features with unclear requirements */
    unclearFeatures?: string[];
    
    /** Technical risks or unknowns */
    technicalRisks?: string[];
  };
  
  missing: string[]; // e.g., ["API design", "database schema"]
}

/**
 * Handoff from the Marketing phase
 * 
 * After creating marketingPlan, declare launch readiness.
 */
export interface MarketingPhaseHandoff extends PhaseHandoff {
  phase: 'marketing';
  
  confirmed: {
    /** Launch channels */
    launchChannels?: string[];
    
    /** Target launch date */
    launchDate?: string;
    
    /** Marketing messaging */
    messaging?: string;
  };
  
  uncertain: {
    /** Unconfirmed distribution channels */
    uncertainChannels?: string[];
    
    /** Budget constraints */
    budgetConstraints?: string;
  };
  
  missing: string[]; // e.g., ["landing page copy", "email sequences"]
}

/**
 * Union type for all phase handoffs
 */
export type AnyPhaseHandoff =
  | CollectorPhaseHandoff
  | ExtractionPhaseHandoff
  | VisionPhaseHandoff
  | MVPPhaseHandoff
  | MarketingPhaseHandoff;

/**
 * Helper to create a minimal phase handoff
 */
export function createPhaseHandoff(
  phase: PhaseType,
  partial: Partial<PhaseHandoff>
): PhaseHandoff {
  return {
    phase,
    readyForNextPhase: false,
    confidence: 0.5,
    confirmed: {},
    uncertain: {},
    missing: [],
    questionsForUser: [],
    sourceEvidence: [],
    version: '1.0',
    timestamp: new Date().toISOString(),
    ...partial,
  };
}