Requirements as Code: Making the Compiler Enforce Your Development Lifecycle📋

// String-based approach: looks safe, is not
[Feature(Id = "FEATURE-456", AcceptanceCriteria = new[] { "Admin can assign roles" })]
public class UserRoleFeature { }  // Empty marker class — dead code

[Implements("FEATURE-456")]       // String. Typo? Compiles fine.
public void AssignRole() { }

[FeatureTest("FEATURE-456", 0)]   // Index 0? What if someone reorders the array?
public void AdminCanAssign() { }

MyApp.sln
├── src/
│   ├── MyApp.Requirements/          ← Features as types, ACs as abstract methods
│   ├── MyApp.SharedKernel/          ← Domain types (User, Role, Permission)
│   ├── MyApp.Specifications/        ← Interfaces the domain must implement
│   ├── MyApp.Domain/                ← Domain implementation (: ISpec)
│   └── MyApp.Api/                   ← Production host (DI, controllers, middleware)
├── test/
│   └── MyApp.Tests/                 ← Type-linked verification
└── tools/
    └── MyApp.Requirements.Analyzers/ ← Source generator (registry, matrix, diagnostics)

Requirements ──┐
               ├──> Specifications ──> Domain ← Api
SharedKernel ──┘         │                │
                         └────────────────┴──> Tests

namespace MyApp.Requirements;

public abstract record RequirementMetadata
{
    public abstract string Title { get; }
    public abstract RequirementPriority Priority { get; }
    public abstract string Owner { get; }
}

public enum RequirementPriority { Critical, High, Medium, Low, Backlog }
public enum BugSeverity { Critical, Major, Minor, Cosmetic }

public abstract record Epic : RequirementMetadata;

public abstract record Feature<TParent> : RequirementMetadata
    where TParent : Epic;

public abstract record Feature : RequirementMetadata;  // root-level, no parent

public abstract record Story<TParent> : RequirementMetadata
    where TParent : RequirementMetadata;

public abstract record Task<TParent> : RequirementMetadata
    where TParent : RequirementMetadata
{
    public abstract int EstimatedHours { get; }
}

public abstract record Bug : RequirementMetadata
{
    public abstract BugSeverity Severity { get; }
}

public readonly record struct AcceptanceCriterionResult
{
    public bool IsSatisfied { get; }
    public string? FailureReason { get; }

    private AcceptanceCriterionResult(bool satisfied, string? reason)
    {
        IsSatisfied = satisfied;
        FailureReason = reason;
    }

    public static AcceptanceCriterionResult Satisfied() => new(true, null);
    public static AcceptanceCriterionResult Failed(string reason) => new(false, reason);
    public static implicit operator bool(AcceptanceCriterionResult r) => r.IsSatisfied;
}

public readonly record struct Email(string Value);
public readonly record struct UserId(Guid Value, string FirstName, string LastName, Email Email);
public readonly record struct RoleId(string Value);
public readonly record struct ResourceId(string Value);
public readonly record struct TokenId(Guid Value);

namespace MyApp.Requirements.Epics;

public abstract record PlatformScalabilityEpic : Epic
{
    public override string Title => "Multi-tenant platform enablement";
    public override RequirementPriority Priority => RequirementPriority.High;
    public override string Owner => "platform-team";
}

namespace MyApp.Requirements.Features;

/// <summary>
/// Feature: User roles and permissions.
/// Each abstract method IS an acceptance criterion.
/// The method signature defines what must be true.
/// The parameters define the domain inputs.
/// The return type enforces that every AC produces a verifiable result.
/// </summary>
public abstract record UserRolesFeature : Feature<PlatformScalabilityEpic>
{
    public override string Title => "User roles and permissions";
    public override RequirementPriority Priority => RequirementPriority.High;
    public override string Owner => "auth-team";

    // AC1: Admin users can assign roles to other users
    public abstract AcceptanceCriterionResult AdminCanAssignRoles(
        UserId actingUser, UserId targetUser, RoleId role);

    // AC2: Viewer users have read-only access
    public abstract AcceptanceCriterionResult ViewerHasReadOnlyAccess(
        UserId viewer, ResourceId resource);

    // AC3: Role changes take effect immediately (no restart required)
    public abstract AcceptanceCriterionResult RoleChangeTakesEffectImmediately(
        UserId user, RoleId previousRole, RoleId newRole);
}

namespace MyApp.Requirements.Stories;

public abstract record JwtRefreshStory : Story<UserRolesFeature>
{
    public override string Title => "Implement JWT refresh token flow";
    public override RequirementPriority Priority => RequirementPriority.Medium;
    public override string Owner => "alice@company.com";

