SDS-021: SEA™ Forge Delivery Pipeline Service

Type

Software Design Specification - Platform / Compiler Service

Status

Proposed

Implements

1. System Overview

The SEA™ Forge Delivery Pipeline Service is a multi-stage compilation system that orchestrates semantic validation, structural mapping, generator execution, and CI enforcement.

It behaves like a compiler toolchain, not a code editor.

2. High-Level Architecture

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Specs (ADR/PRD/SDS)
    ↓
Plan Compiler (Spec Kit)
    ↓
Semantic Compiler (DSL + g3)
    ↓
AST
    ↓
Manifest Compiler
    ↓
Generator Schema Compiler
    ↓
Generators (Nx / bespoke)
    ↓
Generated Code
    ↓
Validation + Drift Check

3. Core Components

3.1 Plan Compiler

Attribute Value
Input ADR/PRD/SDS
Output plan.yaml
Handles Waves, cycles, dependencies, branch naming

Responsibility: Transform specifications into actionable delivery plans structured as waves of TDD cycles.

3.2 Semantic Compiler

Attribute Value
Input Specs + Plan
Output SEA™ DSL models, AST
Validates SEA™ DSL policies, CALM constraints

Responsibility: Translate human-authored specifications into machine-readable semantic models.

3.3 Manifest Compiler

Attribute Value
Input AST
Output Manifest(s)
Enforces Architecture style mappings (e.g., Hexagonal)

Responsibility: Map semantic AST to structural manifests that define code organization.

3.4 Generator Schema Compiler

Attribute Value
Input Manifest
Output Nx generator configs, bespoke generator schemas

Responsibility: Transform manifests into generator-specific input formats.

3.5 Generator Runner

Attribute Value
Executes Nx generators, bespoke generators
Writes to Generated directories only
Produces Regeneration hash for drift detection

Responsibility: Execute code generators deterministically.

3.6 Drift Detector

Attribute Value
Action Re-runs generators
Compares Output to committed state
On mismatch Fails build

Responsibility: Prevent unauthorized manual edits to generated code.

4. Data Models

4.1 Plan Schema

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

planVersion: "1.0"
release: "sprint-1"
waves:
  - id: "wave-1"
    name: "Foundation"
    cycles:
      - id: "cycle-1-1"
        name: "Core Domain Models"
        branch: "feat/wave-1/cycle-1-1-core-domain"
        depends: []
        specs:
          - "SDS-002"
      - id: "cycle-1-2"
        name: "Repository Ports"
        branch: "feat/wave-1/cycle-1-2-repo-ports"
        depends: ["cycle-1-1"]
        specs:
          - "SDS-003"

4.2 Override Record Schema

1
2
3
4
5
6
7
8

overrideId: "override-001"
reason: "Stripe SDK requires manual binding"
scope:
  - "libs/billing/adapters/stripe"
expiry: "2025-03-01"
backfillRef: "JIRA-1234"
approver: "tech-lead"
createdAt: "2025-01-15T10:00:00Z"

5. Execution Flow (TDD Cycle)

sequenceDiagram
    participant Dev as Developer
    participant Plan as Plan Compiler
    participant Sem as Semantic Compiler
    participant Man as Manifest Compiler
    participant Gen as Generator Runner
    participant CI as CI/CD Pipeline

    Dev->>Plan: Author specs
    Plan->>Plan: Generate plan.yaml
    Plan->>Sem: Compile to SEA™ DSL
    Sem->>Sem: Validate semantics
    Sem->>Man: Generate AST
    Man->>Man: Map to manifest
    Man->>Gen: Compile generator inputs
    Gen->>Gen: Execute generators
    Gen->>CI: Generated code
    CI->>CI: Run tests
    CI->>CI: Drift check
    CI->>Dev: Pass/Fail

Step-by-Step Flow

  1. Branch created for TDD cycle
  2. DSL/manifest updated by agent or developer
  3. Generators executed deterministically
  4. Tests run on generated code
  5. Findings resolved upstream (DSL/manifest/schema)
  6. Drift check ensures no manual edits
  7. Merge to trunk on all gates passing

6. Security Model

Agent Permissions

Resource Read Write
Specifications (ADR/PRD/SDS) ✅ ❌ (human only)
SEA™ DSL ✅ ✅
Manifests ✅ ✅
Generator Schemas ✅ ✅
Generated Code ✅ ❌

CI Enforcement

7. CI/CD Integration

Mandatory Pipeline Steps

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

stages:
  - stage: semantic-validate
    command: sea semantic validate
    gate: true

  - stage: manifest-validate
    command: sea manifest validate
    gate: true

  - stage: generate
    command: sea generate
    gate: true

  - stage: test
    command: npm test
    gate: true

  - stage: drift-check
    command: sea drift check
    gate: true

CLI Commands

Command Purpose
sea semantic validate Validate SEA™ DSL models
sea manifest validate Validate manifest schemas
sea generate Execute generators
sea drift check Compare generated vs committed
sea plan compile Generate delivery plan from specs

8. Observability & Audit

Audit Events

Event Payload
spec.authored Spec ID, author, timestamp
plan.compiled Plan ID, wave count, cycle count
semantic.validated Model hash, violations
manifest.generated Manifest ID, DSL refs
code.generated Output hash, generator version
drift.detected File paths, expected vs actual hash

9. Failure Modes

Failure Response
Semantic error Block pipeline
Generator error Fail cycle
Drift detected Fail merge
Manual override without record Hard fail

10. Extensibility

11. Summary

SEA™ Forge Delivery Pipeline is a governed compilation system, not an agent coding framework.