Merge pull request #7 from danghoangnhan/feat/smart-gap-analysis

feat: smart gap analysis with question cards for NOT READY agents

agents/crew_orchestrator.py

@@ -15,6 +15,7 @@ from pathlib import Path
 from agents.base import BaseOrchestrator
 from agents.definitions import AGENTS
 from agents.design_state import DesignState, DesignPlan, extract_decisions, compute_score
+from agents.gap_analyzer import analyze_gaps, generate_question_cards
 from agents.orchestrator import _format_response
 from agents.routing import RoutingEngine
 from config.settings import settings
@@ -123,6 +124,7 @@ class CrewOrchestrator(BaseOrchestrator):
                 "responses": [],
                 "preview": None,
                 "design_state": state.model_dump(),
+                "question_cards": [],
             }
 
         if not self._crew_available:
@@ -144,6 +146,7 @@ class CrewOrchestrator(BaseOrchestrator):
                     )],
                     "preview": None,
                     "design_state": design_state or {},
+                    "question_cards": [],
                 }
 
     def _run_crew(
@@ -259,9 +262,20 @@ class CrewOrchestrator(BaseOrchestrator):
                 )
             elif agent_id == "cam":
                 task_description += (
-                    "\n\nAnalyze the part geometry and create an optimal machining "
-                    "strategy. Select operations in order (roughing before finishing). "
-                    "Use the Generate G-code Toolpath tool to create the G-code."
+                    "\n\nIf there is no CAD model generated yet or critical machining "
+                    "info is missing (material, dimensions, surface finish requirements), "
+                    "start with 'NOT READY:' and list missing items. "
+                    "If enough info exists, analyze the part geometry and create an "
+                    "optimal machining strategy. Select operations in order (roughing "
+                    "before finishing). Use the Generate G-code Toolpath tool to create "
+                    "the G-code."
+                )
+            elif agent_id == "cnc":
+                task_description += (
+                    "\n\nIf the design lacks critical manufacturability info (material, "
+                    "dimensions, feature access, tolerance), start with 'NOT READY:' "
+                    "and list missing items. If enough info exists, provide your "
+                    "manufacturability assessment."
                 )
             else:
                 task_description += (
@@ -269,11 +283,12 @@ class CrewOrchestrator(BaseOrchestrator):
                     "SPECIFIC clarifying question."
                 )
 
