icdev 0.0.3__py3-none-any.whl

tools/forge_studio/intake_bridge.py

@@ -0,0 +1,898 @@
+# CUI // SP-CTI
+"""Forge Studio ↔ RICOAS intake bridge (D-FS-INTAKE-2, D-FS-INTAKE-3).
+
+Thin adapter connecting RICOAS multi-turn requirements intake to Forge Studio
+app generation. Delegates to existing RICOAS and Forge Studio functions —
+does NOT reimplement logic.
+
+Pipeline:
+  1. start_intake(description) → creates RICOAS session, pre-seeds with description
+  2. process_message(session_id, msg) → wraps intake_engine.process_turn()
+  3. check_readiness(session_id) → calls readiness_scorer
+  4. extract_spec(session_id) → translates requirements to Forge Studio spec
+  5. generate_from_intake(session_id) → full pipeline → ForgeApp
+
+The requirements-to-spec translation is deterministic (D-FS-INTAKE-3):
+  - Functional requirements → Pages with CRUD components
+  - Data requirements → ForgeSchema tables
+  - Security requirements → Settings page
+  - Stories → Component types inferred from verb patterns
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from tools.forge_studio.audit import ensure_tables, log_forge_event
+
+logger = logging.getLogger("forge_studio.intake_bridge")
+
+
+# ---------------------------------------------------------------------------
+# 1. Start intake session
+# ---------------------------------------------------------------------------
+
+def start_intake(
+    description: str,
+    project_id: str = "",
+    tenant_id: str = "default",
+) -> Dict[str, Any]:
+    """Start a RICOAS intake session pre-seeded with the user's app description.
+
+    Returns:
+        {session_id, welcome_message, initial_analysis, readiness}
+    """
+    from tools.requirements.intake_engine import create_session, process_turn
+
+    # Create the session
+    session = create_session(
+        project_id=project_id or "",
+        customer_name="Forge Studio User",
+        customer_org="",
+        impact_level="IL4",
+        role="developer",
+        goal="build",
+    )
+    session_id = session.get("session_id", "")
+    welcome = session.get("opening_message", session.get("analyst_response", ""))
+
+    # Pre-seed the conversation with the description
+    initial_analysis = {}
+    if description.strip():
+        try:
+            initial_analysis = process_turn(session_id, description)
+        except Exception as e:
+            logger.warning("Failed to pre-seed intake: %s", e)
+            initial_analysis = {"analyst_response": str(e)}
+
+    # Get initial readiness
+    readiness = _safe_readiness(session_id)
+
+    log_forge_event(
+        "forge_studio_intake_started",
+        {
+            "session_id": session_id,
+            "description_length": len(description),
+            "tenant_id": tenant_id,
+        },
+        project_id=project_id,
+    )
+
+    return {
+        "session_id": session_id,
+        "welcome_message": welcome,
+        "initial_analysis": initial_analysis,
+        "readiness": readiness,
+    }
+
+
+# ---------------------------------------------------------------------------
+# 2. Process message
+# ---------------------------------------------------------------------------
+
+def process_message(
+    session_id: str,
+    user_message: str,
+) -> Dict[str, Any]:
+    """Wrap intake_engine.process_turn() and append readiness update.
+
+    Returns:
+        {analyst_response, readiness_update, requirements_count, turn_number}
+    """
+    from tools.requirements.intake_engine import process_turn
+
+    result = process_turn(session_id, user_message)
+
+    analyst_response = result.get("analyst_response", "")
+    turn_number = result.get("turn_number", 0)
+    requirements_extracted = result.get("requirements_extracted", [])
+
+    readiness = _safe_readiness(session_id)
+
+    return {
+        "analyst_response": analyst_response,
+        "readiness_update": readiness,
+        "requirements_count": _count_requirements(session_id),
+        "turn_number": turn_number,
+        "extracted_this_turn": len(requirements_extracted),
+    }
+
+
+# ---------------------------------------------------------------------------
+# 3. Check readiness
+# ---------------------------------------------------------------------------
+
+def check_readiness(session_id: str) -> Dict[str, Any]:
+    """Check if the intake session has enough requirements to generate an app.
+
+    Uses a lower threshold (0.5) than full DoD RICOAS (0.7) because Forge
+    Studio users won't always specify compliance frameworks.
+
+    Returns:
+        {overall, dimensions, ready_to_generate, recommendation}
+    """
+    readiness = _safe_readiness(session_id)
+
+    overall = readiness.get("overall", 0.0)
+    # For Forge Studio, we focus on completeness + clarity
+    dims = readiness.get("dimensions", {})
+    completeness = dims.get("completeness", 0.0)
+    clarity = dims.get("clarity", 0.0)
+
+    # Ready if overall >= 0.5 OR (completeness + clarity) / 2 >= 0.6
+    functional_score = (completeness + clarity) / 2 if (completeness + clarity) else 0
+    ready = overall >= 0.5 or functional_score >= 0.6
+
+    recommendation = "generate" if ready else "continue_intake"
+
+    return {
+        "overall": overall,
+        "functional_score": round(functional_score, 3),
+        "dimensions": dims,
+        "ready_to_generate": ready,
+        "recommendation": recommendation,
+    }
+
+
+# ---------------------------------------------------------------------------
+# 4. Get intake summary
+# ---------------------------------------------------------------------------
+
+def get_intake_summary(session_id: str) -> Dict[str, Any]:
+    """Get requirements and gaps for a session.
+
+    Returns:
+        {requirements, gaps, requirement_count, types_present, conversation_turns}
+    """
+    from tools.db.storage import get_connection
+
+    with get_connection() as conn:
+        reqs = conn.execute(
+            "SELECT raw_text, requirement_type, priority "
+            "FROM intake_requirements WHERE session_id = ? "
+            "ORDER BY created_at",
+            (session_id,),
+        ).fetchall()
+
+        try:
+            gaps = conn.execute(
+                "SELECT gap_type, description, severity "
+                "FROM intake_gaps WHERE session_id = ? "
+                "ORDER BY created_at",
+                (session_id,),
+            ).fetchall()
+        except Exception:
+            gaps = []  # Table may not exist
+
+        turns = conn.execute(
+            "SELECT COUNT(*) as cnt FROM intake_conversation WHERE session_id = ?",
+            (session_id,),
+        ).fetchone()
+
+    reqs_list = [dict(r) for r in reqs]
+    gaps_list = [dict(g) for g in gaps] if gaps else []
+    types_present = list({r["requirement_type"] for r in reqs_list if r.get("requirement_type")})
+
+    return {
+        "requirements": reqs_list,
+        "gaps": gaps_list,
+        "requirement_count": len(reqs_list),
+        "gap_count": len(gaps_list),
+        "types_present": types_present,
+        "conversation_turns": dict(turns)["cnt"] if turns else 0,
+    }
+
+
+# ---------------------------------------------------------------------------
+# 5. Extract spec (deterministic requirements-to-spec translation)
+# ---------------------------------------------------------------------------
+
+def extract_spec(session_id: str) -> Dict[str, Any]:
+    """Translate RICOAS requirements into a Forge Studio spec dict.
+
+    Mapping (D-FS-INTAKE-3, deterministic):
+      - Functional requirements → Pages with CRUD components
+      - Data requirements → Schema tables
+      - Security requirements → Settings page
+      - Stories → Component type inferred from verb patterns
+
+    Returns:
+        Spec dict compatible with build_app_from_spec().
+    """
+    summary = get_intake_summary(session_id)
+    reqs = summary["requirements"]
+    gaps = summary["gaps"]
+
+    if not reqs:
+        return _minimal_spec("Generated App", "Application generated from requirements session")
+
+    # Collect conversation context for app name
+    app_name, app_description = _infer_app_identity(session_id, reqs)
+
+    # Group requirements by type
+    by_type: Dict[str, List[Dict]] = {}
+    for r in reqs:
+        rtype = (r.get("requirement_type") or "functional").lower()
+        by_type.setdefault(rtype, []).append(r)
+
+    pages: List[Dict] = []
+    tables: List[Dict] = []
+
+    # Always: Login page
+    pages.append({
+        "id": "page-login",
+        "name": "Login",
+        "route": "/login",
+        "is_protected": False,
+        "component_tree": [],
+    })
+
+    # Infer data entities from data requirements
+    data_reqs = by_type.get("data", [])
+    entity_tables = _extract_entities_from_requirements(data_reqs + by_type.get("functional", []))
+    tables.extend(entity_tables)
+
+    # Build pages from functional requirements
+    functional_reqs = by_type.get("functional", [])
+    func_pages = _build_functional_pages(functional_reqs, entity_tables)
+    pages.extend(func_pages)
+
+    # If no functional pages generated, create a default dashboard
+    if len(pages) == 1:  # only login
+        pages.append(_default_dashboard_page())
+
+    # Security requirements → Settings page
+    security_reqs = by_type.get("security", []) + by_type.get("non-functional", [])
+    if security_reqs:
+        pages.append(_build_settings_page(security_reqs))
+
+    # Ensure at least a profiles table
+    table_names = {t["name"] for t in tables}
+    if "profiles" not in table_names:
+        tables.append({
+            "name": "profiles",
+            "columns": [
+                {"name": "full_name", "type": "text"},
+                {"name": "avatar_url", "type": "text"},
+                {"name": "role", "type": "text"},
+            ],
+        })
+
+    spec = {
+        "name": app_name,
+        "description": app_description,
+        "pages": pages,
+        "tables": tables,
+    }
+
+    return spec
+
+
+# ---------------------------------------------------------------------------
+# 6. Generate app from intake
+# ---------------------------------------------------------------------------
+
+def generate_from_intake(
+    session_id: str,
+    project_id: str = "",
+    tenant_id: str = "default",
+    use_llm: bool = True,
+    store: bool = True,
+) -> Dict[str, Any]:
+    """Full pipeline: extract spec from intake → generate ForgeApp.
+
+    If use_llm is True, enriches the spec with LLM-generated component details.
+    If False, uses the deterministic spec directly.
+    """
+    from tools.forge_studio.generator.spec_builder import build_app_from_spec
+    from tools.forge_studio.catalog.schema_validator import validate_app
+    from tools.forge_studio.generator.app_generator import _generate_via_llm, _store_app
+    from tools.forge_studio.generator.spec_builder import get_available_component_types
+
+    start = time.time()
+    errors: List[str] = []
+
+    ensure_tables()
+
+    # Extract structured spec from intake requirements
+    spec = extract_spec(session_id)
+
+    # Optionally enrich with LLM
+    if use_llm:
+        # Build a rich description from the conversation + requirements
+        rich_description = _build_rich_description(session_id, spec)
+        component_types = get_available_component_types()
+        llm_spec = _generate_via_llm(rich_description, component_types, errors)
+        if llm_spec:
+            # Merge: use LLM pages/components but keep our extracted tables if LLM missed them
+            spec = _merge_specs(spec, llm_spec)
+
+    # Build ForgeApp from spec
+    try:
+        app = build_app_from_spec(
+            spec,
+            generation_prompt=spec.get("description", ""),
+            project_id=project_id,
+            tenant_id=tenant_id,
+        )
+    except Exception as e:
+        logger.error("Failed to build app from intake spec: %s", e)
+        return {
+            "status": "error",
+            "errors": [f"Spec build failed: {str(e)}"],
+            "duration_ms": int((time.time() - start) * 1000),
+        }
+
+    # Validate
+    validation = validate_app(app.to_dict())
+
+    # Store
+    if store:
+        _store_app(app)
+        # Link the intake session to the app
+        _link_intake_session(app.id, session_id)
+        log_forge_event(
+            "forge_studio_app_from_intake",
+            {
+                "app_id": app.id,
+                "session_id": session_id,
+                "app_name": app.name,
+                "pages": len(app.pages),
+                "tables": len(app.schema.tables) if app.schema else 0,
+                "used_llm": use_llm,
+                "validation_valid": validation["valid"],
+            },
+            project_id=project_id,
+        )
+
+    duration_ms = int((time.time() - start) * 1000)
+    return {
+        "status": "success" if validation["valid"] else "warning",
+        "app_id": app.id,
+        "app": app.to_dict(),
+        "validation": validation,
+        "duration_ms": duration_ms,
+        "intake_session_id": session_id,
+        "errors": errors,
+    }
+
+
+# ===========================================================================
+# Internal helpers
+# ===========================================================================
+
+def _safe_readiness(session_id: str) -> Dict[str, Any]:
+    """Call readiness scorer, return empty dict on failure."""
+    try:
+        from tools.requirements.readiness_scorer import score_readiness
+        result = score_readiness(session_id)
+        return {
+            "overall": result.get("overall_score", 0.0),
+            "dimensions": result.get("dimensions", {}),
+        }
+    except Exception as e:
+        logger.debug("Readiness scoring failed: %s", e)
+        return {"overall": 0.0, "dimensions": {}}
+
+
+def _count_requirements(session_id: str) -> int:
+    """Count requirements in intake_requirements for this session."""
+    from tools.db.storage import get_connection
+    try:
+        with get_connection() as conn:
+            row = conn.execute(
+                "SELECT COUNT(*) as cnt FROM intake_requirements WHERE session_id = ?",
+                (session_id,),
+            ).fetchone()
+        return dict(row)["cnt"] if row else 0
+    except Exception:
+        return 0
+
+
+def _infer_app_identity(session_id: str, reqs: List[Dict]) -> tuple:
+    """Infer app name and description from conversation context."""
+    from tools.db.storage import get_connection
+
+    # Get the first user message (the original description)
+    try:
+        with get_connection() as conn:
+            first_msg = conn.execute(
+                "SELECT content FROM intake_conversation "
+                "WHERE session_id = ? AND role = 'customer' "
+                "ORDER BY turn_number LIMIT 1",
+                (session_id,),
+            ).fetchone()
+        if first_msg:
+            desc = dict(first_msg)["content"]
+            # Extract a name: take first meaningful phrase
+            name = _extract_app_name(desc)
+            return name, desc
+    except Exception:
+        pass
+
+    return "Generated App", "Application generated from requirements session"
+
+
+def _extract_app_name(description: str) -> str:
+    """Extract a short app name from a description."""
+    desc = description.strip()
+    # Common patterns: "Build me a CRM", "Create a task management app"
+    patterns = [
+        r"(?:build|create|make|design|generate)\s+(?:me\s+)?(?:a|an)\s+(.{3,40}?)(?:\s+(?:with|that|for|using|app|application|system|platform|tool))",
+        r"(?:build|create|make|design|generate)\s+(?:me\s+)?(?:a|an)\s+(.{3,40}?)(?:\.|$)",
+        r"^(?:I\s+(?:need|want)\s+(?:a|an)\s+)(.{3,40}?)(?:\s+(?:with|that|for))",
+    ]
+    for pat in patterns:
+        m = re.search(pat, desc, re.IGNORECASE)
+        if m:
+            name = m.group(1).strip().rstrip(".,;:")
+            return name.title() if len(name) < 30 else name[:30].title()
+
+    # Fallback: first 5 words
+    words = desc.split()[:5]
+    return " ".join(words).title()
+
+
+def _extract_entities_from_requirements(reqs: List[Dict]) -> List[Dict]:
+    """Extract data entities (tables) from requirement text."""
+    entity_pattern = re.compile(
+        r"\b(contacts?|users?|customers?|orders?|products?|tasks?|projects?|"
+        r"deals?|tickets?|invoices?|payments?|events?|articles?|posts?|"
+        r"messages?|comments?|categories?|tags?|roles?|teams?|departments?|"
+        r"employees?|vendors?|suppliers?|assets?|documents?|reports?|"
+        r"schedules?|appointments?|contracts?|activities?|leads?|"
+        r"campaigns?|inventory|notifications?|settings?)\b",
+        re.IGNORECASE,
+    )
+
+    # Column hints per entity type
+    ENTITY_COLUMNS: Dict[str, List[Dict]] = {
+        "contacts": [{"name": "name", "type": "text"}, {"name": "email", "type": "text", "unique": True}, {"name": "phone", "type": "text"}, {"name": "company", "type": "text"}, {"name": "status", "type": "text"}],
+        "users": [{"name": "username", "type": "text", "unique": True}, {"name": "email", "type": "text", "unique": True}, {"name": "full_name", "type": "text"}, {"name": "role", "type": "text"}],
+        "customers": [{"name": "name", "type": "text"}, {"name": "email", "type": "text"}, {"name": "phone", "type": "text"}, {"name": "tier", "type": "text"}],
+        "orders": [{"name": "order_number", "type": "text", "unique": True}, {"name": "status", "type": "text"}, {"name": "total", "type": "numeric"}, {"name": "customer_id", "type": "uuid", "references": "customers(id)"}],
+        "products": [{"name": "name", "type": "text"}, {"name": "sku", "type": "text", "unique": True}, {"name": "price", "type": "numeric"}, {"name": "category", "type": "text"}, {"name": "stock", "type": "integer"}],
+        "tasks": [{"name": "title", "type": "text"}, {"name": "description", "type": "text"}, {"name": "status", "type": "text"}, {"name": "priority", "type": "integer"}, {"name": "assignee_id", "type": "uuid"}],
+        "projects": [{"name": "name", "type": "text"}, {"name": "description", "type": "text"}, {"name": "status", "type": "text"}, {"name": "start_date", "type": "timestamptz"}, {"name": "end_date", "type": "timestamptz"}],
+        "deals": [{"name": "name", "type": "text"}, {"name": "value", "type": "numeric"}, {"name": "stage", "type": "text"}, {"name": "contact_id", "type": "uuid", "references": "contacts(id)"}],
+        "tickets": [{"name": "title", "type": "text"}, {"name": "description", "type": "text"}, {"name": "status", "type": "text"}, {"name": "priority", "type": "text"}, {"name": "assignee_id", "type": "uuid"}],
+        "invoices": [{"name": "invoice_number", "type": "text", "unique": True}, {"name": "amount", "type": "numeric"}, {"name": "status", "type": "text"}, {"name": "due_date", "type": "timestamptz"}],
+        "events": [{"name": "title", "type": "text"}, {"name": "description", "type": "text"}, {"name": "start_time", "type": "timestamptz"}, {"name": "end_time", "type": "timestamptz"}, {"name": "location", "type": "text"}],
+        "activities": [{"name": "type", "type": "text"}, {"name": "description", "type": "text"}, {"name": "contact_id", "type": "uuid"}],
+        "leads": [{"name": "name", "type": "text"}, {"name": "email", "type": "text"}, {"name": "source", "type": "text"}, {"name": "status", "type": "text"}, {"name": "score", "type": "integer"}],
+        "contracts": [{"name": "title", "type": "text"}, {"name": "value", "type": "numeric"}, {"name": "status", "type": "text"}, {"name": "start_date", "type": "timestamptz"}, {"name": "end_date", "type": "timestamptz"}],
+        "campaigns": [{"name": "name", "type": "text"}, {"name": "status", "type": "text"}, {"name": "budget", "type": "numeric"}, {"name": "start_date", "type": "timestamptz"}],
+        "documents": [{"name": "title", "type": "text"}, {"name": "file_url", "type": "text"}, {"name": "category", "type": "text"}, {"name": "classification", "type": "text"}],
+    }
+
+    found_entities: Dict[str, bool] = {}
+    tables: List[Dict] = []
+
+    for req in reqs:
+        text = req.get("raw_text", "")
+        matches = entity_pattern.findall(text)
+        for match in matches:
+            # Normalize to plural lowercase
+            entity = match.lower().rstrip("s") + "s"
+            if entity == "settingss":
+                continue
+            if entity not in found_entities:
+                found_entities[entity] = True
+                columns = ENTITY_COLUMNS.get(entity, [
+                    {"name": "name", "type": "text"},
+                    {"name": "description", "type": "text"},
+                    {"name": "status", "type": "text"},
+                ])
+                tables.append({"name": entity, "columns": columns})
+
+    return tables
+
+
+def _build_functional_pages(
+    reqs: List[Dict], entity_tables: List[Dict]
+) -> List[Dict]:
+    """Build pages from functional requirements."""
+    pages: List[Dict] = []
+    seen_pages: Dict[str, bool] = {}
+
+    # Group requirements by inferred page
+    page_groups: Dict[str, List[Dict]] = {}
+    for req in reqs:
+        text = (req.get("raw_text") or "").lower()
+        page_name = _infer_page_from_text(text)
+        page_groups.setdefault(page_name, []).append(req)
+
+    # Also ensure a page per entity table for CRUD
+    for table in entity_tables:
+        entity_name = table["name"].rstrip("s").title() + "s"
+        page_name = entity_name
+        if page_name not in page_groups:
+            page_groups[page_name] = []
+
+    for page_name, page_reqs in page_groups.items():
+        if page_name in seen_pages:
+            continue
+        seen_pages[page_name] = True
+
+        page_id = f"page-{page_name.lower().replace(' ', '-')}"
+        route = f"/{page_name.lower().replace(' ', '-')}" if page_name != "Dashboard" else "/"
+        components = _build_components_for_page(page_name, page_reqs, entity_tables)
+
+        pages.append({
+            "id": page_id,
+            "name": page_name,
+            "route": route,
+            "is_protected": True,
+            "component_tree": [{
+                "id": f"{page_id}-root",
+                "type": "Page",
+                "props": {"title": page_name},
+                "children": components,
+                "slot": "",
+            }] if components else [],
+        })
+
+    # If no Dashboard page, add one as home
+    page_names = [p["name"] for p in pages]
+    if "Dashboard" not in page_names:
+        pages.insert(0, _default_dashboard_page())
+
+    return pages
+
+
+def _infer_page_from_text(text: str) -> str:
+    """Infer which page a requirement belongs to."""
+    page_keywords = {
+        "Dashboard": ["dashboard", "overview", "summary", "home", "metrics", "kpi"],
+        "Settings": ["settings", "configuration", "preferences", "admin"],
+        "Reports": ["report", "analytics", "chart", "graph", "trend"],
+    }
+    for page, keywords in page_keywords.items():
+        if any(kw in text for kw in keywords):
+            return page
+
+    # Check for entity mentions
+    entity_pattern = re.compile(
+        r"\b(contacts?|tasks?|projects?|deals?|tickets?|orders?|"
+        r"products?|invoices?|leads?|customers?|events?|contracts?)\b",
+        re.IGNORECASE,
+    )
+    match = entity_pattern.search(text)
+    if match:
+        entity = match.group(1).lower().rstrip("s")
+        return entity.title() + "s"
+
+    return "Dashboard"
+
+
+def _build_components_for_page(
+    page_name: str, reqs: List[Dict], entity_tables: List[Dict]
+) -> List[Dict]:
+    """Build component tree for a page based on requirements."""
+    components: List[Dict] = []
+
+    # Find the entity table matching this page
+    page_entity = page_name.lower()
+    matching_table = None
+    for t in entity_tables:
+        if t["name"] == page_entity or t["name"].rstrip("s") == page_entity.rstrip("s"):
+            matching_table = t
+            break
+
+    # Analyze requirement verbs to decide component types
+    has_list = False
+    has_create = False
+    has_search = False
+    has_chart = False
+    has_kanban = False
+    has_metrics = False
+
+    for req in reqs:
+        text = (req.get("raw_text") or "").lower()
+        if any(w in text for w in ["list", "view all", "table", "browse", "display"]):
+            has_list = True
+        if any(w in text for w in ["create", "add", "new", "form", "submit", "register"]):
+            has_create = True
+        if any(w in text for w in ["search", "filter", "find", "query"]):
+            has_search = True
+        if any(w in text for w in ["chart", "graph", "trend", "analytics", "visualiz"]):
+            has_chart = True
+        if any(w in text for w in ["kanban", "board", "pipeline", "stage", "drag"]):
+            has_kanban = True
+        if any(w in text for w in ["metric", "kpi", "count", "total", "summary"]):
+            has_metrics = True
+
+    # Default: if entity table exists, assume CRUD
+    if matching_table and not has_list and not has_kanban:
+        has_list = True
+        has_create = True
+        has_search = True
+
+    # Dashboard page defaults
+    if page_name == "Dashboard" and not any([has_list, has_chart, has_kanban]):
+        has_metrics = True
+        has_chart = True
+
+    uid = lambda suffix: f"{page_name.lower().replace(' ', '-')}-{suffix}"
+
+    # Build components
+    if has_metrics:
+        components.append({
+            "id": uid("metrics"),
+            "type": "Grid",
+            "props": {"columns": 4, "gap": 4},
+            "children": [
+                {"id": uid("metric-1"), "type": "Metric", "props": {"label": "Total", "value": "0", "trend": "up", "trendValue": "+0%"}, "children": [], "slot": "items"},
+                {"id": uid("metric-2"), "type": "Metric", "props": {"label": "Active", "value": "0", "trend": "neutral", "trendValue": "0%"}, "children": [], "slot": "items"},
+                {"id": uid("metric-3"), "type": "Metric", "props": {"label": "Completed", "value": "0", "trend": "up", "trendValue": "+0%"}, "children": [], "slot": "items"},
+                {"id": uid("metric-4"), "type": "Metric", "props": {"label": "Pending", "value": "0", "trend": "neutral", "trendValue": "0%"}, "children": [], "slot": "items"},
+            ],
+            "slot": "content",
+        })
+
+    if has_search:
+        components.append({
+            "id": uid("actions"),
+            "type": "Flex",
+            "props": {"direction": "row", "justify": "between", "align": "center"},
+            "children": [
+                {"id": uid("search"), "type": "Input", "props": {"type": "search", "name": "search", "placeholder": f"Search {page_name.lower()}..."}, "children": [], "slot": "items"},
+                *([{"id": uid("add-btn"), "type": "Button", "props": {"label": f"Add {page_name.rstrip('s')}", "variant": "default"}, "children": [], "slot": "items"}] if has_create else []),
+            ],
+            "slot": "content",
+        })
+
+    if has_kanban:
+        columns = [
+            {"id": "backlog", "title": "Backlog"},
+            {"id": "in_progress", "title": "In Progress"},
+            {"id": "review", "title": "Review"},
+            {"id": "done", "title": "Done"},
+        ]
+        components.append({
+            "id": uid("kanban"),
+            "type": "KanbanBoard",
+            "props": {
+                "dataSource": matching_table["name"] if matching_table else page_entity,
+                "titleKey": "title" if matching_table and any(c["name"] == "title" for c in matching_table.get("columns", [])) else "name",
+                "statusKey": "status",
+                "columns": columns,
+            },
+            "children": [],
+            "slot": "content",
+        })
+    elif has_list and matching_table:
+        columns = [
+            {"key": c["name"], "header": c["name"].replace("_", " ").title(), "sortable": True}
+            for c in matching_table.get("columns", [])[:6]
+            if c["name"] not in ("id", "user_id", "created_at", "updated_at")
+               and not c["name"].endswith("_id")
+        ]
+        components.append({
+            "id": uid("table"),
+            "type": "Table",
+            "props": {
+                "dataSource": matching_table["name"],
+                "searchable": True,
+                "pagination": True,
+                "columns": columns or [{"key": "name", "header": "Name", "sortable": True}],
+            },
+            "children": [],
+            "slot": "content",
+        })
+
+    if has_chart:
+        components.append({
+            "id": uid("chart-card"),
+            "type": "Card",
+            "props": {},
+            "children": [
+                {"id": uid("chart-title"), "type": "Text", "props": {"content": f"{page_name} Overview", "as": "h3"}, "children": [], "slot": "header"},
+                {"id": uid("chart"), "type": "Chart", "props": {"type": "area", "dataSource": "analytics", "xKey": "month", "yKey": "value"}, "children": [], "slot": "content"},
+            ],
+            "slot": "content",
+        })
+
+    return components
+
+
+def _build_settings_page(security_reqs: List[Dict]) -> Dict:
+    """Build a Settings page from security/non-functional requirements."""
+    children = [
+        {
+            "id": "settings-header",
+            "type": "Text",
+            "props": {"content": "Application Settings", "as": "h2"},
+            "children": [],
+            "slot": "content",
+        },
+    ]
+
+    # Add cards for each security requirement
+    for i, req in enumerate(security_reqs[:4]):
+        text = req.get("raw_text", f"Security requirement {i+1}")
+        children.append({
+            "id": f"settings-card-{i}",
+            "type": "Card",
+            "props": {},
+            "children": [
+                {"id": f"settings-text-{i}", "type": "Text", "props": {"content": text[:100]}, "children": [], "slot": "content"},
+            ],
+            "slot": "content",
+        })
+
+    return {
+        "id": "page-settings",
+        "name": "Settings",
+        "route": "/settings",
+        "is_protected": True,
+        "component_tree": [{
+            "id": "page-settings-root",
+            "type": "Page",
+            "props": {"title": "Settings"},
+            "children": children,
+            "slot": "",
+        }],
+    }
+
+
+def _default_dashboard_page() -> Dict:
+    """Default dashboard page with metrics and chart."""
+    return {
+        "id": "page-dashboard",
+        "name": "Dashboard",
+        "route": "/",
+        "is_protected": True,
+        "component_tree": [{
+            "id": "page-dashboard-root",
+            "type": "Page",
+            "props": {"title": "Dashboard"},
+            "children": [
+                {
+                    "id": "dash-metrics",
+                    "type": "Grid",
+                    "props": {"columns": 4, "gap": 4},
+                    "children": [
+                        {"id": "dash-metric-1", "type": "Metric", "props": {"label": "Total Records", "value": "0", "trend": "up", "trendValue": "+0%"}, "children": [], "slot": "items"},
+                        {"id": "dash-metric-2", "type": "Metric", "props": {"label": "Active", "value": "0", "trend": "neutral", "trendValue": "0%"}, "children": [], "slot": "items"},
+                        {"id": "dash-metric-3", "type": "Metric", "props": {"label": "This Week", "value": "0", "trend": "up", "trendValue": "+0%"}, "children": [], "slot": "items"},
+                        {"id": "dash-metric-4", "type": "Metric", "props": {"label": "Completion", "value": "0%", "trend": "up", "trendValue": "+0%"}, "children": [], "slot": "items"},
+                    ],
+                    "slot": "content",
+                },
+                {
+                    "id": "dash-chart-card",
+                    "type": "Card",
+                    "props": {},
+                    "children": [
+                        {"id": "dash-chart-title", "type": "Text", "props": {"content": "Overview", "as": "h3"}, "children": [], "slot": "header"},
+                        {"id": "dash-chart", "type": "Chart", "props": {"type": "area", "dataSource": "analytics", "xKey": "month", "yKey": "value"}, "children": [], "slot": "content"},
+                    ],
+                    "slot": "content",
+                },
+            ],
+            "slot": "",
+        }],
+    }
+
+
+def _minimal_spec(name: str, description: str) -> Dict:
+    """Minimal spec when no requirements are extracted."""
+    return {
+        "name": name,
+        "description": description,
+        "pages": [
+            {"id": "page-login", "name": "Login", "route": "/login", "is_protected": False, "component_tree": []},
+            _default_dashboard_page(),
+        ],
+        "tables": [
+            {"name": "profiles", "columns": [{"name": "full_name", "type": "text"}, {"name": "avatar_url", "type": "text"}, {"name": "role", "type": "text"}]},
+        ],
+    }
+
+
+def _build_rich_description(session_id: str, spec: Dict) -> str:
+    """Build a rich description from conversation + extracted spec for LLM enrichment."""
+    from tools.db.storage import get_connection
+
+    parts = [f"Application: {spec.get('name', 'App')}"]
+    parts.append(f"Description: {spec.get('description', '')}")
+
+    # Get conversation turns
+    try:
+        with get_connection() as conn:
+            turns = conn.execute(
+                "SELECT role, content FROM intake_conversation "
+                "WHERE session_id = ? ORDER BY turn_number",
+                (session_id,),
+            ).fetchall()
+        for turn in turns:
+            t = dict(turn)
+            if t["role"] == "customer":
+                parts.append(f"User requirement: {t['content']}")
+    except Exception:
+        pass
+
+    # Add extracted tables
+    tables = spec.get("tables", [])
+    if tables:
+        table_names = [t["name"] for t in tables]
+        parts.append(f"Data entities: {', '.join(table_names)}")
+
+    # Add page names
+    pages = spec.get("pages", [])
+    page_names = [p["name"] for p in pages if p["name"] != "Login"]
+    if page_names:
+        parts.append(f"Pages needed: {', '.join(page_names)}")
+
+    return "\n".join(parts)
+
+
+def _merge_specs(base_spec: Dict, llm_spec: Dict) -> Dict:
+    """Merge LLM-generated spec with our extracted base spec.
+
+    LLM spec takes priority for pages/components (richer UI).
+    Base spec tables are kept if LLM missed them.
+    """
+    merged = dict(llm_spec)
+
+    # Keep base tables that LLM missed
+    llm_table_names = {t["name"] for t in merged.get("tables", [])}
+    for table in base_spec.get("tables", []):
+        if table["name"] not in llm_table_names:
+            merged.setdefault("tables", []).append(table)
+
+    # Use base name/description if LLM gave generic ones
+    if not merged.get("name") or merged["name"] in ("App", "Application", "New App"):
+        merged["name"] = base_spec.get("name", merged.get("name", "App"))
+    if not merged.get("description"):
+        merged["description"] = base_spec.get("description", "")
+
+    return merged
+
+
+def _link_intake_session(app_id: str, session_id: str):
+    """Link a generated app back to its intake session."""
+    from tools.db.storage import get_connection
+
+    try:
+        with get_connection() as conn:
+            # Add column if it doesn't exist (idempotent)
+            try:
+                conn.execute(
+                    "ALTER TABLE forge_studio_apps ADD COLUMN intake_session_id TEXT"
+                )
+            except Exception:
+                pass  # Column already exists
+
+            conn.execute(
+                "UPDATE forge_studio_apps SET intake_session_id = ? WHERE id = ?",
+                (session_id, app_id),
+            )
+    except Exception as e:
+        logger.warning("Failed to link intake session: %s", e)