Physical Boundaries Are Not Architecture📋

MegaCorp.Core/
├── Orders/
│   ├── OrderService.cs
│   ├── OrderValidator.cs
│   ├── OrderPricingEngine.cs
│   └── OrderEventHandler.cs
├── Payments/
│   ├── PaymentProcessor.cs
│   ├── PaymentValidator.cs
│   └── RefundService.cs
├── Inventory/
│   ├── StockChecker.cs
│   ├── ReservationService.cs
│   └── WarehouseAdapter.cs
├── Users/
│   ├── UserService.cs
│   ├── RoleManager.cs
│   └── AuthorizationService.cs
├── Notifications/
│   ├── NotificationSender.cs
│   ├── EmailTemplateEngine.cs
│   └── SmsGateway.cs
└── Common/
    ├── BaseService.cs
    ├── ServiceHelper.cs
    └── Extensions.cs

namespace MegaCorp.Core.Orders;

public class OrderService
{
    // Can freely reference anything in MegaCorp.Core.Payments,
    // MegaCorp.Core.Inventory, MegaCorp.Core.Users, etc.
    // The namespace provides no isolation whatsoever.
    private readonly PaymentProcessor _payments;     // from MegaCorp.Core.Payments
    private readonly StockChecker _inventory;         // from MegaCorp.Core.Inventory
    private readonly NotificationSender _notifier;    // from MegaCorp.Core.Notifications
    private readonly UserService _users;              // from MegaCorp.Core.Users
}

// MegaCorp.Infrastructure/ServiceLocator.cs
// Original author: unknown (git blame shows a developer who left in 2019)
// Last modified: 2024 (someone added the TryGetService method)
// Referenced by: 47 files across 12 projects

using Microsoft.Extensions.DependencyInjection;

namespace MegaCorp.Infrastructure;

/// <summary>
/// Global service locator. USE CONSTRUCTOR INJECTION INSTEAD.
/// (This comment has been here since 2020. Nobody follows it.)
/// </summary>
public static class ServiceLocator
{
    private static IServiceProvider _provider = null!;
    private static readonly object _lock = new();
    private static bool _initialized;

    /// <summary>
    /// Called once in Program.cs after the DI container is built.
    /// </summary>
    public static void Initialize(IServiceProvider provider)
    {
        lock (_lock)
        {
            _provider = provider ?? throw new ArgumentNullException(nameof(provider));
            _initialized = true;
        }
    }

    /// <summary>
    /// Get a required service. Throws if not registered.
    /// </summary>
    public static T GetService<T>() where T : notnull
    {
        EnsureInitialized();
        return _provider.GetRequiredService<T>();
    }

    /// <summary>
    /// Get a service or null if not registered.
    /// Added in 2021 to handle optional dependencies.
    /// </summary>
    public static T? TryGetService<T>() where T : class
    {
        EnsureInitialized();
        return _provider.GetService<T>();
    }

    /// <summary>
    /// Get a service by type. Used when the type isn't known at compile time.
    /// Added in 2022 for the plugin system that was never finished.
    /// </summary>
    public static object GetService(Type serviceType)
    {
        EnsureInitialized();
        return _provider.GetRequiredService(serviceType);
    }

    /// <summary>
    /// Get all implementations of an interface.
    /// Added in 2023 for the notification system refactor.
    /// </summary>
    public static IEnumerable<T> GetServices<T>() where T : notnull
    {
        EnsureInitialized();
        return _provider.GetServices<T>();
    }

    /// <summary>
    /// Create a scope for scoped services.
    /// Added in 2024 when someone realized background jobs
    /// were resolving scoped services from the root provider.
    /// </summary>
    public static IServiceScope CreateScope()
    {
        EnsureInitialized();
        return _provider.CreateScope();
    }

    /// <summary>
    /// Reset for testing. Added after test parallelism broke everything.
    /// </summary>
    internal static void Reset()
    {
        lock (_lock)
        {
            _provider = null!;
            _initialized = false;
        }
    }

    private static void EnsureInitialized()
    {
        if (!_initialized)
            throw new InvalidOperationException(
                "ServiceLocator not initialized. Call Initialize() in Program.cs first.");
    }
}

// MegaCorp.Core/Orders/OrderService.cs
namespace MegaCorp.Core.Orders;

public class OrderService
{
    // No constructor parameters. No visible dependencies.
    // A reader must scan every method body to discover what this class actually needs.

