┌─────────────────────────────────────────────────────────────────────────────┐
│                              FRONTEND (Next.js 15)                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │ Conversation│  │   Project   │  │    Task     │  │  Form Wizard System │ │
│  │    Pages    │  │  Dashboard  │  │  Management │  │  (23+ field types)  │ │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘ │
└─────────┼────────────────┼────────────────┼────────────────────┼────────────┘
          │                │                │                    │
          ▼                ▼                ▼                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              API LAYER (Hono)                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │  /api/flow  │  │/api/projects│  │ /api/tasks  │  │  /api/agents        │ │
│  │  /api/conv  │  │/api/features│  │/api/actions │  │  /api/specification │ │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘ │
└─────────┼────────────────┼────────────────┼────────────────────┼────────────┘
          │                │                │                    │
          ▼                ▼                ▼                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           SERVICE LAYER (220+ files)                        │
│  ┌───────────────────┐  ┌───────────────────┐  ┌───────────────────────────┐│
│  │   Flow Services   │  │  Feature Services │  │    Planning Services      ││
│  │ - Question Flow   │  │ - Selection       │  │ - Plan Generation         ││
│  │ - Variant Enhance │  │ - Validation      │  │ - Readiness Assessment    ││
│  │ - Ontology Track  │  │ - Scoring         │  │ - Phase Transitions       ││
│  │ - Answer Prefill  │  │ - Curation        │  │ - Blueprint Generation    ││
│  │ - Persona Match   │  └───────────────────┘  └───────────────────────────┘│
│  └───────────────────┘                                                      │
│  ┌───────────────────┐  ┌───────────────────┐  ┌───────────────────────────┐│
│  │   Task Services   │  │  Design Services  │  │   Background Services     ││
│  │ - Task Detection  │  │ - Design Decisions│  │ - Worker (10s poll)       ││
│  │ - Task Generation │  │ - System Compile  │  │ - Post-Answer Processing  ││
│  │ - Output Binding  │  │ - Preference      │  │ - Feature Curation        ││
│  └───────────────────┘  └───────────────────┘  └───────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
          │                │                │                    │
          ▼                ▼                ▼                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                      ENTERPRISE SYSTEMS LAYER (60+ files)                   │
│  ┌───────────────────┐  ┌───────────────────┐  ┌───────────────────────────┐│
│  │Permissions System │  │Document Templates │  │    BPMN Workflows         ││
│  │ - RBAC + ABAC     │  │ - Variable Extract│  │ - Parsing & Validation    ││
│  │ - Policy Engine   │  │ - Mapping & Render│  │ - Normalization           ││
│  └───────────────────┘  └───────────────────┘  └───────────────────────────┘│
│  ┌───────────────────┐  ┌───────────────────┐  ┌───────────────────────────┐│
│  │  Integrations     │  │  Schema Registry  │  │    Gaps Analysis          ││
│  │ - Curated + Custom│  │ - Domain Objects  │  │ - Detector Engine         ││
│  │ - Contract Import │  │ - Versioning      │  │ - Task Synthesis          ││
│  └───────────────────┘  └───────────────────┘  └───────────────────────────┘│
│  ┌───────────────────┐                                                       │
│  │  Export Compiler  │                                                       │
│  │ - Bundle Gen      │                                                       │
│  │ - Readiness Gate  │                                                       │
│  └───────────────────┘                                                       │
└─────────────────────────────────────────────────────────────────────────────┘
          │                │                │                    │
          ▼                ▼                ▼                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         CORE LAYER (Orchestration)                          │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                      PHASE ORCHESTRATOR                               │  │
│  │  (src/services/flow/phase-orchestrator.ts - THE MOST IMPORTANT FILE)  │  │
│  │                                                                       │  │
│  │  - Phase lifecycle management                                         │  │
│  │  - Transition validation                                              │  │
│  │  - Readiness calculation                                              │  │
│  │  - Entry action execution                                             │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐  │
│  │  Agent System   │  │  Graph System   │  │     Ontology System         │  │
│  │  (17 agents)    │  │  (Q&A flow)     │  │  (domain knowledge)         │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
          │                │                │                    │
          ▼                ▼                ▼                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                       MASTRA WORKFLOW LAYER                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐  │
│  │ Phase Workflows │  │ Spec Workflows  │  │   Research Workflows        │  │
│  │ - Transitions   │  │ - compile-spec  │  │ - market-research           │  │
│  │ - Entry Actions │  │ - multi-agent   │  │ - design-intelligence       │  │
│  │ - Validation    │  │ - variant-build │  │ - technical-feasibility     │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
          │                │                │                    │
          ▼                ▼                ▼                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         DATA LAYER (PostgreSQL)                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐  │
│  │ Project Tables  │  │ Question Tables │  │    Agent/Execution Tables   │  │
│  │ - projects      │  │ - graph_nodes   │  │ - agent_memory              │  │
│  │ - tenants       │  │ - plan_questions│  │ - agent_executor_state      │  │
│  │ - users         │  │ - answers       │  │ - checkpoint_snapshots      │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘  │
│                         Row-Level Security (RLS) Enforced                   │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   PHASE 1          PHASE 2           PHASE 3          PHASE 4              │
│  ┌─────────┐      ┌─────────┐       ┌─────────┐      ┌─────────┐           │
│  │DISCOVERY│ ──▶  │ FEATURE │  ──▶  │  PLAN   │ ──▶  │PLANNING │           │
│  │         │      │SELECTION│       │GENERATION│     │         │           │
│  │ ~15 Qs  │      │         │       │ 50-150  │      │Blueprint│           │
│  │template │      │ select  │       │questions│      │ & Plan  │           │
│  │ driven  │      │features │       │AI-gen'd │      │         │           │
│  └─────────┘      └─────────┘       └─────────┘      └─────────┘           │
│       │                                                    │                │
│       │                                                    ▼                │
│       │                                              ┌─────────┐           │
│       │           PHASE 6           PHASE 5          │ VISUAL  │           │
│       │          ┌─────────┐       ┌─────────┐       │DISCOVERY│           │
│       └────────▶ │  SPEC   │ ◀──── │ VISUAL  │ ◀──── │         │           │
│      (terminal)  │(TERMINAL)│      │DISCOVERY│       │ design  │           │
│                  │         │       │         │       │questions│           │
│                  │ review  │       │ 2 tracks│       │ + AI    │           │
│                  │ export  │       │parallel │       │research │           │
│                  └─────────┘       └─────────┘       └─────────┘           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