    public abstract AcceptanceCriterionResult TokensExpireAfterOneHour(
        TokenId token, DateTimeOffset issuedAt, DateTimeOffset checkedAt);

    public abstract AcceptanceCriterionResult RefreshExtendsBySevenDays(
        TokenId token, DateTimeOffset refreshedAt);
}

namespace MyApp.Requirements.Bugs;

public abstract record OrderNegativeTotalBug : Bug
{
    public override string Title => "Orders crash when total is negative";
    public override RequirementPriority Priority => RequirementPriority.Critical;
    public override string Owner => "qa-team";
    public override BugSeverity Severity => BugSeverity.Critical;

    public abstract AcceptanceCriterionResult NegativeTotalIsRejected(
        decimal totalAmount);
}

// Generated by Requirements source generator

/// <summary>
/// Links any type, interface, or method to a requirement.
/// Ctrl+Click on typeof(Feature) in IDE jumps to the requirement definition.
/// "Find All References" on Feature shows specs, implementations, and tests.
/// </summary>
[AttributeUsage(
    AttributeTargets.Class | AttributeTargets.Interface | AttributeTargets.Method,
    AllowMultiple = true)]
public sealed class ForRequirementAttribute : Attribute
{
    public Type RequirementType { get; }
    public string? AcceptanceCriterion { get; }

    public ForRequirementAttribute(Type requirementType, string? acceptanceCriterion = null)
    {
        RequirementType = requirementType;
        AcceptanceCriterion = acceptanceCriterion;
    }
}

