Architecture: Six Pillars vs Six DSLs📋

┌───────────────────────────────────────────────────────────────────┐
│  1. Product-Requirements-Document-Template.txt                     │
│     Defines: features, user stories, ACs, priorities, constraints  │
│     Format: structured text with placeholders                      │
│     Size: ~300 fields across 15 sections                           │
│     Consumed by: humans and AI agents                              │
└───────────────────────────────────────────────────────────────────┘
         │
         ▼
┌───────────────────────────────────────────────────────────────────┐
│  2. Specification-as-Code.txt                                      │
│     Defines: build stages, task definitions, validation gates      │
│     Format: 5 stages × 13 tasks with failure strategies            │
│     Size: ~200 configuration entries                               │
│     Consumed by: build pipeline, AI agents                         │
└───────────────────────────────────────────────────────────────────┘
         │
         ▼
┌───────────────────────────────────────────────────────────────────┐
│  3. Context-Engineering-as-Code.txt                                │
│     Defines: context sources, assembly strategies, validation      │
│     Format: 3 strategies, 4 context sources, quality gates         │
│     Size: 200+ defined structures                                  │
│     Consumed by: AI orchestration layer                            │
└───────────────────────────────────────────────────────────────────┘
         │
         ├────────────────┬────────────────┐
         ▼                ▼                ▼
┌──────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐
│ 4. Testing   │ │ 5. Documentation│ │ 6. Coding Best Practices    │
│    as Code   │ │    as Code      │ │    as Code                  │
│              │ │                 │ │                             │
│ 15+ testing  │ │ Auto-generation │ │ SOLID, DRY, KISS, YAGNI    │
│ strategies   │ │ Living docs     │ │ Language-specific rules     │
│ Metrics      │ │ Quality metrics │ │ Multi-language support      │
│ CI/CD gates  │ │ Maintenance     │ │ Rust, C#, Python, JS       │
└──────────────┘ └─────────────────┘ └─────────────────────────────┘

Spec-driven journey:
  Text → Parser → Validator → Code Generator → Executable
  ↑ you build all of this ↑   ↑ or you hope AI does it ↑

Typed specification journey:
  C# → Compiler → Executable
  ↑ already exists ↑

┌───────────────────────────────────────────────────────────────────┐
│  M3 Meta-Metamodel (self-describing)                              │
│  MetaConcept · MetaProperty · MetaReference · MetaConstraint      │
│  MetaInherits                                                     │
└──────────┬────────────────────────────────────────────────────────┘
           │ defines
           ▼
┌───────────────────────────────────────────────────────────────────┐
│  M2 DSLs (six domain-specific languages)                          │
│                                                                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                           │
│  │ DDD DSL  │ │ Content  │ │ Admin    │                           │
│  │          │ │ DSL      │ │ DSL      │                           │
│  │ Entities │ │ Parts    │ │ Modules  │                           │
│  │ VOs      │ │ Blocks   │ │ Fields   │                           │
│  │ Aggregates│ │ Streams │ │ Filters  │                           │
│  │ CQRS     │ │          │ │ Actions  │                           │
│  └──────────┘ └──────────┘ └──────────┘                           │
│                                                                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐                       │
│  │ Pages    │ │ Workflow │ │ Requirements │                       │
│  │ DSL      │ │ DSL      │ │ DSL          │                       │
│  │          │ │          │ │              │                       │
│  │ Widgets  │ │ Stages   │ │ Epics        │                       │
│  │ Zones    │ │ Transitions│ │ Features    │                      │
│  │ Layouts  │ │ Guards   │ │ Stories      │                       │
│  │          │ │ Locales  │ │ Tests        │                       │
│  └──────────┘ └──────────┘ └──────────────┘                       │
└──────────┬────────────────────────────────────────────────────────┘
           │ generates
           ▼
┌───────────────────────────────────────────────────────────────────┐
│  Five-Stage Generation Pipeline                                   │
│                                                                   │
│  Stage 0: Metamodel Registration → MetamodelRegistry.g.cs         │
│  Stage 1: DSL Validation + Collection → Compiler diagnostics      │
│  Stage 2: Core Generation → Entities, CQRS, EF Core               │
│  Stage 3: Cross-Cutting → Admin UI, REST/GraphQL, workflows       │
│  Stage 4: Traceability → Requirements matrix, compliance reports  │
└───────────────────────────────────────────────────────────────────┘