// Structure in database
interface GraphNode {
  id: string;
  project_id: string;
  type: 'section' | 'question' | 'suggestion';
  parent_id: string | null;
  content: {
    question_text: string;
    variants: QuestionVariant[];
    answer_type: 'text' | 'select' | 'multi_select' | 'boolean';
  };
  status: 'pending' | 'answered' | 'skipped';
  display_order: number;
}

// Structure in database
interface PlanQuestion {
  id: string;
  project_id: string;
  question_plan_id: string;
  feature_id: string | null;
  question_text: string;
  description: string;
  answer_type: string;
  options: Option[] | null;
  prefilled_answer: string | null;
  confidence_score: number;
  user_answer: string | null;
  status: 'pending' | 'prefilled' | 'answered' | 'skipped';
  group_key: string;
  display_order: number;
}

interface QuestionPool {
  id: string;
  name: string;
  category: string;
  industry?: string[];
  scenario_type?: string;
  created_at: Date;
  updated_at: Date;
}

interface PoolQuestion {
  id: string;
  pool_id: string;
  base_prompt: string;
  question_type: string;
  priority: number;
  display_order: number;
  prerequisite_questions?: string[];
  metadata: Record<string, any>;
  embedding?: number[]; // vector(1536) for semantic search
  created_at: Date;
}

interface PoolActivationRule {
  id: string;
  pool_id: string;
  trigger_type: 'keyword' | 'pattern' | 'domain' | 'entity';
  trigger_value: string;
  confidence_threshold: number;
  industry_filter?: string[];
  created_at: Date;
}

// src/services/flow/db-question-pool-loader.ts
export class DBQuestionPoolLoader {
  constructor(private db: Pool) {}

  // Load all pools
  async getAllPools(): Promise<QuestionPool[]>

  // Get questions by pool IDs
  async getPoolQuestions(poolIds: string[]): Promise<PoolQuestion[]>

  // Get activation rules
  async getActivationRules(poolId: string): Promise<PoolActivationRule[]>

  // Fallback to JSON files if DB is empty
  private async loadFromJSON(): Promise<QuestionPool[]>
}

interface DomainTemplate {
  id: string;
  domain: 'ecommerce' | 'saas' | 'healthcare' | 'internal-tools' | 'general';
  category: 'entity' | 'workflow' | 'integration';
  canonicalName: string;
  displayName: string;
  template: {
    suggestedAttributes: Array<{
      name: string;
      type: string;
      required: boolean;
      description: string;
    }>;
    statusEnum?: string[];
    transitions?: Array<{
      from: string;
      to: string;
      trigger: string;
      conditions?: string[];
    }>;
    businessRules?: string[];
    requiredQuestions: string[];  // ← Questions embedded here
    relatedEntities?: string[];
  };
  keywords: string[];
  embedding?: number[];
  created_at: Date;
}

// src/core/ontology/domain-template-service.ts (lines 23-89)
export class DomainTemplateService {
  async getDomainKnowledge(
    projectDescription: string,
    existingAnswers: Record<string, any>
  ): Promise<DomainKnowledge> {
    // Returns aggregated knowledge from templates
    // Includes: entityTemplates, patternTemplates, integrationTemplates
    // Extracts all requiredQuestions from matched templates
  }
}

interface CanonicalQuestion {
  id: string;
  entity_id: string;
  question_text: string;
  category: string;
  priority: number;
  created_at: Date;
}

interface EntityQuestion {
  id: string;
  entity_id: string;
  question_text: string;
  question_type: string;
  context: Record<string, any>;
  created_at: Date;
}

export class FeatureDrivenPlanGenerator {
  constructor(
    private db: Pool,
    private poolLoader: DBQuestionPoolLoader,
    private answerPrefiller: AnswerPrefillerService,
    private questionTaskGenerator: QuestionTaskGenerator
  ) {}

  async generatePlan(params: {
    projectId: string;
    curationId: string;
    agentId: string;
  }): Promise<FeatureDrivenPlan>
}

1. Load feature curation + selected features
2. Build feature structure:
   ├─ Query pool_questions by feature.relatedPoolIds (lines 357-371)
   ├─ Get entity pool questions via NAICS mapping (lines 195-319)
   └─ Deduplicate questions
3. Create feature_driven_plans record
4. Create plan_sections (one per feature)
5. Insert plan_questions for each section
6. Prefill answers (two-pass AI process)
7. Generate tasks (REVIEW vs PROVIDE)
8. Return FeatureDrivenPlan

// This is where KB tables ARE used
private async getEntityPoolQuestionsForIndustry(
  industry: string,
  projectId: string
): Promise<PoolQuestion[]> {
  // 1. Map industry code → NAICS codes
  // 2. Query kb_naics_standard_mappings for entity_ids
  // 3. Get entity names from kb_canonical_entities
  // 4. Find pool questions matching those entities
  // Returns pool questions relevant to the industry
}

const poolQuestions = await this.poolLoader.getPoolQuestions(
  feature.relatedPoolIds || []
);

export class PlanningQuestionGenerator {
  constructor(
    private db: Pool,
    private poolLoader: DBQuestionPoolLoader,
    private answerPrefiller: AnswerPrefillerService
  ) {}

  async generatePlan(params: {
    projectId: string;
    blueprint: DomainBlueprint;
    agentId: string;
  }): Promise<PlanningQuestionPlan>
}

1. Analyze blueprint gaps:
   ├─ Missing entities?
   ├─ Missing workflows?
   ├─ Missing business rules?
   ├─ Missing compliance requirements?
   ├─ Missing integrations?
   └─ Missing UX differentiation?
2. Select pools based on gaps (use PLANNING_POOL_IDS)
3. Load questions from selected pools (lines 545-566)
4. Filter to gap-specific question IDs
5. Create sections + questions
6. Prefill with domain context
7. Convert to DomainOpenQuestion for tracking

