Docs: Organize governance examples and references

Author: rian-be

Examples/Governance/DecisionTaxonomy/DecisionTaxonomy.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <OutputType>Exe</OutputType>
+        <TargetFramework>net10.0</TargetFramework>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+    </PropertyGroup>
+
+    <ItemGroup>
+      <ProjectReference Include="..\..\..\src\ModularityKit.Mutator.Governance.csproj" />
+    </ItemGroup>
+
+</Project>

Examples/Governance/DecisionTaxonomy/Program.cs

@@ -0,0 +1,3 @@
+using DecisionTaxonomy.Scenarios;
+
+GovernanceDecisionTaxonomyScenario.Run();

Examples/Governance/DecisionTaxonomy/README.md

@@ -0,0 +1,29 @@
+# Governance DecisionTaxonomy
+
+This example shows why governance request decisions are split into separate categories instead of being kept in one flat enum.
+
+It demonstrates:
+
+- lifecycle decisions such as `Submitted` and `Approved`
+- approval decisions such as `Requested`, `Granted`, and `Rejected`
+- version-resolution decisions such as `Validated` and `RejectedAsStale`
+- the shared `MutationRequestDecisionType` wrapper with:
+  - `Category`
+  - `Code`
+  - `ToString()`
+
+## Key files
+
+- [`Program.cs`](Program.cs)
+- [`Scenarios/GovernanceDecisionTaxonomyScenario.cs`](Scenarios/GovernanceDecisionTaxonomyScenario.cs)
+- [`src/Governance/Abstractions/Requests/Decisions/MutationRequestDecisionType.cs`](../../../src/Governance/Abstractions/Requests/Decisions/MutationRequestDecisionType.cs)
+- [`src/Governance/Abstractions/Requests/Decisions/MutationRequestDecisionCategory.cs`](../../../src/Governance/Abstractions/Requests/Decisions/MutationRequestDecisionCategory.cs)
+- [`src/Governance/Abstractions/Requests/Decisions/MutationRequestLifecycleDecisionType.cs`](../../../src/Governance/Abstractions/Requests/Decisions/MutationRequestLifecycleDecisionType.cs)
+- [`src/Governance/Abstractions/Requests/Decisions/MutationRequestApprovalDecisionType.cs`](../../../src/Governance/Abstractions/Requests/Decisions/MutationRequestApprovalDecisionType.cs)
+- [`src/Governance/Abstractions/Requests/Decisions/MutationRequestVersionResolutionDecisionType.cs`](../../../src/Governance/Abstractions/Requests/Decisions/MutationRequestVersionResolutionDecisionType.cs)
+
+## Run
+
+```bash
+dotnet run --project Examples/Governance/DecisionTaxonomy/DecisionTaxonomy.csproj
+```

Examples/Governance/DecisionTaxonomy/Scenarios/GovernanceDecisionTaxonomyScenario.cs