// This is impossible — the Requirements project has no reference to Domain
public abstract record OrderFeature : Feature
{
    // OrderService lives in the Domain project — compile error
    public abstract AcceptanceCriterionResult Test(OrderService service);
}

ai-development-specifications/
├── README.md
├── LICENSE
├── Product-Requirements-Document-Template.txt
├── Specification-as-Code.txt
├── Context-Engineering-as-Code.txt
├── Testing-as-Code.txt
├── Documentation-as-Code.txt
└── Coding-Best-Practices-as-Code.txt

MyApp.sln
├── src/
│   ├── MyApp.Requirements/
│   │   ├── Epics/
│   │   │   └── PlatformScalabilityEpic.cs
│   │   ├── Features/
│   │   │   ├── UserRolesFeature.cs
│   │   │   ├── OrderProcessingFeature.cs
│   │   │   └── JwtAuthFeature.cs
│   │   ├── Stories/
│   │   │   ├── AssignRoleStory.cs
│   │   │   └── RevokeRoleStory.cs
│   │   └── Base/
│   │       ├── RequirementMetadata.cs
│   │       ├── AcceptanceCriterionResult.cs
│   │       └── Hierarchy.cs
│   ├── MyApp.SharedKernel/
│   │   ├── ValueTypes/
│   │   │   ├── UserId.cs
│   │   │   ├── RoleId.cs
│   │   │   └── Email.cs
│   │   └── Results/
│   │       └── Result.cs
│   ├── MyApp.Specifications/
│   │   ├── IUserRolesSpec.cs
│   │   ├── IOrderProcessingSpec.cs
│   │   └── IJwtAuthSpec.cs
│   ├── MyApp.Domain/
│   │   ├── AuthorizationService.cs
│   │   ├── OrderService.cs
│   │   └── JwtService.cs
│   └── MyApp.Api/
│       ├── Controllers/
│       ├── Startup.cs
│       └── Program.cs
├── test/
│   └── MyApp.Tests/
│       ├── UserRolesFeatureTests.cs
│       ├── OrderProcessingFeatureTests.cs
│       └── JwtAuthFeatureTests.cs
└── tools/
    └── MyApp.Requirements.Analyzers/
        ├── RequirementCoverageAnalyzer.cs
        ├── SpecImplementationAnalyzer.cs
        ├── TestCoverageAnalyzer.cs
        └── TraceabilityMatrixGenerator.cs

DEFINE_FEATURE(order_processing)
  description: "Order management for e-commerce platform"
  entities:
    - name: "Order"
      type: "AggregateRoot"
      properties:
        - name: "CustomerId"
          type: "string"
          required: true
        - name: "Lines"
          type: "list<OrderLine>"
          required: true
        - name: "Status"
          type: "enum(Draft, Placed, Shipped, Delivered, Cancelled)"
        - name: "ShippingAddress"
          type: "Address"
          required: true
      invariants:
        - "Order must have at least one line"
        - "Total must be positive"
        - "Cannot ship to invalid address"
      commands:
        - "PlaceOrder"
        - "AddLine"
        - "RemoveLine"
        - "CancelOrder"

public class Order
{
    public string CustomerId { get; set; }
    public List<OrderLine> Lines { get; set; } = new();
    public OrderStatus Status { get; set; }
    public Address ShippingAddress { get; set; }

    public void PlaceOrder() { /* AI's interpretation */ }
    public void AddLine(OrderLine line) { /* AI's interpretation */ }
    public void RemoveLine(int lineId) { /* AI's interpretation */ }
    public void CancelOrder() { /* AI's interpretation */ }
}

[AggregateRoot]
public partial record Order
{
    [Required]
    public CustomerId CustomerId { get; init; }

    [Composition(minItems: 1)]
    public IReadOnlyList<OrderLine> Lines { get; init; } = Array.Empty<OrderLine>();

    public OrderStatus Status { get; init; } = OrderStatus.Draft;

    [Required]
    public Address ShippingAddress { get; init; }

    [Invariant]
    private bool HasAtLeastOneLine() => Lines.Count > 0;

    [Invariant]
    private bool TotalIsPositive() => Lines.Sum(l => l.Total) > Money.Zero;