const PLANNING_POOL_IDS = {
  ENTITY_DEFINITION: 'uuid-here',
  WORKFLOW_DEFINITION: 'uuid-here',
  BUSINESS_RULES: 'uuid-here',
  COMPLIANCE: 'uuid-here',
  INTEGRATIONS: 'uuid-here',
  UX_DIFFERENTIATION: 'uuid-here'
};

export async function generateDesignQuestionPlan(
  db: Pool,
  projectId: string,
  blockCatalog: BlockCatalogService
): Promise<DesignQuestionPlan>

1. Load block catalog (NOT pool_questions!)
2. Group surfaces by section:
   ├─ Theme (color, typography, brand)
   ├─ Auth (login, signup, password reset)
   ├─ Marketing (landing, pricing, about)
   ├─ Navigation (header, footer, sidebar)
   ├─ Dashboard (analytics, tables, charts)
   └─ Other surfaces (commerce, admin, settings, etc.)
3. For each surface:
   ├─ Generate hardcoded prompt (lines 202-245)
   ├─ Get matching blocks from catalog
   └─ Build block selection options
4. Create DesignQuestionPlan structure
5. Store in projects.design_question_plan (JSONB column)

export async function generateFollowUpQuestions(
  db: Pool,
  projectId: string,
  previousAnswers: Record<string, any>,
  domainTemplateService: DomainTemplateService
): Promise<FollowUpQuestion[]>

1. Get domain knowledge from templates
   └─ domainTemplateService.getDomainKnowledge()
2. Build AI prompt with:
   ├─ Previous answers
   ├─ Entity templates (state machines)
   ├─ Integration capabilities
   └─ Template requiredQuestions
3. Call AI to generate contextual follow-ups
4. Parse and structure questions
5. Return with context and priority

async generateNextQuestions(session: QASession): Promise<Question[]> {
  const questions: Question[] = [];
  const askedQuestions = new Set<string>(session.askedQuestions || []);

  // Layer 1: AI Evaluator Completeness Questions
  const evaluatorQuestions = await this.completenessEvaluator.evaluate(session);
  for (const q of evaluatorQuestions) {
    if (!askedQuestions.has(q.question) && questions.length < count) {
      questions.push(q);
      askedQuestions.add(q.question);
    }
  }

  // Layer 2: Domain Template Required Questions
  const templateQuestions = session.domainKnowledge?.allRequiredQuestions || [];
  for (const q of templateQuestions) {
    if (!askedQuestions.has(q) && questions.length < count) {
      questions.push({ question: q, source: 'template' });
      askedQuestions.add(q);
    }
  }

  // Layer 3: Semantic Retrieval from Templates
  if (questions.length < count) {
    const semanticQuestions = await this.semanticRetrieval.findRelevant(
      session.currentContext,
      count - questions.length
    );
    for (const q of semanticQuestions) {
      if (!askedQuestions.has(q.question)) {
        questions.push(q);
        askedQuestions.add(q.question);
      }
    }
  }

  return questions;
}

export const LEGACY_RULES: ActivationRule[] = [
  {
    poolId: 'auth-questions',
    triggers: ['authentication', 'login', 'signup'],
    confidence: 0.9
  },
  // ... more hardcoded rules
];

export class AnswerPrefillerService {
  async prefillAnswers(
    questions: PlanQuestion[],
    context: PrefillContext
  ): Promise<PrefilledAnswer[]> {
    // Pass 1: Generate initial drafts (lines 478-703)
    const drafts = await this.generateDrafts(questions, context);

    // Pass 2: Refine with cross-references (lines 707-845)
    const refined = await this.refineDrafts(drafts, context);

    // Detect consistency issues (lines 1101-1134)
    await this.detectInconsistencies(refined);

    return refined;
  }
}

// Group questions by dependency level
const waves = this.buildDependencyWaves(questions);

// Process each wave in parallel
for (const wave of waves) {
  const waveResults = await Promise.all(
    wave.map(q => this.generateSingleDraft(q, context))
  );
  // Results from this wave inform next wave
}

interface PrefilledAnswer {
  questionId: string;
  value: string;
  confidence: number; // 0.0 - 1.0
  reasoning: string;
  sources: string[];
}

async refineDrafts(
  drafts: PrefilledAnswer[],
  context: PrefillContext
): Promise<PrefilledAnswer[]> {
  // For each draft:
  // 1. Find related answers
  // 2. Check for conflicts
  // 3. Enhance with additional context
  // 4. Adjust confidence based on consistency
  // 5. Add validation notes
}

const status = answer.confidence >= 0.9 ? 'auto_completed'
  : answer.confidence >= 0.7 ? 'confirmed'
  : 'pending';

// Workflow:
// confidence >= 0.9: Auto-accept, no user review needed
// 0.7 <= confidence < 0.9: Show to user as "confirmed", easy to accept
// confidence < 0.7: Mark as "pending", requires user review

async detectInconsistencies(
  answers: PrefilledAnswer[]
): Promise<InconsistencyReport[]> {
  const inconsistencies: InconsistencyReport[] = [];

  // Check for:
  // - Contradicting values across related questions
  // - Missing expected relationships
  // - Type mismatches
  // - Business rule violations

  return inconsistencies;
}

export class QuestionTaskGenerator {
  async generateTasksForPlan(
    planId: string,
    questions: PlanQuestion[]
  ): Promise<Task[]> {
    // 1. Get questions needing REVIEW (confidence >= 0.5)
    const reviewQuestions = await this.getReviewQuestions(questions);

    // 2. Get questions needing PROVIDE (confidence < 0.5)
    const provideQuestions = await this.getProvideQuestions(questions);

    // 3. Build tasks
    const tasks = [
      ...this.buildReviewTasks(reviewQuestions),
      ...this.buildProvideTasks(provideQuestions)
    ];

    // 4. Insert into user_tasks table
    await this.insertTasks(tasks);

    return tasks;
  }
}

