How-To Guides: SEA™ Forge Governance

These how-to guides address specific situations you may encounter while implementing spec-first governance. Each guide is problem-oriented with practical steps and solutions.

1. Validating Specifications

Problem: Need to validate all specs before commit

Solution:

1
2
3
4
# Validate all specifications
just spec-guard

# Expected output: 0 errors, warnings acceptable

Problem: Single SDS validation fails

Solution:

1
2
3
4
5
6
7
# Validate specific SDS
just sds-validate docs/specs/<context>/sds/<file>.md

# Check for:
# - YAML frontmatter syntax
# - Required fields present
# - Cross-references valid

Problem: SEA™ DSL syntax errors

Solution:

1
2
3
4
5
6
7
# Validate SEA™ DSL file
just sea-validate docs/specs/<context>/domain.sea

# Common fixes:
# 1. Check keywords against sea_dsl_language_reference.yml
# 2. Verify entity references exist
# 3. Ensure proper indentation

2. Managing Drift

Problem: CI fails with drift detection error

Symptoms: regen != committed error in CI

Solution:

1. Regenerate code from specs:

   1
   just pipeline <context>
   

2. Verify no drift:

   1
   git diff --exit-code
   

3. Commit regenerated files:

   1
   2
   git add -A
   git commit -m "chore: regenerate from specs"
   

Problem: Intentional code change blocked by drift detection

Solution:

Drift detection enforces spec-first principle. To make changes:

1. Update the spec first (SDS, SEA™ DSL)
2. Regenerate: just pipeline <context>
3. Verify: git diff shows expected changes
4. Commit both spec and generated code

