Tutorial: Implementing SEA™ Forge Governance

This tutorial provides a step-by-step guide to applying spec-first governance in SEA™ Forge. It walks through creating a governed AI initiative from business understanding to deployment.

1. Quickstart Overview

Before diving into details, here’s the high-level workflow:

1. Define governance structure: Establish roles and SEA™ DSL policies
2. Create specifications: ADR → PRD → SDS pipeline
3. Author SEA™ DSL model: Express business rules as executable policies
4. Validate and generate: just spec-guard → just pipeline
5. Deploy with governance: Policy Gateway filtering, Evidence Service logging
6. Monitor and evolve: Continuous compliance and improvement

2. Step-by-Step Implementation

2.1 Environment Setup

Prerequisites:

1
2
3
4
5
6
7
8
9
10
# Clone repository
git clone https://github.com/GodSpeedAI/SEA™.git
cd SEA™

# Copy environment template
cp .env.example .env

# Verify environment
just doctor
# Expected: All checks passing

Start Services:

1
2
3
4
docker-compose up -d

# Verify all containers healthy
docker-compose ps

2.2 Create ADR (Architecture Decision Record)

Purpose: Document the architectural decision and governance requirements for your AI initiative.

Steps:

1. Generate ADR template:

   1
   just /spec adr
   

2. Fill in required sections:
   • Context: Business problem and why AI is needed
   • Decision: Proposed solution architecture
   • Consequences: Impact, risks, and governance requirements
   • Compliance: Applicable regulations (EU AI Act, HIPAA, etc.)
3. Example ADR structure:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   # ADR-XXX: Customer Service AI Assistant
   
   ## Status
   Proposed
   
   ## Context
   Customer service receives 10,000+ inquiries daily.
   AI assistant can handle routine queries, reducing response time.
   
   ## Decision
   Implement LLM-based assistant with Policy Gateway filtering
   for PII protection and content safety.
   
   ## Governance Requirements
   - Policy Gateway: Enable PII and jailbreak filters
   - Evidence Service: Log all interactions
   - Human escalation: Complex queries require agent review
   
   ## Compliance
   - GDPR: Data minimization, right to explanation
   - EU AI Act: Limited-risk classification (chatbot transparency)
   

4. Validate:

   1
   just spec-guard
   

2.3 Create PRD (Product Requirements Document)

Purpose: Define functional requirements linked to governing ADR.

Steps:

1. Generate PRD template:

   1
   just /spec prd
   

2. Link to ADR: ```yaml — references:
   • type: adr id: ADR-XXX — ```
3. Define acceptance criteria:
   • Functional requirements
   • Non-functional requirements
   • Governance constraints
4. Validate:

   1
   just spec-guard
   

2.4 Create SDS (Service Design Specification)

Purpose: Define service architecture with governance built-in.

Steps:

1. Generate SDS template:

   1
   just /spec sds
   

2. Include governance sections:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   governance:
     policy_gateway:
       enabled: true
       filters:
         - pii_detection
         - jailbreak_prevention
         - content_safety
     evidence_service:
       enabled: true
       retention: 7_years
     invariants:
       - ref: SDS-035
         controls: [1, 2, 5, 8]
   

3. Define API contracts:
   • Input validation rules
   • Output filtering requirements
   • Error handling with governance context
4. Validate:

   1
   just sds-validate docs/specs/<context>/sds/XXX-<name>.md
   

2.5 Author SEA™ DSL Model

Purpose: Express business rules as executable governance policies.

Steps:

1. Review SEA™ DSL references:
   • docs/reference/sea_dsl_language_reference.yml — Grammar and syntax
   • docs/reference/sea_dsl_language_idioms.yml — Patterns and conventions
2. Create policy file:

   // Customer Service Assistant Policies
      
   context CustomerServiceAssistant:
        
     // PII Protection
     policy PIIFiltering:
       it is obligatory that each CustomerQuery
         has pii_scan = completed
         has pii_detected = false OR pii_redacted = true
         before llm_processing
        
     // Response Safety
     policy ContentSafety:
       it is prohibited that any AssistantResponse
         contains harmful_content = true
         OR contains jailbreak_attempt = true
        
     // Human Escalation
     policy ComplexQueryEscalation:
       it is obligatory that each CustomerQuery
         with complexity_score > 0.7
         has human_agent_assigned = true
         within 5_minutes
   