    public async Task<OrderResult> ProcessOrder(CreateOrderCommand command)
    {
        // Step 1: Validate the order
        var validator = ServiceLocator.GetService<IOrderValidator>();
        var validationResult = validator.Validate(command);
        if (!validationResult.IsValid)
            return OrderResult.Failed(validationResult.Errors);

        // Step 2: Check inventory
        var inventory = ServiceLocator.GetService<IInventoryChecker>();
        var stockResult = await inventory.CheckAvailability(
            command.Items.Select(i => new StockQuery(i.Sku, i.Quantity)));
        if (!stockResult.AllAvailable)
            return OrderResult.Failed("Insufficient stock");

        // Step 3: Calculate pricing
        var pricing = ServiceLocator.GetService<IPricingEngine>();
        var pricedOrder = pricing.Calculate(command, stockResult.Reservations);

        // Step 4: Reserve inventory
        var reservation = ServiceLocator.GetService<IInventoryReserver>();
        var reservationId = await reservation.Reserve(stockResult.Reservations);

        try
        {
            // Step 5: Capture payment
            var payment = ServiceLocator.GetService<IPaymentProcessor>();
            var paymentResult = await payment.Capture(new PaymentRequest
            {
                Amount = pricedOrder.Total,
                Currency = pricedOrder.Currency,
                CustomerId = command.CustomerId,
                PaymentMethodId = command.PaymentMethodId
            });

            if (!paymentResult.Success)
            {
                await reservation.Release(reservationId);
                return OrderResult.Failed($"Payment failed: {paymentResult.Error}");
            }

            // Step 6: Create the order record
            var repository = ServiceLocator.GetService<IOrderRepository>();
            var order = Order.Create(command, pricedOrder, paymentResult, reservationId);
            await repository.Save(order);

            // Step 7: Publish domain event
            var eventBus = ServiceLocator.GetService<IEventBus>();
            await eventBus.Publish(new OrderCreatedEvent
            {
                OrderId = order.Id,
                CustomerId = command.CustomerId,
                Total = pricedOrder.Total,
                Items = command.Items.Count
            });

            // Step 8: Send confirmation
            var notifications = ServiceLocator.GetService<INotificationSender>();
            await notifications.Send(new OrderConfirmationNotification
            {
                OrderId = order.Id,
                CustomerEmail = command.CustomerEmail,
                OrderSummary = pricedOrder.Summary
            });

            // Step 9: Audit log
            var audit = ServiceLocator.GetService<IAuditLogger>();
            audit.Log("OrderCreated", new { order.Id, command.CustomerId, pricedOrder.Total });

            return OrderResult.Success(order.Id);
        }
        catch
        {
            await reservation.Release(reservationId);
            throw;
        }
    }
}

// MegaCorp.Core/Orders/OrderServiceV2.cs
namespace MegaCorp.Core.Orders;

public class OrderServiceV2
{
    private readonly IServiceProvider _serviceProvider;
    private readonly ILogger<OrderServiceV2> _logger;

    public OrderServiceV2(IServiceProvider serviceProvider, ILogger<OrderServiceV2> logger)
    {
        _serviceProvider = serviceProvider;
        _logger = logger;
    }

    public async Task<OrderResult> ProcessOrder(CreateOrderCommand command)
    {
        _logger.LogInformation("Processing order for customer {CustomerId}", command.CustomerId);

        // Same pattern, different syntax
        using var scope = _serviceProvider.CreateScope();
        var sp = scope.ServiceProvider;

        var validator = sp.GetRequiredService<IOrderValidator>();
        var validationResult = validator.Validate(command);
        if (!validationResult.IsValid)
            return OrderResult.Failed(validationResult.Errors);

        var inventory = sp.GetRequiredService<IInventoryChecker>();
        var stockResult = await inventory.CheckAvailability(
            command.Items.Select(i => new StockQuery(i.Sku, i.Quantity)));
        if (!stockResult.AllAvailable)
            return OrderResult.Failed("Insufficient stock");

        var pricing = sp.GetRequiredService<IPricingEngine>();
        var pricedOrder = pricing.Calculate(command, stockResult.Reservations);

        var reservation = sp.GetRequiredService<IInventoryReserver>();
        var reservationId = await reservation.Reserve(stockResult.Reservations);

        try
        {
            var payment = sp.GetRequiredService<IPaymentProcessor>();
            var paymentResult = await payment.Capture(new PaymentRequest
            {
                Amount = pricedOrder.Total,
                Currency = pricedOrder.Currency,
                CustomerId = command.CustomerId,
                PaymentMethodId = command.PaymentMethodId
            });

            if (!paymentResult.Success)
            {
                await reservation.Release(reservationId);
                return OrderResult.Failed($"Payment failed: {paymentResult.Error}");
            }

            var repository = sp.GetRequiredService<IOrderRepository>();
            var order = Order.Create(command, pricedOrder, paymentResult, reservationId);
            await repository.Save(order);

            var eventBus = sp.GetRequiredService<IEventBus>();
            await eventBus.Publish(new OrderCreatedEvent
            {
                OrderId = order.Id,
                CustomerId = command.CustomerId,
                Total = pricedOrder.Total,
                Items = command.Items.Count
            });

            var notifications = sp.GetRequiredService<INotificationSender>();
            await notifications.Send(new OrderConfirmationNotification
            {
                OrderId = order.Id,
                CustomerEmail = command.CustomerEmail,
                OrderSummary = pricedOrder.Summary
            });

            var audit = sp.GetRequiredService<IAuditLogger>();
            audit.Log("OrderCreated", new { order.Id, command.CustomerId, pricedOrder.Total });

            return OrderResult.Success(order.Id);
        }
        catch
        {
            await reservation.Release(reservationId);
            throw;
        }
    }
}

// MegaCorp.Web/Program.cs — abridged, but representative
var builder = WebApplication.CreateBuilder(args);

// === Section 1: Core services (MegaCorp.Core) ===
builder.Services.AddScoped<IOrderService, OrderServiceV2>();
// TODO: Switch back to OrderService when pricing bug is fixed (2022-03-15)
builder.Services.AddScoped<IOrderValidator, OrderValidator>();
builder.Services.AddScoped<IPricingEngine, PricingEngineV3>();
// V1 deprecated 2020, V2 deprecated 2022, V3 current
builder.Services.AddScoped<IDiscountCalculator, DiscountCalculator>();
builder.Services.AddScoped<ICouponEngine, CouponEngine>();
builder.Services.AddScoped<IBulkDiscountCalculator, BulkDiscountCalculator>();
builder.Services.AddScoped<IOrderEventHandler, OrderEventHandler>();
// builder.Services.AddScoped<IOrderProcessor, OrderProcessor>(); // disabled 2023-09
builder.Services.AddScoped<IUserService, UserService>();
builder.Services.AddScoped<IRoleManager, RoleManager>();
builder.Services.AddScoped<IAuthorizationService, AuthorizationService>();
builder.Services.AddTransient<IPasswordHasher, BCryptPasswordHasher>();