// For questions with confidence >= 0.5
// User reviews AI-generated answer
async getReviewQuestions(questions: PlanQuestion[]): Promise<PlanQuestion[]> {
  return questions.filter(q =>
    q.prefilled_answer &&
    q.confidence_score >= 0.5 &&
    q.status === 'prefilled'
  );
}

// For questions with confidence < 0.5
// User provides answer from scratch
async getProvideQuestions(questions: PlanQuestion[]): Promise<PlanQuestion[]> {
  return questions.filter(q =>
    !q.prefilled_answer ||
    q.confidence_score < 0.5 ||
    q.status === 'pending'
  );
}

interface TaskInput {
  type: 'REVIEW_ANSWER' | 'PROVIDE_ANSWER';
  title: string;
  description: string;
  priority: number;
  metadata: {
    questionId: string;
    questionText: string;
    prefilledAnswer?: string;
    confidence?: number;
    reasoning?: string;
  };
  binding: {
    targetType: 'plan_question';
    targetId: string;
    fieldPath: 'user_answer';
  };
}

async onQuestionCompleted(questionId: string): Promise<void> {
  // 1. Find linked task
  const task = await this.findTaskByQuestionId(questionId);

  // 2. Mark task as complete
  await this.completeTask(task.id);

  // 3. Copy answer to task output
  await this.updateTaskOutput(task.id, answer);
}

async onTaskCompleted(taskId: string): Promise<void> {
  // 1. Get task with binding
  const task = await this.getTaskWithBinding(taskId);

  // 2. Extract answer from task output
  const answer = task.output.answer;

  // 3. Update linked question
  await this.updateQuestion(task.metadata.questionId, {
    user_answer: answer,
    status: 'answered'
  });

  // 4. Trigger post-answer processing
  await this.postAnswerProcessor.process(questionId);
}

export class AnswerAnalyzerService {
  async analyze(
    question: PlanQuestion,
    answer: string,
    context: AnalysisContext
  ): Promise<AnalysisResult> {
    // 1. Keyword detection
    const keywords = await this.detectKeywords(answer);

    // 2. Entity extraction
    const entities = await this.extractEntities(answer);

    // 3. Ambiguity scoring
    const ambiguityScore = await this.calculateAmbiguity(answer);

    // 4. Follow-up decision
    const needsFollowup = await this.determineFollowup(
      question,
      answer,
      ambiguityScore
    );

    return { keywords, entities, ambiguityScore, needsFollowup };
  }
}

const KEYWORD_CATEGORIES = {
  authentication: ['login', 'signup', 'oauth', 'jwt', 'session'],
  payment: ['stripe', 'checkout', 'payment', 'billing'],
  notification: ['email', 'sms', 'push', 'notification'],
  storage: ['s3', 'upload', 'file', 'media'],
  search: ['search', 'filter', 'query', 'elasticsearch'],
  analytics: ['tracking', 'analytics', 'metrics', 'events'],
  admin: ['admin', 'dashboard', 'manage', 'crud'],
  workflow: ['approval', 'workflow', 'process', 'state'],
  integration: ['api', 'webhook', 'integration', 'sync']
};

function calculateAmbiguity(answer: string): number {
  let score = 0;

  // Signals of ambiguity:
  if (answer.includes('maybe')) score += 0.2;
  if (answer.includes('not sure')) score += 0.3;
  if (answer.includes('probably')) score += 0.2;
  if (answer.includes('I think')) score += 0.2;
  if (answer.length < 20) score += 0.3; // Too short
  if (!answer.includes('.')) score += 0.1; // No punctuation

  return Math.min(score, 1.0);
}

function determineFollowup(
  question: PlanQuestion,
  answer: string,
  ambiguityScore: number
): boolean {
  // Trigger follow-up if:
  // 1. High ambiguity (> 0.6)
  if (ambiguityScore > 0.6) return true;

  // 2. Keywords detected but insufficient detail
  const keywordCount = detectKeywords(answer).length;
  if (keywordCount > 0 && answer.length < 50) return true;

  // 3. Complex question with simple answer
  if (question.complexity === 'high' && answer.length < 100) return true;

  return false;
}