/// <summary>
/// Links a test method to a specific acceptance criterion.
/// The AC is identified by nameof(Feature.ACMethod) -- compiler-checked.
/// </summary>
[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
public sealed class VerifiesAttribute : Attribute
{
    public Type RequirementType { get; }
    public string AcceptanceCriterionName { get; }

    public VerifiesAttribute(Type requirementType, string acceptanceCriterionName)
    {
        RequirementType = requirementType;
        AcceptanceCriterionName = acceptanceCriterionName;
    }
}

/// <summary>
/// Links a test class to a requirement type.
/// </summary>
[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
public sealed class TestsForAttribute : Attribute
{
    public Type RequirementType { get; }
    public TestsForAttribute(Type requirementType) => RequirementType = requirementType;
}

// Generated: RequirementRegistry.g.cs
public static class RequirementRegistry
{
    public static IReadOnlyDictionary<Type, RequirementInfo> All { get; } =
        new Dictionary<Type, RequirementInfo>
        {
            [typeof(PlatformScalabilityEpic)] = new(
                Type: typeof(PlatformScalabilityEpic),
                Kind: RequirementKind.Epic,
                Title: "Multi-tenant platform enablement",
                Parent: null,
                AcceptanceCriteria: Array.Empty<string>()),

            [typeof(UserRolesFeature)] = new(
                Type: typeof(UserRolesFeature),
                Kind: RequirementKind.Feature,
                Title: "User roles and permissions",
                Parent: typeof(PlatformScalabilityEpic),
                AcceptanceCriteria: new[]
                {
                    nameof(UserRolesFeature.AdminCanAssignRoles),
                    nameof(UserRolesFeature.ViewerHasReadOnlyAccess),
                    nameof(UserRolesFeature.RoleChangeTakesEffectImmediately)
                }),
        };
}

public record RequirementInfo(
    Type Type, RequirementKind Kind, string Title,
    Type? Parent, string[] AcceptanceCriteria);

public enum RequirementKind { Epic, Feature, Story, Task, Bug }

namespace MyApp.SharedKernel;

// Value types from Requirements are reused
using MyApp.Requirements;

public record User(UserId Id, string Name, IReadOnlySet<Role> Roles);
public record Role(RoleId Id, string Name, IReadOnlySet<Permission> Permissions);
public record Resource(ResourceId Id, string Type);
public record Permission(string Name);
public enum Operation { Read, Write, Delete, Admin }

/// <summary>
/// Strongly-typed result for domain operations.
/// Every specification method returns this -- not bool, not void.
/// </summary>
public record Result
{
    public bool IsSuccess { get; }
    public string? Reason { get; }

    private Result(bool success, string? reason) { IsSuccess = success; Reason = reason; }

    public static Result Success() => new(true, null);
    public static Result Failure(string reason) => new(false, reason);
    public static Result Aggregate(params Result[] results) =>
        new(results.All(r => r.IsSuccess), null);
}

namespace MyApp.Specifications;

using MyApp.Requirements.Features;
using MyApp.SharedKernel;

/// <summary>
/// Specification for UserRolesFeature.
/// Any domain service claiming to implement user roles MUST implement this interface.
/// The compiler enforces it -- you cannot compile without satisfying every AC.
/// </summary>
[ForRequirement(typeof(UserRolesFeature))]
public interface IUserRolesSpec
{
    [ForRequirement(typeof(UserRolesFeature), nameof(UserRolesFeature.AdminCanAssignRoles))]
    Result AssignRole(User actingUser, User targetUser, Role role);

    [ForRequirement(typeof(UserRolesFeature), nameof(UserRolesFeature.ViewerHasReadOnlyAccess))]
    Result EnforceReadOnlyAccess(User viewer, Resource resource, Operation operation);

    [ForRequirement(typeof(UserRolesFeature), nameof(UserRolesFeature.RoleChangeTakesEffectImmediately))]
    Result VerifyImmediateRoleEffect(User user, Role previousRole, Role newRole);
}

[ForRequirement(typeof(UserRolesFeature))]
public record UserRolesValidator : UserRolesFeature
{
    private readonly IUserRolesSpec _spec;

    public UserRolesValidator(IUserRolesSpec spec) => _spec = spec;

    public override AcceptanceCriterionResult AdminCanAssignRoles(
        UserId actingUser, UserId targetUser, RoleId role)
    {
        var result = _spec.AssignRole(
            new User(actingUser, "acting", new HashSet<Role>()),
            new User(targetUser, "target", new HashSet<Role>()),
            new Role(role, role.Value, new HashSet<Permission>()));

        return result.IsSuccess
            ? AcceptanceCriterionResult.Satisfied()
            : AcceptanceCriterionResult.Failed(result.Reason!);
    }

    public override AcceptanceCriterionResult ViewerHasReadOnlyAccess(
        UserId viewer, ResourceId resource)
    {
        var result = _spec.EnforceReadOnlyAccess(
            new User(viewer, "viewer", new HashSet<Role>()),
            new Resource(resource, "generic"),
            Operation.Write);

        return !result.IsSuccess
            ? AcceptanceCriterionResult.Satisfied()
            : AcceptanceCriterionResult.Failed("Viewer was allowed to write");
    }

    public override AcceptanceCriterionResult RoleChangeTakesEffectImmediately(
        UserId user, RoleId previousRole, RoleId newRole)
    {
        var result = _spec.VerifyImmediateRoleEffect(
            new User(user, "user", new HashSet<Role>()),
            new Role(previousRole, previousRole.Value, new HashSet<Permission>()),
            new Role(newRole, newRole.Value, new HashSet<Permission>()));

        return result.IsSuccess
            ? AcceptanceCriterionResult.Satisfied()
            : AcceptanceCriterionResult.Failed(result.Reason!);
    }
}

// Mode 1: Normal production flow -- call ISpec directly
public class RoleController
{
    private readonly IUserRolesSpec _spec;

    [HttpPost("users/{targetId}/role")]
    public IActionResult AssignRole(Guid targetId, [FromBody] AssignRoleRequest req)
    {
        var result = _spec.AssignRole(actingUser, targetUser, role);
        return result.IsSuccess ? Ok() : BadRequest(result.Reason);
    }
}

// Mode 2: Compliance mode -- validate ACs explicitly (audit trail, regulatory)
public class ComplianceService
{
    private readonly UserRolesValidator _validator;

    public AcceptanceCriterionResult AuditRoleAssignment(
        UserId acting, UserId target, RoleId role)
    {
        var result = _validator.AdminCanAssignRoles(acting, target, role);
        _auditLog.Record("FEATURE:UserRoles", "AC:AdminCanAssignRoles", result);
        return result;
    }
}

namespace MyApp.Domain.Auth;

using MyApp.Specifications;
using MyApp.Requirements.Features;

/// <summary>
/// Domain service implementing user roles.
/// The compiler FORCES this class to implement all three IUserRolesSpec methods.
/// If a new AC is added to the specification interface, this class
/// will not compile until the new method is implemented.
/// </summary>
[ForRequirement(typeof(UserRolesFeature))]
public class AuthorizationService : IUserRolesSpec
{
    private readonly IUserRepository _users;
    private readonly IRoleRepository _roles;
    private readonly IPermissionCache _cache;

    public AuthorizationService(
        IUserRepository users, IRoleRepository roles, IPermissionCache cache)
    {
        _users = users;
        _roles = roles;
        _cache = cache;
    }

    [ForRequirement(typeof(UserRolesFeature), nameof(UserRolesFeature.AdminCanAssignRoles))]
    public Result AssignRole(User actingUser, User targetUser, Role role)
    {
        if (!actingUser.Roles.Any(r => r.Name == "Admin"))
            return Result.Failure("Only admins can assign roles");

        if (role is null)
            return Result.Failure("Role cannot be null");

        // Domain logic: persist the assignment
        _users.AssignRole(targetUser.Id, role.Id);
        return Result.Success();
    }

    [ForRequirement(typeof(UserRolesFeature), nameof(UserRolesFeature.ViewerHasReadOnlyAccess))]
    public Result EnforceReadOnlyAccess(User viewer, Resource resource, Operation operation)
    {
        var isViewer = viewer.Roles.Any(r => r.Name == "Viewer");
        if (isViewer && operation != Operation.Read)
            return Result.Failure($"Viewer cannot perform {operation} on {resource.Id}");

        return Result.Success();
    }

    [ForRequirement(typeof(UserRolesFeature), nameof(UserRolesFeature.RoleChangeTakesEffectImmediately))]
    public Result VerifyImmediateRoleEffect(User user, Role previousRole, Role newRole)
    {
        _cache.Invalidate(user.Id);

        var currentPermissions = _cache.GetPermissions(user.Id);
        var hasOldPermissions = currentPermissions.Intersect(previousRole.Permissions)
            .Except(newRole.Permissions).Any();

        if (hasOldPermissions)
            return Result.Failure("Old permissions still cached after role change");

        return Result.Success();
    }
}

namespace MyApp.Tests.Auth;

using MyApp.Requirements.Features;
using MyApp.Specifications;
using MyApp.Domain.Auth;

[TestFixture]
[TestsFor(typeof(UserRolesFeature))]
public class UserRolesTests
{
    private AuthorizationService _authService;
    private User _admin;
    private User _viewer;
    private Role _editorRole;

    [SetUp]
    public void Setup()
    {
        _authService = new AuthorizationService(
            new InMemoryUserRepository(),
            new InMemoryRoleRepository(),
            new InMemoryPermissionCache());

        var adminRole = new Role(new RoleId("admin"), "Admin",
            new HashSet<Permission> { new("manage-roles") });
        var viewerRole = new Role(new RoleId("viewer"), "Viewer",
            new HashSet<Permission> { new("read") });

        _admin = new User(new UserId(Guid.NewGuid()), "Alice",
            new HashSet<Role> { adminRole });
        _viewer = new User(new UserId(Guid.NewGuid()), "Bob",
            new HashSet<Role> { viewerRole });
        _editorRole = new Role(new RoleId("editor"), "Editor",
            new HashSet<Permission> { new("read"), new("write") });
    }

    [Test]
    [Verifies(typeof(UserRolesFeature), nameof(UserRolesFeature.AdminCanAssignRoles))]
    public void Admin_can_assign_role_to_another_user()
    {
        var target = new User(new UserId(Guid.NewGuid()), "Charlie", new HashSet<Role>());
        var result = _authService.AssignRole(_admin, target, _editorRole);
        Assert.That(result.IsSuccess, Is.True);
    }

    [Test]
    [Verifies(typeof(UserRolesFeature), nameof(UserRolesFeature.AdminCanAssignRoles))]
    public void Non_admin_cannot_assign_roles()
    {
        var target = new User(new UserId(Guid.NewGuid()), "Charlie", new HashSet<Role>());
        var result = _authService.AssignRole(_viewer, target, _editorRole);
        Assert.That(result.IsSuccess, Is.False);
        Assert.That(result.Reason, Does.Contain("Only admins"));
    }

    [Test]
    [Verifies(typeof(UserRolesFeature), nameof(UserRolesFeature.ViewerHasReadOnlyAccess))]
    public void Viewer_cannot_write()
    {
        var resource = new Resource(new ResourceId("order-123"), "Order");
        var result = _authService.EnforceReadOnlyAccess(_viewer, resource, Operation.Write);
        Assert.That(result.IsSuccess, Is.False);
    }

    [Test]
    [Verifies(typeof(UserRolesFeature), nameof(UserRolesFeature.ViewerHasReadOnlyAccess))]
    public void Viewer_can_read()
    {
        var resource = new Resource(new ResourceId("order-123"), "Order");
        var result = _authService.EnforceReadOnlyAccess(_viewer, resource, Operation.Read);
        Assert.That(result.IsSuccess, Is.True);
    }

    [Test]
    [Verifies(typeof(UserRolesFeature), nameof(UserRolesFeature.RoleChangeTakesEffectImmediately))]
    public void Role_change_invalidates_cache_immediately()
    {
        var previousRole = new Role(new RoleId("viewer"), "Viewer",
            new HashSet<Permission> { new("read") });
        var result = _authService.VerifyImmediateRoleEffect(_admin, previousRole, _editorRole);
        Assert.That(result.IsSuccess, Is.True);
    }
}

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Wire the requirement chain
builder.Services.AddScoped<IUserRolesSpec, AuthorizationService>();
builder.Services.AddScoped<IJwtRefreshSpec, JwtRefreshService>();

// Optional: enable compliance mode for audit-sensitive operations
builder.Services.AddScoped<UserRolesValidator>(sp =>
    new UserRolesValidator(sp.GetRequiredService<IUserRolesSpec>()));

// Optional: enable requirement compliance checking at startup
builder.Services.AddHostedService<RequirementComplianceCheck>();

var app = builder.Build();
app.MapControllers();
app.Run();

namespace MyApp.Api.Controllers;

using MyApp.Specifications;
using MyApp.SharedKernel;
using MyApp.Requirements.Features;

[ApiController]
[Route("api/users")]
[ForRequirement(typeof(UserRolesFeature))]
public class UsersController : ControllerBase
{
    private readonly IUserRolesSpec _spec;

    public UsersController(IUserRolesSpec spec) => _spec = spec;

    [HttpPost("{targetId}/role")]
    [ForRequirement(typeof(UserRolesFeature), nameof(UserRolesFeature.AdminCanAssignRoles))]
    public IActionResult AssignRole(Guid targetId, [FromBody] AssignRoleRequest request)
    {
        var actingUser = HttpContext.GetCurrentUser();
        var targetUser = _users.GetById(new UserId(targetId));
        var role = _roles.GetById(new RoleId(request.RoleId));

        var result = _spec.AssignRole(actingUser, targetUser, role);

        return result.IsSuccess
            ? Ok(new { message = "Role assigned" })
            : BadRequest(new { error = result.Reason });
    }
}

{
  "paths": {
    "/api/users/{targetId}/role": {
      "post": {
        "x-requirement": "UserRolesFeature",
        "x-acceptance-criterion": "AdminCanAssignRoles",
        "summary": "Assign a role to a user"
      }
    }
  }
}

public class RequirementComplianceCheck : IHostedService
{
    private readonly ILogger<RequirementComplianceCheck> _logger;

    public Task StartAsync(CancellationToken ct)
    {
        // TraceabilityMatrix is source-generated
        foreach (var (type, entry) in TraceabilityMatrix.Entries)
        {
            var info = RequirementRegistry.All[type];
            var totalACs = info.AcceptanceCriteria.Length;
            var testedACs = entry.AcceptanceCriteriaCoverage.Count;

            if (testedACs < totalACs)
                _logger.LogWarning("{Feature}: {Tested}/{Total} ACs tested ({Missing} missing)",
                    info.Title, testedACs, totalACs,
                    string.Join(", ", info.AcceptanceCriteria
                        .Except(entry.AcceptanceCriteriaCoverage.Keys)));
            else
                _logger.LogInformation("{Feature}: all {Total} ACs covered",
                    info.Title, totalACs);
        }

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken ct) => Task.CompletedTask;
}

bin/
├── MyApp.Requirements.dll           ← Feature types, AC methods, generated attributes
├── MyApp.SharedKernel.dll           ← User, Role, Permission, Result
├── MyApp.Specifications.dll         ← IUserRolesSpec, IJwtRefreshSpec, validator bridges
├── MyApp.Domain.dll                 ← AuthorizationService : IUserRolesSpec
├── MyApp.Api.dll                    ← Controllers, DI wiring, startup compliance
└── MyApp.Tests.dll                  ← Type-linked tests (not deployed)

Generated at compile time (embedded in respective DLLs):
├── RequirementRegistry.g.cs         ← Type catalog + hierarchy
├── TraceabilityMatrix.g.cs          ← Requirement → Implementation → Test mapping
└── Compiler diagnostics             ← IDE warnings for untested ACs

UserRolesFeature                          <-- Layer 1: requirement definition
|-- IUserRolesSpec                        <-- Layer 2: [ForRequirement(typeof(UserRolesFeature))]
|   |-- .AssignRole                       <-- Layer 2: [ForRequirement(..., nameof(...AdminCanAssignRoles))]
|   |-- .EnforceReadOnlyAccess            <-- Layer 2: [ForRequirement(..., nameof(...ViewerHasReadOnlyAccess))]
|   '-- .VerifyImmediateRoleEffect        <-- Layer 2: [ForRequirement(..., nameof(...RoleChangeTakesEffectImmediately))]
|-- AuthorizationService                  <-- Layer 3: [ForRequirement(typeof(UserRolesFeature))]
|   |-- .AssignRole                       <-- Layer 3: [ForRequirement(..., nameof(...AdminCanAssignRoles))]
|   '-- ...
'-- UserRolesTests                        <-- Layer 4: [TestsFor(typeof(UserRolesFeature))]
    |-- .Admin_can_assign_role            <-- Layer 4: [Verifies(..., nameof(...AdminCanAssignRoles))]
    |-- .Non_admin_cannot_assign_roles    <-- Layer 4: [Verifies(..., nameof(...AdminCanAssignRoles))]
    '-- ...

// Generated: TraceabilityMatrix.g.cs
public static class TraceabilityMatrix
{
    public static IReadOnlyDictionary<Type, TraceabilityEntry> Entries { get; } =
        new Dictionary<Type, TraceabilityEntry>
        {
            [typeof(UserRolesFeature)] = new TraceabilityEntry(
                RequirementType: typeof(UserRolesFeature),
                Implementations: new[]
                {
                    new ImplementationRef(typeof(AuthorizationService), typeof(IUserRolesSpec))
                },
                Tests: new[]
                {
                    new TestRef(typeof(UserRolesTests), "Admin_can_assign_role_to_another_user",
                        nameof(UserRolesFeature.AdminCanAssignRoles)),
                    new TestRef(typeof(UserRolesTests), "Non_admin_cannot_assign_roles",
                        nameof(UserRolesFeature.AdminCanAssignRoles)),
                    new TestRef(typeof(UserRolesTests), "Viewer_cannot_write",
                        nameof(UserRolesFeature.ViewerHasReadOnlyAccess)),
                    new TestRef(typeof(UserRolesTests), "Viewer_can_read",
                        nameof(UserRolesFeature.ViewerHasReadOnlyAccess)),
                    new TestRef(typeof(UserRolesTests), "Role_change_invalidates_cache_immediately",
                        nameof(UserRolesFeature.RoleChangeTakesEffectImmediately)),
                },
                AcceptanceCriteriaCoverage: new Dictionary<string, int>
                {
                    [nameof(UserRolesFeature.AdminCanAssignRoles)] = 2,
                    [nameof(UserRolesFeature.ViewerHasReadOnlyAccess)] = 2,
                    [nameof(UserRolesFeature.RoleChangeTakesEffectImmediately)] = 1
                }),
        };
}

warning REQ001: UserRolesFeature -- all 3 acceptance criteria have tests (100% coverage)
warning REQ002: JwtRefreshStory -- 0/2 acceptance criteria have tests (0% coverage)
  -> Missing: TokensExpireAfterOneHour, RefreshExtendsBySevenDays
warning REQ003: No class found implementing IJwtRefreshSpec
  -> JwtRefreshStory has a specification but no domain implementation

// Build output:
error REQ100: UserRolesFeature has 3 acceptance criteria but no ISpec interface
              references it via [ForRequirement(typeof(UserRolesFeature))]
              → Create IUserRolesSpec with [ForRequirement(typeof(UserRolesFeature))]

error REQ101: UserRolesFeature.RoleChangeTakesEffectImmediately has no matching
              spec method with [ForRequirement(typeof(UserRolesFeature),
              nameof(UserRolesFeature.RoleChangeTakesEffectImmediately))]
              → Add a method to IUserRolesSpec with the matching [ForRequirement]

// Build output:
error REQ200: IUserRolesSpec is not implemented by any class in MyApp.Domain
              → Create a class that implements IUserRolesSpec

warning REQ201: AuthorizationService implements IUserRolesSpec but is missing
                [ForRequirement(typeof(UserRolesFeature))] on the class
                → Add [ForRequirement(typeof(UserRolesFeature))] for traceability

warning REQ202: AuthorizationService.VerifyImmediateRoleEffect implements
                IUserRolesSpec but is missing [ForRequirement(typeof(UserRolesFeature),
                nameof(UserRolesFeature.RoleChangeTakesEffectImmediately))]
                → Add method-level [ForRequirement] for IDE navigation

// Build output:
error REQ300: JwtRefreshStory has 2 acceptance criteria but no test class
              with [TestsFor(typeof(JwtRefreshStory))]

warning REQ301: UserRolesFeature.RoleChangeTakesEffectImmediately has no test
                with [Verifies(typeof(UserRolesFeature),
                nameof(UserRolesFeature.RoleChangeTakesEffectImmediately))]
                → Add a test method with [Verifies] for this AC

warning REQ302: UserRolesTests.OldTest references nameof(UserRolesFeature.DeletedAC)
                which no longer exists on UserRolesFeature
                → Remove or update the stale [Verifies] attribute

<!-- MyApp.Tests.csproj -->
<PropertyGroup>
  <RequirementMinCoverage>80</RequirementMinCoverage>
  <RequirementMinPassRate>100</RequirementMinPassRate>
  <RequirementMaxTestDuration>5000</RequirementMaxTestDuration> <!-- ms per test -->
</PropertyGroup>

<Target Name="RequirementQualityGates" AfterTargets="VSTest">
  <Exec Command="dotnet quality-gates check
    --trx $(TestResultsDir)/*.trx
    --coverage $(CoverageResultsDir)/coverage.cobertura.xml
    --traceability $(IntermediateOutputPath)/TraceabilityMatrix.g.cs
    --min-pass-rate $(RequirementMinPassRate)
    --min-coverage $(RequirementMinCoverage)
    --max-duration $(RequirementMaxTestDuration)"
    ConsoleToMsBuild="true" />
</Target>

$ dotnet quality-gates check --trx results.trx --coverage coverage.xml ...

Quality Gates Report
====================

FEATURE: UserRolesFeature (3 ACs, 5 tests)
  ✓ AdminCanAssignRoles      2 tests, 100% pass, 94% coverage, avg 12ms
    fuzz: 500 inputs, 0 crashes, 12 Result.Failure (expected)
  ✓ ViewerHasReadOnlyAccess  2 tests, 100% pass, 88% coverage, avg 8ms
    fuzz: 500 inputs, 0 crashes, 8 Result.Failure (expected)
  ✗ RoleChangeTakesEffect    1 test,  100% pass, 62% coverage ← BELOW 80% THRESHOLD
    fuzz: 500 inputs, 1 CRASH ← NullReferenceException with empty RoleId
    → AuthorizationService.VerifyImmediateRoleEffect:L45-L52 not covered

STORY: JwtRefreshStory (2 ACs, 0 tests)
  ✗ TokensExpireAfterOneHour   NO TESTS
  ✗ RefreshExtendsBySevenDays  NO TESTS

Summary: 2/3 quality gates passed for UserRolesFeature (fuzz found 1 crash)
         0/2 quality gates passed for JwtRefreshStory
         Overall: FAIL (exit code 1)

# .editorconfig
[*.cs]

# Requirements → Specifications: treat missing specs as errors
dotnet_diagnostic.REQ100.severity = error
dotnet_diagnostic.REQ101.severity = error
dotnet_diagnostic.REQ102.severity = warning

# Specifications → Implementation: treat missing impl as errors
dotnet_diagnostic.REQ200.severity = error
dotnet_diagnostic.REQ201.severity = warning
dotnet_diagnostic.REQ202.severity = suggestion

# Implementation → Tests: treat missing tests as warnings (errors in CI)
dotnet_diagnostic.REQ300.severity = warning
dotnet_diagnostic.REQ301.severity = warning
dotnet_diagnostic.REQ302.severity = error    # stale tests are always errors

<!-- Directory.Build.props -->
<PropertyGroup Condition="'$(CI)' == 'true'">
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  <WarningsAsErrors>REQ100;REQ101;REQ200;REQ300;REQ301</WarningsAsErrors>
</PropertyGroup>

# .github/workflows/build.yml
jobs:
  build:
    steps:
      - run: dotnet build --warnaserror     # REQ1xx, REQ2xx, REQ3xx analyzers
      - run: dotnet test --collect:"XPlat Code Coverage" --logger:trx
      - run: dotnet quality-gates check     # REQ4xx quality gates
        --trx TestResults/*.trx
        --coverage TestResults/**/coverage.cobertura.xml
        --min-pass-rate 100
        --min-coverage 80

Draft --> Proposed --> Approved --> InProgress --> Quality --> Translation --> Review --> Done

public enum RequirementLifecycleState : byte
{
    Draft = 0,
    Proposed = 1,
    Approved = 2,
    InProgress = 3,
    Quality = 4,
    Translation = 5,
    Review = 6,
    Done = 7
}

public class RequirementLifecycleStateMachine
{
    public static bool CanTransition(RequirementLifecycleState from, RequirementLifecycleState to)
    {
        if (to > from) return to == from + 1;   // Forward: one step at a time
        if (to < from) return to == from - 1;   // Backward: one step back allowed
        return false;
    }
}

[ForRequirement(typeof(UserRolesFeature))]
[AggregateRoot]
public partial class AuthAggregate : IUserRolesSpec
{
    [ForRequirement(typeof(UserRolesFeature), nameof(UserRolesFeature.AdminCanAssignRoles))]
    public Result AssignRole(User actingUser, User targetUser, Role role)
    {
        // DDD generator produces Entity + Repository + CQRS handlers
        // ALL tagged with [ForRequirement(typeof(UserRolesFeature))]
    }
}

[ForRequirement(typeof(UserRolesFeature))]
[Workflow(Name = "FeatureApproval", Stages = new[] { "Design", "Impl", "Test", "Review" })]
public partial class FeatureWorkflow { }

// Workflow rules can reference requirement compliance:
[WorkflowRule(Stage = "Test", Condition = "All ACs have [Verifies] tests")]
[WorkflowRule(Stage = "Review", Condition = "Test coverage >= 80%")]

[ForRequirement(typeof(UserRolesFeature))]
[AdminModule(Name = "FeatureTracking", Path = "/admin/features")]
public partial class FeatureAdminPanel { }
// Generates: dashboard with compliance status, implementations per feature, test coverage

[Feature(Id = "FEATURE-456", AcceptanceCriteria = new[] { "Admin can assign roles" })]
public class UserRoleFeature { }  // Empty marker class -- dead code

[Implements(Requirements.FEATURE_USER_ROLES)]  // const string = "FEATURE-456"
public void AssignRole(User u, Role r) { }

[FeatureTest(Requirements.FEATURE_USER_ROLES, 0)]  // AC[0] by fragile index
public void AdminCanAssign() { }

// Requirement IS a type with abstract AC methods
public abstract record UserRolesFeature : Feature<PlatformScalabilityEpic>
{
    public abstract AcceptanceCriterionResult AdminCanAssignRoles(
        UserId actingUser, UserId targetUser, RoleId role);
}

// Specification IS an interface the domain must implement
[ForRequirement(typeof(UserRolesFeature))]
public interface IUserRolesSpec
{
    [ForRequirement(typeof(UserRolesFeature), nameof(UserRolesFeature.AdminCanAssignRoles))]
    Result AssignRole(User actingUser, User targetUser, Role role);
}

// Implementation MUST implement the interface -- compiler enforces it
[ForRequirement(typeof(UserRolesFeature))]
public class AuthorizationService : IUserRolesSpec
{
    public Result AssignRole(User actingUser, User targetUser, Role role) { ... }
    // Remove this method --> compile error
}

// Test linked by type + nameof -- compiler-checked
[Verifies(typeof(UserRolesFeature), nameof(UserRolesFeature.AdminCanAssignRoles))]
public void Admin_can_assign_role() { ... }
// Rename AC method --> compile error. Delete AC method --> compile error.

MyCompany.sln
├── src/
│   ├── MyCompany.Requirements/          ← Every project references this
│   ├── MyCompany.OrderService/          ← [Implements] OrderProcessingSpec
│   ├── MyCompany.PaymentGateway/        ← [Implements] PaymentValidationSpec
│   ├── MyCompany.NotificationWorker/    ← [Implements] OrderNotificationSpec
│   └── MyCompany.SharedKernel/          ← Domain types shared across services
└── test/
    ├── MyCompany.OrderService.Tests/    ← [Verifies] OrderProcessing ACs
    └── MyCompany.PaymentGateway.Tests/  ← [Verifies] PaymentValidation ACs

// In the AC definition (MyCompany.Requirements)
public abstract partial record OrderProcessingFeature : Feature
{
    // This AC is an abstract method -- but its generated validation logic is concrete
    public static bool OrderTotalMustBePositive(Order order)
        => order.Total > 0 && order.Lines.All(l => l.Quantity > 0);
}

// In production code (MyCompany.OrderService)
public class OrderService : IOrderProcessingSpec
{
    public Result<Order, IDomainException> CreateOrder(CreateOrderCommand cmd)
    {
        var order = Order.CreateInstance(cmd);

        // AC validation called in production -- same method the tests use
        if (!OrderProcessingFeature.OrderTotalMustBePositive(order))
            throw new InvalidOrderException("Order total must be positive");

        return Result<Order, IDomainException>.Success(order);
    }
}

// In unit tests (MyCompany.OrderService.Tests)
[Verifies(typeof(OrderProcessingFeature), nameof(OrderProcessingFeature.OrderTotalMustBePositive))]
public void Order_with_positive_total_passes_AC()
{
    var order = CreateValidOrder();
    Assert.True(OrderProcessingFeature.OrderTotalMustBePositive(order));
}