// === Section 2: Data layer (MegaCorp.Data) ===
builder.Services.AddScoped<IOrderRepository, EfOrderRepository>();
builder.Services.AddScoped<IUserRepository, EfUserRepository>();
builder.Services.AddScoped<IInventoryRepository, EfInventoryRepository>();
builder.Services.AddScoped<IPaymentRepository, EfPaymentRepository>();
builder.Services.AddScoped<IAuditRepository, EfAuditRepository>();
builder.Services.AddScoped<INotificationRepository, EfNotificationRepository>();
builder.Services.AddScoped(typeof(IRepository<>), typeof(EfRepository<>));
builder.Services.AddDbContext<MegaCorpDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

// === Section 3: External services ===
builder.Services.AddScoped<IPaymentProcessor, StripePaymentProcessor>();
// builder.Services.AddScoped<IPaymentProcessor, BraintreePaymentProcessor>();
// Switched from Braintree to Stripe in 2023. Braintree code still in repo.
builder.Services.AddScoped<IInventoryChecker, InventoryServiceClient>();
builder.Services.AddScoped<IInventoryReserver, InventoryServiceClient>();
builder.Services.AddScoped<INotificationSender, MultiChannelNotificationSender>();
builder.Services.AddScoped<IEmailSender, SendGridEmailSender>();
builder.Services.AddScoped<ISmsSender, TwilioSmsSender>();
builder.Services.AddScoped<IPushNotificationSender, FirebasePushSender>();

// === Section 4: Infrastructure ===
builder.Services.AddScoped<IEventBus, RabbitMqEventBus>();
builder.Services.AddScoped<ICacheService, RedisCacheService>();
builder.Services.AddScoped<IAuditLogger, DatabaseAuditLogger>();
builder.Services.AddScoped<ISearchService, ElasticsearchService>();
builder.Services.AddSingleton<IFeatureFlagService, LaunchDarklyFeatureFlagService>();

// === Section 5: Background services ===
builder.Services.AddHostedService<OrderFulfillmentWorker>();
builder.Services.AddHostedService<InventorySyncWorker>();
builder.Services.AddHostedService<NotificationRetryWorker>();
builder.Services.AddHostedService<AuditArchiveWorker>();

// === Section 6: The ServiceLocator initialization ===
var app = builder.Build();
ServiceLocator.Initialize(app.Services);
// ^ This one line makes the entire DI container
// accessible from anywhere in the solution.
// Every ServiceLocator.GetService<T>() call
// bypasses the compile-time dependency graph.

MegaCorp.Web/
├── Program.cs                    ← 500 lines of DI registration
├── appsettings.json             ← 300 lines of config
├── appsettings.Development.json ← 200 lines overriding production
├── appsettings.Staging.json     ← 180 lines (subtly different from Dev)
├── appsettings.Production.json  ← 250 lines (the "real" config)
├── Startup/
│   ├── AuthConfiguration.cs     ← 100 lines configuring JWT + OAuth
│   ├── CorsConfiguration.cs     ← 50 lines configuring CORS
│   ├── SwaggerConfiguration.cs  ← 80 lines configuring OpenAPI
│   ├── HealthCheckConfiguration.cs ← 70 lines configuring health checks
│   ├── CachingConfiguration.cs  ← 60 lines configuring Redis
│   └── LoggingConfiguration.cs  ← 90 lines configuring Serilog
└── Middleware/
    ├── ErrorHandlingMiddleware.cs ← 80 lines
    ├── AuditMiddleware.cs        ← 60 lines
    ├── CorrelationIdMiddleware.cs ← 40 lines
    └── FeatureFlagMiddleware.cs  ← 50 lines

Project dependency analysis:
  MegaCorp.Web → MegaCorp.Core → MegaCorp.Data → MegaCorp.Infrastructure
  MegaCorp.Web → MegaCorp.Infrastructure
  MegaCorp.Worker → MegaCorp.Core → MegaCorp.Data → MegaCorp.Infrastructure
  ... (120 edges total)

Unused code detection:
  WARNING: MegaCorp.Core/Orders/LegacyOrderHandler.cs — no compile-time references
  WARNING: MegaCorp.Core/Orders/OrderProcessor.cs — no compile-time references
  WARNING: MegaCorp.Contracts/V2/OrderDtoV2.cs — no compile-time references
  ... (but are these truly unused, or referenced via ServiceLocator/reflection?)

Cyclomatic complexity:
  HIGH: MegaCorp.Core/Orders/OrderService.cs — ProcessOrder method (42)
  HIGH: MegaCorp.Web/Program.cs — ConfigureServices method (38)
  ...

Code duplication:
  DUPLICATE: OrderService.ProcessOrder and OrderServiceV2.ProcessOrder (87% similar)
  DUPLICATE: OrderValidator.Validate and OrderValidatorNew.Validate (72% similar)
  ...

Feature analysis:
  ??? Which features exist in this codebase?
  ??? Which code implements "Order Processing"?
  ??? Which acceptance criteria are tested?
  ??? Which features have no implementation?
  ??? Which features have no tests?
  ??? What percentage of acceptance criteria are covered?