@@ -0,0 +1,64 @@
+using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Governance.Abstractions.Requests.Decisions;
+
+namespace DecisionTaxonomy.Scenarios;
+
+internal static class GovernanceDecisionTaxonomyScenario
+{
+    public static void Run()
+    {
+        PrintSection("Lifecycle Decisions");
+        PrintDecision(MutationRequestDecision.Create(
+            MutationRequestDecisionType.Lifecycle(MutationRequestLifecycleDecisionType.Submitted),
+            MutationContext.User("requester", "Requester", "Submit request"),
+            reason: "Request was submitted into governance."));
+        PrintDecision(MutationRequestDecision.Create(
+            MutationRequestDecisionType.Lifecycle(MutationRequestLifecycleDecisionType.Approved),
+            MutationContext.User("system", "System", "Request reached executable state"),
+            reason: "Request is now approved for execution."));
+
+        PrintSection("Approval Decisions");
+        PrintDecision(MutationRequestDecision.Create(
+            MutationRequestDecisionType.Approval(MutationRequestApprovalDecisionType.Requested),
+            MutationContext.User("requester", "Requester", "Approval needed for sensitive change"),
+            reason: "Sensitive change requires explicit sign-off."));
+        PrintDecision(MutationRequestDecision.Create(
+            MutationRequestDecisionType.Approval(MutationRequestApprovalDecisionType.Granted),
+            MutationContext.User("alice", "Alice", "Manager approved"),
+            reason: "Manager granted the required approval."));
+        PrintDecision(MutationRequestDecision.Create(
+            MutationRequestDecisionType.Approval(MutationRequestApprovalDecisionType.Rejected),
+            MutationContext.User("bob", "Bob", "Security rejected"),
+            reason: "Security review rejected the request."));
+
+        PrintSection("Version Resolution Decisions");
+        PrintDecision(MutationRequestDecision.Create(
+            MutationRequestDecisionType.VersionResolution(MutationRequestVersionResolutionDecisionType.Validated),
+            MutationContext.User("approver", "Approver", "Version still matches"),
+            reason: "Current state version still matches the approved request."));
+        PrintDecision(MutationRequestDecision.Create(
+            MutationRequestDecisionType.VersionResolution(MutationRequestVersionResolutionDecisionType.RejectedAsStale),
+            MutationContext.User("approver", "Approver", "State drift invalidated the request"),
+            reason: "Request was rejected because the approved version is stale."));
+        PrintDecision(MutationRequestDecision.Create(
+            MutationRequestDecisionType.VersionResolution(MutationRequestVersionResolutionDecisionType.RenewedApprovalRequired),
+            MutationContext.User("approver", "Approver", "Re-approval required on latest state"),
+            reason: "Request must be approved again on the latest state version."));
+    }
+
+    private static void PrintSection(string title)
+    {
+        Console.WriteLine();
+        Console.WriteLine($"=== {title} ===");
+    }
+
+    private static void PrintDecision(MutationRequestDecision decision)
+    {
+        Console.WriteLine($"Category: {decision.Type.Category}");
+        Console.WriteLine($"Code: {decision.Type.Code}");
+        Console.WriteLine($"Display: {decision.Type}");
+        Console.WriteLine($"Actor: {decision.Context.ActorId ?? "system"}");
+        Console.WriteLine($"Reason: {decision.Reason ?? "-"}");
+        Console.WriteLine();
+    }
+}

Examples/Governance/RequestLifecycle/README.md

@@ -21,7 +21,7 @@ It focuses on `MutationRequest`, `IMutationRequestStore`, and `MutationRequestLi
 
 - [`Program.cs`](Program.cs)
 - [`Scenarios/GovernanceRequestLifecycleScenario.cs`](Scenarios/GovernanceRequestLifecycleScenario.cs)
-- [`src/Governance/Abstractions/Requests/MutationRequest.cs`](../../../src/Governance/Abstractions/Requests/MutationRequest.cs)
+- [`src/Governance/Abstractions/Requests/Model/MutationRequest.cs`](../../../src/Governance/Abstractions/Requests/Model/MutationRequest.cs)
 - [`src/Governance/Abstractions/Lifecycle/IMutationRequestLifecycleManager.cs`](../../../src/Governance/Abstractions/Lifecycle/IMutationRequestLifecycleManager.cs)
 - [`src/Governance/Runtime/MutationRequestLifecycleManager.cs`](../../../src/Governance/Runtime/MutationRequestLifecycleManager.cs)
 - [`src/Governance/Runtime/InMemoryMutationRequestStore.cs`](../../../src/Governance/Runtime/InMemoryMutationRequestStore.cs)

Examples/Governance/VersionedResolution/README.md

@@ -17,10 +17,10 @@ It is the direct runnable example for the semantics introduced around `ExpectedS
 
 - [`Program.cs`](Program.cs)
 - [`Scenarios/GovernanceVersionedResolutionScenario.cs`](Scenarios/GovernanceVersionedResolutionScenario.cs)
-- [`src/Governance/Runtime/Resolution/MutationRequestVersionResolver.cs`](../../../src/Governance/Runtime/Resolution/MutationRequestVersionResolver.cs)
-- [`src/Governance/Runtime/Resolution/MutationRequestVersionResolutionManager.cs`](../../../src/Governance/Runtime/Resolution/MutationRequestVersionResolutionManager.cs)
-- [`src/Governance/Abstractions/Resolution/VersionedRequestResolutionStrategy.cs`](../../../src/Governance/Abstractions/Resolution/VersionedRequestResolutionStrategy.cs)
-- [`src/Governance/Abstractions/Resolution/MutationRequestVersionResolution.cs`](../../../src/Governance/Abstractions/Resolution/MutationRequestVersionResolution.cs)
+- [`src/Governance/Runtime/Resolution/Execution/MutationRequestVersionResolver.cs`](../../../src/Governance/Runtime/Resolution/Execution/MutationRequestVersionResolver.cs)
+- [`src/Governance/Runtime/Resolution/Execution/MutationRequestVersionResolutionManager.cs`](../../../src/Governance/Runtime/Resolution/Execution/MutationRequestVersionResolutionManager.cs)
+- [`src/Governance/Abstractions/Resolution/Strategies/VersionedRequestResolutionStrategy.cs`](../../../src/Governance/Abstractions/Resolution/Strategies/VersionedRequestResolutionStrategy.cs)
+- [`src/Governance/Abstractions/Resolution/Model/MutationRequestVersionResolution.cs`](../../../src/Governance/Abstractions/Resolution/Model/MutationRequestVersionResolution.cs)
 
 ## Run
 

