<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**

- [ggen v3 Projection Families - Detailed Specification](#ggen-v3-projection-families---detailed-specification)
  - [Table of Contents](#table-of-contents)
  - [Overview](#overview)
    - [Key Characteristics](#key-characteristics)
    - [Projection Execution Model](#projection-execution-model)
    - [Template Frontmatter Format](#template-frontmatter-format)
  - [π_core - Module & Crate Scaffolding](#%CF%80_core---module--crate-scaffolding)
    - [Subprojections](#subprojections)
      - [π_core/1: Workspace Root (Cargo.toml)](#%CF%80_core1-workspace-root-cargotoml)
      - [π_core/2: Crate Cargo.toml](#%CF%80_core2-crate-cargotoml)
      - [π_core/3: Module Scaffold (mod.rs)](#%CF%80_core3-module-scaffold-modrs)
      - [π_core/4: lib.rs Generation](#%CF%80_core4-librs-generation)
    - [Validation in π_core](#validation-in-%CF%80_core)
  - [π_domain - Type System & Domain Model](#%CF%80_domain---type-system--domain-model)
    - [Subprojections](#subprojections-1)
      - [π_domain/1: Struct Definitions](#%CF%80_domain1-struct-definitions)
      - [π_domain/2: Enum Definitions](#%CF%80_domain2-enum-definitions)
      - [π_domain/3: Trait Definitions](#%CF%80_domain3-trait-definitions)
      - [π_domain/4: Impl Blocks (Serialization)](#%CF%80_domain4-impl-blocks-serialization)
      - [π_domain/5: Builder Pattern](#%CF%80_domain5-builder-pattern)
      - [π_domain/6: Constraint Validation](#%CF%80_domain6-constraint-validation)
  - [π_cli - Command Parsing & Dispatch](#%CF%80_cli---command-parsing--dispatch)
    - [Subprojections](#subprojections-2)
      - [π_cli/1: Clap Command Structure](#%CF%80_cli1-clap-command-structure)
      - [π_cli/2: Command Dispatch Router](#%CF%80_cli2-command-dispatch-router)
      - [π_cli/3: Help Text Generation](#%CF%80_cli3-help-text-generation)
      - [π_cli/4: Integration Tests](#%CF%80_cli4-integration-tests)
  - [π_marketplace - Guards & Validation](#%CF%80_marketplace---guards--validation)
    - [Subprojections](#subprojections-3)
      - [π_marketplace/1: Guard Implementation](#%CF%80_marketplace1-guard-implementation)
      - [π_marketplace/2: Scoring Rule Implementation](#%CF%80_marketplace2-scoring-rule-implementation)
      - [π_marketplace/3: Validation Receipt Generator](#%CF%80_marketplace3-validation-receipt-generator)
  - [π_ai - LLM Integration](#%CF%80_ai---llm-integration)
    - [Subprojections](#subprojections-4)
      - [π_ai/1: Provider Client Generator](#%CF%80_ai1-provider-client-generator)
      - [π_ai/2: Model Enumeration](#%CF%80_ai2-model-enumeration)
  - [π_tests - Test Generation](#%CF%80_tests---test-generation)
    - [Subprojections](#subprojections-5)
      - [π_tests/1: Unit Test Scaffold](#%CF%80_tests1-unit-test-scaffold)
      - [π_tests/2: Property-Based Tests](#%CF%80_tests2-property-based-tests)
      - [π_tests/3: Integration Test Scaffold](#%CF%80_tests3-integration-test-scaffold)
      - [π_tests/4: E2E/CLI Tests](#%CF%80_tests4-e2ecli-tests)
  - [π_docs - Documentation Generation](#%CF%80_docs---documentation-generation)
    - [Subprojections](#subprojections-6)
      - [π_docs/1: API Reference](#%CF%80_docs1-api-reference)
  - [Module Organization](#module-organization)
    - [{{ crate.name }}](#-cratename-)
  - [Data Flow](#data-flow)
  - [π_deployment - Container & Infrastructure](#%CF%80_deployment---container--infrastructure)
    - [Subprojections](#subprojections-7)
      - [π_deployment/1: Multi-Stage Dockerfile](#%CF%80_deployment1-multi-stage-dockerfile)
      - [π_deployment/2: Kubernetes Deployment](#%CF%80_deployment2-kubernetes-deployment)
      - [π_deployment/3: GitHub Actions Workflows](#%CF%80_deployment3-github-actions-workflows)
  - [π_utils - Utilities & Shared Code](#%CF%80_utils---utilities--shared-code)
  - [π_node - WASM & JavaScript Bindings](#%CF%80_node---wasm--javascript-bindings)
  - [Projection Composition & Execution Order](#projection-composition--execution-order)
    - [Dependency Graph](#dependency-graph)
    - [Execution Strategy](#execution-strategy)
    - [Delta-Aware Regeneration](#delta-aware-regeneration)
  - [Projection Family Statistics](#projection-family-statistics)
  - [Template Language Features](#template-language-features)
    - [Filters](#filters)
    - [Control Flow](#control-flow)
    - [Macros](#macros)
  - [Conclusion](#conclusion)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# ggen v3 Projection Families - Detailed Specification

**Status**: DETAILED SPECIFICATION
**Version**: 3.0.0-alpha
**Scope**: Complete technical specification of all 8-10 projection families (π_*)

---

## Table of Contents

1. [Overview](#overview)
2. [π_core - Module & Crate Scaffolding](#π_core)
3. [π_domain - Type System & Domain Model](#π_domain)
4. [π_cli - Command Parsing & Dispatch](#π_cli)
5. [π_marketplace - Guards & Validation](#π_marketplace)
6. [π_ai - LLM Integration](#π_ai)
7. [π_tests - Test Generation](#π_tests)
8. [π_docs - Documentation Generation](#π_docs)
9. [π_deployment - Container & Infrastructure](#π_deployment)
10. [π_utils - Utilities & Shared Code](#π_utils)
11. [π_node - WASM & JavaScript Bindings](#π_node)
12. [Projection Composition & Execution Order](#composition)

---

## Overview

Projection families (π_*) are **SPARQL-driven template systems** that transform ontology entities into generated code artifacts.

### Key Characteristics

**Each projection family**:
- Has explicit SPARQL queries that extract relevant ontology data
- Uses Tera templates with extracted data substitution
- Generates specific code/config artifacts
- Has accompanying tests to validate output
- Can be executed independently or as part of full pipeline

### Projection Execution Model

```
For each template in family π_X:
  1. Parse frontmatter (YAML/TOML)
     └─ Extract SPARQL query
     └─ Extract metadata (target files, frequency, etc.)

  2. Execute SPARQL against ontology graph
     └─ Result: Vec<HashMap<String, Value>>

  3. For each result row:
     a. Substitute variables into Tera template
     b. Render template
     c. Apply formatting/validation
     d. Write to target file(s)

  4. Validate generated code
     └─ Compile check (cargo check)
     └─ Guard application
     └─ Integration test

  5. Cache results (for delta detection)
```

### Template Frontmatter Format

```yaml
---
# Metadata
title: "Module Scaffold Generator"
version: "1.0.0"

# SPARQL query to extract data
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?moduleName ?parentCrate ?isPublic ?moduleExports
  WHERE {
    ?module a ggen:Module ;
            ggen:name ?moduleName ;
            ggen:parent ?parent ;
            ggen:isPublic ?isPublic ;
            ggen:exports ?exports .
    ?parent ggen:name ?parentCrate .
    BIND(GROUP_CONCAT(STR(?exports)) AS ?moduleExports)
  }
  GROUP BY ?moduleName ?parentCrate ?isPublic

# Output configuration
target: "crates/{{ parentCrate }}/src/{{ moduleName | snake_case }}/mod.rs"
frequency: "OnChange"  # OnChange | OnDemand | Scheduled
scope: "module"        # What this template affects

# Validation
validates_against: ["cargo_check", "clippy"]
requires_guards: ["GuardCodeQuality"]
---

# Tera template content follows
```

---

## π_core - Module & Crate Scaffolding

**Purpose**: Generate Rust crate structure, module organization, and Cargo configuration.

**Scope**:
- Cargo.toml files
- src/lib.rs and src/main.rs
- Module declarations (mod.rs files)
- Workspace configuration

**Input**: ggen:Crate, ggen:Module entities
**Output**: Complete crate structure

### Subprojections

#### π_core/1: Workspace Root (Cargo.toml)

**Template**: `templates/π_core/workspace_cargo_toml.tmpl`

```yaml
---
title: "Workspace Cargo.toml"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?crateName ?version ?license ?dependencies
  WHERE {
    ?crate a ggen:Crate ;
           ggen:name ?crateName ;
           ggen:version ?version ;
           ggen:license ?license ;
           ggen:dependencies ?dep .
    ?dep ggen:name ?depName .
    BIND(CONCAT("{name = \"", ?depName, "\", path = \"crates/", ?depName, "\"}") AS ?dependencies)
  }
  GROUP BY ?crateName ?version ?license

target: "Cargo.toml"
frequency: "OnChange"
scope: "workspace"
---
```

**Example Output**:
```toml
[workspace]
members = [
    "crates/ggen-core",
    "crates/ggen-cli",
    "crates/ggen-domain",
    "crates/ggen-marketplace",
    "crates/ggen-ai",
    "crates/ggen-utils",
]

resolver = "2"

[profile.release]
lto = true
codegen-units = 1
strip = true
```

#### π_core/2: Crate Cargo.toml

**Template**: `templates/π_core/crate_cargo_toml.tmpl`

```yaml
---
title: "Crate Cargo.toml"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?crateName ?version ?description ?license ?dependencies ?devDependencies ?features
  WHERE {
    ?crate a ggen:Crate ;
           ggen:name ?crateName ;
           ggen:version ?version ;
           ggen:description ?description ;
           ggen:license ?license ;
           ggen:dependencies ?dep .
    ?dep ggen:name ?depName ;
         ggen:version ?depVersion .
    BIND(CONCAT("{ name = \"", ?depName, "\", version = \"", ?depVersion, "\" }") AS ?dependencies)
  }
  GROUP BY ?crateName ?version ?description ?license

target: "crates/{{ crateName }}/Cargo.toml"
frequency: "OnChange"
scope: "crate"
---
```

**Example Output**:
```toml
[package]
name = "ggen-core"
version = "3.0.0"
edition = "2021"
description = "Semantic projection engine for ontology-driven code generation"
license = "MIT"
authors = ["ggen team"]

[dependencies]
oxigraph = "0.5"
tera = "1.20"
tokio = { version = "1.47", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tracing = "0.1"
opentelemetry = "0.21"

[dev-dependencies]
criterion = "0.5"
proptest = "1.4"
```

#### π_core/3: Module Scaffold (mod.rs)

**Template**: `templates/π_core/module_scaffold.tmpl`

```yaml
---
title: "Module Scaffold"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?moduleName ?exports ?documentation
  WHERE {
    ?module a ggen:Module ;
            ggen:name ?moduleName ;
            ggen:exports ?export ;
            ggen:documentation ?documentation .
    BIND(CONCAT("self::", STR(?export)) AS ?exports)
  }
  GROUP BY ?moduleName ?documentation

target: "src/{{ moduleName | snake_case }}/mod.rs"
frequency: "OnChange"
scope: "module"
---

//! {{ documentation }}
//!
//! Generated by ggen v3 from ontology

{% for export in exports %}
pub use self::{{ export | pascal_case }};
{% endfor %}

{% if moduleName == "graph" %}
mod cache;
mod sparql;
mod delta;

pub struct Graph { /* ... */ }
pub struct SparqlResult { /* ... */ }
{% endif %}
```

#### π_core/4: lib.rs Generation

**Template**: `templates/π_core/lib_rs.tmpl`

```yaml
---
title: "Library Root (lib.rs)"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?moduleName ?isPublic ?documentation
  WHERE {
    ?crate a ggen:Crate ;
           ggen:name "ggen-core" ;
           ggen:modules ?module .
    ?module ggen:name ?moduleName ;
            ggen:isPublic ?isPublic ;
            ggen:documentation ?documentation .
  }
  ORDER BY ?moduleName

target: "crates/ggen-core/src/lib.rs"
frequency: "OnChange"
scope: "crate"
---

//! ggen-core: Semantic Projection Engine
//!
//! Core RDF/SPARQL operations, template system, and lifecycle management

{% for module in modules %}
{% if module.isPublic %}
pub mod {{ module.name | snake_case }};
pub use self::{{ module.name | snake_case }}::*;
{% else %}
mod {{ module.name | snake_case }};
{% endif %}
{% endfor %}
```

### Validation in π_core

```rust
// Generated by π_core validator
#[test]
fn test_module_structure() {
    // Verify all modules compile
    // Verify all exports are public
    // Verify no circular dependencies
    // Verify Cargo.toml is valid
}
```

---

## π_domain - Type System & Domain Model

**Purpose**: Generate Rust structs, enums, traits, and their implementations.

**Scope**:
- Type definitions (Struct, Enum, Trait, Newtype)
- Field definitions and constraints
- Derive macros (#[derive(...)])
- Trait implementations (From, Into, Default, etc.)
- Serialization/Deserialization impls
- Builder patterns for complex types
- Validation logic

**Input**: ggen:Type, ggen:Struct, ggen:Enum, ggen:Field, ggen:Constraint entities
**Output**: Type definitions with full feature set

### Subprojections

#### π_domain/1: Struct Definitions

**Template**: `templates/π_domain/struct_def.tmpl`

```yaml
---
title: "Struct Definition Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?structName ?fields ?derives ?documentation
  WHERE {
    ?struct a ggen:Struct ;
            ggen:name ?structName ;
            ggen:fields ?field ;
            ggen:derives ?derive ;
            ggen:documentation ?documentation .
    ?field ggen:name ?fieldName ;
           ggen:type ?fieldType ;
           ggen:isRequired ?isRequired ;
           ggen:visibility ?visibility .
  }

target: "src/{{ module | snake_case }}/{{ structName | snake_case }}.rs"
frequency: "OnChange"
scope: "module"
---

/// {{ documentation }}
{% for derive in derives %}
#[derive({{ derive }})]
{% endfor %}
pub struct {{ structName }} {
{% for field in fields %}
    /// {{ field.documentation }}
    {% if not field.isRequired %}
    #[serde(skip_serializing_if = "Option::is_none")]
    {% endif %}
    pub {{ field.name }}: {{ field.type | rust_type }},
{% endfor %}
}
```

**Example Output**:
```rust
/// Represents a ggen project with configuration and ontology
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Project {
    /// Project name (used in paths and identifiers)
    pub name: String,

    /// Absolute path to project root
    pub path: PathBuf,

    /// Primary ontology file
    pub ontology: String,

    /// Optional template directory override
    #[serde(skip_serializing_if = "Option::is_none")]
    pub templates_dir: Option<PathBuf>,
}
```

#### π_domain/2: Enum Definitions

**Template**: `templates/π_domain/enum_def.tmpl`

```yaml
---
title: "Enum Definition Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?enumName ?variants ?derives ?documentation
  WHERE {
    ?enum a ggen:Enum ;
          ggen:name ?enumName ;
          ggen:variants ?variant ;
          ggen:derives ?derive ;
          ggen:documentation ?documentation .
    ?variant ggen:name ?variantName ;
             ggen:documentation ?variantDoc .
  }

target: "src/{{ module | snake_case }}/{{ enumName | snake_case }}.rs"
---

/// {{ documentation }}
{% for derive in derives %}
#[derive({{ derive }})]
{% endfor %}
pub enum {{ enumName }} {
{% for variant in variants %}
    /// {{ variant.documentation }}
    {{ variant.name }},
{% endfor %}
}
```

**Example Output**:
```rust
/// Production readiness level of a marketplace package
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum MaturityLevel {
    /// Experimental, not for production use
    Alpha,

    /// Beta testing phase
    Beta,

    /// Stable and tested
    Stable,

    /// Ready for production deployments
    Production,

    /// Enterprise support level
    Enterprise,
}
```

#### π_domain/3: Trait Definitions

**Template**: `templates/π_domain/trait_def.tmpl`

```yaml
---
title: "Trait Definition Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?traitName ?methods ?bounds ?documentation
  WHERE {
    ?trait a ggen:Trait ;
           ggen:name ?traitName ;
           ggen:methods ?method ;
           ggen:documentation ?documentation .
    ?method ggen:name ?methodName ;
            ggen:parameters ?param ;
            ggen:returnType ?returnType .
  }

target: "src/{{ module | snake_case }}/{{ traitName | snake_case }}.rs"
---

/// {{ documentation }}
{% if bounds %}
pub trait {{ traitName }}<{{ bounds | join(", ") }}> {
{% else %}
pub trait {{ traitName }} {
{% endif %}
{% for method in methods %}
    /// {{ method.documentation }}
    fn {{ method.name }}({% for param in method.parameters %}{{ param.name }}: {{ param.type | rust_type }}{% if not loop.last %}, {% endif %}{% endfor %}) -> {{ method.returnType | rust_type }};
{% endfor %}
}
```

#### π_domain/4: Impl Blocks (Serialization)

**Template**: `templates/π_domain/impl_serialize.tmpl`

```yaml
---
title: "Serialization Impl Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?typeName ?fields ?hasCustomSerialization
  WHERE {
    ?type ggen:name ?typeName ;
          ggen:fields ?field ;
          ggen:serialization ?ser .
    ?field ggen:name ?fieldName ;
           ggen:serde ?serdeConfig .
  }

target: "src/{{ module | snake_case }}/impl_serialize_{{ typeName | snake_case }}.rs"
---

use serde::{Serialize, Serializer};

impl Serialize for {{ typeName }} {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        // Generated serialization logic
        // Respects field-level serde annotations
        // Handles Option<T> correctly
    }
}
```

#### π_domain/5: Builder Pattern

**Template**: `templates/π_domain/builder_impl.tmpl`

```yaml
---
title: "Builder Pattern Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?structName ?fields ?requiredFields ?optionalFields
  WHERE {
    ?struct a ggen:Struct ;
            ggen:name ?structName ;
            ggen:fields ?field .
    ?field ggen:isRequired ?isRequired ;
           ggen:name ?fieldName ;
           ggen:type ?fieldType .
  }

target: "src/{{ module | snake_case }}/{{ structName | snake_case }}_builder.rs"
frequency: "OnChange"
---

pub struct {{ structName }}Builder {
{% for field in optionalFields %}
    {{ field.name }}: Option<{{ field.type | rust_type }}>,
{% endfor %}
{% for field in requiredFields %}
    {{ field.name }}: Option<{{ field.type | rust_type }}>,
{% endfor %}
}

impl Default for {{ structName }}Builder {
    fn default() -> Self {
        Self::new()
    }
}

impl {{ structName }}Builder {
    pub fn new() -> Self {
        Self {
            {% for field in optionalFields %}
            {{ field.name }}: None,
            {% endfor %}
            {% for field in requiredFields %}
            {{ field.name }}: None,
            {% endfor %}
        }
    }

    {% for field in allFields %}
    pub fn {{ field.name }}(mut self, value: {{ field.type | rust_type }}) -> Self {
        self.{{ field.name }} = Some(value);
        self
    }
    {% endfor %}

    pub fn build(self) -> Result<{{ structName }}, BuildError> {
        {% for field in requiredFields %}
        let {{ field.name }} = self.{{ field.name }}.ok_or(BuildError::Missing{{ field.name }})?;
        {% endfor %}

        Ok({{ structName }} {
            {% for field in allFields %}
            {{ field.name }},
            {% endfor %}
        })
    }
}
```

#### π_domain/6: Constraint Validation

**Template**: `templates/π_domain/constraint_validation.tmpl`

```yaml
---
title: "Constraint Validation Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  PREFIX sh: <http://www.w3.org/ns/shacl#>
  SELECT ?typeName ?field ?constraint ?rule ?minValue ?maxValue ?pattern
  WHERE {
    ?type ggen:name ?typeName ;
          ggen:fields ?fieldEntity .
    ?fieldEntity ggen:name ?field ;
                 ggen:constraints ?constraint .
    ?constraint sh:minInclusive ?minValue | sh:maxInclusive ?maxValue | sh:pattern ?pattern .
  }

target: "src/{{ module | snake_case }}/validate_{{ typeName | snake_case }}.rs"
---

impl {{ typeName }} {
    pub fn validate(&self) -> Result<(), ValidationError> {
        {% for field in fields %}
        {% if field.constraint %}
        // Validate {{ field.name }}
        {% if field.constraint.minValue %}
        if self.{{ field.name }} < {{ field.constraint.minValue }} {
            return Err(ValidationError::{{ field.name }}TooSmall);
        }
        {% endif %}
        {% if field.constraint.maxValue %}
        if self.{{ field.name }} > {{ field.constraint.maxValue }} {
            return Err(ValidationError::{{ field.name }}TooLarge);
        }
        {% endif %}
        {% if field.constraint.pattern %}
        if !{{ field.constraint.pattern }}.is_match(&self.{{ field.name }}) {
            return Err(ValidationError::{{ field.name }}InvalidFormat);
        }
        {% endif %}
        {% endif %}
        {% endfor %}

        Ok(())
    }
}
```

---

## π_cli - Command Parsing & Dispatch

**Purpose**: Generate CLI command structure, argument parsing, and command dispatch.

**Scope**:
- Clap command definitions
- Argument/flag parsing
- Subcommand routing
- Help text generation
- Command implementation stubs
- Integration tests

**Input**: ggencli:CliCommand, ggencli:Argument, ggencli:Flag entities
**Output**: Complete CLI system

### Subprojections

#### π_cli/1: Clap Command Structure

**Template**: `templates/π_cli/clap_commands.tmpl`

```yaml
---
title: "Clap Command Generator"
query: |
  PREFIX ggencli: <http://ggen.io/ontology/v3/cli#>
  SELECT ?noun ?verb ?description ?arguments ?flags ?subcommands
  WHERE {
    ?cmd a ggencli:CliCommand ;
         ggencli:noun ?noun ;
         ggencli:verb ?verb ;
         ggencli:description ?description ;
         ggencli:arguments ?arg ;
         ggencli:flags ?flag .
    ?arg ggencli:name ?argName ;
         ggencli:type ?argType ;
         ggencli:isRequired ?argRequired .
    ?flag ggencli:longForm ?flagLong ;
          ggencli:type ?flagType ;
          ggencli:isRequired ?flagRequired .
  }

target: "crates/ggen-cli/src/commands/{{ noun }}_commands.rs"
frequency: "OnChange"
---

use clap::{Command, Arg, ArgMatches};

pub fn {{ noun }}_command() -> Command {
    Command::new("{{ noun }}")
        .about("{{ description }}")
        .subcommand({{ verb }}_command())
        {% for subcommand in subcommands %}
        .subcommand({{ subcommand.verb }}_command())
        {% endfor %}
}

pub fn {{ verb }}_command() -> Command {
    Command::new("{{ verb }}")
        .about("{{ verb | title }} command for {{ noun }}")
        {% for arg in arguments %}
        .arg(Arg::new("{{ arg.name }}")
            .value_name("{{ arg.name | upper }}")
            .help("{{ arg.description }}")
            .required({{ arg.isRequired }})
            .value_parser(clap::value_parser!({{ arg.type | clap_type }})))
        {% endfor %}
        {% for flag in flags %}
        .arg(Arg::new("{{ flag.longForm | strip_dashes }}")
            .long("{{ flag.longForm | strip_dashes }}")
            {% if flag.shortForm %}
            .short('{{ flag.shortForm | strip_dashes | first_char }}')
            {% endif %}
            .help("{{ flag.description }}")
            .required({{ flag.isRequired }})
            {% if flag.type == "Boolean" %}
            .action(clap::ArgAction::SetTrue)
            {% else %}
            .value_parser(clap::value_parser!({{ flag.type | clap_type }}))
            {% endif %})
        {% endfor %}
}

pub async fn handle_{{ verb }}(matches: &ArgMatches) -> Result<()> {
    // Generated command handler stub
    // Implementation filled in by developers
    todo!("Implement {{ noun }} {{ verb }} command")
}
```

**Example Output**:
```rust
pub fn project_command() -> Command {
    Command::new("project")
        .about("Manage ggen projects")
        .subcommand(new_command())
        .subcommand(gen_command())
        .subcommand(watch_command())
}

pub fn gen_command() -> Command {
    Command::new("gen")
        .about("Generate code from ontology")
        .arg(Arg::new("path")
            .value_name("PATH")
            .help("Project root directory")
            .required(false)
            .default_value(".")
            .value_parser(clap::value_parser!(PathBuf)))
        .arg(Arg::new("ontology")
            .long("ontology")
            .short('o')
            .help("Path to primary ontology file")
            .required(false)
            .value_parser(clap::value_parser!(PathBuf)))
        .arg(Arg::new("force")
            .long("force")
            .short('f')
            .help("Force overwrite of existing files")
            .required(false)
            .action(clap::ArgAction::SetTrue))
}
```

#### π_cli/2: Command Dispatch Router

**Template**: `templates/π_cli/command_dispatch.tmpl`

```yaml
---
title: "Command Dispatch Router"
query: |
  PREFIX ggencli: <http://ggen.io/ontology/v3/cli#>
  SELECT ?noun (GROUP_CONCAT(?verb) as ?verbs)
  WHERE {
    ?cmd a ggencli:CliCommand ;
         ggencli:noun ?noun ;
         ggencli:verb ?verb .
  }
  GROUP BY ?noun

target: "crates/ggen-cli/src/dispatcher.rs"
frequency: "OnChange"
---

pub async fn dispatch(matches: &ArgMatches) -> Result<()> {
    match matches.subcommand() {
        {% for noun, verbs in commands %}
        Some(("{{ noun }}", sub_matches)) => {
            match sub_matches.subcommand() {
                {% for verb in verbs %}
                Some(("{{ verb }}", cmd_matches)) => {
                    commands::{{ noun }}::handle_{{ verb }}(cmd_matches).await
                }
                {% endfor %}
                _ => Err("Unknown {{ noun }} subcommand".into()),
            }
        }
        {% endfor %}
        _ => Err("Unknown command".into()),
    }
}
```

#### π_cli/3: Help Text Generation

**Template**: `templates/π_cli/help_text.tmpl`

```yaml
---
title: "Help Text Generator"
query: |
  PREFIX ggencli: <http://ggen.io/ontology/v3/cli#>
  SELECT ?noun ?verb ?description ?examples
  WHERE {
    ?cmd a ggencli:CliCommand ;
         ggencli:noun ?noun ;
         ggencli:verb ?verb ;
         ggencli:description ?description ;
         ggencli:examples ?example .
  }

target: "docs/reference/cli_help_{{ noun }}_{{ verb }}.md"
frequency: "OnChange"
---

# `ggen {{ noun }} {{ verb }}`

{{ description }}

## Usage

\`\`\`bash
{% for example in examples %}
{{ example }}
{% endfor %}
\`\`\`

## Options

{% for flag in flags %}
- `{{ flag.longForm }}` ({{ flag.type }}): {{ flag.description }}
{% endfor %}

## Examples

See [`ggen {{ noun }} {{ verb }}`](#usage) above.
```

#### π_cli/4: Integration Tests

**Template**: `templates/π_cli/cli_integration_test.tmpl`

```yaml
---
title: "CLI Integration Test Generator"
query: |
  PREFIX ggencli: <http://ggen.io/ontology/v3/cli#>
  SELECT ?noun ?verb ?examples
  WHERE {
    ?cmd a ggencli:CliCommand ;
         ggencli:noun ?noun ;
         ggencli:verb ?verb ;
         ggencli:examples ?example .
  }

target: "tests/cli_{{ noun }}_{{ verb }}.rs"
frequency: "OnChange"
---

#[tokio::test]
async fn test_{{ noun }}_{{ verb }}_command() {
    // Test command parsing
    let matches = parse_args(&["{{ noun }}", "{{ verb }}", "."]);
    assert_eq!(matches.subcommand_name(), Some("{{ noun }}"));

    // Test with all flags
    {% for example in examples %}
    let matches = parse_args(&{{ example | into_args_array }});
    assert!(matches.contains_id("{{ noun }}"));
    {% endfor %}
}

#[test]
fn test_{{ noun }}_{{ verb }}_help() {
    let cmd = generate_{{ noun }}_{{ verb }}_command();
    let help_text = cmd.render_help().to_string();
    assert!(help_text.contains("{{ description }}"));
}
```

---

## π_marketplace - Guards & Validation

**Purpose**: Generate marketplace validation guards, scoring logic, and validation receipts.

**Scope**:
- Guard implementations
- Check implementations
- Scoring rule logic
- Validation receipt generation
- Signed proof generation

**Input**: ggen:Guard, ggen:Check, ggen:ScoringRule, ggen:ValidationReceipt entities
**Output**: Complete validation framework

### Subprojections

#### π_marketplace/1: Guard Implementation

**Template**: `templates/π_marketplace/guard_impl.tmpl`

```yaml
---
title: "Guard Implementation Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?guardName ?description ?checks ?scoringRules ?threshold
  WHERE {
    ?guard ggen:name ?guardName ;
           ggen:description ?description ;
           ggen:checks ?check ;
           ggen:scoringRules ?rule ;
           ggen:threshold ?threshold .
    ?check ggen:name ?checkName ;
           ggen:description ?checkDesc ;
           ggen:isAutomatic ?isAuto ;
           ggen:pointsIfPass ?points .
  }

target: "crates/ggen-marketplace/src/guards/{{ guardName | snake_case }}.rs"
frequency: "OnChange"
---

use crate::{Guard, ValidationReceipt, Check, CheckResult, Package};

/// {{ description }}
pub struct {{ guardName }};

impl Guard for {{ guardName }} {
    fn name(&self) -> &str {
        "{{ guardName }}"
    }

    fn check(&self, package: &Package) -> Result<ValidationReceipt, GuardError> {
        let mut receipt = ValidationReceipt::new(
            package.name.clone(),
            package.version.clone(),
        );

        {% for check in checks %}
        // {{ check.description }}
        let {{ check.name | snake_case }}_result = self.check_{{ check.name | snake_case }}(package)?;
        receipt.record_check(
            "{{ check.name }}",
            {{ check.name | snake_case }}_result,
            {{ check.pointsIfPass }}
        );
        {% endfor %}

        // Calculate score
        receipt.finalize({{ threshold }});

        Ok(receipt)
    }
}

impl {{ guardName }} {
    {% for check in checks %}
    fn check_{{ check.name | snake_case }}(&self, package: &Package) -> Result<bool, GuardError> {
        // Generated check logic for: {{ check.description }}
        todo!("Implement check: {{ check.name }}")
    }
    {% endfor %}
}
```

#### π_marketplace/2: Scoring Rule Implementation

**Template**: `templates/π_marketplace/scoring_rule_impl.tmpl`

```yaml
---
title: "Scoring Rule Implementation"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?criterion ?maxPoints ?algorithm
  WHERE {
    ?rule ggen:criterion ?criterion ;
          ggen:maxPoints ?maxPoints ;
          ggen:algorithm ?algorithm .
  }

target: "crates/ggen-marketplace/src/scoring/{{ criterion | snake_case }}.rs"
---

pub struct {{ criterion }}ScoringRule;

impl ScoringRule for {{ criterion }}ScoringRule {
    fn criterion_name(&self) -> &str {
        "{{ criterion }}"
    }

    fn max_points(&self) -> i32 {
        {{ maxPoints }}
    }

    fn calculate(&self, package: &Package) -> i32 {
        // {{ algorithm }}
        match package.{{ criterion | snake_case }} {
            Some(value) => self.score_value(value),
            None => 0,
        }
    }

    fn score_value(&self, value: impl Into<f64>) -> i32 {
        let normalized = value.into() / 100.0;  // Normalize to 0-1
        ((normalized * self.max_points() as f64) as i32).min(self.max_points())
    }
}
```

#### π_marketplace/3: Validation Receipt Generator

**Template**: `templates/π_marketplace/validation_receipt.tmpl`

```yaml
---
title: "Validation Receipt Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?packageName ?version ?checksPerformed
  WHERE {
    ?pkg ggen:name ?packageName ;
         ggen:version ?version .
    # Infer checks from guards
  }

target: "crates/ggen-marketplace/src/receipt.rs"
---

pub struct ValidationReceipt {
    pub package_name: String,
    pub version: String,
    pub timestamp: DateTime<Utc>,
    pub checks: Vec<CheckResult>,
    pub score: i32,
    pub maturity_level: MaturityLevel,
    pub signature: String,  // ML-DSA signed
}

impl ValidationReceipt {
    pub fn new(name: String, version: String) -> Self {
        Self {
            package_name: name,
            version,
            timestamp: Utc::now(),
            checks: Vec::new(),
            score: 0,
            maturity_level: MaturityLevel::Alpha,
            signature: String::new(),
        }
    }

    pub fn record_check(&mut self, name: &str, passed: bool, points: i32) {
        self.checks.push(CheckResult {
            name: name.to_string(),
            passed,
            points: if passed { points } else { 0 },
        });
    }

    pub fn finalize(&mut self, threshold: i32) {
        self.score = self.checks.iter().map(|c| c.points).sum();
        self.maturity_level = MaturityLevel::from_score(self.score);
        self.sign();
    }

    pub fn sign(&mut self) {
        // ML-DSA signing
        let message = serde_json::to_string(self).unwrap();
        self.signature = ggen_core::crypto::ml_dsa_sign(&message);
    }
}
```

---

## π_ai - LLM Integration

**Purpose**: Generate LLM provider clients, streaming support, and AI-powered generators.

**Scope**:
- Provider client implementations
- Model enumeration
- Streaming response handling
- Schema-anchored generation
- Error handling & retries

**Input**: ggenai:LlmProvider, ggenai:LlmModel entities
**Output**: Complete LLM integration layer

### Subprojections

#### π_ai/1: Provider Client Generator

**Template**: `templates/π_ai/provider_client.tmpl`

```yaml
---
title: "LLM Provider Client Generator"
query: |
  PREFIX ggenai: <http://ggen.io/ontology/v3/ai#>
  SELECT ?providerName ?endpoint ?authentication ?models ?streaming
  WHERE {
    ?provider ggenai:name ?providerName ;
              ggenai:endpoint ?endpoint ;
              ggenai:authentication ?authentication ;
              ggenai:streaming ?streaming ;
              ggenai:models ?model .
    ?model ggenai:name ?modelName ;
           ggenai:modelId ?modelId .
  }

target: "crates/ggen-ai/src/providers/{{ providerName | snake_case }}.rs"
frequency: "OnChange"
---

use async_trait::async_trait;
use crate::{LlmProvider, LlmResponse, LlmRequest};

pub struct {{ providerName }}Client {
    endpoint: String,
    api_key: String,
    models: Vec<String>,
}

#[async_trait]
impl LlmProvider for {{ providerName }}Client {
    async fn complete(&self, request: LlmRequest) -> Result<LlmResponse> {
        let client = reqwest::Client::new();

        let payload = serde_json::json!({
            "model": request.model,
            "messages": request.messages,
            "temperature": request.temperature,
            "max_tokens": request.max_tokens,
        });

        let response = client
            .post(&format!("{}/v1/chat/completions", self.endpoint))
            .bearer_auth(&self.api_key)
            .json(&payload)
            .send()
            .await?;

        self.parse_response(response).await
    }

    async fn stream(&self, request: LlmRequest) -> Result<impl Stream<Item = String>> {
        // Generated streaming implementation
        // Handles SSE parsing for streaming providers
    }
}

impl {{ providerName }}Client {
    pub fn new(api_key: String) -> Self {
        Self {
            endpoint: "{{ endpoint }}".to_string(),
            api_key,
            models: vec![
                {% for model in models %}
                "{{ model.modelId }}".to_string(),
                {% endfor %}
            ],
        }
    }
}
```

#### π_ai/2: Model Enumeration

**Template**: `templates/π_ai/model_enum.tmpl`

```yaml
---
title: "Model Enumeration Generator"
query: |
  PREFIX ggenai: <http://ggen.io/ontology/v3/ai#>
  SELECT ?modelName ?modelId ?contextWindow ?provider
  WHERE {
    ?model ggenai:name ?modelName ;
           ggenai:modelId ?modelId ;
           ggenai:contextWindow ?contextWindow ;
           ggenai:provider ?prov .
    ?prov ggenai:name ?provider .
  }

target: "crates/ggen-ai/src/models.rs"
---

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Model {
    {% for model in models %}
    /// {{ model.name }} (context: {{ model.contextWindow }} tokens)
    {{ model.name | pascal_case }},
    {% endfor %}
}

impl Model {
    pub fn model_id(&self) -> &'static str {
        match self {
            {% for model in models %}
            Model::{{ model.name | pascal_case }} => "{{ model.modelId }}",
            {% endfor %}
        }
    }

    pub fn provider(&self) -> Provider {
        match self {
            {% for model in models %}
            Model::{{ model.name | pascal_case }} => Provider::{{ model.provider | pascal_case }},
            {% endfor %}
        }
    }

    pub fn context_window(&self) -> usize {
        match self {
            {% for model in models %}
            Model::{{ model.name | pascal_case }} => {{ model.contextWindow }},
            {% endfor %}
        }
    }
}
```

---

## π_tests - Test Generation

**Purpose**: Generate comprehensive test scaffolds (unit, integration, E2E, BDD).

**Scope**:
- Unit test templates
- Integration test scaffolds
- Property-based tests
- E2E/CLI tests
- BDD/Cucumber step definitions
- Test utilities and fixtures

**Input**: ggen:TestCase, ggen:TestPattern, ggen:Function entities
**Output**: Complete test suite

### Subprojections

#### π_tests/1: Unit Test Scaffold

**Template**: `templates/π_tests/unit_test.tmpl`

```yaml
---
title: "Unit Test Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?functionName ?module ?parameters ?returnType ?documentation
  WHERE {
    ?func a ggen:Function ;
          ggen:name ?functionName ;
          ggen:module ?mod ;
          ggen:parameters ?param ;
          ggen:returnType ?returnType ;
          ggen:documentation ?documentation ;
          ggen:testCoverage ?coverage .
    FILTER(?coverage < 1.0)  # Generate tests for uncovered functions
    ?mod ggen:name ?module .
  }

target: "tests/unit_{{ module }}_{{ functionName | snake_case }}.rs"
frequency: "OnChange"
---

#[cfg(test)]
mod tests {
    use super::*;

    /// Test: {{ documentation }}
    #[test]
    fn test_{{ functionName | snake_case }}_basic() {
        // ARRANGE
        {% for param in parameters %}
        let {{ param.name }} = todo!("Setup {{ param.name }}");
        {% endfor %}

        // ACT
        let result = {{ functionName }}({% for param in parameters %}{{ param.name }}{% if not loop.last %}, {% endif %}{% endfor %});

        // ASSERT
        assert!(result.is_ok(), "Expected success, got error");
    }

    #[test]
    fn test_{{ functionName | snake_case }}_error_cases() {
        // Test error handling
        todo!("Add error case tests")
    }
}
```

#### π_tests/2: Property-Based Tests

**Template**: `templates/π_tests/property_test.tmpl`

```yaml
---
title: "Property Test Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?functionName ?constraints ?returnType
  WHERE {
    ?func a ggen:Function ;
          ggen:name ?functionName ;
          ggen:constraints ?constraint ;
          ggen:returnType ?returnType .
  }

target: "tests/property_{{ functionName | snake_case }}.rs"
frequency: "OnChange"
---

#[cfg(test)]
mod property_tests {
    use proptest::prelude::*;
    use super::*;

    proptest! {
        #[test]
        fn test_{{ functionName | snake_case }}_properties(
            {% for constraint in constraints %}
            {{ constraint.name }} in {{ constraint.strategy }},
            {% endfor %}
        ) {
            let result = {{ functionName }}({{ constraints | map(attribute='name') | join(", ") }});

            prop_assert!(result.is_ok());
            // Assert properties hold
        }
    }
}
```

#### π_tests/3: Integration Test Scaffold

**Template**: `templates/π_tests/integration_test.tmpl`

```yaml
---
title: "Integration Test Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?moduleName ?exports
  WHERE {
    ?module a ggen:Module ;
            ggen:name ?moduleName ;
            ggen:exports ?export .
  }

target: "tests/integration_{{ moduleName }}.rs"
frequency: "OnChange"
---

#[tokio::test]
async fn test_{{ moduleName }}_integration() {
    // Setup
    let project = create_test_project().await;

    // Test module functionality
    {% for export in exports %}
    let result = {{ export }}::new();
    assert!(result.is_ok());
    {% endfor %}

    // Cleanup
    project.cleanup().await;
}
```

#### π_tests/4: E2E/CLI Tests

**Template**: `templates/π_tests/e2e_cli_test.tmpl`

```yaml
---
title: "E2E CLI Test Generator"
query: |
  PREFIX ggencli: <http://ggen.io/ontology/v3/cli#>
  SELECT ?noun ?verb ?examples
  WHERE {
    ?cmd a ggencli:CliCommand ;
         ggencli:noun ?noun ;
         ggencli:verb ?verb ;
         ggencli:examples ?example .
  }

target: "tests/e2e_{{ noun }}_{{ verb }}.rs"
frequency: "OnChange"
---

#[tokio::test]
async fn test_{{ noun }}_{{ verb }}_e2e() {
    // Create test directory with sample project
    let tmpdir = tempfile::tempdir().unwrap();
    let project_path = tmpdir.path();

    // Initialize project
    assert_cmd::Command::cargo_bin("ggen")
        .unwrap()
        .arg("project")
        .arg("new")
        .arg(project_path)
        .assert()
        .success();

    // Run command
    assert_cmd::Command::cargo_bin("ggen")
        .unwrap()
        .arg("{{ noun }}")
        .arg("{{ verb }}")
        .arg(project_path)
        .assert()
        .success();

    // Verify output
    assert!(project_path.join("generated").exists());
}
```

---

## π_docs - Documentation Generation

**Purpose**: Generate API documentation, architecture guides, tutorials, and migration guides.

**Scope**:
- API reference documentation
- Architecture diagrams (auto-generated)
- Tutorials & how-to guides
- Changelog entries
- Migration guides
- CLI reference

**Input**: All ontology entities (types, functions, commands)
**Output**: Complete documentation site

### Subprojections

#### π_docs/1: API Reference

**Template**: `templates/π_docs/api_reference.tmpl`

```yaml
---
title: "API Reference Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?typeName ?documentation ?fields ?methods ?module ?isPublic
  WHERE {
    ?type ggen:name ?typeName ;
          ggen:documentation ?documentation ;
          ggen:isPublic ?isPublic ;
          ggen:module ?mod .
    ?mod ggen:name ?module .
  }
  FILTER(?isPublic)

target: "docs/API_{{ module | title }}.md"
frequency: "OnChange"
---

# {{ module | title }} API Reference

{% for type in types %}
## `{{ type.typeName }}`

{{ type.documentation }}

{% if type.fields %}
### Fields

| Name | Type | Description |
|------|------|-------------|
{% for field in type.fields %}
| `{{ field.name }}` | `{{ field.type }}` | {{ field.documentation }} |
{% endfor %}
{% endif %}

{% if type.methods %}
### Methods

{% for method in type.methods %}
#### `{{ method.name }}`

```rust
{{ method.signature }}
```

{{ method.documentation }}

{% endfor %}
{% endif %}

{% endfor %}
```

#### π_docs/2: Architecture Guide

**Template**: `templates/π_docs/architecture_guide.tmpl`

```yaml
---
title: "Architecture Guide Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?crateName ?modules ?dependencies
  WHERE {
    ?crate a ggen:Crate ;
           ggen:name ?crateName ;
           ggen:modules ?mod ;
           ggen:dependencies ?dep .
  }

target: "docs/ARCHITECTURE.md"
frequency: "OnChange"
---

# ggen Architecture Guide

This document describes the architecture of ggen v3.

## System Overview

```mermaid
graph LR
  CLI["CLI Layer<br/>ggen-cli"]
  Domain["Domain Layer<br/>ggen-domain"]
  Core["Core Engine<br/>ggen-core"]
  AI["AI Module<br/>ggen-ai"]
  MP["Marketplace<br/>ggen-marketplace"]

  CLI -->|dispatch| Domain
  Domain -->|execute| Core
  Domain -->|generate| AI
  Domain -->|validate| MP
  Core -->|RDF/SPARQL| Store[("RDF Store<br/>Oxigraph")]
```

## Module Organization

{% for crate in crates %}
### {{ crate.name }}

{% for module in crate.modules %}
- **{{ module.name }}**: {{ module.documentation }}
{% endfor %}

{% endfor %}

## Data Flow

1. User inputs CLI command
2. CLI dispatches to Domain layer
3. Domain executes business logic
4. Core engine performs RDF/SPARQL operations
5. Results are formatted and output

```
```

---

## π_deployment - Container & Infrastructure

**Purpose**: Generate Docker, Kubernetes, and CI/CD configurations.

**Scope**:
- Dockerfile (multi-stage builds)
- Docker Compose for local development
- Kubernetes manifests (Deployment, Service, ConfigMap)
- GitHub Actions workflows
- Release automation

**Input**: ggen:DeploymentTarget, ggen:Crate, ggen:Phase entities
**Output**: Complete deployment infrastructure

### Subprojections

#### π_deployment/1: Multi-Stage Dockerfile

**Template**: `templates/π_deployment/dockerfile.tmpl`

```yaml
---
title: "Dockerfile Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?crateName ?buildTarget ?runtimeTarget ?version
  WHERE {
    ?crate ggen:name ?crateName ;
           ggen:version ?version .
  }

target: "Dockerfile"
frequency: "OnChange"
---

# Build stage
FROM rust:1.70 as builder

WORKDIR /app

# Copy source
COPY . .

# Build with optimizations
RUN cargo build --release --bin {{ crateName }}

# Runtime stage
FROM debian:bookworm-slim

# Install runtime dependencies
RUN apt-get update && apt-get install -y \
    ca-certificates \
    libssl3 \
    && rm -rf /var/lib/apt/lists/*

# Copy binary from builder
COPY --from=builder /app/target/release/{{ crateName }} /usr/local/bin/

# Security: run as non-root
RUN useradd -m -u 1000 ggen
USER ggen

ENTRYPOINT ["/usr/local/bin/{{ crateName }}"]
```

#### π_deployment/2: Kubernetes Deployment

**Template**: `templates/π_deployment/k8s_deployment.tmpl`

```yaml
---
title: "Kubernetes Deployment Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?crateName ?version
  WHERE {
    ?crate ggen:name ?crateName ;
           ggen:version ?version .
  }

target: "k8s/deployment.yaml"
frequency: "OnChange"
---

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ crateName | kebab_case }}
  labels:
    app: {{ crateName | kebab_case }}
spec:
  replicas: 3
  selector:
    matchLabels:
      app: {{ crateName | kebab_case }}
  template:
    metadata:
      labels:
        app: {{ crateName | kebab_case }}
    spec:
      containers:
      - name: {{ crateName | kebab_case }}
        image: ggen:{{ version }}
        imagePullPolicy: Always
        ports:
        - containerPort: 8080
        env:
        - name: LOG_LEVEL
          value: "info"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: {{ crateName | kebab_case }}
spec:
  type: ClusterIP
  ports:
  - port: 80
    targetPort: 8080
  selector:
    app: {{ crateName | kebab_case }}
```

#### π_deployment/3: GitHub Actions Workflows

**Template**: `templates/π_deployment/github_actions.tmpl`

```yaml
---
title: "GitHub Actions Workflow Generator"
query: |
  PREFIX ggen: <http://ggen.io/ontology/v3/ggen#>
  SELECT ?crateName
  WHERE {
    ?crate ggen:name ?crateName .
  }

target: ".github/workflows/ci_cd.yml"
frequency: "OnChange"
---

name: CI/CD

on:
  push:
    branches: [main, claude/*]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: dtolnay/rust-toolchain@stable
    - uses: Swatinem/rust-cache@v2

    - name: Run tests
      run: cargo test --all

    - name: Run clippy
      run: cargo clippy --all -- -D warnings

    - name: Check formatting
      run: cargo fmt --all -- --check

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: docker/setup-buildx-action@v2

    - name: Build Docker image
      run: docker build -t ggen:${{ github.sha }} .

    - name: Run smoke test
      run: docker run ggen:${{ github.sha }} --version

  security:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: dtolnay/rust-toolchain@stable

    - name: Run cargo-audit
      run: cargo install cargo-audit && cargo audit

    - name: Run MIRI
      run: cargo miri test
```

---

## π_utils - Utilities & Shared Code

**Purpose**: Generate shared utility functions, logging, configuration, and error handling.

**Scope**:
- Error type definitions
- Configuration structures
- Logging setup
- File operations
- Git operations
- Diagnostic tools

**Input**: ggen:Crate, error patterns, configuration schema
**Output**: Shared utility module

---

## π_node - WASM & JavaScript Bindings

**Purpose**: Generate WASM bindings and npm package for JavaScript integration.

**Scope**:
- Wasm binding code (wasm-bindgen)
- TypeScript type definitions
- NPM package configuration
- JavaScript API documentation

**Input**: ggen:Function, public APIs
**Output**: WASM package for npm

---

## Projection Composition & Execution Order

### Dependency Graph

```
π_core (Module scaffolding)
  ↓
  ├─→ π_domain (Type definitions)
  │     ├─→ π_tests (Test scaffolds)
  │     └─→ π_docs (API documentation)
  │
  ├─→ π_cli (Command dispatch)
  │     └─→ π_tests (CLI tests)
  │
  ├─→ π_marketplace (Guards & validation)
  │     └─→ π_tests (Guard tests)
  │
  ├─→ π_ai (LLM client generation)
  │
  ├─→ π_deployment (Docker/K8s)
  │
  └─→ π_utils (Shared code)

π_docs (generated throughout)

π_node (Optional, depends on all core modules)
```

### Execution Strategy

**Phase 1 - Foundation**:
1. π_core - Generate module structure
2. π_domain - Generate types
3. π_utils - Generate shared utilities

**Phase 2 - Integration**:
4. π_cli - Generate command system
5. π_marketplace - Generate validation
6. π_ai - Generate LLM integration

**Phase 3 - Testing & Operations**:
7. π_tests - Generate test suite
8. π_deployment - Generate Docker/K8s
9. π_docs - Generate documentation

**Phase 4 - Optional**:
10. π_node - Generate WASM bindings (if needed)

### Delta-Aware Regeneration

When ontology changes:

```
Diff ggen_v3_core.ttl(v3.0.0) vs ggen_v3_core.ttl(v3.0.1)
  ├─ ggen:Module "graph" modified
  │   ├─ Regenerate: π_core (module scaffold)
  │   ├─ Regenerate: π_domain (affected types)
  │   ├─ Regenerate: π_tests (affected tests)
  │   └─ Regenerate: π_docs (affected docs)
  │
  └─ ggencli:CliCommand "project gen" modified
      ├─ Regenerate: π_cli (command handler)
      └─ Regenerate: π_tests (CLI test)

Skip unchanged:
  - π_deployment (no infrastructure changes)
  - π_ai (no LLM model changes)
  - π_utils (no util changes)

Result: 40% of templates regenerated vs 100% full rebuild
```

---

## Projection Family Statistics

| Family | Templates | Generated LOC | Frequency | Test Coverage |
|--------|-----------|---------------|-----------|--------------|
| π_core | 4 | ~1,500 | OnChange | 100% |
| π_domain | 6 | ~3,000 | OnChange | 95% |
| π_cli | 4 | ~2,000 | OnChange | 100% |
| π_marketplace | 3 | ~1,200 | OnChange | 90% |
| π_ai | 2 | ~1,500 | OnChange | 85% |
| π_tests | 4 | ~2,500 | OnChange | 100% |
| π_docs | 3 | ~800 (markdown) | OnChange | 100% |
| π_deployment | 3 | ~1,000 (YAML) | OnChange | 80% |
| π_utils | 2 | ~800 | OnChange | 90% |
| π_node | 2 | ~500 | OnDemand | 70% |
| **Total** | **33** | **~16,300** | - | **92%** |

---

## Template Language Features

### Filters

```
| upper                # Uppercase
| lower                # Lowercase
| pascal_case          # PascalCase
| snake_case           # snake_case
| kebab_case           # kebab-case
| screaming_snake_case # SCREAMING_SNAKE_CASE
| title_case           # Title Case
| indent(4)            # Indent by 4 spaces
| trim                 # Remove whitespace
| truncate(80)         # Truncate to 80 chars
| join(", ")           # Join array with separator
| first / last         # Get first/last element
| length               # Get length
| sort                 # Sort array
| unique               # Remove duplicates
| reverse              # Reverse array
```

### Control Flow

```
{% if condition %}
  ...
{% elif other_condition %}
  ...
{% else %}
  ...
{% endif %}

{% for item in collection %}
  {{ item.name }}
  {% if loop.first %}First item{% endif %}
  {% if loop.last %}Last item{% endif %}
  {{ loop.index }} / {{ loop.length }}
{% endfor %}

{% for i in range(1, 10) %}
  Item {{ i }}
{% endfor %}

{% set variable = value %}
{% set array = [1, 2, 3] %}
```

### Macros

```
{% macro render_field(field) %}
  pub {{ field.name }}: {{ field.type | rust_type }},
{% endmacro %}

{% for field in fields %}
  {{ render_field(field) }}
{% endfor %}
```

---

## Conclusion

The projection family architecture provides a **modular, composable system** for generating all aspects of ggen v3:

- **Separation of Concerns**: Each family handles one domain
- **Composability**: Families can depend on each other
- **Reusability**: Templates can be shared across projects
- **Extensibility**: Custom families can be added
- **Testability**: Each family has tests
- **Auditability**: SPARQL queries are explicit and queryable

This deep specification enables ggen v3 to generate >95% of its codebase from a single ontology.

---

**Document Version**: 1.0
**Created**: November 17, 2025
**Branch**: `claude/plan-ggen-v3-rewrite-01PyJAjvvvwdVWwD6wickodF`
**Next**: Type System Specification (π_domain deep dive across languages)