    [Invariant]
    private bool ShippingAddressIsValid() => ShippingAddress.IsValid();
}

// ========================================================================
// Auto-generated by DDD Source Generator — Stage 2
// Source: Order (AggregateRoot)
// DO NOT MODIFY — regenerated on every build
// ========================================================================

// --- Order.Builder.g.cs ---

public partial record Order
{
    public sealed class Builder
    {
        private CustomerId _customerId;
        private IReadOnlyList<OrderLine> _lines = Array.Empty<OrderLine>();
        private OrderStatus _status = OrderStatus.Draft;
        private Address _shippingAddress;
        private bool _customerIdSet;
        private bool _shippingAddressSet;

        public Builder WithCustomerId(CustomerId value)
        {
            _customerId = value;
            _customerIdSet = true;
            return this;
        }

        public Builder WithLines(IReadOnlyList<OrderLine> value)
        {
            _lines = value ?? throw new ArgumentNullException(nameof(value));
            return this;
        }

        public Builder AddLine(OrderLine line)
        {
            var list = new List<OrderLine>(_lines) { line };
            _lines = list.AsReadOnly();
            return this;
        }

        public Builder WithStatus(OrderStatus value)
        {
            _status = value;
            return this;
        }

        public Builder WithShippingAddress(Address value)
        {
            _shippingAddress = value;
            _shippingAddressSet = true;
            return this;
        }

        public Result<Order, ValidationError> Build()
        {
            var errors = new List<ValidationError>();

            if (!_customerIdSet)
                errors.Add(new ValidationError(
                    nameof(CustomerId), "CustomerId is required"));

            if (!_shippingAddressSet)
                errors.Add(new ValidationError(
                    nameof(ShippingAddress), "ShippingAddress is required"));

            if (errors.Count > 0)
                return Result<Order, ValidationError>.Failure(errors);

            var candidate = new Order
            {
                CustomerId = _customerId,
                Lines = _lines,
                Status = _status,
                ShippingAddress = _shippingAddress
            };

            // Run invariants
            if (!candidate.HasAtLeastOneLine())
                errors.Add(new ValidationError(
                    "Invariant", "Order must have at least one line"));

            if (!candidate.TotalIsPositive())
                errors.Add(new ValidationError(
                    "Invariant", "Total must be positive"));

            if (!candidate.ShippingAddressIsValid())
                errors.Add(new ValidationError(
                    "Invariant", "Shipping address must be valid"));

            if (errors.Count > 0)
                return Result<Order, ValidationError>.Failure(errors);

            return Result<Order, ValidationError>.Success(candidate);
        }
    }

    public static Builder CreateBuilder() => new();
}

// --- Order.EfCoreConfiguration.g.cs ---

public sealed class OrderEntityTypeConfiguration
    : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.ToTable("Orders");
        builder.HasKey(e => e.Id);

        builder.Property(e => e.CustomerId)
            .HasConversion(
                v => v.Value,
                v => new CustomerId(v))
            .IsRequired();

        builder.OwnsMany(e => e.Lines, lineBuilder =>
        {
            lineBuilder.ToTable("OrderLines");
            lineBuilder.WithOwner().HasForeignKey("OrderId");
            lineBuilder.Property(l => l.ProductId)
                .HasConversion(v => v.Value, v => new ProductId(v))
                .IsRequired();
            lineBuilder.Property(l => l.Quantity).IsRequired();
            lineBuilder.Property(l => l.UnitPrice)
                .HasConversion(v => v.Amount, v => Money.From(v))
                .IsRequired();
        });

        builder.Property(e => e.Status)
            .HasConversion<string>()
            .IsRequired();

        builder.OwnsOne(e => e.ShippingAddress, addressBuilder =>
        {
            addressBuilder.Property(a => a.Street).IsRequired();
            addressBuilder.Property(a => a.City).IsRequired();
            addressBuilder.Property(a => a.PostalCode).IsRequired();
            addressBuilder.Property(a => a.Country).IsRequired();
        });
    }
}

// --- Order.Commands.g.cs ---

public sealed record PlaceOrderCommand(
    CustomerId CustomerId,
    IReadOnlyList<OrderLineDto> Lines,
    Address ShippingAddress) : ICommand<Result<OrderId, DomainException>>;