Examples/README.md

@@ -23,6 +23,8 @@ The projects are intentionally small and focused. Each one demonstrates a differ
 | Example | Focus | Readme |
 | --- | --- | --- |
 | `RequestLifecycle` | pending requests, lifecycle transitions, expiration, and cancellation | [`Examples/Governance/RequestLifecycle/README.md`](Governance/RequestLifecycle/README.md) |
+| `DecisionTaxonomy` | lifecycle, approval, and version-resolution decision categories | [`Examples/Governance/DecisionTaxonomy/README.md`](Governance/DecisionTaxonomy/README.md) |
+| `ApprovalWorkflow` | request-level approvals, multi-step sign-off, and governed approval actions | [`Examples/Governance/ApprovalWorkflow/README.md`](Governance/ApprovalWorkflow/README.md) |
 | `VersionedResolution` | stale request handling and expected state version semantics | [`Examples/Governance/VersionedResolution/README.md`](Governance/VersionedResolution/README.md) |
 
 ## How to use these examples
@@ -52,6 +54,8 @@ dotnet build Examples/Core/FeatureFlags/FeatureFlags.csproj -c Release
 dotnet build Examples/Core/IamRoles/IamRoles.csproj -c Release
 dotnet build Examples/Core/WorkflowApprovals/WorkflowApprovals.csproj -c Release
 dotnet build Examples/Governance/RequestLifecycle/RequestLifecycle.csproj -c Release
+dotnet build Examples/Governance/DecisionTaxonomy/DecisionTaxonomy.csproj -c Release
+dotnet build Examples/Governance/ApprovalWorkflow/ApprovalWorkflow.csproj -c Release
 dotnet build Examples/Governance/VersionedResolution/VersionedResolution.csproj -c Release
 ```
 
@@ -67,6 +71,8 @@ dotnet run --project Examples/Core/FeatureFlags/FeatureFlags.csproj
 dotnet run --project Examples/Core/IamRoles/IamRoles.csproj
 dotnet run --project Examples/Core/WorkflowApprovals/WorkflowApprovals.csproj
 dotnet run --project Examples/Governance/RequestLifecycle/RequestLifecycle.csproj
+dotnet run --project Examples/Governance/DecisionTaxonomy/DecisionTaxonomy.csproj
+dotnet run --project Examples/Governance/ApprovalWorkflow/ApprovalWorkflow.csproj
 dotnet run --project Examples/Governance/VersionedResolution/VersionedResolution.csproj
 ```
 
@@ -131,6 +137,18 @@ Shows the governance runtime as a request lifecycle system instead of an immedia
 
 See [`Governance/RequestLifecycle/README.md`](Governance/RequestLifecycle/README.md).
 
+### ApprovalWorkflow
+
+Shows how governance turns approval requirements into explicit request-level approval actions with ordered steps and terminal approval or rejection behavior.
+
+See [`Governance/ApprovalWorkflow/README.md`](Governance/ApprovalWorkflow/README.md).
+
+### DecisionTaxonomy
+
+Shows why governance request decisions are split into lifecycle, approval, and version-resolution categories instead of being kept in one flat enum.
+
+See [`Governance/DecisionTaxonomy/README.md`](Governance/DecisionTaxonomy/README.md).
+
 ### VersionedResolution
 
 Shows how governance resolves approved requests once the underlying state version has moved. This is the example to read if you want concrete stale request semantics.

ModularityKit.Mutator.slnx

@@ -8,6 +8,8 @@
     <Project Path="Examples/Core/FeatureFlags/FeatureFlags.csproj" />
     <Project Path="Examples/Core/IamRoles/IamRoles.csproj" />
     <Project Path="Examples/Core/WorkflowApprovals/WorkflowApprovals.csproj" />