<!-- MegaCorp.OrderService/MegaCorp.OrderService.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <RootNamespace>MegaCorp.OrderService</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\MegaCorp.Core\MegaCorp.Core.csproj" />
    <ProjectReference Include="..\MegaCorp.Data\MegaCorp.Data.csproj" />
    <ProjectReference Include="..\MegaCorp.Contracts\MegaCorp.Contracts.csproj" />
    <ProjectReference Include="..\MegaCorp.Infrastructure\MegaCorp.Infrastructure.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Logging" Version="8.0.0" />
    <PackageReference Include="Polly" Version="8.2.0" />
  </ItemGroup>
</Project>

Build order (MSBuild):
  1. MegaCorp.Infrastructure       (no project deps)
  2. MegaCorp.Common.Utils         (no project deps)
  3. MegaCorp.Contracts            (→ Infrastructure, Utils)
  4. MegaCorp.Core.Abstractions    (→ Contracts, Utils)
  5. MegaCorp.Data                 (→ Core.Abstractions, Contracts, Utils)
  6. MegaCorp.Core                 (→ Core.Abstractions, Data, Contracts, Utils, EventBus)
  7. MegaCorp.EventBus             (→ Contracts, Utils)
  8. MegaCorp.PaymentGateway       (→ Core, Contracts, EventBus, Utils)
  9. ... (42 more projects)

Developer changes: MegaCorp.Core/Orders/PricingEngine.cs

MSBuild incremental rebuild:
  ✓ MegaCorp.Core                  ← changed
  ✓ MegaCorp.Web                   ← depends on Core
  ✓ MegaCorp.Worker                ← depends on Core
  ✓ MegaCorp.PaymentGateway        ← depends on Core
  ✓ MegaCorp.InventoryService      ← depends on Core
  ✓ MegaCorp.NotificationService   ← depends on Core
  ✓ MegaCorp.BillingService        ← depends on Core (via Payment)
  ✓ MegaCorp.ReportingService      ← depends on Core
  ✓ MegaCorp.AuditService          ← depends on Core
  ✓ MegaCorp.SearchService         ← depends on Core
  ✓ MegaCorp.UserService           ← depends on Core
  = 11 projects rebuilt

What actually changed from a feature perspective:
  ✓ Order Processing pricing logic  ← PricingEngine is part of this feature
  ✗ User Management                 ← not affected
  ✗ Inventory Management            ← not affected (stock checking is separate)
  ✗ Reporting                       ← not affected
  = 1 feature affected

Developer changes: MegaCorp.Core/Orders/PricingEngine.cs

Feature-aware incremental rebuild:
  Feature affected: OrderProcessingFeature
  Projects implementing OrderProcessingFeature:
    ✓ MegaCorp.OrderService          ← : IOrderProcessingSpec
    ✓ MegaCorp.PaymentGateway        ← : IPaymentIntegrationSpec (for OrderProcessing)
  Tests for OrderProcessingFeature:
    ✓ MegaCorp.OrderService.Tests    ← [TestsFor(typeof(OrderProcessingFeature))]
  = 3 projects rebuilt (not 11)

Acceptance criteria affected:
    ✓ AC-1: OrderTotalMustBePositive  ← PricingEngine calculates totals
    ✗ AC-2: InventoryReservedBeforePayment  ← not affected
    ...

// In MegaCorp.OrderService project
// This project does NOT have <ProjectReference> to MegaCorp.PaymentGateway.

using MegaCorp.PaymentGateway; // ← COMPILE ERROR: CS0246
// The type or namespace 'PaymentGateway' does not exist
// in the namespace 'MegaCorp'

// In MegaCorp.Core
internal class PricingEngineHelper  // Only visible within MegaCorp.Core
{
    internal decimal ApplyDiscount(decimal total, decimal discount) { ... }
}

// In MegaCorp.Web — even with <ProjectReference> to MegaCorp.Core
var helper = new PricingEngineHelper(); // ← COMPILE ERROR
// 'PricingEngineHelper' is inaccessible due to its protection level

<!-- This compiles fine. The compiler doesn't enforce architectural layers. -->
<ProjectReference Include="..\MegaCorp.Core\MegaCorp.Core.csproj" />

// MegaCorp.Contracts/IOrderService.cs
namespace MegaCorp.Contracts;

public interface IOrderService
{
    Task<OrderResult> ProcessOrder(CreateOrderCommand command);
    Task<OrderResult> CancelOrder(Guid orderId);
    Task<OrderResult> RefundOrder(Guid orderId, decimal amount);
    Task<IReadOnlyList<Order>> GetOrdersByCustomer(Guid customerId);
    Task<Order?> GetOrderById(Guid orderId);
    Task UpdateOrderStatus(Guid orderId, OrderStatus status);
    Task<decimal> CalculateOrderTotal(IReadOnlyList<OrderItem> items);
    Task ApplyDiscount(Guid orderId, string couponCode);
    Task<bool> ValidateOrder(CreateOrderCommand command);
    Task<ShippingEstimate> EstimateShipping(Guid orderId);
}

// Contract grab-bag: mirrors the implementation
public interface IOrderService
{
    Task<OrderResult> ProcessOrder(CreateOrderCommand command);
    // 9 more methods that describe WHAT THE CODE DOES
}

// Specification: mirrors the requirement
[ForRequirement(typeof(OrderProcessingFeature))]
public interface IOrderProcessingSpec
{
    [ForRequirement(typeof(OrderProcessingFeature),
        nameof(OrderProcessingFeature.OrderTotalMustBePositive))]
    Result ValidateOrderTotal(Order order);

    [ForRequirement(typeof(OrderProcessingFeature),
        nameof(OrderProcessingFeature.InventoryReservedBeforePayment))]
    Result ReserveInventory(Order order);