public sealed record AddLineCommand(
    OrderId OrderId,
    ProductId ProductId,
    int Quantity,
    Money UnitPrice) : ICommand<Result<Unit, DomainException>>;

public sealed record RemoveLineCommand(
    OrderId OrderId,
    OrderLineId LineId) : ICommand<Result<Unit, DomainException>>;

public sealed record CancelOrderCommand(
    OrderId OrderId,
    string Reason) : ICommand<Result<Unit, DomainException>>;

// --- Order.CommandHandlers.g.cs ---

public sealed class PlaceOrderCommandHandler
    : ICommandHandler<PlaceOrderCommand, Result<OrderId, DomainException>>
{
    private readonly IOrderRepository _repository;
    private readonly IUnitOfWork _unitOfWork;

    public PlaceOrderCommandHandler(
        IOrderRepository repository,
        IUnitOfWork unitOfWork)
    {
        _repository = repository;
        _unitOfWork = unitOfWork;
    }

    public async Task<Result<OrderId, DomainException>> Handle(
        PlaceOrderCommand command,
        CancellationToken ct)
    {
        var buildResult = Order.CreateBuilder()
            .WithCustomerId(command.CustomerId)
            .WithLines(command.Lines.Select(l => l.ToOrderLine()).ToList().AsReadOnly())
            .WithShippingAddress(command.ShippingAddress)
            .WithStatus(OrderStatus.Placed)
            .Build();

        if (!buildResult.IsSuccess)
            return Result<OrderId, DomainException>.Failure(
                new InvalidOrderException(buildResult.Errors));

        var order = buildResult.Value;
        await _repository.Add(order, ct);
        await _unitOfWork.Commit(ct);
        return Result<OrderId, DomainException>.Success(order.Id);
    }
}

// ... (AddLineCommandHandler, RemoveLineCommandHandler, CancelOrderCommandHandler follow the same pattern)

// --- Order.Repository.g.cs ---

public interface IOrderRepository
{
    Task<Order?> FindById(OrderId id, CancellationToken ct);
    Task Add(Order order, CancellationToken ct);
    Task Update(Order order, CancellationToken ct);
}

public sealed class OrderRepository : IOrderRepository
{
    private readonly AppDbContext _context;

    public OrderRepository(AppDbContext context) => _context = context;

    public async Task<Order?> FindById(OrderId id, CancellationToken ct) =>
        await _context.Orders
            .Include(o => o.Lines)
            .FirstOrDefaultAsync(o => o.Id == id, ct);

    public async Task Add(Order order, CancellationToken ct) =>
        await _context.Orders.AddAsync(order, ct);

    public async Task Update(Order order, CancellationToken ct) =>
        _context.Orders.Update(order);
}

// --- Order.DiRegistration.g.cs ---

public static class OrderDiRegistration
{
    public static IServiceCollection AddOrderAggregate(
        this IServiceCollection services)
    {
        services.AddScoped<IOrderRepository, OrderRepository>();
        services.AddScoped<ICommandHandler<PlaceOrderCommand,
            Result<OrderId, DomainException>>, PlaceOrderCommandHandler>();
        services.AddScoped<ICommandHandler<AddLineCommand,
            Result<Unit, DomainException>>, AddLineCommandHandler>();
        services.AddScoped<ICommandHandler<RemoveLineCommand,
            Result<Unit, DomainException>>, RemoveLineCommandHandler>();
        services.AddScoped<ICommandHandler<CancelOrderCommand,
            Result<Unit, DomainException>>, CancelOrderCommandHandler>();
        return services;
    }
}

AUDIT_REQUIREMENTS:
  audit_trail: true
  audit_events:
    - entity_created
    - entity_modified
    - entity_deleted
    - permission_changed
  retention_period: "7 years"
  storage: "append-only log"
  compliance: ["SOX", "HIPAA"]

DEFINE_STRATEGY(audit_testing)
  Category: Compliance
  Principles:
    - "Every auditable action produces exactly one audit event"
    - "Audit events are immutable after creation"
    - "Audit log must survive entity deletion"
  Practices:
    - Verify audit event creation for each auditable operation
    - Verify audit event immutability
    - Verify audit retention across deletion cascades
  Metrics:
    - audit_coverage: percentage of auditable operations with audit events
    - audit_integrity: percentage of audit events that match source operations