-            expected_output = (
-                "A concise response from your expert perspective (2-4 sentences)."
-                if agent_id != "cad"
-                else "Valid CadQuery Python code or a 'NOT READY:' message."
-            )
+            if agent_id == "cad":
+                expected_output = "Valid CadQuery Python code or a 'NOT READY:' message."
+            elif agent_id in ("cnc", "cam"):
+                expected_output = "A concise expert assessment or a 'NOT READY:' message listing missing items."
+            else:
+                expected_output = "A concise response from your expert perspective (2-4 sentences)."
 
             task = Task(
                 description=task_description,
@@ -286,7 +301,7 @@ class CrewOrchestrator(BaseOrchestrator):
             crew_tasks.append(task)
 
         if not crew_agents:
-            return {"responses": [], "preview": None, "design_state": state.model_dump()}
+            return {"responses": [], "preview": None, "design_state": state.model_dump(), "question_cards": []}
 
         crew = Crew(
             agents=crew_agents,
@@ -389,6 +404,13 @@ class CrewOrchestrator(BaseOrchestrator):
         agent_msgs = [{"message": r.get("message", "")} for r in responses]
         updated_state = extract_decisions(agent_msgs, state, message)
 
+        # Gap analysis — detect missing info and generate question cards
+        gap_result = analyze_gaps(responses)
+        question_cards = []
+        if gap_result.has_gaps:
+            cards = generate_question_cards(gap_result, updated_state)
+            question_cards = [c.model_dump() for c in cards]
+
         # Auto-trigger plan if score crosses threshold
         if updated_state.phase == "exploring":
             score = compute_score(updated_state)
@@ -409,6 +431,7 @@ class CrewOrchestrator(BaseOrchestrator):
             "responses": responses,
             "preview": preview,
             "design_state": updated_state.model_dump(),
+            "question_cards": question_cards,
         }
 
     def _extract_code(self, text: str) -> str | None:
@@ -431,4 +454,15 @@ class CrewOrchestrator(BaseOrchestrator):
         """Fall back to MockChatBackend."""
         from agents.orchestrator import MockChatBackend
         mock = MockChatBackend(output_dir=self.output_dir)
-        return mock.chat_turn(message, history, mentions, design_state=design_state)
+        result = mock.chat_turn(message, history, mentions, design_state=design_state)
+        if "question_cards" not in result:
+            from agents.design_state import DesignState
+            result_responses = result.get("responses", [])
+            gap_result = analyze_gaps(result_responses)
+            if gap_result.has_gaps:
+                state = DesignState(**(design_state or {}))
+                cards = generate_question_cards(gap_result, state)
+                result["question_cards"] = [c.model_dump() for c in cards]
+            else:
+                result["question_cards"] = []
+        return result

agents/gap_analyzer.py

@@ -0,0 +1,195 @@
+"""Gap analyzer — detects missing design information from agent responses.
+
+Scans for NOT READY: prefixes, classifies missing items into categories,
+and generates structured question cards for the UI to present to the user.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from config.settings import settings
+from agents.definitions import AGENTS
+
+
+# ── Models ────────────────────────────────────────────────────────────────────
+
+
+class MissingItem(BaseModel):
+    category: str       # "dimension", "material", "feature", etc.
+    description: str    # the keyword that matched
+    agent_id: str       # which agent flagged it
+
+
+class GapAnalysis(BaseModel):
+    has_gaps: bool = False
+    missing_items: list[MissingItem] = Field(default_factory=list)
+
+
+class QuestionCard(BaseModel):
+    category: str
+    question: str
+    responsible_agent: str
+    agent_name: str
+    agent_color: str
+    suggestions: list[str] = Field(default_factory=list)
+    allow_custom: bool = True
+
+
+# ── Question templates ────────────────────────────────────────────────────────
+
+QUESTION_TEMPLATES: dict[str, dict] = {
+    "dimension": {
+        "question": "What are the part dimensions?",
+        "suggestions": [],
+        "allow_custom": True,
+    },
+    "material": {
+        "question": "What material should this be made from?",
+        "suggestions": ["Aluminum 6061", "Aluminum 7075", "Steel 304", "Steel 316", "Brass", "Titanium"],
+        "allow_custom": True,
+    },
+    "shape": {
+        "question": "What type of part are you designing?",
+        "suggestions": ["Bracket", "Enclosure", "Plate", "Shaft", "Gear", "Flange"],
+        "allow_custom": True,
+    },
+    "feature": {
+        "question": "What features does the part need?",
+        "suggestions": ["Mounting holes", "Fillets", "Chamfers", "Pockets", "Slots"],
+        "allow_custom": True,
+    },
+    "constraint": {
+        "question": "Are there any manufacturing constraints?",
+        "suggestions": ["Min wall 2mm", "Min wall 3mm", "Min wall 5mm"],
+        "allow_custom": True,
+    },
+    "machining": {
+        "question": "What machining approach?",
+        "suggestions": ["3-axis", "3+2-axis", "5-axis", "Auto"],
+        "allow_custom": False,
+    },
+    "finish": {
+        "question": "What surface finish is required?",
+        "suggestions": ["Standard", "Fine (Ra 1.6)", "Mirror (Ra 0.4)"],
+        "allow_custom": False,
+    },
+    "model": {
+        "question": "A 3D model is needed first. Provide more design details or approve the plan to generate.",
+        "suggestions": [],
+        "allow_custom": False,
+    },
+}
+
+
+# ── Core functions ────────────────────────────────────────────────────────────
+
+
+def analyze_gaps(responses: list[dict]) -> GapAnalysis:
+    """Scan agent responses for NOT READY: prefixes and classify missing items.
+
+    Deduplicates by category — first agent to flag a category wins.
+    """
+    category_keywords: dict[str, list[str]] = settings.gap_analysis.category_keywords
+
+    # Track which categories have already been claimed (first-agent-wins)
+    seen_categories: set[str] = set()
+    missing_items: list[MissingItem] = []
+
+    for response in responses:
+        message: str = response.get("message", "")
+        agent_id: str = response.get("agent_id", "")
+
+        # Case-insensitive check for NOT READY: prefix
+        stripped = message.strip()
+        lower_stripped = stripped.lower()
+        if not lower_stripped.startswith("not ready:"):
+            continue
+
+        # Extract the text after the "NOT READY:" prefix
+        colon_pos = stripped.index(":") + 1
+        gap_text = stripped[colon_pos:].strip()
+        gap_lower = gap_text.lower()
+
+        # Match keywords for each category
+        for category, keywords in category_keywords.items():
+            if category in seen_categories:
+                continue
+            for keyword in keywords:
+                if keyword.lower() in gap_lower:
+                    seen_categories.add(category)
+                    missing_items.append(MissingItem(
+                        category=category,
+                        description=keyword,
+                        agent_id=agent_id,
+                    ))
+                    break  # one keyword match per category per response is enough
+
+    return GapAnalysis(
+        has_gaps=bool(missing_items),
+        missing_items=missing_items,
+    )
+
+
+def _is_category_satisfied(category: str, state) -> bool:
+    """Return True if the state already has data covering this category."""
+    if category == "material":
+        return bool(state.material)
+    if category == "dimension":
+        return bool(state.dimensions)
+    if category == "shape":
+        return bool(state.part_name)
+    if category == "feature":
+        return bool(state.features)
+    if category == "constraint":
+        return bool(state.constraints)
+    if category == "machining":
+        return bool(state.axis_recommendation)
+    return False
+
+
+def generate_question_cards(gaps: GapAnalysis, state) -> list[QuestionCard]:
+    """Convert a GapAnalysis into question cards, skipping already-satisfied categories.
+
+    Looks up responsible agent from settings, agent metadata from AGENTS dict,
+    and question text/suggestions from QUESTION_TEMPLATES.
+    """
+    if not gaps.has_gaps:
+        return []
+
+    category_agents: dict[str, str] = settings.gap_analysis.category_agents
+    cards: list[QuestionCard] = []
+
+    for item in gaps.missing_items:
+        category = item.category
+
+        # Skip if the state already satisfies this gap
+        if _is_category_satisfied(category, state):
+            continue
+
+        # Look up responsible agent id
+        responsible_agent = category_agents.get(category, item.agent_id)
+
+        # Look up agent metadata
+        agent_def = AGENTS.get(responsible_agent)
+        agent_name = agent_def.name if agent_def else responsible_agent.title()
+        agent_color = agent_def.color if agent_def else "#888888"
+
+        # Look up question template
+        template = QUESTION_TEMPLATES.get(category, {
+            "question": f"Please provide {category} details.",
+            "suggestions": [],
+            "allow_custom": True,
+        })
+
+        cards.append(QuestionCard(
+            category=category,
+            question=template["question"],
+            responsible_agent=responsible_agent,
+            agent_name=agent_name,
+            agent_color=agent_color,
+            suggestions=list(template["suggestions"]),
+            allow_custom=template["allow_custom"],
+        ))
+
+    return cards

config.yaml

@@ -96,6 +96,68 @@ planning:
     - "cad"
     - "cnc"
 
+gap_analysis:
+  category_keywords:
+    dimension:
+      - width
+      - height
+      - depth
+      - length
+      - diameter
+      - dimension
+      - size
+    material:
+      - material
+      - alloy
+      - grade
+      - aluminum
+      - steel
+      - metal
+    shape:
+      - shape
+      - form
+      - type
+      - profile
+      - geometry
+      - what kind
+    feature:
+      - hole
+      - fillet
+      - chamfer
+      - pocket
+      - slot
+      - feature
+    constraint:
+      - tolerance
+      - wall thickness
+      - constraint
+      - min wall
+      - max size
+    machining:
+      - axis
+      - machine
+      - setup
+      - fixture
+      - tool access
+    finish:
+      - surface finish
+      - roughness
+      - Ra
+    model:
+      - model
+      - CAD
+      - 3D
+      - generate
+  category_agents:
+    dimension: engineering
+    material: engineering
+    shape: design
+    feature: design
+    constraint: engineering
+    machining: cnc
+    finish: cnc
+    model: cad
+
 agents:
   design:
     name: Design Agent

config/settings.py

@@ -111,6 +111,29 @@ class PlanningConfig(BaseModel):
     approved_agents: list[str] = Field(default_factory=lambda: ["cad", "cnc"])
 
 
+class GapAnalysisConfig(BaseModel):
+    category_keywords: dict[str, list[str]] = Field(default_factory=lambda: {
+        "dimension": ["width", "height", "depth", "length", "diameter", "dimension", "size"],
+        "material": ["material", "alloy", "grade", "aluminum", "steel", "metal"],
+        "shape": ["shape", "form", "type", "profile", "geometry", "what kind"],
+        "feature": ["hole", "fillet", "chamfer", "pocket", "slot", "feature"],
+        "constraint": ["tolerance", "wall thickness", "constraint", "min wall", "max size"],
+        "machining": ["axis", "machine", "setup", "fixture", "tool access"],
+        "finish": ["surface finish", "roughness", "Ra"],
+        "model": ["model", "CAD", "3D", "generate"],
+    })
+    category_agents: dict[str, str] = Field(default_factory=lambda: {
+        "dimension": "engineering",
+        "material": "engineering",
+        "shape": "design",
+        "feature": "design",
+        "constraint": "engineering",
+        "machining": "cnc",
+        "finish": "cnc",
+        "model": "cad",
+    })
+
+
 # ── Main Settings ─────────────────────────────────────────────────────────
 
 
@@ -136,6 +159,7 @@ class Settings(BaseSettings):
     export: ExportConfig = Field(default_factory=ExportConfig)
     cam: CAMConfig = Field(default_factory=CAMConfig)
     planning: PlanningConfig = Field(default_factory=PlanningConfig)
+    gap_analysis: GapAnalysisConfig = Field(default_factory=GapAnalysisConfig)
     agents: dict[str, AgentConfig] = Field(default_factory=dict)
     routing: RoutingConfig = Field(default_factory=RoutingConfig)
 

docs/superpowers/plans/2026-04-12-smart-gap-analysis.md

@@ -0,0 +1,963 @@
+# Smart Gap Analysis & Question Cards Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** When CAD/CNC/CAM agents report missing info via "NOT READY:", the orchestrator analyzes the gaps, categorizes them, and returns actionable question cards to the frontend.
+
+**Architecture:** A new `agents/gap_analyzer.py` module provides pure functions for gap analysis and question card generation. The orchestrator calls these after collecting agent responses. The frontend renders interactive cards inline in chat.
+
+**Tech Stack:** Python/Pydantic (models), regex/keyword matching (analysis), vanilla JS (frontend cards)
+
+---
+
+### Task 1: GapAnalysisConfig in settings
+
+**Files:**
+- Modify: `config/settings.py:93-111` (add `GapAnalysisConfig` after `PlanningConfig`)
+- Modify: `config/settings.py:138-140` (add `gap_analysis` field to `Settings`)
+- Modify: `config.yaml` (add `gap_analysis` section after `planning`)
+- Test: `tests/test_settings.py`
+
+- [ ] **Step 1: Write failing test**
+
+```python
+# tests/test_settings.py — add to existing file
+
+class TestGapAnalysisConfig:
+    def test_gap_analysis_defaults(self):
+        from config.settings import Settings
+        s = Settings()
+        assert "dimension" in s.gap_analysis.category_keywords
+        assert "material" in s.gap_analysis.category_keywords
+        assert s.gap_analysis.category_agents["dimension"] == "engineering"
+        assert s.gap_analysis.category_agents["shape"] == "design"
+
+    def test_gap_analysis_loaded_from_yaml(self):
+        from config.settings import settings
+        assert "width" in settings.gap_analysis.category_keywords.get("dimension", [])
+        assert settings.gap_analysis.category_agents["machining"] == "cnc"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_settings.py::TestGapAnalysisConfig -v`
+Expected: FAIL with `AttributeError: 'Settings' object has no attribute 'gap_analysis'`
+
+- [ ] **Step 3: Add GapAnalysisConfig to settings.py**
+
+Add after `PlanningConfig` class (around line 112):
+
+```python
+class GapAnalysisConfig(BaseModel):
+    category_keywords: dict[str, list[str]] = Field(default_factory=lambda: {
+        "dimension": ["width", "height", "depth", "length", "diameter", "dimension", "size"],
+        "material": ["material", "alloy", "grade", "aluminum", "steel", "metal"],
+        "shape": ["shape", "form", "type", "profile", "geometry", "what kind"],
+        "feature": ["hole", "fillet", "chamfer", "pocket", "slot", "feature"],
+        "constraint": ["tolerance", "wall thickness", "constraint", "min wall", "max size"],
+        "machining": ["axis", "machine", "setup", "fixture", "tool access"],
+        "finish": ["surface finish", "roughness", "Ra"],
+        "model": ["model", "CAD", "3D", "generate"],
+    })
+    category_agents: dict[str, str] = Field(default_factory=lambda: {
+        "dimension": "engineering",
+        "material": "engineering",
+        "shape": "design",
+        "feature": "design",
+        "constraint": "engineering",
+        "machining": "cnc",
+        "finish": "cnc",
+        "model": "cad",
+    })
+```
+
+Add to `Settings` class after `planning` field (line 138):
+
+```python
+    gap_analysis: GapAnalysisConfig = Field(default_factory=GapAnalysisConfig)
+```
+
+- [ ] **Step 4: Add gap_analysis section to config.yaml**
+
+Add after the `planning` section (before `agents:`):
+
+```yaml
+gap_analysis:
+  category_keywords:
+    dimension:
+      - width
+      - height
+      - depth
+      - length
+      - diameter
+      - dimension
+      - size
+    material:
+      - material
+      - alloy
+      - grade
+      - aluminum
+      - steel
+      - metal
+    shape:
+      - shape
+      - form
+      - type
+      - profile
+      - geometry
+      - what kind
+    feature:
+      - hole
+      - fillet
+      - chamfer
+      - pocket
+      - slot
+      - feature
+    constraint:
+      - tolerance
+      - wall thickness
+      - constraint
+      - min wall
+      - max size
+    machining:
+      - axis
+      - machine
+      - setup
+      - fixture
+      - tool access
+    finish:
+      - surface finish
+      - roughness
+      - Ra
+    model:
+      - model
+      - CAD
+      - 3D
+      - generate
+  category_agents:
+    dimension: engineering
+    material: engineering
+    shape: design
+    feature: design
+    constraint: engineering
+    machining: cnc
+    finish: cnc
+    model: cad
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_settings.py -v`
+Expected: All pass
+
+- [ ] **Step 6: Run full test suite**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/ --tb=short`
+Expected: All pass
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add config/settings.py config.yaml tests/test_settings.py
+git commit -m "feat: add GapAnalysisConfig to settings with category keywords and agents"
+```
+
+---
+
+### Task 2: Gap analyzer module — models and analyze_gaps()
+
+**Files:**
+- Create: `agents/gap_analyzer.py`
+- Create: `tests/test_gap_analyzer.py`
+
+- [ ] **Step 1: Write failing tests**
+
+```python
+# tests/test_gap_analyzer.py
+
+from agents.gap_analyzer import MissingItem, GapAnalysis, analyze_gaps
+
+
+class TestAnalyzeGaps:
+    def test_no_gaps_when_no_not_ready(self):
+        responses = [
+            {"agent_id": "design", "message": "I suggest an L-bracket design."},
+            {"agent_id": "engineering", "message": "Aluminum 6061 would work well."},
+        ]
+        result = analyze_gaps(responses)
+        assert not result.has_gaps
+        assert result.missing_items == []
+
+    def test_detects_not_ready_from_cad(self):
+        responses = [
+            {"agent_id": "cad", "message": "NOT READY: Need dimensions (width, height) and material selection."},
+        ]
+        result = analyze_gaps(responses)
+        assert result.has_gaps
+        categories = [item.category for item in result.missing_items]
+        assert "dimension" in categories
+        assert "material" in categories
+
+    def test_detects_not_ready_from_cnc(self):
+        responses = [
+            {"agent_id": "cnc", "message": "NOT READY: Need material and tolerance info for manufacturability check."},
+        ]
+        result = analyze_gaps(responses)
+        assert result.has_gaps
+        categories = [item.category for item in result.missing_items]
+        assert "material" in categories
+        assert "constraint" in categories
+
+    def test_detects_not_ready_from_cam(self):
+        responses = [
+            {"agent_id": "cam", "message": "NOT READY: No 3D model available. Need CAD generation first."},
+        ]
+        result = analyze_gaps(responses)
+        assert result.has_gaps
+        categories = [item.category for item in result.missing_items]
+        assert "model" in categories
+
+    def test_deduplicates_across_agents(self):
+        responses = [
+            {"agent_id": "cad", "message": "NOT READY: Need material and dimensions."},
+            {"agent_id": "cnc", "message": "NOT READY: Material is required for manufacturability."},
+        ]
+        result = analyze_gaps(responses)
+        material_items = [i for i in result.missing_items if i.category == "material"]
+        assert len(material_items) == 1
+        assert material_items[0].agent_id == "cad"  # first wins
+
+    def test_case_insensitive_not_ready(self):
+        responses = [
+            {"agent_id": "cad", "message": "not ready: missing width and height dimensions."},
+        ]
+        result = analyze_gaps(responses)
+        assert result.has_gaps
+        assert any(item.category == "dimension" for item in result.missing_items)
+
+    def test_no_false_positive_on_regular_message(self):
+        responses = [
+            {"agent_id": "cad", "message": "Model generated successfully."},
+            {"agent_id": "cnc", "message": "3-axis machining is ready for this part."},
+        ]
+        result = analyze_gaps(responses)
+        assert not result.has_gaps
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_gap_analyzer.py -v`
+Expected: FAIL with `ModuleNotFoundError`
+
+- [ ] **Step 3: Create agents/gap_analyzer.py with models and analyze_gaps()**
+
+```python
+"""Gap analyzer — detects missing info from agent NOT READY responses and generates question cards."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from agents.definitions import AGENTS
+from config.settings import settings
+
+
+# ── Data Models ──────────────────────────────────────────────────────────
+
+
+class MissingItem(BaseModel):
+    """A single piece of missing information flagged by an agent."""
+    category: str
+    description: str
+    agent_id: str
+
+
+class GapAnalysis(BaseModel):
+    """Result of scanning agent responses for missing information."""
+    has_gaps: bool = False
+    missing_items: list[MissingItem] = Field(default_factory=list)
+
+
+# ── Gap Analysis ─────────────────────────────────────────────────────────
+
+
+def analyze_gaps(responses: list[dict]) -> GapAnalysis:
+    """Scan agent responses for NOT READY prefixes and categorize missing items.
+
+    Args:
+        responses: List of agent response dicts with 'agent_id' and 'message' keys.
+
+    Returns:
+        GapAnalysis with categorized missing items, deduplicated across agents.
+    """
+    cfg = settings.gap_analysis
+    items: list[MissingItem] = []
+    seen_categories: set[str] = set()
+
+    for resp in responses:
+        message = resp.get("message", "")
+        agent_id = resp.get("agent_id", "")
+
+        if not message.upper().startswith("NOT READY:"):
+            continue
+
+        # Extract text after "NOT READY:"
+        gap_text = message.split(":", 1)[1].strip().lower()
+
+        # Match against category keywords
+        for category, keywords in cfg.category_keywords.items():
+            if category in seen_categories:
+                continue
+            for keyword in keywords:
+                if keyword.lower() in gap_text:
+                    items.append(MissingItem(
+                        category=category,
+                        description=keyword,
+                        agent_id=agent_id,
+                    ))
+                    seen_categories.add(category)
+                    break
+
+    return GapAnalysis(
+        has_gaps=len(items) > 0,
+        missing_items=items,
+    )
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_gap_analyzer.py -v`
+Expected: All pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add agents/gap_analyzer.py tests/test_gap_analyzer.py
+git commit -m "feat: add gap analyzer with MissingItem, GapAnalysis models and analyze_gaps()"
+```
+
+---
+
+### Task 3: generate_question_cards() with state filtering
+
+**Files:**
+- Modify: `agents/gap_analyzer.py` (add `QuestionCard` model and `generate_question_cards()`)
+- Modify: `tests/test_gap_analyzer.py` (add tests)
+
+- [ ] **Step 1: Write failing tests**
+
+```python
+# tests/test_gap_analyzer.py — add to existing file
+
+from agents.gap_analyzer import QuestionCard, generate_question_cards
+from agents.design_state import DesignState
+
+
+class TestGenerateQuestionCards:
+    def test_generates_cards_from_gaps(self):
+        gaps = GapAnalysis(
+            has_gaps=True,
+            missing_items=[
+                MissingItem(category="material", description="material", agent_id="cad"),
+                MissingItem(category="dimension", description="width", agent_id="cad"),
+            ],
+        )
+        cards = generate_question_cards(gaps, DesignState())
+        assert len(cards) == 2
+        material_card = next(c for c in cards if c.category == "material")
+        assert material_card.responsible_agent == "engineering"
+        assert len(material_card.suggestions) > 0
+        assert material_card.allow_custom is True
+
+    def test_filters_out_already_set_material(self):
+        gaps = GapAnalysis(
+            has_gaps=True,
+            missing_items=[
+                MissingItem(category="material", description="material", agent_id="cad"),
+                MissingItem(category="dimension", description="width", agent_id="cad"),
+            ],
+        )
+        state = DesignState(material="aluminum 6061")
+        cards = generate_question_cards(gaps, state)
+        categories = [c.category for c in cards]
+        assert "material" not in categories
+        assert "dimension" in categories
+
+    def test_filters_out_already_set_dimensions(self):
+        gaps = GapAnalysis(
+            has_gaps=True,
+            missing_items=[
+                MissingItem(category="dimension", description="width", agent_id="cad"),
+            ],
+        )
+        state = DesignState(dimensions={"width": 60, "height": 40})
+        cards = generate_question_cards(gaps, state)
+        assert len(cards) == 0
+
+    def test_no_cards_when_no_gaps(self):
+        gaps = GapAnalysis(has_gaps=False, missing_items=[])
+        cards = generate_question_cards(gaps, DesignState())
+        assert cards == []
+
+    def test_card_has_agent_metadata(self):
+        gaps = GapAnalysis(
+            has_gaps=True,
+            missing_items=[
+                MissingItem(category="machining", description="axis", agent_id="cnc"),
+            ],
+        )
+        cards = generate_question_cards(gaps, DesignState())
+        assert len(cards) == 1
+        assert cards[0].responsible_agent == "cnc"
+        assert cards[0].agent_name == "CNC Agent"
+        assert cards[0].agent_color == "#00e676"
+
+    def test_model_category_no_suggestions(self):
+        gaps = GapAnalysis(
+            has_gaps=True,
+            missing_items=[
+                MissingItem(category="model", description="3D", agent_id="cam"),
+            ],
+        )
+        cards = generate_question_cards(gaps, DesignState())
+        assert len(cards) == 1
+        assert cards[0].suggestions == []
+        assert cards[0].allow_custom is False
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_gap_analyzer.py::TestGenerateQuestionCards -v`
+Expected: FAIL with `ImportError: cannot import name 'QuestionCard'`
+
+- [ ] **Step 3: Add QuestionCard model and generate_question_cards()**
+
+Add to `agents/gap_analyzer.py`:
+
+```python
+class QuestionCard(BaseModel):
+    """An actionable question card for the frontend."""
+    category: str
+    question: str
+    responsible_agent: str
+    agent_name: str
+    agent_color: str
+    suggestions: list[str] = Field(default_factory=list)
+    allow_custom: bool = True
+
+
+# ── Question Templates ───────────────────────────────────────────────────
+
+QUESTION_TEMPLATES: dict[str, dict] = {
+    "dimension": {
+        "question": "What are the part dimensions?",
+        "suggestions": [],
+        "allow_custom": True,
+    },
+    "material": {
+        "question": "What material should this be made from?",
+        "suggestions": ["Aluminum 6061", "Aluminum 7075", "Steel 304", "Steel 316", "Brass", "Titanium"],
+        "allow_custom": True,
+    },
+    "shape": {
+        "question": "What type of part are you designing?",
+        "suggestions": ["Bracket", "Enclosure", "Plate", "Shaft", "Gear", "Flange"],
+        "allow_custom": True,
+    },
+    "feature": {
+        "question": "What features does the part need?",
+        "suggestions": ["Mounting holes", "Fillets", "Chamfers", "Pockets", "Slots"],
+        "allow_custom": True,
+    },
+    "constraint": {
+        "question": "Are there any manufacturing constraints?",
+        "suggestions": ["Min wall 2mm", "Min wall 3mm", "Min wall 5mm"],
+        "allow_custom": True,
+    },
+    "machining": {
+        "question": "What machining approach?",
+        "suggestions": ["3-axis", "3+2-axis", "5-axis", "Auto"],
+        "allow_custom": False,
+    },
+    "finish": {
+        "question": "What surface finish is required?",
+        "suggestions": ["Standard", "Fine (Ra 1.6)", "Mirror (Ra 0.4)"],
+        "allow_custom": False,
+    },
+    "model": {
+        "question": "A 3D model is needed first. Provide more design details or approve the plan to generate.",
+        "suggestions": [],
+        "allow_custom": False,
+    },
+}
+
+
+# ── Question Card Generation ─────────────────────────────────────────────
+
+def _is_category_satisfied(category: str, state) -> bool:
+    """Check if a category's info is already present in the design state."""
+    if category == "material" and state.material:
+        return True
+    if category == "dimension" and state.dimensions:
+        return True
+    if category == "shape" and state.part_name:
+        return True
+    if category == "feature" and state.features:
+        return True
+    if category == "constraint" and state.constraints:
+        return True
+    if category == "machining" and state.axis_recommendation:
+        return True
+    return False
+
+
+def generate_question_cards(gaps: GapAnalysis, state) -> list[QuestionCard]:
+    """Generate question cards from gap analysis, filtering out already-answered items.
+
+    Args:
+        gaps: Result of analyze_gaps().
+        state: Current DesignState to filter against.
+
+    Returns:
+        List of QuestionCard objects for the frontend.
+    """
+    if not gaps.has_gaps:
+        return []
+
+    cfg = settings.gap_analysis
+    cards: list[QuestionCard] = []
+
+    for item in gaps.missing_items:
+        if _is_category_satisfied(item.category, state):
+            continue
+
+        template = QUESTION_TEMPLATES.get(item.category)
+        if not template:
+            continue
+
+        agent_id = cfg.category_agents.get(item.category, "design")
+        agent_def = AGENTS.get(agent_id)
+        agent_name = agent_def.name if agent_def else agent_id
+        agent_color = agent_def.color if agent_def else "#888888"
+
+        cards.append(QuestionCard(
+            category=item.category,
+            question=template["question"],
+            responsible_agent=agent_id,
+            agent_name=agent_name,
+            agent_color=agent_color,
+            suggestions=list(template["suggestions"]),
+            allow_custom=template["allow_custom"],
+        ))
+
+    return cards
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_gap_analyzer.py -v`
+Expected: All pass
+
+- [ ] **Step 5: Run full test suite**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/ --tb=short`
+Expected: All pass
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add agents/gap_analyzer.py tests/test_gap_analyzer.py
+git commit -m "feat: add QuestionCard model and generate_question_cards() with state filtering"
+```
+
+---
+
+### Task 4: Orchestrator integration — call gap analyzer and update CNC/CAM prompts
+
+**Files:**
+- Modify: `agents/crew_orchestrator.py:17` (add import)
+- Modify: `agents/crew_orchestrator.py:260-270` (update CNC/CAM task descriptions)
+- Modify: `agents/crew_orchestrator.py:388-412` (call gap analyzer, add question_cards to return)
+- Test: `tests/test_crew_orchestrator.py`
+
+- [ ] **Step 1: Write failing tests**
+
+Read `tests/test_crew_orchestrator.py` first to understand existing patterns. Then add:
+
+```python
+# tests/test_crew_orchestrator.py — add to existing file
+
+class TestGapAnalysis:
+    """Tests for gap analysis integration in CrewOrchestrator."""
+
+    def test_not_ready_produces_question_cards(self):
+        """Mock backend CAD agent returns NOT READY, should produce question cards."""
+        orch = CrewOrchestrator(backend_name="mock")
+        result = orch.chat_turn(
+            message="generate a bracket",
+            history=[],
+            design_state={},
+        )
+        # Mock backend's CAD fallback message starts with "NOT READY:"
+        # Check that question_cards key exists
+        assert "question_cards" in result
+
+    def test_no_question_cards_when_no_gaps(self):
+        """Normal responses should produce empty question_cards."""
+        orch = CrewOrchestrator(backend_name="mock")
+        result = orch.chat_turn(
+            message="I need a bracket",
+            history=[],
+            design_state={"material": "aluminum", "dimensions": {"width": 60}},
+        )
+        assert "question_cards" in result
+        # Even if cards generated, state filtering should remove some
+        assert isinstance(result["question_cards"], list)
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_crew_orchestrator.py::TestGapAnalysis -v`
+Expected: FAIL (question_cards key doesn't exist in response)
+
+- [ ] **Step 3: Add import to crew_orchestrator.py**
+
+Add to imports at top:
+
+```python
+from agents.gap_analyzer import analyze_gaps, generate_question_cards
+```
+
+- [ ] **Step 4: Update CNC and CAM task descriptions**
+
+In `_run_crew`, find the `elif agent_id == "cam":` block (around line 260) and replace:
+
+```python
+            elif agent_id == "cam":
+                task_description += (
+                    "\n\nIf there is no CAD model generated yet or critical machining "
+                    "info is missing (material, dimensions, surface finish requirements), "
+                    "start with 'NOT READY:' and list missing items. "
+                    "If enough info exists, analyze the part geometry and create an "
+                    "optimal machining strategy. Select operations in order (roughing "
+                    "before finishing). Use the Generate G-code Toolpath tool to create "
+                    "the G-code."
+                )
+```
+
+Find the `else:` block (around line 266) that handles non-CAD agents and change it to also handle CNC:
+
+```python
+            elif agent_id == "cnc":
+                task_description += (
+                    "\n\nIf the design lacks critical manufacturability info (material, "
+                    "dimensions, feature access, tolerance), start with 'NOT READY:' "
+                    "and list missing items. If enough info exists, provide your "
+                    "manufacturability assessment."
+                )
+            else:
+                task_description += (
+                    "\n\nIf key information is missing in YOUR domain, ask a "
+                    "SPECIFIC clarifying question."
+                )
+```
+
+Also update the `expected_output` to cover CNC and CAM:
+
+```python
+            if agent_id == "cad":
+                expected_output = "Valid CadQuery Python code or a 'NOT READY:' message."
+            elif agent_id in ("cnc", "cam"):
+                expected_output = "A concise expert assessment or a 'NOT READY:' message listing missing items."
+            else:
+                expected_output = "A concise response from your expert perspective (2-4 sentences)."
+```
+
+- [ ] **Step 5: Add gap analysis call and question_cards to response**
+
+In `_run_crew`, after `updated_state = extract_decisions(...)` (around line 390) and before the auto-trigger plan check, add:
+
+```python
+        # Gap analysis — detect missing info and generate question cards
+        gap_result = analyze_gaps(responses)
+        question_cards = []
+        if gap_result.has_gaps:
+            cards = generate_question_cards(gap_result, updated_state)
+            question_cards = [c.model_dump() for c in cards]
+```
+
+Update the return dict to include `question_cards`:
+
+```python
+        return {
+            "responses": responses,
+            "preview": preview,
+            "design_state": updated_state.model_dump(),
+            "question_cards": question_cards,
+        }
+```
+
+- [ ] **Step 6: Add question_cards to fallback return paths**
+
+In `chat_turn`, find the manual plan trigger early return (around line 117-126) and the error return (around line 128-135). Add `"question_cards": []` to each return dict. Also update `_fallback` wrapper — after calling `mock.chat_turn()`, add `question_cards` key if missing:
+
+In `_fallback` method, wrap the result:
+
+```python
+    def _fallback(self, message, history, mentions, max_history, design_state):
+        from agents.orchestrator import MockChatBackend
+        mock = MockChatBackend(output_dir=self.output_dir)
+        result = mock.chat_turn(message, history, mentions, design_state=design_state)
+        if "question_cards" not in result:
+            result_responses = result.get("responses", [])
+            gap_result = analyze_gaps(result_responses)
+            if gap_result.has_gaps:
+                from agents.design_state import DesignState
+                state = DesignState(**(design_state or {}))
+                cards = generate_question_cards(gap_result, state)
+                result["question_cards"] = [c.model_dump() for c in cards]
+            else:
+                result["question_cards"] = []
+        return result
+```
+
+- [ ] **Step 7: Run tests to verify they pass**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_crew_orchestrator.py -v`
+Expected: All pass
+
+- [ ] **Step 8: Run full test suite**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/ --tb=short`
+Expected: All pass
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add agents/crew_orchestrator.py tests/test_crew_orchestrator.py
+git commit -m "feat: integrate gap analyzer into orchestrator, update CNC/CAM NOT READY prompts"
+```
+
+---
+
+### Task 5: Frontend question cards
+
+**Files:**
+- Modify: `web/index.html` (add CSS, JS, update sendMessage)
+
+- [ ] **Step 1: Add gap card CSS**
+
+Add to the `<style>` section after the existing plan card styles:
+
+```css
+  /* ---- GAP / QUESTION CARDS ---- */
+  .gap-cards {
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 12px;
+    margin: 8px 0;
+  }
+  .gap-cards-title {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    font-weight: 700;
+    color: var(--warning);
+    margin-bottom: 10px;
+  }
+  .gap-card {
+    padding: 10px;
+    margin-bottom: 8px;
+    border-left: 3px solid var(--border);
+    background: var(--bg-input);
+    border-radius: 0 6px 6px 0;
+  }
+  .gap-card:last-child { margin-bottom: 0; }
+  .gap-card-header {
+    display: flex; align-items: center; gap: 6px;
+    margin-bottom: 6px;
+  }
+  .gap-card-dot {
+    width: 8px; height: 8px; border-radius: 50%;
+    flex-shrink: 0;
+  }
+  .gap-card-agent {
+    font-family: var(--font-mono); font-size: 10px;
+    color: var(--text-secondary); font-weight: 600;
+  }
+  .gap-card-question {
+    font-family: var(--font-body); font-size: 12px;
+    color: var(--text-primary); margin-bottom: 8px;
+  }
+  .gap-card .wizard-chips { margin-bottom: 0; }
+  .gap-card .wizard-dim-row { margin-top: 4px; }
+  .gap-card-submit {
+    margin-top: 8px; padding: 5px 14px;
+    background: var(--accent); color: var(--bg-void);
+    border: none; border-radius: 4px;
+    font-family: var(--font-mono); font-size: 11px;
+    font-weight: 600; cursor: pointer;
+  }
+```
+
+- [ ] **Step 2: Add renderQuestionCards() and interaction handlers**
+
+Add to the `<script>` section:
+
+```javascript
+// ── QUESTION CARDS ────────────────────────────────────
+
+function renderQuestionCards(cards) {
+  if (!cards || cards.length === 0) return '';
+  let html = '<div class="gap-cards" id="active-gap-cards">';
+  html += '<div class="gap-cards-title">\u26a0 MISSING INFO</div>';
+  for (const card of cards) {
+    html += '<div class="gap-card" style="border-left-color:' + escapeHtml(card.agent_color) + ';">';
+    html += '<div class="gap-card-header">';
+    html += '<div class="gap-card-dot" style="background:' + escapeHtml(card.agent_color) + ';"></div>';
+    html += '<span class="gap-card-agent">' + escapeHtml(card.agent_name) + '</span>';
+    html += '</div>';
+    html += '<div class="gap-card-question">' + escapeHtml(card.question) + '</div>';
+
+    if (card.category === 'dimension') {
+      html += '<div class="wizard-dim-row"><span class="wizard-dim-label">Width</span><input class="wizard-dim-input gap-dim" id="gap-dim-width" type="number"><span class="wizard-dim-unit">mm</span></div>';
+      html += '<div class="wizard-dim-row"><span class="wizard-dim-label">Height</span><input class="wizard-dim-input gap-dim" id="gap-dim-height" type="number"><span class="wizard-dim-unit">mm</span></div>';
+      html += '<div class="wizard-dim-row"><span class="wizard-dim-label">Depth</span><input class="wizard-dim-input gap-dim" id="gap-dim-depth" type="number"><span class="wizard-dim-unit">mm</span></div>';
+      html += '<button class="gap-card-submit" onclick="gapSubmitDimensions()">Submit</button>';
+    } else if (card.suggestions && card.suggestions.length > 0) {
+      html += '<div class="wizard-chips">';
+      for (const s of card.suggestions) {
+        html += '<button class="wizard-chip" onclick="gapSelectChip(\'' + escapeHtml(s) + '\',\'' + escapeHtml(card.category) + '\')">' + escapeHtml(s) + '</button>';
+      }
+      if (card.allow_custom) {
+        html += '</div><input class="wizard-input" placeholder="Or type custom..." onkeydown="if(event.key===\'Enter\')gapSelectChip(this.value,\'' + escapeHtml(card.category) + '\')">';
+      } else {
+        html += '</div>';
+      }
+    }
+    html += '</div>';
+  }
+  html += '</div>';
+  return html;
+}
+
+function removeGapCards() {
+  const el = document.getElementById('active-gap-cards');
+  if (el) el.remove();
+}
+
+function gapSelectChip(value, category) {
+  if (!value.trim()) return;
+  // Update local state
+  if (category === 'material') designState.material = value;
+  else if (category === 'shape') { designState.part_name = value; designState.description = value; }
+  else if (category === 'machining') designState.axis_recommendation = value;
+  else if (category === 'constraint') {
+    if (!designState.constraints) designState.constraints = [];
+    designState.constraints.push(value);
+  } else if (category === 'feature') {
+    if (!designState.features) designState.features = [];
+    designState.features.push(value);
+  } else if (category === 'finish') {
+    if (!designState.constraints) designState.constraints = [];
+    designState.constraints.push('surface finish: ' + value);
+  }
+  saveState();
+  removeGapCards();
+  sendMessage(value);
+}
+
+function gapSubmitDimensions() {
+  const w = document.getElementById('gap-dim-width')?.value;
+  const h = document.getElementById('gap-dim-height')?.value;
+  const d = document.getElementById('gap-dim-depth')?.value;
+  if (!designState.dimensions) designState.dimensions = {};
+  const parts = [];
+  if (w) { designState.dimensions.width = parseFloat(w); parts.push(w + 'mm wide'); }
+  if (h) { designState.dimensions.height = parseFloat(h); parts.push(h + 'mm high'); }
+  if (d) { designState.dimensions.depth = parseFloat(d); parts.push(d + 'mm deep'); }
+  if (parts.length === 0) return;
+  saveState();
+  removeGapCards();
+  sendMessage(parts.join(', '));
+}
+```
+
+- [ ] **Step 3: Update sendMessage to render question cards and clear old ones**
+
+In `sendMessage`, at the very top (after `if (!text.trim()) return;`), add:
+
+```javascript
+  removeGapCards();
+```
+
+After the plan card insertion block (around the `if (designState.phase === 'planning' && designState.plan)` block), add:
+
+```javascript
+    // If question cards are present, render them
+    if (data.question_cards && data.question_cards.length > 0) {
+      removeGapCards();
+      const msgs = document.getElementById('chat-messages');
+      const cardDiv = document.createElement('div');
+      cardDiv.innerHTML = renderQuestionCards(data.question_cards);
+      msgs.appendChild(cardDiv.firstChild);
+      msgs.scrollTop = msgs.scrollHeight;
+    }
+```
+
+- [ ] **Step 4: Test manually**
+
+Run: `cd /home/daniel/NeuralCAD && python -m server.web --port 5000`
+Open `http://localhost:5000`. Test:
+1. Type "@cad generate a bracket" — CAD agent should return NOT READY, question cards should appear
+2. Click a material chip (e.g., "Aluminum 6061") — card removed, message sent
+3. After providing dimensions and material, cards should stop appearing
+4. Type a free message while cards are showing — cards should be cleared
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/index.html
+git commit -m "feat: add frontend question cards with gap card rendering and interaction handlers"
+```
+
+---
+
+### Task 6: Full integration test
+
+**Files:**
+- Run all tests and manual verification
+
+- [ ] **Step 1: Run full test suite**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/ -v --tb=short`
+Expected: All pass
+
+- [ ] **Step 2: Manual end-to-end test — NOT READY flow**
+
+1. Open `http://localhost:5000`
+2. Type "I need a bracket" — Design + Engineering agents respond, no question cards
+3. Type "@cad generate it" — CAD should say NOT READY, question cards appear for missing items
+4. Click "Aluminum 6061" chip — message sent, card removed
+5. Enter dimensions via card — message sent, card removed
+6. Type "@cad generate it" again — if enough info, CAD generates code; if not, new cards with remaining gaps
+
+- [ ] **Step 3: Manual test — card clearing**
+
+1. Trigger question cards with "@cad generate"
+2. Instead of clicking a card, type freely in the chat input
+3. Verify cards are removed on send
+
+- [ ] **Step 4: Manual test — guided wizard interaction**
+
+1. Fill in material and dimensions via the Guided wizard tab
+2. Switch to Chat, type "@cad generate"
+3. Verify cards do NOT appear for material/dimension (already in state)
+4. Verify cards only appear for remaining missing items
+
+- [ ] **Step 5: Commit any fixes**
+
+```bash
+git add -A
+git commit -m "fix: integration test fixes for gap analysis"
+```

tests/test_crew_orchestrator.py

@@ -71,6 +71,37 @@ class TestGetOrchestrator:
         assert isinstance(orch, CrewOrchestrator)
 
 
+class TestGapAnalysis:
+    def test_not_ready_produces_question_cards(self):
+        orch = CrewOrchestrator(backend_name="mock")
+        result = orch.chat_turn(
+            message="generate a bracket",
+            history=[],
+            design_state={},
+        )
+        assert "question_cards" in result
+
+    def test_no_question_cards_when_no_gaps(self):
+        orch = CrewOrchestrator(backend_name="mock")
+        result = orch.chat_turn(
+            message="I need a bracket",
+            history=[],
+            design_state={"material": "aluminum", "dimensions": {"width": 60}},
+        )
+        assert "question_cards" in result
+        assert isinstance(result["question_cards"], list)
+
+    def test_plan_trigger_includes_question_cards_key(self):
+        orch = CrewOrchestrator(backend_name="mock")
+        result = orch.chat_turn(
+            message="show plan",
+            history=[],
+            design_state={"material": "aluminum"},
+        )
+        assert "question_cards" in result
+        assert result["question_cards"] == []
+
+
 class TestPlanningPhase:
     """Tests for planning phase in CrewOrchestrator."""
 

tests/test_gap_analyzer.py

@@ -0,0 +1,145 @@
+"""Tests for agents/gap_analyzer.py — gap detection and question card generation."""
+
+from agents.gap_analyzer import (
+    MissingItem, GapAnalysis, QuestionCard,
+    analyze_gaps, generate_question_cards,
+)
+from agents.design_state import DesignState
+
+
+class TestAnalyzeGaps:
+    def test_no_gaps_when_no_not_ready(self):
+        responses = [
+            {"agent_id": "design", "message": "I suggest an L-bracket design."},
+            {"agent_id": "engineering", "message": "Aluminum 6061 would work well."},
+        ]
+        result = analyze_gaps(responses)
+        assert not result.has_gaps
+        assert result.missing_items == []
+
+    def test_detects_not_ready_from_cad(self):
+        responses = [
+            {"agent_id": "cad", "message": "NOT READY: Need dimensions (width, height) and material selection."},
+        ]
+        result = analyze_gaps(responses)
+        assert result.has_gaps
+        categories = [item.category for item in result.missing_items]
+        assert "dimension" in categories
+        assert "material" in categories
+
+    def test_detects_not_ready_from_cnc(self):
+        responses = [
+            {"agent_id": "cnc", "message": "NOT READY: Need material and tolerance info for manufacturability check."},
+        ]
+        result = analyze_gaps(responses)
+        assert result.has_gaps
+        categories = [item.category for item in result.missing_items]
+        assert "material" in categories
+        assert "constraint" in categories
+
+    def test_detects_not_ready_from_cam(self):
+        responses = [
+            {"agent_id": "cam", "message": "NOT READY: No 3D model available. Need CAD generation first."},
+        ]
+        result = analyze_gaps(responses)
+        assert result.has_gaps
+        categories = [item.category for item in result.missing_items]
+        assert "model" in categories
+
+    def test_deduplicates_across_agents(self):
+        responses = [
+            {"agent_id": "cad", "message": "NOT READY: Need material and dimensions."},
+            {"agent_id": "cnc", "message": "NOT READY: Material is required for manufacturability."},
+        ]
+        result = analyze_gaps(responses)
+        material_items = [i for i in result.missing_items if i.category == "material"]
+        assert len(material_items) == 1
+        assert material_items[0].agent_id == "cad"
+
+    def test_case_insensitive_not_ready(self):
+        responses = [
+            {"agent_id": "cad", "message": "not ready: missing width and height dimensions."},
+        ]
+        result = analyze_gaps(responses)
+        assert result.has_gaps
+        assert any(item.category == "dimension" for item in result.missing_items)
+
+    def test_no_false_positive_on_regular_message(self):
+        responses = [
+            {"agent_id": "cad", "message": "Model generated successfully."},
+            {"agent_id": "cnc", "message": "3-axis machining is ready for this part."},
+        ]
+        result = analyze_gaps(responses)
+        assert not result.has_gaps
+
+
+class TestGenerateQuestionCards:
+    def test_generates_cards_from_gaps(self):
+        gaps = GapAnalysis(
+            has_gaps=True,
+            missing_items=[
+                MissingItem(category="material", description="material", agent_id="cad"),
+                MissingItem(category="dimension", description="width", agent_id="cad"),
+            ],
+        )
+        cards = generate_question_cards(gaps, DesignState())
+        assert len(cards) == 2
+        material_card = next(c for c in cards if c.category == "material")
+        assert material_card.responsible_agent == "engineering"
+        assert len(material_card.suggestions) > 0
+        assert material_card.allow_custom is True
+
+    def test_filters_out_already_set_material(self):
+        gaps = GapAnalysis(
+            has_gaps=True,
+            missing_items=[
+                MissingItem(category="material", description="material", agent_id="cad"),
+                MissingItem(category="dimension", description="width", agent_id="cad"),
+            ],
+        )
+        state = DesignState(material="aluminum 6061")
+        cards = generate_question_cards(gaps, state)
+        categories = [c.category for c in cards]
+        assert "material" not in categories
+        assert "dimension" in categories
+
+    def test_filters_out_already_set_dimensions(self):
+        gaps = GapAnalysis(
+            has_gaps=True,
+            missing_items=[
+                MissingItem(category="dimension", description="width", agent_id="cad"),
+            ],
+        )
+        state = DesignState(dimensions={"width": 60, "height": 40})
+        cards = generate_question_cards(gaps, state)
+        assert len(cards) == 0
+
+    def test_no_cards_when_no_gaps(self):
+        gaps = GapAnalysis(has_gaps=False, missing_items=[])
+        cards = generate_question_cards(gaps, DesignState())
+        assert cards == []
+
+    def test_card_has_agent_metadata(self):
+        gaps = GapAnalysis(
+            has_gaps=True,
+            missing_items=[
+                MissingItem(category="machining", description="axis", agent_id="cnc"),
+            ],
+        )
+        cards = generate_question_cards(gaps, DesignState())
+        assert len(cards) == 1
+        assert cards[0].responsible_agent == "cnc"
+        assert cards[0].agent_name == "CNC Agent"
+        assert cards[0].agent_color == "#00e676"
+
+    def test_model_category_no_suggestions(self):
+        gaps = GapAnalysis(
+            has_gaps=True,
+            missing_items=[
+                MissingItem(category="model", description="3D", agent_id="cam"),
+            ],
+        )
+        cards = generate_question_cards(gaps, DesignState())
+        assert len(cards) == 1
+        assert cards[0].suggestions == []
+        assert cards[0].allow_custom is False

tests/test_settings.py

@@ -63,3 +63,18 @@ class TestPlanningConfig:
     def test_planning_threshold_from_yaml(self):
         from config.settings import settings
         assert settings.planning.threshold == 8.0
+
+
+class TestGapAnalysisConfig:
+    def test_gap_analysis_defaults(self):
+        from config.settings import Settings
+        s = Settings()
+        assert "dimension" in s.gap_analysis.category_keywords
+        assert "material" in s.gap_analysis.category_keywords
+        assert s.gap_analysis.category_agents["dimension"] == "engineering"
+        assert s.gap_analysis.category_agents["shape"] == "design"
+
+    def test_gap_analysis_loaded_from_yaml(self):
+        from config.settings import settings
+        assert "width" in settings.gap_analysis.category_keywords.get("dimension", [])
+        assert settings.gap_analysis.category_agents["machining"] == "cnc"

web/index.html

@@ -1316,6 +1316,55 @@
     background: var(--bg-surface); color: var(--text-secondary);
   }
 
+  /* ---- GAP / QUESTION CARDS ---- */
+  .gap-cards {
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 12px;
+    margin: 8px 0;
+  }
+  .gap-cards-title {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    font-weight: 700;
+    color: var(--warning);
+    margin-bottom: 10px;
+  }
+  .gap-card {
+    padding: 10px;
+    margin-bottom: 8px;
+    border-left: 3px solid var(--border);
+    background: var(--bg-input);
+    border-radius: 0 6px 6px 0;
+  }
+  .gap-card:last-child { margin-bottom: 0; }
+  .gap-card-header {
+    display: flex; align-items: center; gap: 6px;
+    margin-bottom: 6px;
+  }
+  .gap-card-dot {
+    width: 8px; height: 8px; border-radius: 50%;
+    flex-shrink: 0;
+  }
+  .gap-card-agent {
+    font-family: var(--font-mono); font-size: 10px;
+    color: var(--text-secondary); font-weight: 600;
+  }
+  .gap-card-question {
+    font-family: var(--font-body); font-size: 12px;
+    color: var(--text-primary); margin-bottom: 8px;
+  }
+  .gap-card .wizard-chips { margin-bottom: 0; }
+  .gap-card .wizard-dim-row { margin-top: 4px; }
+  .gap-card-submit {
+    margin-top: 8px; padding: 5px 14px;
+    background: var(--accent); color: var(--bg-void);
+    border: none; border-radius: 4px;
+    font-family: var(--font-mono); font-size: 11px;
+    font-weight: 600; cursor: pointer;
+  }
+
   /* ---- RESPONSIVE ---- */
 
   @media (max-width: 768px) {
@@ -1850,6 +1899,82 @@ async function rejectPlanCard() {
   }
 }
 
+// ── QUESTION CARDS ────────────────────────────────────
+
+function renderQuestionCards(cards) {
+  if (!cards || cards.length === 0) return '';
+  let html = '<div class="gap-cards" id="active-gap-cards">';
+  html += '<div class="gap-cards-title">\u26a0 MISSING INFO</div>';
+  for (const card of cards) {
+    html += '<div class="gap-card" style="border-left-color:' + escapeHtml(card.agent_color) + ';">';
+    html += '<div class="gap-card-header">';
+    html += '<div class="gap-card-dot" style="background:' + escapeHtml(card.agent_color) + ';"></div>';
+    html += '<span class="gap-card-agent">' + escapeHtml(card.agent_name) + '</span>';
+    html += '</div>';
+    html += '<div class="gap-card-question">' + escapeHtml(card.question) + '</div>';
+
+    if (card.category === 'dimension') {
+      html += '<div class="wizard-dim-row"><span class="wizard-dim-label">Width</span><input class="wizard-dim-input gap-dim" id="gap-dim-width" type="number"><span class="wizard-dim-unit">mm</span></div>';
+      html += '<div class="wizard-dim-row"><span class="wizard-dim-label">Height</span><input class="wizard-dim-input gap-dim" id="gap-dim-height" type="number"><span class="wizard-dim-unit">mm</span></div>';
+      html += '<div class="wizard-dim-row"><span class="wizard-dim-label">Depth</span><input class="wizard-dim-input gap-dim" id="gap-dim-depth" type="number"><span class="wizard-dim-unit">mm</span></div>';
+      html += '<button class="gap-card-submit" onclick="gapSubmitDimensions()">Submit</button>';
+    } else if (card.suggestions && card.suggestions.length > 0) {
+      html += '<div class="wizard-chips">';
+      for (const s of card.suggestions) {
+        html += '<button class="wizard-chip" onclick="gapSelectChip(\'' + escapeHtml(s) + '\',\'' + escapeHtml(card.category) + '\')">' + escapeHtml(s) + '</button>';
+      }
+      if (card.allow_custom) {
+        html += '</div><input class="wizard-input" placeholder="Or type custom..." onkeydown="if(event.key===\'Enter\')gapSelectChip(this.value,\'' + escapeHtml(card.category) + '\')">';
+      } else {
+        html += '</div>';
+      }
+    }
+    html += '</div>';
+  }
+  html += '</div>';
+  return html;
+}
+
+function removeGapCards() {
+  const el = document.getElementById('active-gap-cards');
+  if (el) el.remove();
+}
+
+function gapSelectChip(value, category) {
+  if (!value.trim()) return;
+  if (category === 'material') designState.material = value;
+  else if (category === 'shape') { designState.part_name = value; designState.description = value; }
+  else if (category === 'machining') designState.axis_recommendation = value;
+  else if (category === 'constraint') {
+    if (!designState.constraints) designState.constraints = [];
+    designState.constraints.push(value);
+  } else if (category === 'feature') {
+    if (!designState.features) designState.features = [];
+    designState.features.push(value);
+  } else if (category === 'finish') {
+    if (!designState.constraints) designState.constraints = [];
+    designState.constraints.push('surface finish: ' + value);
+  }
+  saveState();
+  removeGapCards();
+  sendMessage(value);
+}
+
+function gapSubmitDimensions() {
+  const w = document.getElementById('gap-dim-width')?.value;
+  const h = document.getElementById('gap-dim-height')?.value;
+  const d = document.getElementById('gap-dim-depth')?.value;
+  if (!designState.dimensions) designState.dimensions = {};
+  const parts = [];
+  if (w) { designState.dimensions.width = parseFloat(w); parts.push(w + 'mm wide'); }
+  if (h) { designState.dimensions.height = parseFloat(h); parts.push(h + 'mm high'); }
+  if (d) { designState.dimensions.depth = parseFloat(d); parts.push(d + 'mm deep'); }
+  if (parts.length === 0) return;
+  saveState();
+  removeGapCards();
+  sendMessage(parts.join(', '));
+}
+
 // ── i18n ─────────────────────────────────────────────
 
 const I18N = {
@@ -2392,6 +2517,7 @@ function toggleChat() {
 
 async function sendMessage(text) {
   if (!text.trim()) return;
+  removeGapCards();
 
   // Parse @mentions
   const mentions = [];
@@ -2463,6 +2589,16 @@ async function sendMessage(text) {
       msgs.scrollTop = msgs.scrollHeight;
     }
 
+    // If question cards are present, render them
+    if (data.question_cards && data.question_cards.length > 0) {
+      removeGapCards();
+      const msgs = document.getElementById('chat-messages');
+      const cardDiv = document.createElement('div');
+      cardDiv.innerHTML = renderQuestionCards(data.question_cards);
+      msgs.appendChild(cardDiv.firstChild);
+      msgs.scrollTop = msgs.scrollHeight;
+    }
+
     // If preview available, load 3D model
     if (data.preview && data.preview.success) {
       setViewerLoading(true, t('loadingModel'));