    [ForRequirement(typeof(OrderProcessingFeature),
        nameof(OrderProcessingFeature.PaymentCapturedAfterReservation))]
    Result CapturePayment(Order order, InventoryReservation reservation);

    // Methods that describe WHAT THE BUSINESS REQUIRES
}

MegaCorp.Common.Utils/
├── Extensions/
│   ├── StringExtensions.cs          ← 47 extension methods
│   ├── DateTimeExtensions.cs        ← 23 extension methods
│   ├── EnumerableExtensions.cs      ← 31 extension methods
│   ├── GuidExtensions.cs            ← 8 extension methods
│   └── TaskExtensions.cs            ← 12 extension methods
├── Helpers/
│   ├── JsonHelper.cs                ← Wraps System.Text.Json
│   ├── CryptoHelper.cs             ← Wraps BCrypt
│   ├── EmailHelper.cs              ← Email validation regex
│   ├── PhoneHelper.cs              ← Phone formatting
│   ├── CurrencyHelper.cs           ← Currency conversion
│   ├── FileHelper.cs               ← File I/O wrappers
│   └── RetryHelper.cs              ← Polly retry wrapper
├── Constants/
│   ├── AppConstants.cs              ← 200+ const strings
│   ├── ErrorCodes.cs                ← 150+ error code strings
│   └── RegexPatterns.cs             ← 40+ regex patterns
├── Attributes/
│   ├── AuditableAttribute.cs
│   ├── CacheableAttribute.cs
│   └── LoggableAttribute.cs
├── Exceptions/
│   ├── BusinessException.cs
│   ├── ValidationException.cs
│   ├── NotFoundException.cs
│   ├── ConflictException.cs
│   └── UnauthorizedException.cs
└── Models/
    ├── PagedResult.cs
    ├── SortDirection.cs
    ├── ApiResponse.cs
    └── ErrorResponse.cs

MegaCorp.Core.Tests/
├── Orders/
│   ├── OrderServiceTests.cs           ← Tests OrderService
│   ├── OrderServiceV2Tests.cs         ← Tests OrderServiceV2 (which is active?)
│   ├── OrderValidatorTests.cs         ← Tests OrderValidator
│   └── OrderPricingEngineTests.cs     ← Tests PricingEngine
├── Payments/
│   ├── PaymentProcessorTests.cs
│   └── RefundServiceTests.cs
└── Users/
    ├── UserServiceTests.cs
    └── AuthorizationServiceTests.cs

// MegaCorp.Core.Tests/Orders/OrderServiceTests.cs
[TestFixture]
public class OrderServiceTests
{
    [Test]
    public async Task ProcessOrder_ValidInput_ReturnsSuccess()
    {
        // This test verifies... what exactly?
        // Which business requirement?
        // Which acceptance criterion?
        // If this test passes, what can we tell the PM?
        // "Your order processing works" — but which PART works?
    }

    [Test]
    public async Task ProcessOrder_NegativeTotal_ReturnsFailed()
    {
        // Is this AC-1? AC-3? Is there even a numbered AC?
        // The PM said "orders with negative totals must be rejected"
        // This test does that. But there's no compile-time link.
        // If the PM removes this AC, this test keeps running.
        // If the PM adds AC-4, no test is created.
        // The tests and requirements drift apart silently.
    }

    [Test]
    public async Task ProcessOrder_InsufficientStock_ReturnsFailed()
    {
        // Is this the same AC as the inventory test in
        // MegaCorp.InventoryService.Tests? Or a different one?
        // Nobody knows. The tests reference classes, not requirements.
    }
}

// MegaCorp.Core.Tests/Orders/OrderServiceTests.cs
[TestFixture]
public class OrderServiceTests
{
    private Mock<IServiceProvider> _mockServiceProvider;
    private Mock<IOrderValidator> _mockValidator;
    private Mock<IInventoryChecker> _mockInventory;
    private Mock<IPricingEngine> _mockPricing;
    private Mock<IInventoryReserver> _mockReserver;
    private Mock<IPaymentProcessor> _mockPayment;
    private Mock<IOrderRepository> _mockRepository;
    private Mock<IEventBus> _mockEventBus;
    private Mock<INotificationSender> _mockNotifier;
    private Mock<IAuditLogger> _mockAudit;

    [SetUp]
    public void Setup()
    {
        _mockValidator = new Mock<IOrderValidator>();
        _mockInventory = new Mock<IInventoryChecker>();
        _mockPricing = new Mock<IPricingEngine>();
        _mockReserver = new Mock<IInventoryReserver>();
        _mockPayment = new Mock<IPaymentProcessor>();
        _mockRepository = new Mock<IOrderRepository>();
        _mockEventBus = new Mock<IEventBus>();
        _mockNotifier = new Mock<INotificationSender>();
        _mockAudit = new Mock<IAuditLogger>();

        // Build a mock IServiceProvider that returns each mock
        _mockServiceProvider = new Mock<IServiceProvider>();
        _mockServiceProvider
            .Setup(sp => sp.GetService(typeof(IOrderValidator)))
            .Returns(_mockValidator.Object);
        _mockServiceProvider
            .Setup(sp => sp.GetService(typeof(IInventoryChecker)))
            .Returns(_mockInventory.Object);
        _mockServiceProvider
            .Setup(sp => sp.GetService(typeof(IPricingEngine)))
            .Returns(_mockPricing.Object);
        _mockServiceProvider
            .Setup(sp => sp.GetService(typeof(IInventoryReserver)))
            .Returns(_mockReserver.Object);
        _mockServiceProvider
            .Setup(sp => sp.GetService(typeof(IPaymentProcessor)))
            .Returns(_mockPayment.Object);
        _mockServiceProvider
            .Setup(sp => sp.GetService(typeof(IOrderRepository)))
            .Returns(_mockRepository.Object);
        _mockServiceProvider
            .Setup(sp => sp.GetService(typeof(IEventBus)))
            .Returns(_mockEventBus.Object);
        _mockServiceProvider
            .Setup(sp => sp.GetService(typeof(INotificationSender)))
            .Returns(_mockNotifier.Object);
        _mockServiceProvider
            .Setup(sp => sp.GetService(typeof(IAuditLogger)))
            .Returns(_mockAudit.Object);

        // Initialize the static ServiceLocator with the mock provider
        ServiceLocator.Reset();
        ServiceLocator.Initialize(_mockServiceProvider.Object);
    }