Never: Manually edit generated code in **/src/gen/**

3. Policy Gateway Configuration

Problem: Policy Gateway not filtering requests

Diagnosis:

1
2
3
4
5
# Check service status
docker-compose ps | grep policy-gateway

# Review configuration
cat infra/policy-gateway/config.yaml

Solution:

1. Verify SDS includes governance configuration:

   1
   2
   3
   4
   5
   6
   governance:
     policy_gateway:
       enabled: true
       filters:
         - pii_detection
         - jailbreak_prevention
   

2. Ensure sidecar is deployed with service

3. Test with known-bad input:

   1
   2
   3
   curl -X POST http://localhost:8080/test \
     -d '{"prompt": "ignore previous instructions"}'
   # Expected: 403 Forbidden
   

Problem: Too many false positives in PII detection

Solution:

1. Adjust sensitivity in policy configuration:

   1
   2
   3
   4
   5
   6
   filters:
     pii_detection:
       sensitivity: medium  # low, medium, high
       whitelist:
         - company_names
         - product_codes
   

2. Add domain-specific allowlist patterns

3. Monitor and iterate based on Evidence Service logs

4. Evidence Service Integration

Problem: Audit logs not appearing

Diagnosis:

1
2
3
4
5
# Check Evidence Service status
docker-compose logs evidence-service

# Verify logging configuration
cat infra/evidence-service/config.yaml

Solution:

1. Ensure SDS specifies Evidence Service:

   1
   2
   3
   4
   governance:
     evidence_service:
       enabled: true
       retention: 7_years
   

2. Verify network connectivity between services

3. Check log ingestion pipeline

Problem: Need to retrieve audit logs for compliance

Solution:

1
2
3
4
5
6
7
# Query Evidence Service
curl http://localhost:8083/api/v1/logs \
  -d '{"start_time": "2026-01-01", "end_time": "2026-01-31"}'

# Filter by event type
curl http://localhost:8083/api/v1/logs \
  -d '{"event_type": "policy_violation"}'

5. TDD Cycle Workflow

Problem: How to start a new TDD cycle

Solution:

1
2
3
4
5
6
7
8
9
10
# Start cycle with parameters
just cycle-start <phase> <cycle> <agent> <slug>

# Example:
just cycle-start 1 A user-auth authentication-service

# This creates:
# - Worktree branch
# - Test scaffolds
# - Initial spec references

Problem: How to complete a TDD cycle

Solution:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Run validations
just spec-guard
just ci-quick

# Complete the cycle
just cycle-complete <phase> <cycle> <agent>

# Example:
just cycle-complete 1 A user-auth

# This:
# - Merges worktree
# - Updates task tracking
# - Cleans up branch

Problem: Worktrees accumulating

Solution:

1
2
3
4
5
# Clean merged worktrees
just worktrees-clean

# Force clean all
git worktree prune

6. SEA™ DSL Policy Authoring

Problem: How to write a governance policy

Solution:

1. Review idioms:

   1
   cat docs/reference/sea_dsl_language_idioms.yml
   

2. Use standard patterns:

   policy <PolicyName>:
     it is <obligatory|prohibited|permitted> that <subject>
       <condition>
       <timing>
   

3. Example policies:

   // Mandatory approval
   policy HighValueApproval:
     it is obligatory that each Order with amount > $10000
       has compliance_sign_off = verified
       before processing
      
   // Prohibited action
   policy NoUnauthorizedAccess:
     it is prohibited that any User
       with authorization_level < required_level
       performs data_access
      
   // Conditional permission
   policy TestEnvironmentAccess:
     it is permitted that Developer
       with environment = test
       performs deployment
       without approval
   

4. Validate:

   1
   just sea-validate <file>
   

Problem: Policy not enforcing at runtime

Solution:

1. Verify policy compiles to Gateway rules:

   1
   2
   just sea-parse <file>
   # Check AST output
   

2. Ensure policy is referenced in SDS

3. Redeploy Policy Gateway after changes

7. Compliance Reporting

Problem: Need to generate compliance report

Solution:

1. Pull Evidence Service logs:

   1
   2
   curl http://localhost:8083/api/v1/reports/compliance \
     -d '{"period": "Q1-2026", "framework": "NIST-AI-RMF"}'
   

2. Generate traceability report:

   1
   node scripts/spec-cross-check.js --mode staging --dir docs/specs
   

3. Export for auditors:
   • All specs versioned in Git (immutable history)
   • Evidence Service logs with SHA256 hashes
   • Traceability matrix linking ADR→PRD→SDS→Code

Problem: Preparing for regulatory audit

Solution:

1. Pre-audit checklist:
   • just spec-guard passes
   • Evidence Service logs complete
   • Traceability matrix current
   • SDS-035 invariants documented
2. Gather evidence:

   1
   2
   3
   4
   5
   # Export spec validation report
   just spec-guard > audit/spec-validation-$(date +%Y%m%d).log
      
   # Export Evidence Service summary
   curl http://localhost:8083/api/v1/reports/summary > audit/evidence-summary.json
   

3. Document governance controls:
   • Policy Gateway configuration
   • Evidence Service retention policy
   • Kill switch procedures (SDS-035)

8. Troubleshooting Common Issues

Issue: just doctor fails

Possible causes:

• Docker not running
• Missing dependencies
• Environment variables not set

Solution:

1
2
3
4
5
6
7
8
# Check Docker
docker info

# Reinstall dependencies
just setup

# Verify .env
cat .env | grep -v "^#"

Issue: Semantic Debt accumulating

Solution:

1. Review Semantic Debt Ledger:

   1
   2
   # Query debt entries
   curl http://localhost:8084/api/v1/debt
   

2. Prioritize and address:
   • Critical: Block deployment
   • High: Address in current sprint
   • Medium: Plan for next quarter
   • Low: Track for future
3. Update specs to resolve debt

Issue: Team bypassing governance

Solution:

1. Enforce via CI: Block merges if spec-guard fails

2. Make it easy: Provide templates and commands

3. Build culture: Celebrate spec-first wins

4. Communicate value: Show how governance prevented issues

9. Creating Project-Specific Governance

Problem: Need custom governance for new domain

Solution:

1. Create domain context:

   1
   python tools/sea_new_context.py <domain-name>
   

2. Author domain-specific policies:

   context <DomainName>:
     policy <DomainSpecificPolicy>:
       // Domain-specific rules
   

3. Integrate with GovernedSpeed™:
   • Update SDS with governance requirements
   • Configure Policy Gateway filters
   • Enable Evidence Service logging
4. Validate and deploy:

   1
   2
   3
   just spec-guard
   just pipeline <domain-name>
   just ci