@girardmedia/bootspring 1.2.0 → 2.0.3

package/core/preseed-workflow.js

@@ -0,0 +1,934 @@
+/**
+ * Bootspring Preseed Workflow Engine
+ *
+ * Professional-grade approval workflow for AI-assisted document generation.
+ * Handles state machine, versioning, phase dependencies, and quality gates.
+ *
+ * @package bootspring
+ * @module core/preseed-workflow
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const crypto = require('crypto');
+
+/**
+ * Document lifecycle states
+ */
+const DOCUMENT_STATUS = {
+  EMPTY: 'empty',
+  DRAFT: 'draft',
+  IN_REVIEW: 'in_review',
+  APPROVED: 'approved',
+  REJECTED: 'rejected',
+  LOCKED: 'locked'
+};
+
+/**
+ * Workflow modes
+ */
+const WORKFLOW_MODE = {
+  GENERATION: 'generation',
+  REVIEW: 'review',
+  APPROVAL: 'approval'
+};
+
+/**
+ * Phase definitions with dependencies
+ */
+const WORKFLOW_PHASES = {
+  foundation: {
+    name: 'Foundation',
+    description: 'Core vision and audience definition',
+    documents: ['vision', 'audience'],
+    dependencies: [],
+    parallel: true
+  },
+  market: {
+    name: 'Market Analysis',
+    description: 'Market opportunity and competitive landscape',
+    documents: ['market', 'competitors'],
+    dependencies: ['foundation'],
+    parallel: true
+  },
+  business: {
+    name: 'Business Model',
+    description: 'Revenue model and pricing strategy',
+    documents: ['business-model'],
+    dependencies: ['foundation'],
+    parallel: false
+  },
+  product: {
+    name: 'Product Definition',
+    description: 'Product requirements and specifications',
+    documents: ['prd'],
+    dependencies: ['foundation', 'market', 'business'],
+    parallel: false
+  },
+  technical: {
+    name: 'Technical Specification',
+    description: 'Architecture and implementation details',
+    documents: ['technical-spec'],
+    dependencies: ['product'],
+    parallel: false
+  },
+  execution: {
+    name: 'Execution Planning',
+    description: 'Roadmap and milestones',
+    documents: ['roadmap'],
+    dependencies: ['product'],
+    parallel: false
+  }
+};
+
+/**
+ * Quality check criteria per document type
+ */
+const QUALITY_CRITERIA = {
+  vision: {
+    completeness: [
+      { id: 'problem', label: 'Problem statement defined', weight: 20 },
+      { id: 'solution', label: 'Solution overview provided', weight: 20 },
+      { id: 'value', label: 'Unique value proposition', weight: 15 },
+      { id: 'why_now', label: 'Why now timing explained', weight: 10 },
+      { id: 'features', label: 'Key features listed', weight: 15 }
+    ],
+    clarity: [
+      { id: 'specific', label: 'Specific and measurable', weight: 10 },
+      { id: 'actionable', label: 'Actionable next steps', weight: 10 }
+    ]
+  },
+  audience: {
+    completeness: [
+      { id: 'primary', label: 'Primary audience defined', weight: 25 },
+      { id: 'segments', label: 'Market segments identified', weight: 20 },
+      { id: 'personas', label: 'User personas created', weight: 25 },
+      { id: 'icp', label: 'Ideal customer profile', weight: 20 }
+    ],
+    clarity: [
+      { id: 'specific', label: 'Specific demographics', weight: 10 }
+    ]
+  },
+  market: {
+    completeness: [
+      { id: 'tam', label: 'TAM calculated', weight: 20 },
+      { id: 'sam', label: 'SAM calculated', weight: 20 },
+      { id: 'som', label: 'SOM projected', weight: 20 },
+      { id: 'trends', label: 'Market trends identified', weight: 20 }
+    ],
+    clarity: [
+      { id: 'sources', label: 'Data sources cited', weight: 10 },
+      { id: 'growth', label: 'Growth projections', weight: 10 }
+    ]
+  },
+  competitors: {
+    completeness: [
+      { id: 'direct', label: 'Direct competitors listed', weight: 25 },
+      { id: 'indirect', label: 'Indirect competitors noted', weight: 15 },
+      { id: 'positioning', label: 'Positioning defined', weight: 25 },
+      { id: 'differentiation', label: 'Differentiators identified', weight: 25 }
+    ],
+    clarity: [
+      { id: 'strengths', label: 'Strengths/weaknesses analyzed', weight: 10 }
+    ]
+  },
+  'business-model': {
+    completeness: [
+      { id: 'model', label: 'Business model type', weight: 20 },
+      { id: 'revenue', label: 'Revenue streams defined', weight: 25 },
+      { id: 'pricing', label: 'Pricing strategy set', weight: 25 },
+      { id: 'economics', label: 'Unit economics calculated', weight: 20 }
+    ],
+    clarity: [
+      { id: 'scalable', label: 'Scalability addressed', weight: 10 }
+    ]
+  },
+  prd: {
+    completeness: [
+      { id: 'vision', label: 'Product vision stated', weight: 15 },
+      { id: 'mvp', label: 'MVP features defined', weight: 25 },
+      { id: 'stories', label: 'User stories written', weight: 25 },
+      { id: 'acceptance', label: 'Acceptance criteria', weight: 20 }
+    ],
+    clarity: [
+      { id: 'priority', label: 'Priorities clear', weight: 10 },
+      { id: 'scope', label: 'Scope boundaries set', weight: 5 }
+    ]
+  },
+  'technical-spec': {
+    completeness: [
+      { id: 'stack', label: 'Tech stack defined', weight: 25 },
+      { id: 'architecture', label: 'Architecture documented', weight: 25 },
+      { id: 'integrations', label: 'Integrations listed', weight: 20 },
+      { id: 'constraints', label: 'Constraints noted', weight: 15 }
+    ],
+    clarity: [
+      { id: 'diagrams', label: 'Diagrams included', weight: 10 },
+      { id: 'decisions', label: 'Decision rationale', weight: 5 }
+    ]
+  },
+  roadmap: {
+    completeness: [
+      { id: 'phases', label: 'Development phases', weight: 30 },
+      { id: 'milestones', label: 'Milestones defined', weight: 25 },
+      { id: 'timeline', label: 'Timeline estimated', weight: 25 }
+    ],
+    clarity: [
+      { id: 'dependencies', label: 'Dependencies mapped', weight: 10 },
+      { id: 'measurable', label: 'Measurable outcomes', weight: 10 }
+    ]
+  }
+};
+
+/**
+ * Default workflow state
+ */
+const DEFAULT_WORKFLOW_STATE = {
+  version: '1.0.0',
+  currentPhase: null,
+  currentDocument: null,
+  mode: WORKFLOW_MODE.GENERATION,
+  resumePoint: null,
+  startedAt: null,
+  lastUpdated: null,
+  documents: {},
+  phases: {},
+  overrides: []
+};
+
+/**
+ * PreseedWorkflowEngine - Manages document approval workflow
+ */
+class PreseedWorkflowEngine {
+  constructor(projectRoot, options = {}) {
+    this.projectRoot = projectRoot;
+    this.preseedDir = path.join(projectRoot, '.bootspring', 'preseed');
+    this.draftsDir = path.join(this.preseedDir, 'drafts');
+    this.approvedDir = path.join(this.preseedDir, 'approved');
+    this.historyDir = path.join(this.preseedDir, 'history');
+    this.stateFile = path.join(this.preseedDir, 'workflow-state.json');
+    this.options = options;
+    this.state = null;
+  }
+
+  /**
+   * Initialize workflow directories
+   */
+  setupDirectories() {
+    const dirs = [this.preseedDir, this.draftsDir, this.approvedDir, this.historyDir];
+    for (const dir of dirs) {
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+    }
+  }
+
+  /**
+   * Load workflow state from file
+   */
+  loadState() {
+    if (fs.existsSync(this.stateFile)) {
+      try {
+        this.state = JSON.parse(fs.readFileSync(this.stateFile, 'utf-8'));
+        return true;
+      } catch (_e) {
+        this.state = { ...DEFAULT_WORKFLOW_STATE };
+        return false;
+      }
+    }
+    this.state = { ...DEFAULT_WORKFLOW_STATE };
+    return false;
+  }
+
+  /**
+   * Save workflow state to file
+   */
+  saveState() {
+    this.setupDirectories();
+    this.state.lastUpdated = new Date().toISOString();
+    fs.writeFileSync(this.stateFile, JSON.stringify(this.state, null, 2));
+  }
+
+  /**
+   * Initialize a new workflow
+   */
+  initializeWorkflow() {
+    this.setupDirectories();
+    this.state = {
+      ...DEFAULT_WORKFLOW_STATE,
+      startedAt: new Date().toISOString(),
+      lastUpdated: new Date().toISOString()
+    };
+
+    // Initialize phase states
+    for (const [phaseId, phase] of Object.entries(WORKFLOW_PHASES)) {
+      this.state.phases[phaseId] = {
+        status: 'pending',
+        documents: phase.documents.map(docType => docType)
+      };
+    }
+
+    // Initialize document states
+    for (const phase of Object.values(WORKFLOW_PHASES)) {
+      for (const docType of phase.documents) {
+        this.state.documents[docType] = {
+          status: DOCUMENT_STATUS.EMPTY,
+          version: 0,
+          qualityScore: null,
+          source: null,
+          feedback: [],
+          history: []
+        };
+      }
+    }
+
+    // Start with first phase
+    this.state.currentPhase = 'foundation';
+    this.state.currentDocument = WORKFLOW_PHASES.foundation.documents[0];
+    this.state.mode = WORKFLOW_MODE.GENERATION;
+
+    this.saveState();
+    return this.state;
+  }
+
+  /**
+   * Check if a phase's dependencies are met
+   */
+  arePhaseDependenciesMet(phaseId) {
+    const phase = WORKFLOW_PHASES[phaseId];
+    if (!phase || !phase.dependencies || phase.dependencies.length === 0) {
+      return true;
+    }
+
+    for (const depPhaseId of phase.dependencies) {
+      const depPhase = this.state.phases[depPhaseId];
+      if (!depPhase || depPhase.status !== 'completed') {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Check if all documents in a phase are approved
+   */
+  isPhaseComplete(phaseId) {
+    const phase = WORKFLOW_PHASES[phaseId];
+    if (!phase) return false;
+
+    for (const docType of phase.documents) {
+      const doc = this.state.documents[docType];
+      if (!doc || (doc.status !== DOCUMENT_STATUS.APPROVED && doc.status !== DOCUMENT_STATUS.LOCKED)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get the next available phase
+   */
+  getNextPhase(currentPhaseId) {
+    const phaseOrder = Object.keys(WORKFLOW_PHASES);
+    const currentIndex = phaseOrder.indexOf(currentPhaseId);
+
+    // Mark current phase as complete if all docs approved
+    if (this.isPhaseComplete(currentPhaseId)) {
+      this.state.phases[currentPhaseId].status = 'completed';
+    }
+
+    // Find next phase with met dependencies
+    for (let i = currentIndex + 1; i < phaseOrder.length; i++) {
+      const nextPhaseId = phaseOrder[i];
+      if (this.arePhaseDependenciesMet(nextPhaseId)) {
+        return nextPhaseId;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Get the next document to work on
+   */
+  getNextDocument() {
+    // First, try to find unapproved docs in current phase
+    if (this.state.currentPhase) {
+      const phase = WORKFLOW_PHASES[this.state.currentPhase];
+      for (const docType of phase.documents) {
+        const doc = this.state.documents[docType];
+        if (doc.status !== DOCUMENT_STATUS.APPROVED && doc.status !== DOCUMENT_STATUS.LOCKED) {
+          return { phase: this.state.currentPhase, document: docType };
+        }
+      }
+    }
+
+    // Try next phase
+    const nextPhase = this.getNextPhase(this.state.currentPhase);
+    if (nextPhase) {
+      const phase = WORKFLOW_PHASES[nextPhase];
+      return { phase: nextPhase, document: phase.documents[0] };
+    }
+
+    return null;
+  }
+
+  /**
+   * Get document filename
+   */
+  getDocumentFilename(docType) {
+    const names = {
+      vision: 'VISION.md',
+      audience: 'AUDIENCE.md',
+      market: 'MARKET.md',
+      competitors: 'COMPETITORS.md',
+      'business-model': 'BUSINESS_MODEL.md',
+      prd: 'PRD.md',
+      'technical-spec': 'TECHNICAL_SPEC.md',
+      roadmap: 'ROADMAP.md'
+    };
+    return names[docType] || `${docType.toUpperCase()}.md`;
+  }
+
+  /**
+   * Create a new draft version
+   */
+  createDraft(docType, content, source = 'generated') {
+    const doc = this.state.documents[docType];
+    const newVersion = doc.version + 1;
+    const filename = this.getDocumentFilename(docType);
+    const baseName = filename.replace('.md', '');
+    const draftPath = path.join(this.draftsDir, `${baseName}.v${newVersion}.md`);
+
+    // Write draft
+    fs.writeFileSync(draftPath, content);
+
+    // Update state
+    doc.version = newVersion;
+    doc.status = DOCUMENT_STATUS.DRAFT;
+    doc.source = source;
+    doc.history.push({
+      version: newVersion,
+      action: 'created',
+      timestamp: new Date().toISOString(),
+      source
+    });
+
+    this.saveState();
+
+    return {
+      path: draftPath,
+      version: newVersion,
+      docType
+    };
+  }
+
+  /**
+   * Get current draft path
+   */
+  getCurrentDraftPath(docType) {
+    const doc = this.state.documents[docType];
+    if (!doc || doc.version === 0) return null;
+
+    const filename = this.getDocumentFilename(docType);
+    const baseName = filename.replace('.md', '');
+    return path.join(this.draftsDir, `${baseName}.v${doc.version}.md`);
+  }
+
+  /**
+   * Get approved document path
+   */
+  getApprovedPath(docType) {
+    const filename = this.getDocumentFilename(docType);
+    return path.join(this.approvedDir, filename);
+  }
+
+  /**
+   * Read current draft content
+   */
+  readDraft(docType) {
+    const draftPath = this.getCurrentDraftPath(docType);
+    if (!draftPath || !fs.existsSync(draftPath)) return null;
+    return fs.readFileSync(draftPath, 'utf-8');
+  }
+
+  /**
+   * Calculate quality score for a document
+   */
+  calculateQualityScore(docType, content) {
+    const criteria = QUALITY_CRITERIA[docType];
+    if (!criteria) {
+      return { score: 100, breakdown: {} };
+    }
+
+    const breakdown = {
+      completeness: { score: 0, maxScore: 0, checks: [] },
+      clarity: { score: 0, maxScore: 0, checks: [] }
+    };
+
+    // Check completeness criteria
+    for (const check of criteria.completeness || []) {
+      breakdown.completeness.maxScore += check.weight;
+      // Simple heuristic: check if relevant sections exist
+      const passed = this.checkCriterion(check.id, docType, content);
+      if (passed) {
+        breakdown.completeness.score += check.weight;
+      }
+      breakdown.completeness.checks.push({
+        ...check,
+        passed
+      });
+    }
+
+    // Check clarity criteria
+    for (const check of criteria.clarity || []) {
+      breakdown.clarity.maxScore += check.weight;
+      const passed = this.checkCriterion(check.id, docType, content);
+      if (passed) {
+        breakdown.clarity.score += check.weight;
+      }
+      breakdown.clarity.checks.push({
+        ...check,
+        passed
+      });
+    }
+
+    const totalScore = breakdown.completeness.maxScore + breakdown.clarity.maxScore;
+    const earnedScore = breakdown.completeness.score + breakdown.clarity.score;
+    const score = totalScore > 0 ? Math.round((earnedScore / totalScore) * 100) : 0;
+
+    return {
+      score,
+      completeness: breakdown.completeness.maxScore > 0
+        ? Math.round((breakdown.completeness.score / breakdown.completeness.maxScore) * 100)
+        : 0,
+      clarity: breakdown.clarity.maxScore > 0
+        ? Math.round((breakdown.clarity.score / breakdown.clarity.maxScore) * 100)
+        : 0,
+      breakdown
+    };
+  }
+
+  /**
+   * Check a specific quality criterion
+   */
+  checkCriterion(criterionId, docType, content) {
+    const contentLower = content.toLowerCase();
+    const contentLength = content.length;
+
+    // Generic checks
+    const checks = {
+      // Vision checks
+      problem: () => contentLower.includes('problem') || contentLower.includes('challenge'),
+      solution: () => contentLower.includes('solution') || contentLower.includes('our approach'),
+      value: () => contentLower.includes('value') || contentLower.includes('unique'),
+      why_now: () => contentLower.includes('why now') || contentLower.includes('timing'),
+      features: () => contentLower.includes('feature') || contentLower.includes('capability'),
+
+      // Audience checks
+      primary: () => contentLower.includes('primary') || contentLower.includes('target'),
+      segments: () => contentLower.includes('segment'),
+      personas: () => contentLower.includes('persona'),
+      icp: () => contentLower.includes('ideal customer') || contentLower.includes('icp'),
+
+      // Market checks
+      tam: () => contentLower.includes('tam') || contentLower.includes('total addressable'),
+      sam: () => contentLower.includes('sam') || contentLower.includes('serviceable addressable'),
+      som: () => contentLower.includes('som') || contentLower.includes('serviceable obtainable'),
+      trends: () => contentLower.includes('trend'),
+      sources: () => contentLower.includes('source') || contentLower.includes('data'),
+      growth: () => contentLower.includes('growth') || contentLower.includes('%'),
+
+      // Competitor checks
+      direct: () => contentLower.includes('direct competitor'),
+      indirect: () => contentLower.includes('indirect') || contentLower.includes('alternative'),
+      positioning: () => contentLower.includes('position'),
+      differentiation: () => contentLower.includes('differenti') || contentLower.includes('unique'),
+      strengths: () => contentLower.includes('strength') || contentLower.includes('weakness'),
+
+      // Business model checks
+      model: () => contentLower.includes('model') || contentLower.includes('subscription') || contentLower.includes('freemium'),
+      revenue: () => contentLower.includes('revenue'),
+      pricing: () => contentLower.includes('pricing') || contentLower.includes('$'),
+      economics: () => contentLower.includes('cac') || contentLower.includes('ltv') || contentLower.includes('economics'),
+      scalable: () => contentLower.includes('scale') || contentLower.includes('growth'),
+
+      // PRD checks
+      vision: () => contentLower.includes('vision') || contentLower.includes('goal'),
+      mvp: () => contentLower.includes('mvp') || contentLower.includes('minimum viable'),
+      stories: () => contentLower.includes('user story') || contentLower.includes('as a'),
+      acceptance: () => contentLower.includes('acceptance') || contentLower.includes('criteria'),
+      priority: () => contentLower.includes('priority') || contentLower.includes('p1') || contentLower.includes('must'),
+      scope: () => contentLower.includes('scope') || contentLower.includes('out of scope'),
+
+      // Technical spec checks
+      stack: () => contentLower.includes('stack') || contentLower.includes('technology'),
+      architecture: () => contentLower.includes('architecture') || contentLower.includes('design'),
+      integrations: () => contentLower.includes('integration') || contentLower.includes('api'),
+      constraints: () => contentLower.includes('constraint') || contentLower.includes('requirement'),
+      diagrams: () => contentLower.includes('diagram') || contentLower.includes('```') || contentLength > 2000,
+      decisions: () => contentLower.includes('decision') || contentLower.includes('chose') || contentLower.includes('rationale'),
+
+      // Roadmap checks
+      phases: () => contentLower.includes('phase') || contentLower.includes('stage'),
+      milestones: () => contentLower.includes('milestone'),
+      timeline: () => contentLower.includes('timeline') || contentLower.includes('week') || contentLower.includes('month'),
+      dependencies: () => contentLower.includes('depend') || contentLower.includes('requires'),
+      measurable: () => contentLower.includes('measur') || contentLower.includes('kpi') || contentLower.includes('metric'),
+
+      // Generic
+      specific: () => contentLength > 500,
+      actionable: () => contentLower.includes('next step') || contentLower.includes('action') || contentLower.includes('todo')
+    };
+
+    const checkFn = checks[criterionId];
+    return checkFn ? checkFn() : false;
+  }
+
+  /**
+   * Transition document to review state
+   */
+  submitForReview(docType) {
+    const doc = this.state.documents[docType];
+    if (!doc || doc.status !== DOCUMENT_STATUS.DRAFT) {
+      throw new Error(`Document ${docType} is not in draft state`);
+    }
+
+    // Calculate quality score
+    const content = this.readDraft(docType);
+    if (!content) {
+      throw new Error(`Cannot read draft for ${docType}`);
+    }
+
+    const quality = this.calculateQualityScore(docType, content);
+    doc.qualityScore = quality.score;
+    doc.status = DOCUMENT_STATUS.IN_REVIEW;
+    doc.history.push({
+      version: doc.version,
+      action: 'submitted_for_review',
+      timestamp: new Date().toISOString(),
+      qualityScore: quality.score
+    });
+
+    this.state.mode = WORKFLOW_MODE.REVIEW;
+    this.saveState();
+
+    return quality;
+  }
+
+  /**
+   * Approve a document
+   */
+  approveDocument(docType) {
+    const doc = this.state.documents[docType];
+    if (!doc || (doc.status !== DOCUMENT_STATUS.IN_REVIEW && doc.status !== DOCUMENT_STATUS.DRAFT)) {
+      throw new Error(`Document ${docType} cannot be approved from status: ${doc?.status}`);
+    }
+
+    // Copy draft to approved
+    const draftPath = this.getCurrentDraftPath(docType);
+    const approvedPath = this.getApprovedPath(docType);
+
+    if (draftPath && fs.existsSync(draftPath)) {
+      // Ensure approved directory exists
+      if (!fs.existsSync(this.approvedDir)) {
+        fs.mkdirSync(this.approvedDir, { recursive: true });
+      }
+      fs.copyFileSync(draftPath, approvedPath);
+    }
+
+    // Archive the draft to history
+    const historyPath = path.join(
+      this.historyDir,
+      `${this.getDocumentFilename(docType).replace('.md', '')}.v${doc.version}.approved.md`
+    );
+    if (draftPath && fs.existsSync(draftPath)) {
+      fs.copyFileSync(draftPath, historyPath);
+    }
+
+    // Update state
+    doc.status = DOCUMENT_STATUS.APPROVED;
+    doc.approvedAt = new Date().toISOString();
+    doc.history.push({
+      version: doc.version,
+      action: 'approved',
+      timestamp: new Date().toISOString()
+    });
+
+    // Check if phase is complete
+    const phaseId = this.findPhaseForDocument(docType);
+    if (phaseId && this.isPhaseComplete(phaseId)) {
+      this.state.phases[phaseId].status = 'completed';
+    }
+
+    // Move to next document
+    const next = this.getNextDocument();
+    if (next) {
+      this.state.currentPhase = next.phase;
+      this.state.currentDocument = next.document;
+      this.state.mode = WORKFLOW_MODE.GENERATION;
+    } else {
+      // Workflow complete
+      this.state.currentPhase = null;
+      this.state.currentDocument = null;
+      this.state.mode = null;
+    }
+
+    this.saveState();
+
+    return {
+      approved: true,
+      next,
+      workflowComplete: !next
+    };
+  }
+
+  /**
+   * Reject a document with feedback
+   */
+  rejectDocument(docType, feedback = '') {
+    const doc = this.state.documents[docType];
+    if (!doc || doc.status !== DOCUMENT_STATUS.IN_REVIEW) {
+      throw new Error(`Document ${docType} is not in review state`);
+    }
+
+    doc.status = DOCUMENT_STATUS.REJECTED;
+    doc.feedback.push({
+      timestamp: new Date().toISOString(),
+      message: feedback
+    });
+    doc.history.push({
+      version: doc.version,
+      action: 'rejected',
+      timestamp: new Date().toISOString(),
+      feedback
+    });
+
+    this.state.mode = WORKFLOW_MODE.GENERATION;
+    this.saveState();
+
+    return {
+      rejected: true,
+      feedback
+    };
+  }
+
+  /**
+   * Find which phase a document belongs to
+   */
+  findPhaseForDocument(docType) {
+    for (const [phaseId, phase] of Object.entries(WORKFLOW_PHASES)) {
+      if (phase.documents.includes(docType)) {
+        return phaseId;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Open document in external editor
+   */
+  openInEditor(docType) {
+    const draftPath = this.getCurrentDraftPath(docType);
+    if (!draftPath || !fs.existsSync(draftPath)) {
+      throw new Error(`No draft found for ${docType}`);
+    }
+
+    // Get file hash before editing
+    const beforeContent = fs.readFileSync(draftPath, 'utf-8');
+    const beforeHash = crypto.createHash('md5').update(beforeContent).digest('hex');
+
+    // Get editor from environment
+    const editor = process.env.EDITOR || process.env.VISUAL || 'vim';
+
+    return new Promise((resolve, reject) => {
+      const child = spawn(editor, [draftPath], {
+        stdio: 'inherit',
+        shell: true
+      });
+
+      child.on('close', (code) => {
+        if (code !== 0) {
+          reject(new Error(`Editor exited with code ${code}`));
+          return;
+        }
+
+        // Check if file changed
+        const afterContent = fs.readFileSync(draftPath, 'utf-8');
+        const afterHash = crypto.createHash('md5').update(afterContent).digest('hex');
+
+        const changed = beforeHash !== afterHash;
+
+        if (changed) {
+          // Update document state
+          const doc = this.state.documents[docType];
+          doc.history.push({
+            version: doc.version,
+            action: 'edited',
+            timestamp: new Date().toISOString()
+          });
+          this.saveState();
+        }
+
+        resolve({
+          changed,
+          path: draftPath
+        });
+      });
+
+      child.on('error', (err) => {
+        reject(new Error(`Failed to open editor: ${err.message}`));
+      });
+    });
+  }
+
+  /**
+   * Import/upload an existing document
+   */
+  importDocument(docType, sourcePath) {
+    if (!fs.existsSync(sourcePath)) {
+      throw new Error(`Source file not found: ${sourcePath}`);
+    }
+
+    const content = fs.readFileSync(sourcePath, 'utf-8');
+    return this.createDraft(docType, content, 'uploaded');
+  }
+
+  /**
+   * Get workflow progress summary
+   */
+  getProgress() {
+    if (!this.state) {
+      return null;
+    }
+
+    const phases = Object.entries(WORKFLOW_PHASES).map(([phaseId, phase]) => {
+      const phaseState = this.state.phases[phaseId] || { status: 'pending' };
+      const documents = phase.documents.map(docType => {
+        const doc = this.state.documents[docType] || { status: DOCUMENT_STATUS.EMPTY };
+        return {
+          type: docType,
+          name: this.getDocumentFilename(docType),
+          status: doc.status,
+          version: doc.version,
+          qualityScore: doc.qualityScore
+        };
+      });
+
+      const approvedCount = documents.filter(
+        d => d.status === DOCUMENT_STATUS.APPROVED || d.status === DOCUMENT_STATUS.LOCKED
+      ).length;
+
+      return {
+        id: phaseId,
+        name: phase.name,
+        description: phase.description,
+        status: phaseState.status,
+        dependenciesMet: this.arePhaseDependenciesMet(phaseId),
+        documents,
+        progress: {
+          approved: approvedCount,
+          total: documents.length,
+          percentage: Math.round((approvedCount / documents.length) * 100)
+        }
+      };
+    });
+
+    const totalDocs = Object.keys(this.state.documents).length;
+    const approvedDocs = Object.values(this.state.documents).filter(
+      d => d.status === DOCUMENT_STATUS.APPROVED || d.status === DOCUMENT_STATUS.LOCKED
+    ).length;
+
+    return {
+      currentPhase: this.state.currentPhase,
+      currentDocument: this.state.currentDocument,
+      mode: this.state.mode,
+      startedAt: this.state.startedAt,
+      lastUpdated: this.state.lastUpdated,
+      phases,
+      overall: {
+        approved: approvedDocs,
+        total: totalDocs,
+        percentage: Math.round((approvedDocs / totalDocs) * 100)
+      },
+      isComplete: approvedDocs === totalDocs
+    };
+  }
+
+  /**
+   * Get resume point for continuing workflow
+   */
+  getResumePoint() {
+    if (!this.state || !this.state.currentPhase) {
+      return null;
+    }
+
+    const doc = this.state.documents[this.state.currentDocument];
+
+    return {
+      phase: this.state.currentPhase,
+      phaseName: WORKFLOW_PHASES[this.state.currentPhase]?.name,
+      document: this.state.currentDocument,
+      documentName: this.getDocumentFilename(this.state.currentDocument),
+      documentStatus: doc?.status,
+      mode: this.state.mode,
+      lastUpdated: this.state.lastUpdated
+    };
+  }
+
+  /**
+   * Override a phase gate (with justification)
+   */
+  overridePhaseGate(phaseId, justification) {
+    if (!justification || justification.trim().length < 10) {
+      throw new Error('A meaningful justification (10+ chars) is required to override phase gates');
+    }
+
+    this.state.overrides.push({
+      phaseId,
+      justification,
+      timestamp: new Date().toISOString()
+    });
+
+    // Mark dependencies as overridden
+    this.state.phases[phaseId].overridden = true;
+
+    this.saveState();
+
+    return {
+      overridden: true,
+      phaseId,
+      justification
+    };
+  }
+
+  /**
+   * Check if workflow exists
+   */
+  hasWorkflow() {
+    return fs.existsSync(this.stateFile);
+  }
+
+  /**
+   * Reset workflow (dangerous!)
+   */
+  resetWorkflow() {
+    if (fs.existsSync(this.stateFile)) {
+      fs.unlinkSync(this.stateFile);
+    }
+    this.state = null;
+    return true;
+  }
+}
+
+module.exports = {
+  PreseedWorkflowEngine,
+  DOCUMENT_STATUS,
+  WORKFLOW_MODE,
+  WORKFLOW_PHASES,
+  QUALITY_CRITERIA,
+  DEFAULT_WORKFLOW_STATE
+};