    [TearDown]
    public void TearDown()
    {
        ServiceLocator.Reset(); // Clean up static state between tests
    }

    [Test]
    public async Task ProcessOrder_ValidInput_ReturnsSuccess()
    {
        // Arrange: configure 9 mocks to return happy-path values
        _mockValidator.Setup(v => v.Validate(It.IsAny<CreateOrderCommand>()))
            .Returns(ValidationResult.Success());
        _mockInventory.Setup(i => i.CheckAvailability(It.IsAny<IEnumerable<StockQuery>>()))
            .ReturnsAsync(StockResult.AllAvailable(/* mock reservations */));
        _mockPricing.Setup(p => p.Calculate(It.IsAny<CreateOrderCommand>(), It.IsAny<object>()))
            .Returns(new PricedOrder { Total = 100m, Currency = "EUR" });
        _mockReserver.Setup(r => r.Reserve(It.IsAny<object>()))
            .ReturnsAsync(Guid.NewGuid());
        _mockPayment.Setup(p => p.Capture(It.IsAny<PaymentRequest>()))
            .ReturnsAsync(PaymentResult.Success("txn_123"));
        _mockRepository.Setup(r => r.Save(It.IsAny<Order>()))
            .Returns(Task.CompletedTask);
        _mockEventBus.Setup(e => e.Publish(It.IsAny<OrderCreatedEvent>()))
            .Returns(Task.CompletedTask);
        _mockNotifier.Setup(n => n.Send(It.IsAny<OrderConfirmationNotification>()))
            .Returns(Task.CompletedTask);

        var service = new OrderService();
        var command = CreateValidOrderCommand();

        // Act
        var result = await service.ProcessOrder(command);

        // Assert
        Assert.That(result.IsSuccess, Is.True);
    }
}

// With Requirements as Code — the test is 15 lines, not 90
[Test]
[Verifies(typeof(OrderProcessingFeature),
    nameof(OrderProcessingFeature.PaymentCapturedAfterReservation))]
public async Task Payment_captured_only_after_reservation()
{
    // Arrange: use the real spec interface, not 9 mocks
    var spec = new OrderService(inventoryRepo, paymentGateway, orderRepo);
    var order = CreateValidOrder();
    var reservation = await spec.ReserveInventory(order);

    // Act
    var result = await spec.CapturePayment(order, reservation, /* payment context */);

    // Assert
    Assert.That(result.IsSuccess, Is.True);
}

// A developer adds a new service
public class ShippingEstimator : IShippingEstimator
{
    private readonly IShippingRateProvider _rateProvider;
    public ShippingEstimator(IShippingRateProvider rateProvider)
        => _rateProvider = rateProvider;

    public async Task<ShippingEstimate> Estimate(Order order) { ... }
}

// They register it in Program.cs
services.AddScoped<IShippingEstimator, ShippingEstimator>();

// But they forget to register the dependency
// services.AddScoped<IShippingRateProvider, FedExRateProvider>();

// The solution compiles. All tests pass (they mock IShippingRateProvider).
// In production, the first request to estimate shipping:
//
// System.InvalidOperationException:
//   Unable to resolve service for type 'IShippingRateProvider'
//   while attempting to activate 'ShippingEstimator'.

// Program.cs
services.AddSingleton<IBackgroundOrderProcessor, BackgroundOrderProcessor>();
services.AddScoped<IOrderRepository, EfOrderRepository>();

// BackgroundOrderProcessor receives IServiceProvider (Pattern B)
// and resolves IOrderRepository from the root scope.
// EfOrderRepository holds an EF DbContext — which is scoped.
// The DbContext is disposed after the first request scope ends.
// The singleton BackgroundOrderProcessor holds a reference to a disposed DbContext.
// Every subsequent order processing call throws ObjectDisposedException.

// MegaCorp.OrderService/OrderService.cs
public class OrderService
{
    public async Task<OrderResult> ProcessOrder(CreateOrderCommand cmd)
    {
        var pricing = ServiceLocator.GetService<IPricingEngine>();
        var pricedOrder = pricing.Calculate(cmd);
        // ...
    }
}

// MegaCorp.Core/PricingEngine.cs
public class PricingEngine : IPricingEngine
{
    public PricedOrder Calculate(CreateOrderCommand cmd)
    {
        // Pricing needs tax rates — resolved at runtime
        var taxService = ServiceLocator.GetService<ITaxRateService>();
        var taxRate = taxService.GetRate(cmd.ShippingAddress.Country);
        // ...
    }
}

// MegaCorp.BillingService/TaxRateService.cs
public class TaxRateService : ITaxRateService
{
    public decimal GetRate(string country)
    {
        // Tax rates come from a database table
        var repo = ServiceLocator.GetService<ITaxRateRepository>();
        return repo.GetCurrentRate(country);
        // ...
    }
}

