@claudetools/tools 0.8.11 → 0.9.0

package/docs/research/2026-01-02-kappa-v3-specification.md

@@ -0,0 +1,1864 @@
+# Kappa v3: Outcome-Oriented Programming
+
+**Version:** 3.0.0-alpha
+**Date:** 2026-01-02
+**Status:** Paradigm Definition
+**Authors:** Owen Innes, Claude (Anthropic)
+
+---
+
+## Abstract
+
+Kappa v3 introduces **Outcome-Oriented Programming (OOP2)** — a paradigm where developers specify desired outcomes, constraints, and design intent rather than implementation details. A constraint solver synthesises optimal implementations that satisfy all requirements. This document specifies the complete language, constraint system, design intent model, and synthesis engine.
+
+---
+
+## Part I: The Paradigm
+
+### 1.1 The Evolution
+
+| Generation | You Specify | System Does |
+|------------|-------------|-------------|
+| **Imperative** (C, Python) | How to do it step by step | Execute instructions |
+| **Declarative** (SQL, React) | What result you want | Figure out how |
+| **Specification** (Kappa v1-v2) | What code structure you want | Generate boilerplate |
+| **Outcome-Oriented** (Kappa v3) | What success looks like | Synthesise everything |
+
+### 1.2 The Core Insight
+
+Traditional programming:
+```
+Developer → Code → Compiler → Binary → Outcome
+```
+
+Outcome-Oriented:
+```
+Developer → Outcomes + Constraints → Solver → Code → Compiler → Binary
+                                       ↑
+                            Verify outcomes met
+```
+
+You define the destination. The system finds the path.
+
+### 1.3 The Five Pillars
+
+1. **Goals** — What you want to achieve (business outcomes)
+2. **Constraints** — What must be true (non-negotiable requirements)
+3. **Entities** — What exists in your domain (data model + behavior)
+4. **Journeys** — How users accomplish tasks (interaction flows)
+5. **Design Intent** — How it should feel (aesthetic + UX goals)
+
+---
+
+## Part II: Language Specification
+
+### 2.1 Goals
+
+Goals express desired business outcomes, not technical implementation.
+
+```kappa
+goal <Name> {
+  # What should be possible
+  enable: <capability>, <capability>, ...
+
+  # What must be true
+  ensure: <invariant>, <invariant>, ...
+
+  # Compliance requirements
+  comply: <standard>, <standard>, ...
+
+  # Audit requirements
+  audit: <event_pattern>
+
+  # Performance requirements
+  perform: <metric> <comparator> <value>
+
+  # Success metrics
+  measure: <metric> -> <target>
+}
+```
+
+**Example:**
+
+```kappa
+goal UserAuthentication {
+  enable:
+    users can sign_up with email and password,
+    users can log_in with credentials,
+    users can reset_password via email,
+    users can enable two_factor_auth,
+    admins can impersonate users (with audit)
+
+  ensure:
+    no duplicate accounts (by email),
+    passwords are never stored plaintext,
+    sessions expire after inactivity,
+    failed attempts trigger lockout (5 attempts, 15 min)
+
+  comply: GDPR, SOC2, OWASP_Top_10
+
+  audit: all authentication events with ip, user_agent, outcome
+
+  perform:
+    login p99 < 200ms,
+    signup p99 < 500ms
+
+  measure:
+    signup_completion_rate -> > 80%,
+    login_success_rate -> > 95%
+}
+
+goal RealtimeCollaboration {
+  enable:
+    multiple users can edit same document simultaneously,
+    users see each other's cursors and selections,
+    changes sync within 100ms,
+    offline edits merge on reconnect
+
+  ensure:
+    no data loss on conflict (CRDT),
+    eventual consistency,
+    causal ordering preserved
+
+  perform:
+    sync_latency p99 < 100ms,
+    merge_time < 50ms
+}
+```
+
+### 2.2 Constraints
+
+Constraints are non-negotiable requirements that ALL generated code must satisfy.
+
+```kappa
+constraints <Category> {
+  <aspect>: <requirement>
+}
+```
+
+**Built-in constraint categories:**
+
+```kappa
+constraints Security {
+  # Authentication
+  passwords: hashed(<algorithm>), min_length(<n>), require(<complexity>), breach_check
+  sessions: <type>, expires(<duration>), refresh(<strategy>), revokable
+  tokens: <type>, signed(<algorithm>), expires(<duration>)
+
+  # Input handling
+  inputs: sanitized, validated, parameterized  # SQL injection prevention
+  uploads: scanned, size_limit(<n>), type_whitelist([...])
+
+  # Rate limiting
+  rate_limit: <n> per <duration> per <scope>
+
+  # Encryption
+  data_at_rest: encrypted(<algorithm>)
+  data_in_transit: tls(<min_version>)
+
+  # Headers
+  headers: csp(<policy>), hsts, x_frame_options(<value>)
+}
+
+constraints Privacy {
+  pii_fields: [<field_patterns>]
+  retention: <duration> then <action>
+  consent: required_for([<purposes>])
+  export: available_within(<duration>)  # GDPR right to portability
+  deletion: complete_within(<duration>)  # GDPR right to erasure
+  anonymization: <strategy> for analytics
+}
+
+constraints Accessibility {
+  level: WCAG_A | WCAG_AA | WCAG_AAA
+  contrast: min(<ratio>)
+  motion: respect_prefers_reduced
+  keyboard: full_navigation
+  screen_reader: aria_complete
+  focus: visible_always
+  text: resizable_to(<percentage>)
+}
+
+constraints Performance {
+  # Core Web Vitals
+  lcp: < <duration>   # Largest Contentful Paint
+  fid: < <duration>   # First Input Delay
+  cls: < <value>      # Cumulative Layout Shift
+
+  # Bundle
+  initial_bundle: < <size>
+  lazy_threshold: > <size>  # Code-split if larger
+
+  # API
+  api_p50: < <duration>
+  api_p99: < <duration>
+
+  # Database
+  query_limit: < <duration>
+  n_plus_one: forbidden
+}
+
+constraints Reliability {
+  availability: <percentage>  # e.g., 99.9%
+  rto: < <duration>           # Recovery Time Objective
+  rpo: < <duration>           # Recovery Point Objective
+  backup: every(<duration>), retain(<duration>)
+  failover: automatic within(<duration>)
+}
+
+constraints Cost {
+  infrastructure: < <amount> per <period>
+  per_user: < <amount> per <period>
+  scale_strategy: <horizontal | vertical | serverless>
+}
+```
+
+### 2.3 Entities
+
+Entities define your domain model with behavior, not just data.
+
+```kappa
+entity <Name> {
+  # Identity
+  identify_by: <field> | composite(<fields>)
+
+  # Attributes
+  <name>: <type> [= <default>] [<modifiers>]
+
+  # Relationships
+  belongs_to: <Entity> [(as <role>)]
+  has_one: <Entity> [(as <role>)]
+  has_many: <Entity> [(as <role>)] [limit(<n>)]
+
+  # Capabilities (who can do what)
+  can: <action> [when <condition>]
+  cannot: <action> [unless <condition>]
+
+  # Visibility
+  visible_to: <roles | conditions>
+  <field>.visible_to: <roles | conditions>
+
+  # Editability
+  editable_by: <roles | conditions>
+  <field>.editable_by: <roles | conditions>
+
+  # State machine
+  states: <state> -> <state> [-> <state>]*
+  transitions:
+    <from> -> <to>: when <condition>, by <roles>
+
+  # Lifecycle hooks
+  on_create: <action>, <action>, ...
+  on_update: <action>, <action>, ...
+  on_delete: <action>, <action>, ...
+  on_<transition>: <action>, <action>, ...
+
+  # Computeds
+  compute <name>: <expression>
+
+  # Validations
+  validate: <expression> else <error>
+
+  # Indexes
+  index: <fields> [unique] [where <condition>]
+}
+```
+
+**Example:**
+
+```kappa
+entity User {
+  identify_by: email
+
+  # Attributes
+  email: email, unique, immutable
+  name: string(2..100)
+  avatar: image?, max_size(5mb)
+  role: Role = member
+  status: active | suspended | deleted = active
+  last_login: timestamp?
+  mfa_enabled: bool = false
+  mfa_secret: string?, encrypted, internal  # never exposed to API
+
+  # Relationships
+  has_many: Project (as owner), limit(100)
+  has_many: Membership
+  has_many: Project through Membership (as member)
+  has_many: AuditLog
+
+  # Capabilities
+  can: create Project
+  can: read Project when member_of(Project) or owner_of(Project)
+  can: update Project when owner_of(Project) or role_in(Project, editor)
+  can: delete Project when owner_of(Project)
+  can: invite_to Project when owner_of(Project)
+  cannot: delete self when has_owned_projects  # must transfer first
+
+  # Visibility
+  visible_to: self, admin
+  email.visible_to: self, admin, members_of_shared_projects
+  mfa_secret.visible_to: none  # internal only
+
+  # State
+  states: active -> suspended -> deleted
+  transitions:
+    active -> suspended: by admin, on_transition notify(user, "account_suspended")
+    suspended -> active: by admin
+    suspended -> deleted: by admin, after(30 days)
+    active -> deleted: by self, requires confirmation
+
+  # Lifecycle
+  on_create:
+    send_email(welcome_template),
+    log_audit(user_created),
+    enqueue(onboarding_sequence)
+
+  on_delete:
+    anonymize(email -> "deleted_{id}@anon.local"),
+    anonymize(name -> "Deleted User"),
+    delete(avatar),
+    transfer_or_delete(owned_projects),
+    log_audit(user_deleted, retain: 7 years)  # legal requirement
+
+  # Computed
+  compute display_name: name or email.local_part
+  compute is_admin: role == admin
+  compute project_count: projects.count
+
+  # Validations
+  validate: email.domain not in disposable_domains else "Please use a permanent email"
+  validate: name !~ /<script>/i else "Invalid characters in name"
+
+  # Indexes
+  index: email, unique
+  index: [status, last_login] where status == active  # for cleanup queries
+}
+
+entity Project {
+  identify_by: slug (scoped_to owner)
+
+  name: string(1..100)
+  slug: slug, auto_from(name)
+  description: markdown?, max_length(10000)
+  visibility: public | private | team = private
+  status: draft | active | archived = draft
+
+  belongs_to: User (as owner)
+  has_many: Membership
+  has_many: User through Membership (as members)
+  has_many: Task, ordered_by(position)
+
+  # Capabilities contextual to relationship
+  owner can: read, update, delete, archive, transfer_ownership, manage_members
+  member(editor) can: read, update, create_task, update_task
+  member(viewer) can: read
+  public: anyone can read when visibility == public
+
+  states: draft -> active -> archived
+  transitions:
+    draft -> active: by owner
+    active -> archived: by owner, on_transition notify_members("project_archived")
+    archived -> active: by owner, within(30 days)  # after 30 days, cannot restore
+
+  on_delete:
+    require: no active_tasks or force_confirmed,
+    delete: all tasks (cascade),
+    notify: all members,
+    log_audit: project_deleted
+
+  compute member_count: memberships.count
+  compute task_count: tasks.count
+  compute completion_rate: tasks.where(done).count / tasks.count
+
+  index: [owner_id, slug], unique
+  index: [visibility, status] where visibility == public
+}
+
+entity Membership {
+  identify_by: composite(user, project)
+
+  belongs_to: User
+  belongs_to: Project
+
+  role: owner | editor | viewer
+  invited_by: User?
+  invited_at: timestamp = now
+  accepted_at: timestamp?
+
+  states: pending -> accepted -> revoked
+  transitions:
+    pending -> accepted: by self (the invited user)
+    pending -> revoked: by inviter or project_owner
+    accepted -> revoked: by project_owner or self
+
+  validate: user != project.owner else "Owner cannot have membership"
+  validate: role != owner else "Only one owner allowed, use transfer"
+
+  on_create: send_email(invitation_template) when state == pending
+  on_transition(accepted): log_audit(member_joined)
+  on_transition(revoked): log_audit(member_removed)
+}
+```
+
+### 2.4 Journeys
+
+Journeys define how users accomplish goals, not routes or pages.
+
+```kappa
+journey <Name> {
+  # Who takes this journey
+  actor: <role | condition>
+
+  # What triggers entry
+  entry: <trigger>
+
+  # Steps (not pages - semantic steps)
+  steps: <step> -> <step> [-> <step>]*
+
+  # Step definitions
+  step <name> {
+    goal: <what user accomplishes>
+    show: <information needed>
+    collect: <input needed>
+    validate: <constraints on input>
+    on_complete: <actions>
+    next: <step> [when <condition>] | done
+    alternatives: <step> [when <condition>]
+  }
+
+  # Optimization targets
+  optimize_for: <metric>
+
+  # Failure handling
+  on_drop_off(<step>): <action>
+  on_error: <action>
+
+  # Testing
+  test: <scenario> -> <expected_outcome>
+
+  # Experimentation
+  experiment(<name>) {
+    control: <variant>
+    variants: <variant>, <variant>
+    measure: <metric>
+    significance: <threshold>
+  }
+}
+```
+
+**Example:**
+
+```kappa
+journey Onboarding {
+  actor: unauthenticated user
+  entry: visit(landing_page) or referral_link or direct(signup_url)
+
+  steps: land -> signup -> verify_email -> create_workspace -> invite_team -> done
+
+  step land {
+    goal: understand value proposition
+    show: hero, features, social_proof, pricing_preview
+    collect: nothing  # awareness only
+    next: signup when cta_clicked
+    track: time_on_page, scroll_depth, cta_hover
+  }
+
+  step signup {
+    goal: create account
+    show: signup_form, oauth_options, terms_link
+    collect: {
+      email: email, required
+      password: password, required, strength_meter
+      name: string, required
+    }
+    validate:
+      email not in existing_users else "Already have an account? [Log in]",
+      password.strength >= medium else "Please choose a stronger password"
+    on_complete:
+      create(User),
+      send_verification_email,
+      set_cookie(session),
+      track(signup_completed)
+    next: verify_email
+    alternatives: oauth_flow when oauth_clicked
+  }
+
+  step verify_email {
+    goal: confirm email ownership
+    show: check_email_message, resend_option, change_email_option
+    collect: verification_code(6 digits) or magic_link_click
+    validate: code matches sent_code and not expired(10 min)
+    on_complete:
+      mark_verified,
+      track(email_verified)
+    next: create_workspace
+    timeout: 24 hours -> send_reminder, 72 hours -> expire_account
+  }
+
+  step create_workspace {
+    goal: set up first project space
+    show: workspace_form, template_options, skip_option
+    collect: {
+      workspace_name: string, required, suggested(from user.name + "'s Workspace")
+      template: template_id?, recommended(blank)
+    }
+    on_complete:
+      create(Project, from: template),
+      assign_owner(current_user),
+      track(workspace_created, template: selected_template)
+    next: invite_team
+    alternatives: done when skip_clicked  # allow skipping
+  }
+
+  step invite_team {
+    goal: add collaborators (activation metric)
+    show: invite_form, skip_option, benefits_of_collaboration
+    collect: {
+      emails: [email], min(0), max(10)
+      message: string?, default(standard_invite_message)
+    }
+    on_complete:
+      send_invitations(emails),
+      track(invitations_sent, count: emails.length)
+    next: done
+    skip_allowed: true  # but track it
+  }
+
+  step done {
+    goal: start using product
+    show: success_message, quick_start_guide, first_action_prompt
+    on_complete:
+      track(onboarding_completed, duration: journey_time),
+      trigger(product_tour) when first_visit
+    next: dashboard
+  }
+
+  optimize_for: completion_rate, time_to_value
+
+  on_drop_off(signup):
+    track(signup_abandoned),
+    cookie(intent),
+    retarget_after(24 hours) when email_collected
+
+  on_drop_off(verify_email):
+    send_reminder(after: 1 hour),
+    send_reminder(after: 24 hours),
+    send_final_notice(after: 48 hours)
+
+  on_drop_off(invite_team):
+    track(skipped_invites),
+    prompt_later(after: 3 days) in_app
+
+  experiment(signup_flow) {
+    control: email_first
+    variants:
+      oauth_prominent: show oauth buttons first, email below
+      social_proof: add testimonial next to form
+      minimal: remove all but essential fields
+    measure: signup_completion_rate, time_to_complete
+    significance: 95%
+  }
+
+  test: complete_flow -> user.verified and project.exists
+  test: oauth_google -> user.verified(immediate) and provider(google)
+  test: drop_at_verify -> reminder_sent(after: 1 hour)
+}
+
+journey TaskCompletion {
+  actor: authenticated project_member
+  entry: view_task or notification_click or search_result
+
+  steps: view -> work -> complete -> celebrate
+
+  step view {
+    goal: understand what needs to be done
+    show: task_details, attachments, comments, related_tasks, assignee, due_date
+    collect: nothing
+    next: work when start_clicked or comment_added or file_uploaded
+  }
+
+  step work {
+    goal: make progress on task
+    show: task_details, timer_option, progress_updates, collaboration_tools
+    collect: {
+      progress_note: string?,
+      time_logged: duration?,
+      blockers: [blocker]?
+    }
+    on_progress:
+      notify(watchers, throttled: 5 min),
+      update(last_activity)
+    next: complete when mark_done_clicked
+    alternatives: blocked when blocker_added
+  }
+
+  step complete {
+    goal: mark task as finished
+    show: completion_form, summary
+    collect: {
+      completion_note: string?
+      actual_time: duration?, suggested(tracked_time)
+    }
+    validate: all subtasks.completed when has_subtasks
+    on_complete:
+      mark_done,
+      notify(stakeholders),
+      track(task_completed, time: actual_time),
+      update_project_progress
+    next: celebrate
+  }
+
+  step celebrate {
+    goal: positive reinforcement
+    show: success_animation, streak_count, next_task_suggestion
+    duration: 2 seconds
+    next: view(next_task) or dashboard
+  }
+
+  optimize_for: completion_rate, time_to_complete
+
+  test: complete_task -> task.status == done and audit_logged
+  test: blocked_task -> blocker.assigned and notifications_sent
+}
+```
+
+### 2.5 Design Intent
+
+Design intent expresses how the product should *feel*, not just how it looks.
+
+```kappa
+design {
+  # === MOOD & PERSONALITY ===
+
+  mood: <mood_descriptors>
+  # Moods: professional, playful, serious, friendly, luxurious, minimal,
+  #        energetic, calm, bold, subtle, warm, cool, technical, approachable
+
+  personality {
+    voice: "<brand voice description>"
+    tone: <tone_descriptors>  # confident, humble, casual, formal, witty, direct
+
+    # Microcopy patterns
+    empty_states: <encouraging | minimal | instructive>
+    errors: <apologetic | direct | helpful>
+    success: <celebratory | subtle | informative>
+    loading: <patient | progress | skeleton>
+  }
+
+  # === VISUAL FOUNDATION ===
+
+  foundation {
+    # Can derive from assets
+    primary: <color> | from_logo(<path>) | from_brand(<url>)
+
+    # Or specify mood-based derivation
+    palette: derive(mood, base: <color>)
+
+    # Explicit overrides
+    colors {
+      background: <color>
+      surface: <color>
+      text: <color>
+      # ... etc
+    }
+
+    # Typography
+    typography {
+      heading: <font> | derive(mood)
+      body: <font> | derive(mood, readable: true)
+      mono: <font>
+      scale: <ratio>  # e.g., 1.25 (major third), 1.333 (perfect fourth)
+    }
+
+    # Spacing & Layout
+    density: compact | comfortable | spacious
+    spacing_unit: <size>  # base unit, e.g., 4px
+    radius: none | subtle | medium | full
+
+    # Effects
+    shadows: none | subtle | medium | dramatic
+    borders: none | subtle | prominent
+  }
+
+  # === MOTION & INTERACTION ===
+
+  motion {
+    level: none | reduced | standard | expressive
+
+    # Semantic animations (what they mean, not how they move)
+    enter: <style>    # elements appearing
+    exit: <style>     # elements disappearing
+    move: <style>     # elements relocating
+    feedback: <style> # response to interaction
+
+    # Derived from mood
+    style: derive(mood)  # playful = bouncy, professional = smooth, etc.
+
+    duration {
+      instant: <ms>    # micro-interactions
+      fast: <ms>       # standard transitions
+      slow: <ms>       # emphasis transitions
+    }
+  }
+
+  # === RESPONSIVE BEHAVIOR ===
+
+  responsive {
+    strategy: mobile_first | desktop_first
+
+    breakpoints {
+      mobile: < <width>
+      tablet: <width> to <width>
+      desktop: > <width>
+    }
+
+    # Layout adaptations (semantic, not CSS)
+    mobile {
+      navigation: bottom_tabs | hamburger | minimal
+      layout: stack | full_width
+      interactions: touch_optimized, larger_targets
+      content: prioritized, progressive_disclosure
+    }
+
+    tablet {
+      navigation: sidebar_collapsible | top
+      layout: adaptive_grid
+    }
+
+    desktop {
+      navigation: sidebar_fixed | top_full
+      layout: multi_column, max_width(<width>)
+      interactions: hover_states, keyboard_shortcuts
+    }
+  }
+
+  # === COMPONENT PATTERNS ===
+
+  patterns {
+    # Form style
+    forms {
+      layout: stacked | inline | floating_label
+      validation: instant | on_blur | on_submit
+      errors: inline | tooltip | summary
+    }
+
+    # Data display
+    data {
+      tables: full | cards_on_mobile
+      lists: separated | bordered | minimal
+      empty: illustration | message | cta
+    }
+
+    # Feedback
+    feedback {
+      success: toast | inline | modal
+      error: toast | inline | modal
+      confirm: modal | inline | popover
+    }
+
+    # Navigation
+    navigation {
+      breadcrumbs: always | deep_only | never
+      back_button: always | when_nested | never
+    }
+  }
+
+  # === DARK MODE ===
+
+  dark_mode {
+    enabled: true | false | system_only
+    strategy: invert_lightness | separate_palette | auto_derive
+
+    # If separate palette
+    overrides {
+      background: <color>
+      surface: <color>
+      # ...
+    }
+  }
+
+  # === ACCESSIBILITY OVERRIDES ===
+
+  accessibility {
+    # Beyond constraints (which are requirements), these are enhancements
+    focus_visible: always | keyboard_only
+    link_underlines: always | hover | never(with_color_only)
+    reduced_motion_alternative: true
+  }
+}
+```
+
+**Example:**
+
+```kappa
+design {
+  mood: professional + approachable + minimal
+
+  personality {
+    voice: "We help teams ship faster without the chaos"
+    tone: confident, helpful, occasionally witty
+
+    empty_states: encouraging  # "No projects yet. Let's create your first one!"
+    errors: helpful           # "That email's already taken. Did you mean to log in?"
+    success: celebratory      # Subtle confetti on milestones
+    loading: skeleton         # Content-shaped placeholders
+  }
+
+  foundation {
+    primary: from_logo("./assets/logo.svg")  # Extract dominant color
+    palette: derive(mood, base: primary)     # Generate full palette
+
+    typography {
+      heading: "Inter"
+      body: "Inter"
+      mono: "JetBrains Mono"
+      scale: 1.25
+    }
+
+    density: comfortable
+    spacing_unit: 4px
+    radius: medium  # ~8px, friendly but not childish
+    shadows: subtle
+    borders: subtle
+  }
+
+  motion {
+    level: standard
+    style: derive(mood)  # smooth, purposeful (from professional + approachable)
+
+    enter: fade_up       # elements rise into view
+    exit: fade           # elements fade out (don't distract)
+    feedback: scale      # buttons subtly press
+
+    duration {
+      instant: 100ms
+      fast: 200ms
+      slow: 400ms
+    }
+  }
+
+  responsive {
+    strategy: mobile_first
+
+    breakpoints {
+      mobile: < 640px
+      tablet: 640px to 1024px
+      desktop: > 1024px
+    }
+
+    mobile {
+      navigation: bottom_tabs
+      layout: stack
+      content: prioritized  # Show key info first, details on tap
+    }
+
+    desktop {
+      navigation: sidebar_fixed
+      layout: multi_column, max_width(1280px)
+      interactions: hover_states, keyboard_shortcuts
+    }
+  }
+
+  patterns {
+    forms {
+      layout: stacked
+      validation: on_blur
+      errors: inline
+    }
+
+    data {
+      tables: cards_on_mobile  # Convert tables to cards on small screens
+      empty: illustration      # Friendly illustrations for empty states
+    }
+
+    feedback {
+      success: toast
+      error: inline
+      confirm: modal
+    }
+  }
+
+  dark_mode {
+    enabled: true
+    strategy: auto_derive  # Automatically create dark versions
+  }
+}
+```
+
+---
+
+## Part III: The Constraint Solver
+
+### 3.1 Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Kappa Specification                      │
+│  (Goals, Constraints, Entities, Journeys, Design Intent)    │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      PARSER & ANALYZER                       │
+│  - Parse Kappa syntax                                        │
+│  - Build dependency graph                                    │
+│  - Identify constraint interactions                          │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    CONSTRAINT COMPILER                       │
+│  - Convert goals to formal constraints                       │
+│  - Convert design intent to design tokens                    │
+│  - Compile to SAT/SMT representation                         │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      SYNTHESIS ENGINE                        │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │  Schema     │  │  API        │  │  UI         │         │
+│  │  Generator  │  │  Generator  │  │  Generator  │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘         │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │  Auth       │  │  Journey    │  │  Design     │         │
+│  │  Generator  │  │  Generator  │  │  Generator  │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘         │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      CONSTRAINT SOLVER                       │
+│  - Find implementation satisfying all constraints            │
+│  - Optimize for specified metrics                            │
+│  - Report conflicts for human resolution                     │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       VERIFIER                               │
+│  - Prove constraints are satisfied                           │
+│  - Generate test cases                                       │
+│  - Add runtime checks where static proof impossible          │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    GENERATED OUTPUT                          │
+│  - Database schema with migrations                           │
+│  - API routes with middleware                                │
+│  - UI components with design tokens                          │
+│  - Journey flows with analytics                              │
+│  - Tests covering all constraints                            │
+│  - Provenance comments linking to specs                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 Constraint Resolution
+
+When constraints interact or conflict:
+
+```kappa
+# Example conflict
+constraints Performance {
+  lcp: < 1.5s
+}
+
+entity Project {
+  has_many: Task, limit(10000)  # Could have many tasks
+}
+
+journey Dashboard {
+  step overview {
+    show: all project tasks with status  # Potentially slow
+  }
+}
+```
+
+**Solver detects:**
+```
+⚠️ Potential Constraint Conflict
+
+Performance.lcp < 1.5s may conflict with:
+  - Project.has_many Task (up to 10,000)
+  - Dashboard.overview.show all tasks
+
+Analysis:
+  - Fetching 10,000 tasks: ~800ms DB + ~400ms render = 1.2s (OK)
+  - Fetching 10,000 tasks with details: ~2.5s (EXCEEDS)
+
+Solutions:
+  ┌─────────────────────────────────────────────────────────┐
+  │ (a) Add pagination [RECOMMENDED]                        │
+  │     Fetch 50 tasks per page                             │
+  │     Impact: UX change (pagination controls)             │
+  │     Satisfies: All constraints                          │
+  ├─────────────────────────────────────────────────────────┤
+  │ (b) Add virtualization                                  │
+  │     Render only visible rows                            │
+  │     Impact: Complexity +2, bundle +15kb                 │
+  │     Satisfies: All constraints                          │
+  ├─────────────────────────────────────────────────────────┤
+  │ (c) Relax LCP constraint for large projects             │
+  │     Change: lcp < 1.5s when tasks < 1000                │
+  │             lcp < 3.0s when tasks >= 1000               │
+  │     Impact: Degraded experience for power users         │
+  ├─────────────────────────────────────────────────────────┤
+  │ (d) Add caching layer                                   │
+  │     Cache task summaries, invalidate on change          │
+  │     Impact: Cost +$20/mo, eventual consistency          │
+  └─────────────────────────────────────────────────────────┘
+
+> Select solution: [a] / b / c / d / custom
+```
+
+### 3.3 Design Intent Resolution
+
+```kappa
+design {
+  mood: professional + playful  # Slight tension
+}
+```
+
+**Solver interprets:**
+```
+Mood Analysis: professional + playful
+
+These moods have tension points:
+  - professional suggests: muted colors, clean lines, formal typography
+  - playful suggests: bright colors, rounded shapes, casual typography
+
+Resolution strategy: Professional foundation, playful accents
+
+Generated tokens:
+  colors:
+    background: #FAFAFA    (professional: neutral)
+    text: #1A1A1A          (professional: high contrast)
+    primary: #6366F1       (playful: vibrant purple)
+    accent: #F59E0B        (playful: warm amber)
+
+  typography:
+    heading: "Inter"       (professional: clean sans-serif)
+    body: "Inter"          (professional: readable)
+    weight: medium         (professional: substantial)
+
+  radius: 12px             (playful: rounded but not bubbly)
+
+  motion:
+    style: smooth          (professional: controlled)
+    feedback: bounce(subtle) (playful: responsive)
+
+  personality:
+    microcopy: friendly but concise
+    empty_states: illustrated (playful) with direct CTA (professional)
+
+Confidence: 87% this interpretation matches intent
+> Accept / Adjust toward professional / Adjust toward playful / Custom
+```
+
+---
+
+## Part IV: Provenance & Debugging
+
+### 4.1 Provenance Comments
+
+Every generated line traces to its source:
+
+```typescript
+// FILE: app/api/projects/[id]/route.ts
+// GENERATED: 2026-01-02T14:30:00Z
+// KAPPA: entities.Project, goals.ProjectCollaboration
+
+import { db } from "@/lib/db";
+import { requireAuth, requireRole } from "@/lib/auth";
+
+// [GOAL: ProjectCollaboration.ensure.only_owners_can_delete]
+// [ENTITY: Project.owner can delete]
+export async function DELETE(req: Request, { params }: { params: { id: string } }) {
+  // [CONSTRAINT: Security.sessions.jwt]
+  const user = await requireAuth(req);
+
+  // [ENTITY: Project.owner can delete]
+  // [GOAL: ProjectCollaboration.ensure.only_owners_can_delete]
+  const project = await db.project.findUnique({
+    where: { id: params.id },
+    include: { owner: true }
+  });
+
+  if (!project) {
+    // [CONSTRAINT: Security.inputs.validated]
+    return Response.json({ error: "Project not found" }, { status: 404 });
+  }
+
+  if (project.ownerId !== user.id) {
+    // [GOAL: ProjectCollaboration.ensure.only_owners_can_delete]
+    return Response.json({ error: "Only owners can delete projects" }, { status: 403 });
+  }
+
+  // [ENTITY: Project.on_delete.require no active_tasks]
+  const activeTasks = await db.task.count({
+    where: { projectId: params.id, status: { not: "done" } }
+  });
+
+  if (activeTasks > 0 && !req.headers.get("X-Force-Delete")) {
+    return Response.json({
+      error: "Project has active tasks",
+      active_count: activeTasks,
+      hint: "Complete or delete tasks first, or send X-Force-Delete header"
+    }, { status: 409 });
+  }
+
+  // [ENTITY: Project.on_delete.delete all tasks (cascade)]
+  await db.task.deleteMany({ where: { projectId: params.id } });
+
+  // [ENTITY: Project.on_delete.notify all members]
+  // [JOURNEY: implicit notification on significant events]
+  await notifyProjectMembers(params.id, "project_deleted", {
+    project_name: project.name,
+    deleted_by: user.name
+  });
+
+  // [ENTITY: Project.on_delete.log_audit]
+  // [GOAL: ProjectCollaboration.audit]
+  await auditLog("project.deleted", {
+    projectId: params.id,
+    userId: user.id,
+    projectName: project.name,
+    taskCount: activeTasks,
+    forced: !!req.headers.get("X-Force-Delete")
+  });
+
+  // [ENTITY: Project primary delete action]
+  await db.project.delete({ where: { id: params.id } });
+
+  return Response.json({ success: true });
+}
+```
+
+### 4.2 Constraint Violation Detection
+
+Runtime monitoring for constraints that can't be statically verified:
+
+```typescript
+// [CONSTRAINT: Performance.api_p99 < 200ms]
+// [MONITORING: runtime_check]
+export const withPerformanceConstraint = (handler: Handler) => async (req, res) => {
+  const start = performance.now();
+
+  try {
+    const result = await handler(req, res);
+    return result;
+  } finally {
+    const duration = performance.now() - start;
+
+    // Track for p99 calculation
+    metrics.recordApiLatency(req.path, duration);
+
+    // [CONSTRAINT: Performance.api_p99 < 200ms]
+    if (duration > 200) {
+      constraintViolation({
+        constraint: "Performance.api_p99",
+        expected: "< 200ms",
+        actual: `${duration.toFixed(0)}ms`,
+        endpoint: req.path,
+        severity: duration > 500 ? "critical" : "warning"
+      });
+    }
+  }
+};
+```
+
+### 4.3 Bidirectional Sync
+
+When you edit generated code:
+
+```typescript
+// Developer adds this line:
+if (user.role === "admin") {
+  // Skip ownership check for admins
+  // TODO: Is this intentional?
+}
+```
+
+**Kappa detects the drift:**
+```
+⚠️ Generated Code Modified
+
+File: app/api/projects/[id]/route.ts
+Line: 23-26 (new code)
+
+Change analysis:
+  - Allows admins to bypass ownership check
+  - Affects: GOAL ProjectCollaboration.ensure.only_owners_can_delete
+
+This change implies a new capability. Update spec?
+
+Options:
+  ┌─────────────────────────────────────────────────────────┐
+  │ (a) Update spec to match code [RECOMMENDED]             │
+  │     Add: admin can: delete any Project                  │
+  │     Regenerates other affected code consistently        │
+  ├─────────────────────────────────────────────────────────┤
+  │ (b) Revert code to match spec                           │
+  │     Removes admin bypass                                │
+  ├─────────────────────────────────────────────────────────┤
+  │ (c) Mark as intentional deviation                       │
+  │     Adds @override annotation, preserves on regenerate  │
+  └─────────────────────────────────────────────────────────┘
+
+> Select: [a] / b / c
+```
+
+If (a) selected, spec updates automatically:
+
+```kappa
+entity Project {
+  # ... existing ...
+
+  # Auto-added from code sync
+  owner can: delete
+  admin can: delete any  # [SYNCED: app/api/projects/[id]/route.ts:23-26]
+}
+```
+
+---
+
+## Part V: Learning & Evolution
+
+### 5.1 Escape Hatch with Learning
+
+When Kappa can't express something:
+
+```kappa
+entity Payment {
+  amount: money
+  currency: currency_code
+  status: pending | processing | completed | failed
+
+  # Complex tax calculation - hard to specify declaratively
+  custom {
+    @target(typescript)
+    @learn("external_tax_integration")
+
+    calculateTax: (amount: number, shipping: Address, items: LineItem[]) => {
+      // Tax jurisdiction logic is complex and varies
+      // Delegate to TaxJar API
+      const taxjar = new TaxJar({ apiKey: env.TAXJAR_KEY });
+      return taxjar.taxForOrder({
+        from_country: 'US',
+        from_zip: warehouse.zip,
+        to_country: shipping.country,
+        to_zip: shipping.zip,
+        amount: amount,
+        shipping: shipping.cost,
+        line_items: items.map(i => ({
+          quantity: i.quantity,
+          unit_price: i.price,
+          product_tax_code: i.taxCode
+        }))
+      });
+    }
+  }
+}
+```
+
+**After seeing similar patterns across projects:**
+
+```
+📚 Pattern Learned: external_tax_integration
+
+Observed in: 12 projects
+Common structure:
+  - Third-party tax service (TaxJar, Avalara, TaxCloud)
+  - Inputs: amount, addresses, line items
+  - Outputs: tax breakdown by jurisdiction
+
+Proposing first-class primitive:
+
+  tax_calculation {
+    provider: taxjar | avalara | taxcloud | stripe_tax
+    from: <address_field>
+    to: <address_field>
+    items: <line_items_field>
+    cache: <duration>
+  }
+
+Add to Kappa standard library? [Y/n]
+```
+
+### 5.2 Community Pattern Library
+
+```kappa
+# Import community patterns
+import patterns/saas_billing from kappa-hub
+import patterns/team_permissions from kappa-hub
+import patterns/audit_logging from kappa-hub
+
+# Use them
+entity Subscription {
+  uses: saas_billing(
+    provider: stripe,
+    plans: [free, pro, enterprise],
+    billing_cycle: monthly | yearly,
+    trial: 14 days
+  )
+}
+
+entity Organization {
+  uses: team_permissions(
+    roles: [owner, admin, member, viewer],
+    invitations: email_based,
+    sso: optional(saml, oidc)
+  )
+}
+```
+
+### 5.3 Spec Evolution
+
+As requirements change:
+
+```kappa
+# Version 1
+entity User {
+  email: email
+  name: string
+}
+
+# Version 2 - add teams
+entity User {
+  email: email
+  name: string
+  belongs_to: Team?  # NEW
+}
+
+entity Team {  # NEW
+  name: string
+  has_many: User
+}
+```
+
+**Solver generates migration:**
+```
+Migration Analysis: v1 → v2
+
+Changes detected:
+  1. New entity: Team
+  2. New relationship: User.belongs_to Team (optional)
+
+Generated migrations:
+
+  1. Create teams table
+     - Safe: Yes (new table)
+
+  2. Add team_id to users
+     - Safe: Yes (nullable)
+
+  3. Data migration needed: No
+     - Existing users have team_id = null (valid for optional)
+
+Rollback plan:
+  1. Drop team_id from users
+  2. Drop teams table
+
+> Apply migration? [Y/n]
+```
+
+---
+
+## Part VI: Complete Example
+
+### 6.1 Full Specification
+
+```kappa
+# ============================================
+# PROJECT: TaskFlow - Team Task Management
+# ============================================
+
+# === GOALS ===
+
+goal Authentication {
+  enable:
+    users sign up with email,
+    users log in securely,
+    users recover forgotten passwords,
+    users enable two-factor auth
+
+  ensure:
+    no duplicate accounts,
+    sessions expire after inactivity,
+    passwords meet security standards
+
+  comply: OWASP_Top_10
+  audit: all auth events
+
+  perform:
+    login p99 < 200ms,
+    signup p99 < 500ms
+}
+
+goal TaskManagement {
+  enable:
+    users create and organize tasks,
+    users assign tasks to team members,
+    users set due dates and priorities,
+    users track task progress,
+    users collaborate with comments
+
+  ensure:
+    only team members see team tasks,
+    completed tasks are never lost,
+    task history is preserved
+
+  audit: task status changes, assignments
+
+  measure:
+    tasks_completed_per_user_per_week -> track,
+    overdue_task_rate -> < 20%
+}
+
+goal TeamCollaboration {
+  enable:
+    users create teams,
+    team owners invite members,
+    members have roles (admin, member, viewer),
+    teams share projects
+
+  ensure:
+    only owners can delete teams,
+    removing member preserves their task history,
+    transferring ownership is atomic
+
+  audit: membership changes, role changes
+}
+
+# === CONSTRAINTS ===
+
+constraints Security {
+  passwords: hashed(argon2id), min(12), breach_check
+  sessions: jwt, expires(7d), refresh(sliding), revokable
+  inputs: sanitized, validated, rate_limited(100/min/ip)
+  uploads: scanned, max_size(10mb), type_whitelist([image/*, .pdf, .doc, .docx])
+}
+
+constraints Privacy {
+  pii_fields: [email, name, avatar]
+  retention: 3 years then anonymize
+  deletion: complete within 30 days
+  export: available within 48 hours
+}
+
+constraints Accessibility {
+  level: WCAG_AA
+  contrast: min(4.5)
+  keyboard: full_navigation
+  motion: respect_prefers_reduced
+}
+
+constraints Performance {
+  lcp: < 2s
+  fid: < 100ms
+  cls: < 0.1
+  api_p99: < 300ms
+  initial_bundle: < 150kb
+}
+
+# === ENTITIES ===
+
+entity User {
+  identify_by: email
+
+  email: email, unique, immutable
+  name: string(2..100)
+  avatar: image?, max_size(5mb)
+  role: Role = member
+
+  has_many: Team (as owner), limit(10)
+  has_many: Membership
+  has_many: Team through Membership
+  has_many: Task (as assignee)
+  has_many: Comment
+
+  can: create Team, create Task (in own teams)
+  visible_to: self, team_members, admin
+
+  on_create: send_email(welcome), log_audit
+  on_delete: anonymize, transfer_ownership, log_audit
+
+  compute display_name: name or email.local_part
+}
+
+entity Team {
+  identify_by: slug
+
+  name: string(2..50)
+  slug: slug, auto_from(name), unique
+  description: string?, max(500)
+
+  belongs_to: User (as owner)
+  has_many: Membership
+  has_many: User through Membership (as members)
+  has_many: Project
+
+  owner can: update, delete, manage_members, transfer_ownership
+  admin can: update, manage_members, create_project
+  member can: read, create_task, comment
+  viewer can: read
+
+  on_delete: require(no_projects or confirmed), notify_members
+
+  compute member_count: memberships.count
+}
+
+entity Membership {
+  identify_by: composite(user, team)
+
+  belongs_to: User
+  belongs_to: Team
+  role: owner | admin | member | viewer = member
+
+  states: invited -> active -> removed
+
+  on_create: send_email(invitation) when invited
+  on_transition(active): log_audit(member_joined)
+}
+
+entity Project {
+  identify_by: slug (scoped_to team)
+
+  name: string(1..100)
+  slug: slug, auto_from(name)
+  description: markdown?, max(10000)
+  status: active | archived = active
+
+  belongs_to: Team
+  has_many: Task, ordered_by(position)
+
+  visible_to: team.members
+  editable_by: team.owner, team.admin, team.member
+
+  states: active -> archived
+
+  compute task_count: tasks.count
+  compute completion_rate: tasks.done.count / tasks.count
+
+  index: [team_id, slug], unique
+}
+
+entity Task {
+  identify_by: number (scoped_to project, auto_increment)
+
+  title: string(1..200)
+  description: markdown?, max(50000)
+  status: todo | in_progress | in_review | done = todo
+  priority: low | medium | high | urgent = medium
+  due_date: date?
+  position: integer, auto
+
+  belongs_to: Project
+  belongs_to: User? (as assignee)
+  belongs_to: User (as creator)
+  has_many: Comment, ordered_by(created_at)
+  has_many: Task (as subtasks)
+  belongs_to: Task? (as parent)
+
+  visible_to: project.team.members
+  editable_by: creator, assignee, project.team.admin, project.team.owner
+
+  states: todo -> in_progress -> in_review -> done
+  transitions:
+    any -> done: log_audit(task_completed)
+    done -> any: log_audit(task_reopened)
+
+  on_assign: notify(assignee), log_audit
+  on_due_soon(1 day): notify(assignee, creator)
+  on_overdue: notify(assignee, creator, project.team.owner)
+
+  compute is_overdue: due_date < today and status != done
+  compute subtask_progress: subtasks.done.count / subtasks.count
+
+  index: [project_id, number], unique
+  index: [assignee_id, status] where assignee_id != null
+  index: [due_date] where status != done
+}
+
+entity Comment {
+  identify_by: auto
+
+  body: markdown(1..10000)
+
+  belongs_to: Task
+  belongs_to: User (as author)
+
+  visible_to: task.project.team.members
+  editable_by: author (within 15 minutes)
+  deletable_by: author, task.project.team.admin
+
+  on_create: notify(task.participants except author)
+}
+
+# === JOURNEYS ===
+
+journey Onboarding {
+  actor: new_user
+  entry: signup or invitation_accept
+
+  steps: signup -> verify -> create_team -> invite -> ready
+
+  step signup {
+    goal: create account
+    collect: { email: email, password: password, name: string }
+    on_complete: create(User), send_verification
+    next: verify
+  }
+
+  step verify {
+    goal: confirm email
+    show: check_email_prompt, resend_option
+    collect: verification_code or magic_link
+    timeout: 24h -> reminder, 72h -> expire
+    next: create_team
+  }
+
+  step create_team {
+    goal: set up workspace
+    show: team_form, templates
+    collect: { name: string, template?: template_id }
+    on_complete: create(Team), assign_owner
+    next: invite
+    skip_to: ready when invited_to_existing_team
+  }
+
+  step invite {
+    goal: bring in collaborators
+    show: invite_form, skip_option, benefits
+    collect: { emails: [email], message?: string }
+    on_complete: send_invitations
+    next: ready
+  }
+
+  step ready {
+    goal: start using product
+    show: success, quick_tour_offer, first_task_prompt
+    next: dashboard
+  }
+
+  optimize_for: completion_rate, time_to_first_task
+
+  on_drop_off(signup): retarget(24h) when email_collected
+  on_drop_off(verify): send_reminder(1h), send_reminder(24h)
+}
+
+journey DailyTaskWork {
+  actor: team_member
+  entry: app_open or notification
+
+  steps: review -> select -> work -> complete
+
+  step review {
+    goal: understand priorities
+    show: my_tasks, due_today, overdue, recent_activity
+    next: select when task_clicked
+  }
+
+  step select {
+    goal: choose what to work on
+    show: task_detail, subtasks, comments, attachments
+    next: work when start_clicked
+  }
+
+  step work {
+    goal: make progress
+    show: task_in_focus, timer_option, quick_add_subtask
+    collect: progress_updates, time_logged
+    next: complete when mark_done
+  }
+
+  step complete {
+    goal: finish task
+    show: completion_form, next_suggestion
+    on_complete: update_status, notify_stakeholders, celebrate
+    next: review
+  }
+
+  optimize_for: tasks_completed, time_in_flow
+}
+
+# === DESIGN ===
+
+design {
+  mood: focused + friendly
+
+  personality {
+    voice: "Your calm, capable task companion"
+    tone: encouraging, not pushy
+    empty_states: motivating
+    success: celebratory (subtle)
+  }
+
+  foundation {
+    primary: "#6366F1"  # Indigo - focused, professional
+    palette: derive(mood)
+
+    typography {
+      heading: "Inter"
+      body: "Inter"
+      scale: 1.25
+    }
+
+    density: comfortable
+    radius: medium
+    shadows: subtle
+  }
+
+  motion {
+    level: standard
+    enter: fade_up
+    feedback: scale
+  }
+
+  responsive {
+    strategy: mobile_first
+
+    mobile {
+      navigation: bottom_tabs
+      layout: stack
+    }
+
+    desktop {
+      navigation: sidebar_fixed
+      layout: multi_column
+    }
+  }
+
+  dark_mode {
+    enabled: true
+    strategy: auto_derive
+  }
+}
+```
+
+### 6.2 What Gets Generated
+
+From this ~400 line spec, the solver generates:
+
+```
+Generated Output Structure:
+├── db/
+│   ├── schema.ts                 # Drizzle schema (all entities)
+│   ├── migrations/               # Migration files
+│   └── seed.ts                   # Test data seeder
+├── lib/
+│   ├── auth.ts                   # Auth utilities
+│   ├── permissions.ts            # RBAC logic
+│   ├── audit.ts                  # Audit logging
+│   └── notifications.ts          # Notification dispatch
+├── app/
+│   ├── api/
+│   │   ├── auth/                 # Auth endpoints
+│   │   ├── users/                # User CRUD
+│   │   ├── teams/                # Team CRUD
+│   │   ├── projects/             # Project CRUD
+│   │   └── tasks/                # Task CRUD
+│   ├── routes/
+│   │   ├── _layout.tsx           # Root layout
+│   │   ├── index.tsx             # Landing/redirect
+│   │   ├── login.tsx             # Login page
+│   │   ├── signup.tsx            # Signup flow
+│   │   ├── dashboard.tsx         # Main dashboard
+│   │   ├── teams/
+│   │   │   ├── $teamSlug.tsx
+│   │   │   └── $teamSlug.settings.tsx
+│   │   └── projects/
+│   │       ├── $projectSlug.tsx
+│   │       └── $projectSlug.task.$taskNumber.tsx
+│   └── components/
+│       ├── ui/                   # Design system components
+│       ├── forms/                # Form components
+│       └── features/             # Feature components
+├── styles/
+│   └── tokens.css                # Generated design tokens
+├── tests/
+│   ├── constraints/              # Constraint verification tests
+│   ├── journeys/                 # Journey flow tests
+│   └── e2e/                      # End-to-end tests
+└── docs/
+    ├── provenance.json           # Spec → code mapping
+    └── constraints.md            # Constraint documentation
+
+Total: ~15,000 lines of production code
+From: ~400 lines of Kappa spec
+Expansion: 37.5x
+```
+
+---
+
+## Part VII: Why This Is Novel
+
+### 7.1 Comparison to Existing Approaches
+
+| Approach | Input | Output | Intelligence |
+|----------|-------|--------|--------------|
+| **Traditional Coding** | Implementation | Executable | None |
+| **Code Generation (Copilot)** | Context + partial code | More code | Pattern matching |
+| **Low-Code (Retool)** | Visual config | App | Template filling |
+| **DSLs (Terraform)** | Declarative config | Infrastructure | Provider mapping |
+| **Kappa v1-v2** | Code specification | Expanded code | Boilerplate expansion |
+| **Kappa v3** | Outcomes + Constraints | Optimal implementation | Constraint solving + synthesis |
+
+### 7.2 Key Innovations
+
+1. **Outcome Specification** — You specify what success looks like, not how to achieve it
+2. **Constraint Satisfaction** — System finds implementation meeting ALL constraints
+3. **Design Intent** — Mood and personality derive actual design, not just config
+4. **Journey-Centric** — User flows are first-class, not derived from routes
+5. **Bidirectional Sync** — Edit generated code, spec updates; edit spec, code regenerates
+6. **Provenance Tracking** — Every line traces to constraints, debuggable
+7. **Learning System** — Escape hatches teach new patterns, system evolves
+
+### 7.3 Why It Works
+
+The insight: **There's a finite, solvable design space.**
+
+For any given set of:
+- Business goals
+- Security constraints
+- Performance constraints
+- Accessibility constraints
+- Design intent
+
+There are only so many valid implementations. The space is large but bounded. A constraint solver can explore it.
+
+Traditional programming makes humans explore this space manually. Kappa v3 makes the computer explore it systematically.
+
+---
+
+## Part VIII: Implementation Roadmap
+
+### Phase 1: Core Language
+- Parser and analyzer
+- Constraint compiler
+- Basic generators (schema, API, pages)
+
+### Phase 2: Constraint Solver
+- SAT/SMT integration
+- Conflict detection and resolution
+- Performance optimization
+
+### Phase 3: Design System
+- Mood interpretation model
+- Design token generation
+- Component library integration
+
+### Phase 4: Intelligence
+- Provenance tracking
+- Bidirectional sync
+- Pattern learning
+
+### Phase 5: Ecosystem
+- Community pattern library
+- IDE integration
+- CI/CD integration
+
+---
+
+*Kappa v3: Tell the machine what success looks like. Let it figure out the rest.*