+    <Project Path="Examples/Governance/ApprovalWorkflow/ApprovalWorkflow.csproj" />
+    <Project Path="Examples/Governance/DecisionTaxonomy/DecisionTaxonomy.csproj" />
     <Project Path="Examples/Governance/RequestLifecycle/RequestLifecycle.csproj" />
     <Project Path="Examples/Governance/VersionedResolution/VersionedResolution.csproj" />
   </Folder>

src/Governance/README.md

@@ -9,6 +9,7 @@ The core package stays responsible for direct mutation execution. Governance bui
 - **Mutation Requests** - model governed mutation submission as a durable request
 - **Pending Lifecycle** - represent requests that cannot execute immediately
 - **Decision History** - record approvals, rejections, cancellations, and other lifecycle transitions
+- **Approval Workflow** - model request-level approval requirements and explicit approver actions
 - **Request Storage Contracts** - define a persistence seam for governance-oriented stores
 - **Runtime Lifecycle Management** - move requests through pending, approval, expiration, and execution transitions
 - **In-Memory Runtime Support** - provide lightweight request runtime services for development and tests
@@ -20,6 +21,7 @@ The core package stays responsible for direct mutation execution. Governance bui
 The package defines governance-first abstractions under:
 
 - `Abstractions/Requests`
+- `Abstractions/Approval`
 - `Abstractions/Lifecycle`
 - `Abstractions/Storage`
 - `Abstractions/Resolution`
@@ -28,31 +30,85 @@ The package defines governance-first abstractions under:
 Key types:
 
 - `MutationRequest`
+- `MutationApprovalRequirement`
+- `MutationApprovalRequirementStatus`
 - `MutationRequestDecision`
 - `MutationRequestDecisionType`
+- `MutationRequestDecisionCategory`
+- `MutationRequestLifecycleDecisionType`
+- `MutationRequestApprovalDecisionType`
+- `MutationRequestVersionResolutionDecisionType`
 - `MutationRequestStatus`
 - `PendingMutationReason`
 - `IMutationRequestStore`
+- `IMutationRequestApprovalWorkflowManager`
 - `IMutationRequestLifecycleManager`
 - `IMutationRequestVersionResolver`
 - `IMutationRequestVersionResolutionManager`
 - `MutationRequestVersionResolution`
 - `MutationRequestVersionResolutionOutcome`
 - `VersionedRequestResolutionStrategy`
 - `MutationRequestAlreadyExistsException`
+- `MutationApprovalRequirementNotFoundException`
+- `InvalidMutationApprovalActionException`
 - `MutationRequestConcurrencyException`
 - `MutationRequestNotFoundException`
 - `InvalidMutationRequestTransitionException`
 
+`Abstractions/Requests` is further split into:
+
+- `Requests/Model`
+- `Requests/Decisions`
+
+`Abstractions/Approval` is further split into:
+
+- `Approval/Contracts`
+- `Approval/Model`
+- `Approval/Mapping`
+
+`Abstractions/Resolution` is further split into:
+
+- `Resolution/Contracts`
+- `Resolution/Model`
+- `Resolution/Strategies`
+
+`Abstractions/Lifecycle` is further split into:
+
+- `Lifecycle/Contracts`
+- `Lifecycle/Model`
+
+`Abstractions/Exceptions` is further split into:
+
+- `Exceptions/Approval`
+- `Exceptions/Lifecycle`
+- `Exceptions/Storage`
+
 ### Runtime
 
 The initial runtime layer currently provides:
 
 - `Runtime/Storage/InMemoryMutationRequestStore`
+- `Runtime/Approval/MutationRequestApprovalWorkflowManager`
 - `Runtime/Lifecycle/MutationRequestLifecycleManager`
 - `Runtime/Resolution/MutationRequestVersionResolver`
 - `Runtime/Resolution/MutationRequestVersionResolutionManager`
 
+`Runtime/Resolution` is further split into:
+
+- `Resolution/Evaluation`
+- `Resolution/Execution`
+
+`Runtime/Lifecycle` is further split into:
+
+- `Lifecycle/Execution`
+- `Lifecycle/Validation`
+- `Lifecycle/State`
+
+`Runtime/Approval` is further split into:
+
+- `Approval/Execution`
+- `Approval/State`
+
 This keeps the first version small while leaving room for later persistence providers such as Entity Framework Core or PostgreSQL-backed governance stores.
 
 ## Relationship to Core