// MegaCorp.Data/TaxRateRepository.cs
public class TaxRateRepository : ITaxRateRepository
{
    public decimal GetCurrentRate(string country)
    {
        // Queries the tax_rates table
        // ...
    }
}

OrderService → PricingEngine → TaxRateService → TaxRateRepository → Database

MegaCorp.OrderService → (nothing related to tax)
MegaCorp.Core → (nothing related to billing)
MegaCorp.BillingService → (nothing related to orders)

// Using NetArchTest
var result = Types.InAssembly(typeof(OrderService).Assembly)
    .That().ResideInNamespace("MegaCorp.Core.Orders")
    .ShouldNot().HaveDependencyOn("MegaCorp.PaymentGateway")
    .GetResult();

/// AC-7: Loyalty points are credited after successful order.
public abstract AcceptanceCriterionResult LoyaltyPointsCredited(
    Order order, CustomerId customer, int pointsEarned);

// Before:
public interface IPricingEngine
{
    PricedOrder Calculate(CreateOrderCommand command, IReadOnlyList<Reservation> reservations);
}

// After (Team A change):
public interface IPricingEngine
{
    PricedOrder Calculate(CreateOrderCommand command, IReadOnlyList<Reservation> reservations,
        DiscountContext? discountContext = null);  // New optional parameter
}

Auditor: "Which code handles payment processing?"
Team: *spends 3 days compiling a spreadsheet*

The spreadsheet:
| File | Project | Description | Last Modified |
|------|---------|-------------|---------------|
| PaymentProcessor.cs | PaymentGateway | Main payment flow | 2024-03-15 |
| StripePaymentProcessor.cs | PaymentGateway | Stripe integration | 2024-02-28 |
| PaymentValidator.cs | Core | Payment validation | 2023-11-20 |
| OrderPaymentCapture.cs | PaymentGateway | Order payment capture | 2024-01-10 |
| RefundService.cs | Core | Refund processing | 2024-03-01 |
| BillingPaymentHandler.cs | BillingService | Invoice payments | 2023-09-15 |
| PaymentEventHandler.cs | EventBus | Payment events | 2023-12-01 |
| ... | ... | ... | ... |

Auditor: "Are all acceptance criteria tested?"
Team: "We have 87% code coverage."
Auditor: "I didn't ask about code coverage. I asked about acceptance criteria."
Team: *silence*

Auditor: "Which code handles payment processing?"
Team: *runs dotnet build → TraceabilityMatrix.g.cs*

Generated traceability:
  PaymentProcessingFeature (6 ACs)
  ├── AC-1: PaymentAmountMatchesOrderTotal
  │   ├── Spec: IPaymentProcessingSpec.ValidateAmount
  │   ├── Impl: StripePaymentProcessor.ValidateAmount [MegaCorp.PaymentGateway]
  │   └── Test: PaymentTests.Amount_matches_order_total [Verifies]
  ├── AC-2: RefundDoesNotExceedOriginal
  │   ├── Spec: IPaymentProcessingSpec.ValidateRefund
  │   ├── Impl: RefundService.ValidateRefund [MegaCorp.Core]
  │   └── Test: RefundTests.Refund_cannot_exceed_original [Verifies]
  ├── AC-3: PaymentFailureRollsBackOrder
  │   ├── Spec: IPaymentProcessingSpec.HandleFailure
  │   ├── Impl: OrderPaymentCapture.HandleFailure [MegaCorp.PaymentGateway]
  │   └── Test: PaymentTests.Failed_payment_rolls_back_order [Verifies]
  └── ... (3 more ACs, all with Spec → Impl → Test chain)

Coverage: 6/6 ACs implemented, 6/6 ACs tested, 100% requirement coverage.

Auditor: "Show me the test for AC-2."
Team: *Ctrl+Click on RefundTests.Refund_cannot_exceed_original*
Auditor: "Satisfactory."

# Developer searches for "Order" across the solution
grep -r "Order" --include="*.cs" -l | wc -l
# Result: 247 files mention "Order"

grep -r "class.*Order" --include="*.cs" -l
# Result: 34 files define classes with "Order" in the name

MegaCorp.Core/Orders/OrderService.cs              ← Probably relevant
MegaCorp.Core/Orders/OrderServiceV2.cs             ← Probably relevant? Which is active?
MegaCorp.Core/Orders/OrderValidator.cs             ← Relevant
MegaCorp.Core/Orders/OrderPricingEngine.cs         ← Relevant
MegaCorp.Core/Orders/LegacyOrderHandler.cs         ← Dead code? Active?
MegaCorp.Core/Orders/OrderEventHandler.cs          ← Relevant
MegaCorp.Core/Orders/OrderProcessor.cs             ← What's this? Different from OrderService?
MegaCorp.Data/Repositories/OrderRepository.cs      ← Relevant
MegaCorp.Data/ReadModels/OrderReadModel.cs         ← Maybe relevant
MegaCorp.Contracts/IOrderService.cs                ← The grab-bag interface
MegaCorp.Contracts/OrderDto.cs                     ← Data transfer
MegaCorp.Contracts/CreateOrderCommand.cs           ← Input model
MegaCorp.Contracts/OrderResult.cs                  ← Output model
MegaCorp.Contracts/OrderStatus.cs                  ← Enum
MegaCorp.Contracts/V2/OrderDtoV2.cs                ← New version? Old?
MegaCorp.Web/Controllers/OrderController.cs        ← API endpoint
MegaCorp.Web/Controllers/OrderAdminController.cs   ← Admin endpoint
MegaCorp.Worker/Handlers/OrderFulfillmentHandler.cs ← Background processing
MegaCorp.PaymentGateway/OrderPaymentCapture.cs     ← Payment integration
MegaCorp.InventoryService/OrderStockReserver.cs    ← Inventory integration
MegaCorp.NotificationService/OrderNotifier.cs      ← Email integration
MegaCorp.BillingService/OrderInvoiceGenerator.cs   ← Billing integration
MegaCorp.AuditService/Handlers/OrderAuditHandler.cs ← Audit logging
... and 11 more