3. Validate SEA™ DSL:

   1
   just sea-validate docs/specs/<context>/domain.sea
   

4. Parse to AST:

   1
   just sea-parse docs/specs/<context>/domain.sea
   

2.6 Generate Code

Purpose: Transform specifications into governed implementation.

Steps:

1. Run full pipeline:

   1
   just pipeline <context>
   

2. Verify determinism:

   1
   2
   # Regenerate should match committed code
   git diff --exit-code
   

3. Review generated code:
   • Check governance hooks are present
   • Verify policy references in code comments
   • Confirm audit trail integration

2.7 Deploy with Governance

Purpose: Ensure runtime governance is active.

Steps:

1. Run full CI:

   1
   2
   just ci
   # Includes: spec-guard, drift detection, tests
   

2. Verify Policy Gateway:
   • Test with sample inputs
   • Confirm filtering is active
   • Review blocked requests
3. Verify Evidence Service:
   • Generate test events
   • Confirm logging
   • Test retrieval
4. Deploy:

   1
   2
   # After CI passes
   git push origin main
   

2.8 Monitor and Evolve

Purpose: Maintain continuous governance.

Daily:

• Review Policy Gateway violations
• Check Evidence Service logs
• Address drift alerts

Weekly:

• Review governance metrics
• Update policies as needed
• Team sync on learnings

Quarterly:

• Comprehensive policy review
• Regulatory alignment check
• AGC governance audit

3. Example Project: Financial Advisor Assistant

Scenario

A financial services firm wants to deploy an AI assistant to help customers with investment queries while maintaining GLBA compliance.

Implementation

3.1 ADR:

1
2
3
4
5
6
7
# ADR-042: Investment Query Assistant

## Governance
- High-risk classification (financial advice)
- GLBA compliance required
- Full audit trail for regulatory review
- Human-in-the-loop for recommendations

3.2 SEA™ DSL Policies:

context InvestmentAdvisor:
  
  policy FinancialAdviceDisclosure:
    it is obligatory that each InvestmentRecommendation
      has disclaimer_shown = true
      has risk_disclosure = acknowledged
      before display_to_customer
  
  policy HumanReviewRequired:
    it is obligatory that each InvestmentRecommendation
      with risk_level = high
      has advisor_review = approved
      before display_to_customer
  
  policy AuditTrailRequired:
    it is obligatory that each CustomerInteraction
      has evidence_logged = true
      has timestamp = captured
      has customer_id = recorded

3.3 Validation:

1
2
3
just sea-validate docs/specs/investment-advisor/policies.sea
just spec-guard
just ci

3.4 Monitoring:

• Policy Gateway: Blocks unauthorized financial advice
• Evidence Service: 7-year retention for GLBA
• Metrics: < 1% human escalation rate

4. Troubleshooting

SEA™ DSL Validation Fails

Problem: just sea-validate returns errors

Solution:

1. Check syntax against sea_dsl_language_reference.yml
2. Verify all referenced entities exist
3. Ensure policy structure follows idioms

Drift Detection Blocks Deployment

Problem: CI fails with drift detection error

Solution:

1. Regenerate code: just pipeline <context>
2. Commit regenerated files
3. Verify: git diff --exit-code

Policy Gateway Not Filtering

Problem: Requests bypass Policy Gateway

Solution:

1. Check SDS governance configuration
2. Verify service deployment includes sidecar
3. Test with known-bad input

5. Next Steps

After completing this tutorial:

1. Apply to real project: Use TDD cycle workflow

   1
   just cycle-start <phase> <cycle> <agent> <slug>
   

2. Expand policies: Add domain-specific governance rules

3. Train team: Share learnings via Enablement curriculum

4. Contribute: Improve shared policy patterns