namespace Cmf.Audit.Lib;

/// <summary>
/// Marks an entity as auditable. The source generator will produce
/// audit event types, an audit logger, and EF Core configuration
/// for the audit trail.
/// </summary>
[MetaConcept(
    Name = "Auditable",
    Category = MetaConceptCategory.CrossCutting,
    Description = "Marks an entity for audit trail generation")]
[AttributeUsage(AttributeTargets.Class, AllowMultiple = false)]
public sealed class AuditableAttribute : Attribute
{
    /// <summary>
    /// Which operations generate audit events.
    /// Default: all CRUD operations.
    /// </summary>
    public AuditOperations Operations { get; init; } = AuditOperations.All;

    /// <summary>
    /// Retention period for audit records.
    /// </summary>
    public string RetentionPeriod { get; init; } = "7 years";

    /// <summary>
    /// Compliance frameworks requiring this audit trail.
    /// </summary>
    public string[] ComplianceFrameworks { get; init; } = Array.Empty<string>();
}

[Flags]
public enum AuditOperations
{
    None = 0,
    Create = 1,
    Read = 2,
    Update = 4,
    Delete = 8,
    PermissionChange = 16,
    All = Create | Read | Update | Delete | PermissionChange
}

/// <summary>
/// Marks a specific property as requiring field-level audit
/// (captures old value and new value on change).
/// </summary>
[MetaConcept(
    Name = "AuditedField",
    Category = MetaConceptCategory.CrossCutting,
    Description = "Field-level audit tracking")]
[AttributeUsage(AttributeTargets.Property, AllowMultiple = false)]
public sealed class AuditedFieldAttribute : Attribute
{
    public bool CaptureOldValue { get; init; } = true;
    public bool CaptureNewValue { get; init; } = true;
    public bool Sensitive { get; init; } = false;
}

namespace Cmf.Audit.Generators;

[Generator]
public sealed class AuditGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        var auditableTypes = context.SyntaxProvider
            .ForAttributeWithMetadataName(
                "Cmf.Audit.Lib.AuditableAttribute",
                predicate: static (node, _) => node is ClassDeclarationSyntax,
                transform: static (ctx, _) => ExtractAuditMetadata(ctx));

        context.RegisterSourceOutput(
            auditableTypes,
            static (spc, metadata) => GenerateAuditCode(spc, metadata));
    }

    private static void GenerateAuditCode(
        SourceProductionContext context, AuditMetadata metadata)
    {
        // Generates:
        // 1. {Entity}AuditEvent record (immutable, with timestamp, actor, operation)
        // 2. {Entity}AuditLogger (logs to IAuditStore)
        // 3. {Entity}AuditEventConfiguration (EF Core, append-only table)
        // 4. Interceptor that auto-logs on SaveChanges
        // 5. DI registration for audit infrastructure
    }
}

[AggregateRoot]
[Auditable(
    Operations = AuditOperations.All,
    RetentionPeriod = "7 years",
    ComplianceFrameworks = new[] { "SOX", "HIPAA" })]
public partial record Order
{
    [Required]
    public CustomerId CustomerId { get; init; }

    [Composition(minItems: 1)]
    public IReadOnlyList<OrderLine> Lines { get; init; }

    [AuditedField(Sensitive = false)]
    public OrderStatus Status { get; init; }

    [AuditedField(CaptureOldValue = true, CaptureNewValue = true)]
    public Address ShippingAddress { get; init; }
}

// Auto-generated by Stage 0: MetamodelRegistry.g.cs

public static partial class MetamodelRegistry
{
    static MetamodelRegistry()
    {
        // Existing DSL registrations
        Register<AggregateRootAttribute>(MetaConceptCategory.DDD);
        Register<ValueObjectAttribute>(MetaConceptCategory.DDD);
        Register<ContentPartAttribute>(MetaConceptCategory.Content);
        Register<AdminModuleAttribute>(MetaConceptCategory.Admin);
        Register<WorkflowAttribute>(MetaConceptCategory.Workflow);
        Register<FeatureAttribute>(MetaConceptCategory.Requirements);

        // Auto-discovered: new Audit DSL concepts
        Register<AuditableAttribute>(MetaConceptCategory.CrossCutting);
        Register<AuditedFieldAttribute>(MetaConceptCategory.CrossCutting);
    }
}