Given a valid order with positive total
When the user submits the order
Then the order is created and a confirmation email is sent

Given an order with negative total
When the user submits the order
Then the order is rejected with an error message

OrderController
  → OrderService.ProcessOrder()
    → ServiceLocator → IOrderValidator (MegaCorp.Core)
    → ServiceLocator → IInventoryChecker (MegaCorp.InventoryService)
    → ServiceLocator → IPricingEngine (MegaCorp.Core)
    → ServiceLocator → IInventoryReserver (MegaCorp.InventoryService)
    → ServiceLocator → IPaymentProcessor (MegaCorp.PaymentGateway)
    → ServiceLocator → IOrderRepository (MegaCorp.Data)
    → ServiceLocator → IEventBus (MegaCorp.EventBus.RabbitMQ)
    → ServiceLocator → INotificationSender (MegaCorp.NotificationService)
    → ServiceLocator → IAuditLogger (MegaCorp.AuditService)

// MegaCorp.Web/Controllers/OrderController.cs
public class OrderController : ControllerBase
{
    private readonly IServiceProvider _sp;

    public OrderController(IServiceProvider sp) => _sp = sp;

    [HttpPost]
    public async Task<IActionResult> CreateOrder([FromBody] CreateOrderCommand cmd)
    {
        // Which OrderService is resolved here?
        // The developer must check Startup.cs / Program.cs
        // to find the DI registration.
        var service = _sp.GetRequiredService<IOrderService>();
        var result = await service.ProcessOrder(cmd);
        return result.IsSuccess ? Ok(result) : BadRequest(result);
    }
}

// Line 247 of a 500-line Program.cs
services.AddScoped<IOrderService, OrderServiceV2>();
// Wait — why V2? Was V1 deprecated? Is OrderProcessor something else?
// A comment three lines above says:
// TODO: Switch back to OrderService when pricing bug is fixed (2022-03-15)
// It's now 2026. The TODO is 4 years old.

// The developer opens MegaCorp.Requirements and types "Order"
// IDE autocomplete shows: OrderProcessingFeature
// Ctrl+Click → jumps to:

namespace MegaCorp.Requirements.Features;

public abstract record OrderProcessingFeature : Feature<ECommerceEpic>
{
    public override string Title => "Order Processing";
    public override RequirementPriority Priority => RequirementPriority.Critical;
    public override string Owner => "order-team";

    /// AC-1: Orders with negative or zero total are rejected before payment.
    public abstract AcceptanceCriterionResult OrderTotalMustBePositive(
        Order order);

    /// AC-2: Inventory is reserved before payment is captured.
    public abstract AcceptanceCriterionResult InventoryReservedBeforePayment(
        Order order, IReadOnlyList<StockReservation> reservations);

    /// AC-3: Payment is captured only after successful inventory reservation.
    public abstract AcceptanceCriterionResult PaymentCapturedAfterReservation(
        Order order, InventoryReservation reservation, PaymentResult payment);

    /// AC-4: Order confirmation is sent after successful payment.
    public abstract AcceptanceCriterionResult ConfirmationSentAfterPayment(
        Order order, PaymentResult payment, NotificationResult notification);

    /// AC-5: All order operations are recorded in the audit log.
    public abstract AcceptanceCriterionResult AllOperationsAudited(
        Order order, IReadOnlyList<AuditEntry> auditEntries);

    /// AC-6: Failed payments release inventory reservations.
    public abstract AcceptanceCriterionResult FailedPaymentReleasesInventory(
        Order order, PaymentResult failedPayment, InventoryReservation reservation);
}

OrderProcessingFeature                                    ← Definition
├── IOrderProcessingSpec                                  ← Specification interface
│   ├── .ValidateOrderTotal                               ← [ForRequirement(..., AC-1)]
│   ├── .ReserveInventory                                 ← [ForRequirement(..., AC-2)]
│   ├── .CapturePayment                                   ← [ForRequirement(..., AC-3)]
│   ├── .SendConfirmation                                 ← [ForRequirement(..., AC-4)]
│   ├── .RecordAudit                                      ← [ForRequirement(..., AC-5)]
│   └── .ReleaseOnFailure                                 ← [ForRequirement(..., AC-6)]
├── OrderService : IOrderProcessingSpec                   ← MegaCorp.OrderService
├── PaymentCaptureService : IPaymentIntegrationSpec       ← MegaCorp.PaymentGateway
├── InventoryReserver : IInventoryIntegrationSpec          ← MegaCorp.InventoryService
├── OrderNotifier : INotificationIntegrationSpec           ← MegaCorp.NotificationService
└── OrderProcessingTests                                  ← [TestsFor(typeof(OrderProcessingFeature))]
    ├── .Negative_total_is_rejected                        ← [Verifies(..., AC-1)]
    ├── .Inventory_reserved_before_payment                 ← [Verifies(..., AC-2)]
    ├── .Payment_captured_after_reservation                ← [Verifies(..., AC-3)]
    ├── .Confirmation_sent_after_payment                   ← [Verifies(..., AC-4)]
    ├── .All_operations_audited                            ← [Verifies(..., AC-5)]
    └── .Failed_payment_releases_inventory                 ← [Verifies(..., AC-6)]