CREATE TABLE question_pools (
  id UUID PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  category VARCHAR(100),
  industry VARCHAR(100)[],
  scenario_type VARCHAR(100),
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE pool_questions (
  id UUID PRIMARY KEY,
  pool_id UUID REFERENCES question_pools(id),
  base_prompt TEXT NOT NULL,
  question_type VARCHAR(50),
  priority INTEGER DEFAULT 0,
  display_order INTEGER,
  prerequisite_questions UUID[],
  metadata JSONB,
  embedding vector(1536),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE pool_activation_rules (
  id UUID PRIMARY KEY,
  pool_id UUID REFERENCES question_pools(id),
  trigger_type VARCHAR(50), -- 'keyword', 'pattern', 'domain', 'entity'
  trigger_value TEXT,
  confidence_threshold NUMERIC(3,2),
  industry_filter VARCHAR(100)[],
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE feature_driven_plans (
  id UUID PRIMARY KEY,
  project_id UUID REFERENCES projects(id),
  curation_id UUID REFERENCES feature_curations(id),
  agent_id VARCHAR(255),
  status VARCHAR(50) DEFAULT 'active',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE plan_sections (
  id UUID PRIMARY KEY,
  plan_id UUID REFERENCES feature_driven_plans(id),
  feature_id UUID REFERENCES feature_catalog(id),
  title VARCHAR(255) NOT NULL,
  description TEXT,
  display_order INTEGER,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE plan_questions (
  id UUID PRIMARY KEY,
  section_id UUID REFERENCES plan_sections(id),
  pool_question_id UUID REFERENCES pool_questions(id),
  question_text TEXT NOT NULL,
  display_order INTEGER,
  answer TEXT,
  prefill_value TEXT,
  prefill_confidence NUMERIC(3,2),
  auto_accepted BOOLEAN DEFAULT FALSE,
  is_suppressed BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE ontology_domain_templates (
  id UUID PRIMARY KEY,
  domain VARCHAR(50) NOT NULL,
  category VARCHAR(50) NOT NULL,
  canonical_name VARCHAR(255) NOT NULL,
  display_name VARCHAR(255),
  template JSONB NOT NULL, -- Contains requiredQuestions[]
  keywords TEXT[],
  embedding vector(1536),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE ontology_pattern_templates (
  id UUID PRIMARY KEY,
  pattern_name VARCHAR(255) NOT NULL,
  display_name VARCHAR(255),
  category VARCHAR(100),
  complexity VARCHAR(50),
  template JSONB NOT NULL, -- Contains requiredQuestions[]
  keywords TEXT[],
  compatible_domains TEXT[],
  embedding vector(1536),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE ontology_integration_templates (
  id UUID PRIMARY KEY,
  provider VARCHAR(255) NOT NULL,
  display_name VARCHAR(255),
  category VARCHAR(100),
  capabilities TEXT[],
  required_config TEXT[],
  template JSONB NOT NULL, -- Contains webhookEvents, requiredQuestions
  docs_reference TEXT,
  embedding vector(1536),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE canonical_questions (
  id UUID PRIMARY KEY,
  entity_id UUID,
  question_text TEXT NOT NULL,
  category VARCHAR(100),
  priority INTEGER,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE entity_questions (
  id UUID PRIMARY KEY,
  entity_id UUID REFERENCES kb_canonical_entities(id),
  question_text TEXT NOT NULL,
  question_type VARCHAR(50),
  context JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- ❌ These tables are populated but never queried in active code

CREATE TABLE kb_naics_standard_mappings (
  id UUID PRIMARY KEY,
  naics_code VARCHAR(6) REFERENCES kb_naics_codes(code),
  entity_id UUID REFERENCES kb_canonical_entities(id),
  relevance_score NUMERIC(3,2),
  created_at TIMESTAMPTZ DEFAULT NOW()
);
-- ✅ Used in getEntityPoolQuestionsForIndustry()

CREATE TABLE kb_canonical_entities (
  id UUID PRIMARY KEY,
  entity_name VARCHAR(255) NOT NULL,
  entity_type VARCHAR(100),
  synonyms TEXT[],
  description TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);
-- ✅ Used for entity synonym matching

if (!askedQuestions.has(q.question) && questions.length < count) {
  questions.push(q);
  askedQuestions.add(q.question);
}

interface GraphNode {
  id: string;
  project_id: string;
  parent_id: string | null;  // ← Creates tree structure
  type: 'section' | 'question' | 'suggestion';
  title: string;
  description: string;
  question_data: {
    concept: string;
    basePrompt: string;
    formComponent: string;
    options?: Array<{ value: string; label: string }>;
    metadata?: Record<string, any>;
  };
  answer_data: {
    value: string | string[] | number | boolean;
    confidence?: number;
    source?: 'user' | 'prefill' | 'agent';
  } | null;
  status: 'pending' | 'unanswered' | 'answered' | 'skipped';
  order_index: number;
  level: number;  // Tree depth (0 = root)
  is_dynamic: boolean;  // Injected during conversation
  trigger_conditions: Record<string, any> | null;
  created_at: Date;
  updated_at: Date;
  answered_at: Date | null;
}

Section (type: 'section', level: 0)
  ├─ Question 1 (type: 'question', level: 1, parent_id: section.id)
  │   ├─ Suggestion 1.1 (type: 'suggestion', level: 2, parent_id: q1.id)
  │   └─ Dynamic Question 1.2 (injected based on answer, is_dynamic: true)
  ├─ Question 2 (type: 'question', level: 1)
  └─ Question 3 (type: 'question', level: 1)

async process(task: BackgroundTask): Promise<void> {
  // Payload contains:
  // - projectId, tenantId, userId, sessionId
  // - questionNodeId (the answered question)
  // - answer (the submitted answer value)

  // STEP 1: Dynamic Question Generation (lines 88-283)
  await this.checkAndCreateDynamicQuestions(payload, nodes)
  // Sub-steps:
  // 1. Calculate ontology completeness
  // 2. Analyze completeness for gaps
  // 3. Determine if question injection needed
  // 4. Generate next best question
  // 5. Inject into graph_nodes
  // 6. Emit SSE event to frontend

  // STEP 2: Follow-up Analysis (lines 91-486)
  await this.analyzeAnswerAndGenerateFollowups(payload, nodes)
  // Sub-steps:
  // 1. Get answered question
  // 2. Analyze answer (word count, complexity, confidence)
  // 3. Generate follow-up questions using AI
  // 4. Filter by confidence threshold (>= 0.75)
  // 5. Check activated pools to avoid duplicates
  // 6. Inject best follow-up
  // 7. Emit SSE event

  // STEP 3: Pool Activation (lines 97-591)
  await this.checkAndActivatePools(payload, nodes)
  // Sub-steps:
  // 1. Analyze answer text for keywords
  // 2. Match against pool activation rules
  // 3. Get high-confidence activations
  // 4. Check if pools already activated
  // 5. Activate each new pool
  // 6. Mark pool as activated
  // 7. Emit SSE events
}

// Insert new node into graph_nodes table
const nodeId = await db.insert({
  type: 'question',
  title: concept,
  description: rationale,
  question_data: {
    concept,
    basePrompt: questionText,
    formComponent,
    metadata: { targetEntity, targetAttribute, priority }
  },
  is_dynamic: true,  // ← Marks as injected
  trigger_conditions: { type: 'gap-filling', targetEntity },
  order_index: maxOrder + 1,  // Append to end
  status: 'unanswered'
})

CREATE TABLE IF NOT EXISTS activated_pools (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id TEXT NOT NULL,
  project_id TEXT NOT NULL,
  pool_id TEXT NOT NULL,
  pool_name TEXT NOT NULL,
  reasoning TEXT,
  activated_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(tenant_id, project_id, pool_id)
);

OPEN → IN_PROGRESS → DONE
   ↓         ↓         ↓
SKIPPED  CANCELLED  (terminal states)

async createTask(input: CreateTaskInput): Promise<Task> {
  // Calls database function create_task_with_actions()
  // Creates task + actions + targets atomically
  // Returns full Task object
}

async createTaskIfNotExists(input: CreateTaskInput): Promise<Task | null> {
  // Deduplication logic:
  // - Check if task exists for plan_question_id
  // - Check if task exists for graph_node_id
  // - Only create if no existing task
  // Returns null if task already exists
}

// Tasks can link to questions via:
// - plan_question_id (plan-phase questions)
// - graph_node_id (discovery questions)

async taskExistsForPlanQuestion(planQuestionId: string): Promise<boolean>
async getTaskByPlanQuestion(planQuestionId: string): Promise<Task | null>

async cancelTasksForQuestion(
  planQuestionId: string | null,
  graphNodeId: string | null,
  reason: string
): Promise<number>
// Used when question is skipped or removed

async getTasksWithCount(filter: TaskFilter): Promise<TaskListResult> {
  // Filtering:
  // - status, taskType, category, priority
  // - assignedTo, blocking flag
  // - Text search on title/description
  // - Exclude blocked tasks (depends_on not satisfied)

  // Ordering:
  // 1. By status (OPEN first, then IN_PROGRESS, then others)
  // 2. By blocking flag (blocking tasks first)
  // 3. By priority (urgent → high → medium → low)
  // 4. By created_at (oldest first)
}

async getNextActionableTask(projectId: string, userId?: string): Promise<Task | null>
// Returns highest priority unblocked task

async claimTask(taskId: string, userId: string): Promise<boolean>
// Atomic claim (sets assigned_to)

async startTask(taskId: string, userId?: string): Promise<void>
// OPEN → IN_PROGRESS, sets started_at

async completeTask(taskId: string, result: Record<string, unknown>, actor?: string): Promise<void>
// Calls complete_task_with_result() DB function
// Executes output bindings
// Updates question if linked

async skipTask(taskId: string, userId?: string, reason?: string): Promise<void>
// Only for non-blocking tasks

async cancelTask(taskId: string, userId?: string, reason?: string): Promise<void>
// Can cancel any task

async getStatistics(projectId: string): Promise<TaskStatistics> {
  return {
    totalTasks: number,
    openTasks: number,
    inProgressTasks: number,
    completedTasks: number,
    blockedTasks: number,  // Has unsatisfied dependencies
    blockingTasks: number  // Marked as blocking
  }
}

BackgroundWorker (singleton)
  ├─ Poll Loop (every 2s)
  ├─ Task Handlers (Map<TaskType, Handler>)
  ├─ Concurrency Control (max 3 concurrent)
  └─ Task Detectors (auto-trigger chains)

export class BackgroundWorker {
  private config: WorkerConfig
  private isRunning: boolean = false
  private pollTimer: NodeJS.Timeout | null = null
  private activeTaskCount: number = 0
  private handlers: Map<TaskType, TaskHandler> = new Map()
  private detectorUnsubscribers: Array<() => void> = []

  constructor(config: WorkerConfig) {
    this.config = {
      pollIntervalMs: config.pollIntervalMs || 2000,  // Poll every 2s
      maxConcurrent: config.maxConcurrent || 3,       // Max 3 parallel tasks
      taskTypes: config.taskTypes,                    // Optional filter
      emitter: config.emitter,                        // SSE event emitter
      ontologyTracker: config.ontologyTracker         // Optional tracker
    }
  }
}

private async poll(): Promise<void> {
  if (!this.isRunning) return

  // Check capacity
  if (this.activeTaskCount >= this.config.maxConcurrent) {
    this.scheduleNextPoll()
    return
  }

  const taskService = getTaskService()

  // Claim next task (FIFO within priority)
  let task: BackgroundTask | null = null

  if (this.config.taskTypes) {
    // Try each type in order
    for (const taskType of this.config.taskTypes) {
      task = await taskService.claimNextTask(taskType)
      if (task) break
    }
  } else {
    // Claim any task type
    task = await taskService.claimNextTask()
  }

  if (task) {
    // Process in background (don't await)
    this.processTask(task).catch(...)

    // Immediately poll again if we have capacity
    if (this.activeTaskCount < this.config.maxConcurrent) {
      setImmediate(() => this.poll())
      return
    }
  }

  // Schedule next poll
  this.scheduleNextPoll()  // setTimeout(poll, pollIntervalMs)
}

private async processTask(task: BackgroundTask): Promise<void> {
  this.activeTaskCount++
  const timer = createTimer()

  try {
    const handler = this.handlers.get(task.taskType)

    if (!handler) {
      await taskService.failTask(task.id, `No handler for: ${task.taskType}`)
      return
    }

    logger.info({ taskId, taskType, projectId }, 'Processing task')

    await handler(task)  // Execute handler

    logger.info({ taskId, durationMs: timer() }, 'Task completed')

    // Log to orchestration_debug_events
    await logOrchestrationEvent({
      eventType: 'step.completed',
      payload: { taskId, taskType, durationMs }
    })

  } catch (error) {
    logger.error({ error, taskId }, 'Task failed')

    await taskService.failTask(task.id, error.message, { stack: error.stack })

    await logOrchestrationEvent({
      eventType: 'step.failed',
      payload: { taskId, error, durationMs }
    })
  } finally {
    this.activeTaskCount--
  }
}

// Auto-trigger task chains based on events
private initializeDetectors(): void {
  // Option generation: Tier 2 tasks when Tier 1 completes
  const optionUnsubscribe = initOptionGenerationDetector()

  // User story: Triggers backlog generation chains
  const userStoryUnsubscribe = initUserStoryDetector()

  // Feature curation: External event-triggered
  initFeatureCurationDetector()
}

// When market-research task completes:
eventEmitter.on('task.completed', async (event) => {
  if (event.taskType === 'market-research') {
    // Auto-trigger color-palette-generation
    await taskService.createTask({
      taskType: 'color-palette-generation',
      projectId: event.projectId,
      parameters: { researchResults: event.result }
    })
  }
})

export async function flushBackgroundTasks(
  projectId: string,
  options: {
    taskTypes?: TaskType[]
    maxTasks?: number          // default: 100
    continueOnError?: boolean   // default: true
    taskTimeoutMs?: number      // default: 60000
  }
): Promise<FlushTasksResult>

// Usage in tests:
const result = await flushBackgroundTasks(projectId, {
  taskTypes: ['post-answer-processing'],
  maxTasks: 10
})
// Result: { processed: 5, succeeded: 5, failed: 0, tasks: [...] }

export async function waitForBackgroundTasks(
  projectId: string,
  options: {
    timeoutMs?: number       // default: 300000 (5 min)
    pollIntervalMs?: number  // default: 1000
  }
): Promise<{ completed: number; failed: number; timedOut: boolean }>

// Usage in tests:
await waitForBackgroundTasks(projectId, { timeoutMs: 60000 })

interface UserStory {
  id: string
  backlog_id: string
  epic_id?: string

  // Story statement
  as_a: string       // User role (e.g., "customer", "admin")
  i_want: string     // Desired capability
  so_that: string    // Business value

  // Acceptance criteria
  acceptance_criteria: {
    given: string
    when: string
    then: string
  }[]

  // Priority and effort
  priority: 'must_have' | 'should_have' | 'could_have' | 'wont_have'  // MoSCoW
  estimated_effort: 'xs' | 's' | 'm' | 'l' | 'xl'

  // Traceability
  trace: {
    surfaces: string[]        // Design surfaces this story affects
    blocks: string[]          // UI blocks needed for implementation
    concepts: string[]        // Domain concepts referenced
    features: string[]        // Features this story implements
    visualAssets: string[]    // Design assets (colors, typography, etc.)
  }

  status: 'draft' | 'refined' | 'ready' | 'in_progress' | 'done'
}

User Answers Question
       ↓
[API: POST /api/flow/answer]
       ↓
1. Save answer to graph_nodes.answer_data
2. Create background task: 'post-answer-processing'
       ↓
Background Worker Claims Task
       ↓
PostAnswerProcessor.process()
       ↓
├─ Dynamic Question Injection
│  └─ New graph_node created (is_dynamic: true)
├─ Follow-up Analysis
│  └─ New graph_node created (follow-up question)
└─ Pool Activation
   └─ New graph_node created (first pool question)
       ↓
SSE Events Emitted → Frontend Updates

Feature-Driven Plan Generated
       ↓
plan_questions created with prefilled answers
       ↓
QuestionTaskGenerator.generateTasksForPlan()
       ↓
For each question:
  if (confidence >= 0.5) → REVIEW task
  if (confidence < 0.5) → PROVIDE task
       ↓
Tasks created with:
  - plan_question_id link
  - Task actions (APPROVE, EDIT, SKIP)
  - Output bindings (to plan_questions.user_answer)
       ↓
User Completes Task
       ↓
Task completion triggers binding execution
       ↓
plan_questions.user_answer updated
plan_questions.status = 'answered'
       ↓
Task marked as DONE

const poolTopicPatterns: Record<string, RegExp[]> = {
  'payment-stripe': [
    /stripe/i,
    /payment.*method/i,
    /payment.*feature/i,
    // ...
  ]
}

// Filter out questions matching activated pool topics
highConfidenceQuestions = highConfidenceQuestions.filter((q) => {
  const questionText = q.questionText.toLowerCase()
  return !coveredPatterns.some((pattern) => pattern.test(questionText))
})

const conversationHistory = nodes
  .filter((n) => n.answerData)
  .map((n) => ({
    question: n.questionData?.concept || n.title,
    answer: typeof n.answerData?.value === 'string'
      ? n.answerData.value
      : JSON.stringify(n.answerData?.value)
  }))

const projectConstraints: string[] = projectMetadata?.constraints || []

let textToAnalyze = answerText
if (projectConstraints.length > 0) {
  const constraintText = projectConstraints.join(' ')
  textToAnalyze = `${answerText} [Project Constraints: ${constraintText}]`
}

async createTaskIfNotExists(input: CreateTaskInput): Promise<Task | null> {
  // Check for existing task by plan question ID
  if (input.planQuestionId) {
    const exists = await this.taskExistsForPlanQuestion(input.planQuestionId)
    if (exists) return null
  }

  // Check for existing task by graph node ID
  if (!input.planQuestionId && input.graphNodeId) {
    const exists = await this.taskExistsForGraphNode(input.graphNodeId)
    if (exists) return null
  }

  return this.createTask(input)
}

if (this.activeTaskCount >= this.config.maxConcurrent) {
  this.scheduleNextPoll()
  return
}

// ... later ...

if (task) {
  // Process in background (don't await!)
  this.processTask(task).catch(...)

  // Immediately poll again if we have capacity
  if (this.activeTaskCount < this.config.maxConcurrent) {
    setImmediate(() => this.poll())
    return
  }
}

┌─────────────────────────────────────────────────────────────────────────────┐
│                           USER INPUT FLOW                                   │
│                                                                             │
│  User ──▶ Question ──▶ Answer ──▶ Post-Processing ──▶ Next Question        │
│              │            │              │                                  │
│              ▼            ▼              ▼                                  │
│         graph_nodes   answers     ┌─────────────────┐                      │
│              or                   │ Post-Answer      │                      │
│        plan_questions             │ Processing:      │                      │
│                                   │ - Ontology update│                      │
│                                   │ - Suggestions    │                      │
│                                   │ - Prefill cascade│                      │
│                                   │ - Task detection │                      │
│                                   └─────────────────┘                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        SPECIFICATION COMPILATION                            │
│                                                                             │
│  Discovery Output ──▶ Feature Selection ──▶ Plan Answers ──▶ Spec Compiler │
│         │                    │                   │                │        │
│         ▼                    ▼                   ▼                ▼        │
│   ┌──────────┐        ┌──────────┐        ┌──────────┐     ┌──────────┐   │
│   │ Entity   │        │ Feature  │        │ Require- │     │ Multi-   │   │
│   │Extraction│        │ Context  │        │  ments   │     │  Agent   │   │
│   │          │        │          │        │          │     │ Enhance  │   │
│   └──────────┘        └──────────┘        └──────────┘     └──────────┘   │
│         │                    │                   │                │        │
│         └────────────────────┴───────────────────┴────────────────┘        │
│                                        │                                    │
│                                        ▼                                    │
│                              ┌─────────────────┐                           │
│                              │     SpecV1      │                           │
│                              │   (Validated)   │                           │
│                              │                 │                           │
│                              │ - Entities      │                           │
│                              │ - Endpoints     │                           │
│                              │ - Workflows     │                           │
│                              │ - Requirements  │                           │
│                              │ - Test Cases    │                           │
│                              └─────────────────┘                           │
└─────────────────────────────────────────────────────────────────────────────┘

// Simplified flow from post-answer-processor.ts
async function processAnswer(answer: Answer) {
  // 1. Update ontology with extracted entities
  await ontologyTracker.extractAndUpdate(answer);

  // 2. Generate follow-up suggestions
  const suggestions = await suggestionGenerator.generate(answer);

  // 3. Cascade prefills to related questions
  await prefillCascade.propagate(answer);

  // 4. Detect new tasks
  await taskDetector.checkForTasks(answer);

  // 5. Update completion metrics
  await completionManager.recalculate(answer.project_id);

  // 6. Check phase readiness
  await phaseOrchestrator.checkReadiness(answer.project_id);
}

// User selects 'gcp' → load patterns WHERE cloud_provider IN ('agnostic', 'gcp')
// User selects 'agnostic' → load patterns WHERE cloud_provider = 'agnostic'
// Prefer cloud-specific over agnostic when both exist

interface Feature {
  id: string
  name: string  // "User Authentication", "Payment Processing"
  description: string
  category: string  // "Identity & Access", "Commerce"

  // Matching metadata
  applies_to: {
    industries: string[]  // ["all"], ["healthcare", "finance"]
    project_types: string[]  // ["saas", "marketplace"]
  }
  supports_goals: string[]  // ["security", "compliance", "user-management"]

  // Linkages
  related_patterns: string[]  // Pattern IDs from kb_patterns
  related_pool_ids: string[]  // Question pool IDs

  // Cloud awareness
  cloud_provider?: string  // Inherits from primary pattern
}

┌─────────────────────────────────────────────────────────────────┐
│                     KNOWLEDGE BASE LAYER                        │
│                                                                 │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐     │
│  │   Standards  │ →  │   Patterns   │ →  │   Features   │     │
│  │              │    │              │    │              │     │
│  │ Schema.org   │    │ MITRE ATT&CK │    │ 165 features │     │
│  │ NAICS        │    │ OWASP ASVS   │    │ Commodity: 85│     │
│  │ FHIR         │    │ NIST         │    │ Variable: 80 │     │
│  │ HR Open      │    │ CNCF         │    │ 9 categories │     │
│  │ Ed-Fi        │    │ 12-Factor    │    │              │     │
│  │ SALI         │    │ AWS (109)    │    │ With cloud-  │     │
│  │ ISO 20022    │    │ GCP (plan)   │    │ awareness    │     │
│  │ RESO         │    │              │    │              │     │
│  │              │    │              │    │              │     │
│  │ 3,000+       │    │ 751 patterns │    │ 129 pattern  │     │
│  │ entities     │    │ 642 agnostic │    │ mappings     │     │
│  │              │    │ 109 AWS      │    │              │     │
│  └──────────────┘    └──────────────┘    └──────┬───────┘     │
│                                                   │             │
└───────────────────────────────────────────────────┼─────────────┘
                                                    │
                                   ┌────────────────▼─────────────┐
                                   │    RUNTIME LAYER             │
                                   │                              │
                                   │  Discovery → Feature Match   │
                                   │  Feature → Question Pools    │
                                   │  Questions → Specifications  │
                                   └──────────────────────────────┘

// Old approach: naive keyword search
const signals = extractKeywords(answers);  // ["payment", "stripe", "checkout"]
const features = featureCatalog.filter(f =>
  signals.some(s => f.name.toLowerCase().includes(s))
);

// 1. Bridge requirements discovery to DiscoveryContext
const context = await bridgeRequirementsDiscovery(projectId, tenantId);

// 2. Extract structured signals
const signals = {
  goals: context.purpose_and_problem.goals,  // ["accept payments", "subscription billing"]
  painPoints: context.users_and_personas.painPoints,  // ["manual invoicing", "payment failures"]
  jobsToBeDone: context.users_and_personas.jobsToBeDone,  // ["process credit cards"]
  constraints: context.constraints.existingSystems,  // ["Stripe"]
  dealbreakers: context.success_criteria.dealbreakers,  // ["PCI compliance required"]
  sensitiveData: context.non_functional_screening.sensitiveData,  // ["credit cards"]
  expectedScale: context.non_functional_screening.expectedScale  // ["10k transactions/month"]
};

// 3. Match features using structured signals
const features = featureMatcher.matchFeatures(context);
// Returns: Payment Processing, Stripe Integration, PCI Compliance, Subscription Management

// 4. Score and rank by relevance
const rankedFeatures = scoreFeatures(features, context);

function scoreFeature(feature: Feature, context: DiscoveryContext): number {
  let score = 0;

  // Industry match (30 points)
  if (feature.applies_to.industries.includes(context.industry)) score += 30;
  else if (feature.applies_to.industries.includes('all')) score += 10;

  // Goal match (20 points per match)
  const goalMatches = context.goals.filter(g => feature.supports_goals.includes(g));
  score += goalMatches.length * 20;

  // Constraint match (25 points per match)
  const constraintMatches = context.constraints.mustHaves?.filter(c =>
    feature.supports_goals.includes(c.toLowerCase())
  ) || [];
  score += constraintMatches.length * 25;

  // Existing system integration (15 points)
  if (context.constraints.existingSystems?.length > 0) {
    if (feature.category === 'Integrations') score += 15;
  }

  // Pattern match (10 points per pattern)
  const patternMatches = feature.related_patterns.filter(p =>
    detectedPatterns.includes(p)
  );
  score += patternMatches.length * 10;

  return score;
}

pnpm run import:schema-org    # ~827 types
pnpm run import:naics         # ~1,012 codes
pnpm run import:fhir          # ~157 resources
pnpm run import:hr-open       # 50 entities
pnpm run import:ed-fi         # 86 entities
pnpm run import:sali          # 267 entities
pnpm run import:iso20022      # 323 entities
pnpm run import:reso          # 331 entities