diff --git a/tests/Polyphony.Tests/Routing/CrossProcessPhaseDetectorTests.cs b/tests/Polyphony.Tests/Routing/CrossProcessPhaseDetectorTests.cs new file mode 100644 index 00000000..af6682ff --- /dev/null +++ b/tests/Polyphony.Tests/Routing/CrossProcessPhaseDetectorTests.cs @@ -0,0 +1,583 @@ +using Polyphony.Routing; +using Polyphony.Tests.TestFixtures; +using Shouldly; +using Twig.Domain.Enums; +using Twig.Domain.Services.Process; +using Xunit; + +namespace Polyphony.Tests.Routing; + +/// +/// Cross-process template tests for composite plannable→plannable→implementable hierarchy chains. +/// Validates that phase detection routes correctly at each level of a three-tier hierarchy +/// across Basic, Agile, Scrum, and CMMI process templates. +/// +public sealed class CrossProcessPhaseDetectorTests +{ + /// + /// Defines the composite hierarchy structure for a single process template. + /// + private sealed record CompositeTemplate( + string Name, + string TopType, + string MiddleType, + string[] MiddleCapabilities, + string LeafType, + string ProposedState, + string InProgressState, + string CompletedState); + + private static readonly CompositeTemplate[] Templates = + [ + new("Basic", "Epic", "Issue", ["plannable"], "Task", "To Do", "Doing", "Done"), + new("Agile", "Epic", "User Story", ["plannable", "implementable"], "Task", "New", "Active", "Closed"), + new("Scrum", "Epic", "Product Backlog Item", ["plannable", "implementable"], "Task", "New", "Committed", "Done"), + new("CMMI", "Epic", "Requirement", ["plannable", "implementable"], "Task", "Proposed", "Active", "Closed"), + ]; + + public static IEnumerable AllTemplateNames => + Templates.Select(t => new object[] { t.Name }); + + public static IEnumerable IntermediateNoChildrenData => + Templates.Select(t => new object[] + { + t.Name, + Array.Exists(t.MiddleCapabilities, c => c == "implementable") + ? SdlcPhase.ReadyForImplementation + : SdlcPhase.NeedsSeeding, + Array.Exists(t.MiddleCapabilities, c => c == "implementable") + ? SdlcAction.Implement + : SdlcAction.Seed, + }); + + private static CompositeTemplate GetTemplate(string name) => + Templates.First(t => t.Name == name); + + private static PhaseDetector CreateDetector(CompositeTemplate template) + { + var config = new ProcessConfigBuilder() + .WithProcessTemplate(template.Name) + .WithType(template.TopType, ["plannable"]) + .WithType(template.MiddleType, template.MiddleCapabilities) + .WithType(template.LeafType, ["implementable"]) + .Build(); + return new PhaseDetector(config); + } + + // --- Scenario 1: Top-level plannable in Proposed → NeedsPlanning --- + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void TopLevel_InProposed_WithUnsortedChildren_ReturnsNeedsPlanning(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var epic = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.ProposedState).Build(); + var middle = new WorkItemBuilder().WithId(2).WithType(t.MiddleType).WithState(t.ProposedState).Build(); + + var result = detector.Detect(epic, [middle]); + + result.Phase.ShouldBe(SdlcPhase.NeedsPlanning); + result.Action.ShouldBe(SdlcAction.Plan); + } + + // --- Scenario 2: Intermediate plannable routes based on capabilities --- + + [Theory] + [MemberData(nameof(IntermediateNoChildrenData))] + public void IntermediatePlannable_InProgress_NoChildren_RoutesBasedOnCapabilities( + string templateName, string expectedPhase, string expectedAction) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var middle = new WorkItemBuilder().WithId(2).WithType(t.MiddleType).WithState(t.InProgressState).Build(); + + var result = detector.Detect(middle, []); + + result.Phase.ShouldBe(expectedPhase); + result.Action.ShouldBe(expectedAction); + } + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void IntermediatePlannable_AllLeafChildrenProposed_ReturnsReadyForImplementation(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var middle = new WorkItemBuilder().WithId(2).WithType(t.MiddleType).WithState(t.InProgressState).Build(); + var leaf1 = new WorkItemBuilder().WithId(10).WithType(t.LeafType).WithState(t.ProposedState).Build(); + var leaf2 = new WorkItemBuilder().WithId(11).WithType(t.LeafType).WithState(t.ProposedState).Build(); + + var result = detector.Detect(middle, [leaf1, leaf2]); + + result.Phase.ShouldBe(SdlcPhase.ReadyForImplementation); + result.Action.ShouldBe(SdlcAction.Implement); + } + + // --- Scenario 3: Implementable leaf routes based on its own state --- + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void ImplementableLeaf_InProposed_ReturnsReadyForImplementation(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var leaf = new WorkItemBuilder().WithId(3).WithType(t.LeafType).WithState(t.ProposedState).Build(); + + var result = detector.Detect(leaf, []); + + result.Phase.ShouldBe(SdlcPhase.ReadyForImplementation); + result.Action.ShouldBe(SdlcAction.Implement); + } + + // --- Scenario 4: All children complete at each level → ReadyForCompletion --- + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void TopLevel_AllChildrenCompleted_ReturnsReadyForCompletion(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var epic = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.InProgressState).Build(); + var middle1 = new WorkItemBuilder().WithId(2).WithType(t.MiddleType).WithState(t.CompletedState).Build(); + var middle2 = new WorkItemBuilder().WithId(3).WithType(t.MiddleType).WithState(t.CompletedState).Build(); + + var result = detector.Detect(epic, [middle1, middle2]); + + result.Phase.ShouldBe(SdlcPhase.ReadyForCompletion); + result.Action.ShouldBe(SdlcAction.Close); + } + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void IntermediatePlannable_AllLeafChildrenCompleted_ReturnsReadyForCompletion(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var middle = new WorkItemBuilder().WithId(2).WithType(t.MiddleType).WithState(t.InProgressState).Build(); + var leaf1 = new WorkItemBuilder().WithId(10).WithType(t.LeafType).WithState(t.CompletedState).Build(); + var leaf2 = new WorkItemBuilder().WithId(11).WithType(t.LeafType).WithState(t.CompletedState).Build(); + + var result = detector.Detect(middle, [leaf1, leaf2]); + + result.Phase.ShouldBe(SdlcPhase.ReadyForCompletion); + result.Action.ShouldBe(SdlcAction.Close); + } + + // --- Scenario 5: Mixed children states → InProgress --- + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void TopLevel_MixedChildrenStates_ReturnsInProgress(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var epic = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.InProgressState).Build(); + var completedMiddle = new WorkItemBuilder().WithId(2).WithType(t.MiddleType).WithState(t.CompletedState).Build(); + var proposedMiddle = new WorkItemBuilder().WithId(3).WithType(t.MiddleType).WithState(t.ProposedState).Build(); + + var result = detector.Detect(epic, [completedMiddle, proposedMiddle]); + + result.Phase.ShouldBe(SdlcPhase.InProgress); + result.Action.ShouldBe(SdlcAction.Monitor); + } + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void IntermediatePlannable_MixedLeafStates_ReturnsInProgress(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var middle = new WorkItemBuilder().WithId(2).WithType(t.MiddleType).WithState(t.InProgressState).Build(); + var doneLeaf = new WorkItemBuilder().WithId(10).WithType(t.LeafType).WithState(t.CompletedState).Build(); + var todoLeaf = new WorkItemBuilder().WithId(11).WithType(t.LeafType).WithState(t.ProposedState).Build(); + + var result = detector.Detect(middle, [doneLeaf, todoLeaf]); + + result.Phase.ShouldBe(SdlcPhase.InProgress); + result.Action.ShouldBe(SdlcAction.Monitor); + } + + // --- Additional: Top-level with all proposed children → ReadyForImplementation --- + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void TopLevel_AllChildrenProposed_ReturnsReadyForImplementation(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var epic = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.InProgressState).Build(); + var middle1 = new WorkItemBuilder().WithId(2).WithType(t.MiddleType).WithState(t.ProposedState).Build(); + var middle2 = new WorkItemBuilder().WithId(3).WithType(t.MiddleType).WithState(t.ProposedState).Build(); + + var result = detector.Detect(epic, [middle1, middle2]); + + result.Phase.ShouldBe(SdlcPhase.ReadyForImplementation); + result.Action.ShouldBe(SdlcAction.Implement); + } + + // --- Scenario 6: Top-level plannable-only in InProgress with no children → NeedsSeeding --- + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void TopLevel_InProgress_NoChildren_ReturnsNeedsSeeding(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var epic = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.InProgressState).Build(); + + var result = detector.Detect(epic, []); + + result.Phase.ShouldBe(SdlcPhase.NeedsSeeding); + result.Action.ShouldBe(SdlcAction.Seed); + } + + // --- Scenario 7: Implementable leaf in InProgress → InProgress --- + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void ImplementableLeaf_InProgress_ReturnsInProgress(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var leaf = new WorkItemBuilder().WithId(3).WithType(t.LeafType).WithState(t.InProgressState).Build(); + + var result = detector.Detect(leaf, []); + + result.Phase.ShouldBe(SdlcPhase.InProgress); + result.Action.ShouldBe(SdlcAction.Monitor); + } + + // --- Scenario 8: Terminal state — Completed → Done --- + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void AnyItem_InCompleted_ReturnsDone(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var item = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.CompletedState).Build(); + + var result = detector.Detect(item, []); + + result.Phase.ShouldBe(SdlcPhase.Done); + result.Action.ShouldBe(SdlcAction.None); + } + + // --- Scenario 9: Terminal state — Removed --- + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void AnyItem_InRemoved_ReturnsRemoved(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + var item = new WorkItemBuilder().WithId(1).WithType(t.LeafType).WithState("Removed").Build(); + + var result = detector.Detect(item, []); + + result.Phase.ShouldBe(SdlcPhase.Removed); + result.Action.ShouldBe(SdlcAction.None); + } + + // ═══════════════════════════════════════════════════════════════════ + // Scrum-specific: Three InProgress state variants + // (Approved, Committed, In Progress) all map to StateCategory.InProgress + // ═══════════════════════════════════════════════════════════════════ + + [Theory] + [InlineData("Approved")] + [InlineData("Committed")] + [InlineData("In Progress")] + public void ScrumInProgressVariant_MapsToStateCategoryInProgress(string state) + { + var category = StateCategoryResolver.Resolve(state, entries: null); + + category.ShouldBe(StateCategory.InProgress); + } + + // --- PBI (plannable+implementable) with Approved state --- + + [Fact] + public void ScrumPBI_InApproved_AllChildrenComplete_ReturnsReadyForCompletion() + { + var t = GetTemplate("Scrum"); + var detector = CreateDetector(t); + var pbi = new WorkItemBuilder().WithId(2).WithType("Product Backlog Item").WithState("Approved").Build(); + var task1 = new WorkItemBuilder().WithId(10).WithType("Task").WithState("Done").Build(); + var task2 = new WorkItemBuilder().WithId(11).WithType("Task").WithState("Done").Build(); + + var result = detector.Detect(pbi, [task1, task2]); + + result.Phase.ShouldBe(SdlcPhase.ReadyForCompletion); + result.Action.ShouldBe(SdlcAction.Close); + } + + [Fact] + public void ScrumPBI_InApproved_NoChildren_ReturnsReadyForImplementation() + { + var t = GetTemplate("Scrum"); + var detector = CreateDetector(t); + var pbi = new WorkItemBuilder().WithId(2).WithType("Product Backlog Item").WithState("Approved").Build(); + + var result = detector.Detect(pbi, []); + + result.Phase.ShouldBe(SdlcPhase.ReadyForImplementation); + result.Action.ShouldBe(SdlcAction.Implement); + } + + [Fact] + public void ScrumPBI_InApproved_MixedChildren_ReturnsInProgress() + { + var t = GetTemplate("Scrum"); + var detector = CreateDetector(t); + var pbi = new WorkItemBuilder().WithId(2).WithType("Product Backlog Item").WithState("Approved").Build(); + var doneTask = new WorkItemBuilder().WithId(10).WithType("Task").WithState("Done").Build(); + var newTask = new WorkItemBuilder().WithId(11).WithType("Task").WithState("New").Build(); + + var result = detector.Detect(pbi, [doneTask, newTask]); + + result.Phase.ShouldBe(SdlcPhase.InProgress); + result.Action.ShouldBe(SdlcAction.Monitor); + } + + // --- PBI with "In Progress" state (distinct from Committed/Approved) --- + + [Fact] + public void ScrumPBI_InInProgress_AllChildrenComplete_ReturnsReadyForCompletion() + { + var t = GetTemplate("Scrum"); + var detector = CreateDetector(t); + var pbi = new WorkItemBuilder().WithId(2).WithType("Product Backlog Item").WithState("In Progress").Build(); + var task1 = new WorkItemBuilder().WithId(10).WithType("Task").WithState("Done").Build(); + var task2 = new WorkItemBuilder().WithId(11).WithType("Task").WithState("Done").Build(); + + var result = detector.Detect(pbi, [task1, task2]); + + result.Phase.ShouldBe(SdlcPhase.ReadyForCompletion); + result.Action.ShouldBe(SdlcAction.Close); + } + + [Fact] + public void ScrumPBI_InInProgress_NoChildren_ReturnsReadyForImplementation() + { + var t = GetTemplate("Scrum"); + var detector = CreateDetector(t); + var pbi = new WorkItemBuilder().WithId(2).WithType("Product Backlog Item").WithState("In Progress").Build(); + + var result = detector.Detect(pbi, []); + + result.Phase.ShouldBe(SdlcPhase.ReadyForImplementation); + result.Action.ShouldBe(SdlcAction.Implement); + } + + // --- Task (implementable-only) with Approved and "In Progress" states --- + + [Fact] + public void ScrumTask_InApproved_ReturnsInProgress() + { + var t = GetTemplate("Scrum"); + var detector = CreateDetector(t); + var task = new WorkItemBuilder().WithId(10).WithType("Task").WithState("Approved").Build(); + + var result = detector.Detect(task, []); + + result.Phase.ShouldBe(SdlcPhase.InProgress); + result.Action.ShouldBe(SdlcAction.Monitor); + } + + [Fact] + public void ScrumTask_InInProgress_ReturnsInProgress() + { + var t = GetTemplate("Scrum"); + var detector = CreateDetector(t); + var task = new WorkItemBuilder().WithId(10).WithType("Task").WithState("In Progress").Build(); + + var result = detector.Detect(task, []); + + result.Phase.ShouldBe(SdlcPhase.InProgress); + result.Action.ShouldBe(SdlcAction.Monitor); + } + + // --- Epic (plannable-only) with Approved and "In Progress" states --- + + [Fact] + public void ScrumEpic_InApproved_AllChildrenComplete_ReturnsReadyForCompletion() + { + var t = GetTemplate("Scrum"); + var detector = CreateDetector(t); + var epic = new WorkItemBuilder().WithId(1).WithType("Epic").WithState("Approved").Build(); + var pbi1 = new WorkItemBuilder().WithId(2).WithType("Product Backlog Item").WithState("Done").Build(); + var pbi2 = new WorkItemBuilder().WithId(3).WithType("Product Backlog Item").WithState("Done").Build(); + + var result = detector.Detect(epic, [pbi1, pbi2]); + + result.Phase.ShouldBe(SdlcPhase.ReadyForCompletion); + result.Action.ShouldBe(SdlcAction.Close); + } + + [Fact] + public void ScrumEpic_InApproved_NoChildren_ReturnsNeedsSeeding() + { + var t = GetTemplate("Scrum"); + var detector = CreateDetector(t); + var epic = new WorkItemBuilder().WithId(1).WithType("Epic").WithState("Approved").Build(); + + var result = detector.Detect(epic, []); + + result.Phase.ShouldBe(SdlcPhase.NeedsSeeding); + result.Action.ShouldBe(SdlcAction.Seed); + } + + [Fact] + public void ScrumEpic_InInProgress_AllChildrenComplete_ReturnsReadyForCompletion() + { + var t = GetTemplate("Scrum"); + var detector = CreateDetector(t); + var epic = new WorkItemBuilder().WithId(1).WithType("Epic").WithState("In Progress").Build(); + var pbi1 = new WorkItemBuilder().WithId(2).WithType("Product Backlog Item").WithState("Done").Build(); + var pbi2 = new WorkItemBuilder().WithId(3).WithType("Product Backlog Item").WithState("Done").Build(); + + var result = detector.Detect(epic, [pbi1, pbi2]); + + result.Phase.ShouldBe(SdlcPhase.ReadyForCompletion); + result.Action.ShouldBe(SdlcAction.Close); + } + + [Fact] + public void ScrumEpic_InInProgress_NoChildren_ReturnsNeedsSeeding() + { + var t = GetTemplate("Scrum"); + var detector = CreateDetector(t); + var epic = new WorkItemBuilder().WithId(1).WithType("Epic").WithState("In Progress").Build(); + + var result = detector.Detect(epic, []); + + result.Phase.ShouldBe(SdlcPhase.NeedsSeeding); + result.Action.ShouldBe(SdlcAction.Seed); + } + + // ═══════════════════════════════════════════════════════════════════ + // CMMI-specific: Resolved state mapping and routing + // ═══════════════════════════════════════════════════════════════════ + + [Fact] + public void CmmiResolvedState_MapsToStateCategoryResolved() + { + // Explicit verification that the CMMI "Resolved" state name + // resolves to StateCategory.Resolved via the fallback heuristic. + var category = StateCategoryResolver.Resolve("Resolved", entries: null); + + category.ShouldBe(StateCategory.Resolved); + } + + [Fact] + public void CmmiRequirement_InResolved_AllChildrenComplete_ReturnsReadyForCompletion() + { + // Key CMMI edge case: a plannable+implementable Requirement in the + // Resolved state with all children complete should route to ReadyForCompletion. + var t = GetTemplate("CMMI"); + var detector = CreateDetector(t); + var requirement = new WorkItemBuilder().WithId(2).WithType("Requirement").WithState("Resolved").Build(); + var task1 = new WorkItemBuilder().WithId(10).WithType("Task").WithState("Closed").Build(); + var task2 = new WorkItemBuilder().WithId(11).WithType("Task").WithState("Closed").Build(); + + var result = detector.Detect(requirement, [task1, task2]); + + result.Phase.ShouldBe(SdlcPhase.ReadyForCompletion); + result.Action.ShouldBe(SdlcAction.Close); + } + + [Fact] + public void CmmiRequirement_InResolved_NoChildren_ReturnsReadyForImplementation() + { + // Plannable+implementable item in Resolved with no children + // behaves like InProgress — routes to direct implementation. + var t = GetTemplate("CMMI"); + var detector = CreateDetector(t); + var requirement = new WorkItemBuilder().WithId(2).WithType("Requirement").WithState("Resolved").Build(); + + var result = detector.Detect(requirement, []); + + result.Phase.ShouldBe(SdlcPhase.ReadyForImplementation); + result.Action.ShouldBe(SdlcAction.Implement); + } + + [Fact] + public void CmmiRequirement_InResolved_MixedChildren_ReturnsInProgress() + { + var t = GetTemplate("CMMI"); + var detector = CreateDetector(t); + var requirement = new WorkItemBuilder().WithId(2).WithType("Requirement").WithState("Resolved").Build(); + var doneTask = new WorkItemBuilder().WithId(10).WithType("Task").WithState("Closed").Build(); + var proposedTask = new WorkItemBuilder().WithId(11).WithType("Task").WithState("Proposed").Build(); + + var result = detector.Detect(requirement, [doneTask, proposedTask]); + + result.Phase.ShouldBe(SdlcPhase.InProgress); + result.Action.ShouldBe(SdlcAction.Monitor); + } + + [Fact] + public void CmmiTask_InResolved_ReturnsInProgress() + { + // Implementable-only item in Resolved maps to InProgress/Monitor. + var t = GetTemplate("CMMI"); + var detector = CreateDetector(t); + var task = new WorkItemBuilder().WithId(10).WithType("Task").WithState("Resolved").Build(); + + var result = detector.Detect(task, []); + + result.Phase.ShouldBe(SdlcPhase.InProgress); + result.Action.ShouldBe(SdlcAction.Monitor); + } + + [Fact] + public void CmmiEpic_InResolved_AllChildrenComplete_ReturnsReadyForCompletion() + { + // Plannable-only Epic in Resolved with all children complete → ReadyForCompletion. + var t = GetTemplate("CMMI"); + var detector = CreateDetector(t); + var epic = new WorkItemBuilder().WithId(1).WithType("Epic").WithState("Resolved").Build(); + var req1 = new WorkItemBuilder().WithId(2).WithType("Requirement").WithState("Closed").Build(); + var req2 = new WorkItemBuilder().WithId(3).WithType("Requirement").WithState("Closed").Build(); + + var result = detector.Detect(epic, [req1, req2]); + + result.Phase.ShouldBe(SdlcPhase.ReadyForCompletion); + result.Action.ShouldBe(SdlcAction.Close); + } + + [Fact] + public void CmmiEpic_InResolved_NoChildren_ReturnsNeedsSeeding() + { + // Plannable-only Epic in Resolved with no children → NeedsSeeding. + var t = GetTemplate("CMMI"); + var detector = CreateDetector(t); + var epic = new WorkItemBuilder().WithId(1).WithType("Epic").WithState("Resolved").Build(); + + var result = detector.Detect(epic, []); + + result.Phase.ShouldBe(SdlcPhase.NeedsSeeding); + result.Action.ShouldBe(SdlcAction.Seed); + } + + // ═══════════════════════════════════════════════════════════════════ + // Unknown phase: type not registered in process config + // ═══════════════════════════════════════════════════════════════════ + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void UnregisteredType_ReturnsUnknown(string templateName) + { + var t = GetTemplate(templateName); + var detector = CreateDetector(t); + // "Bug" is not registered in any template config + var item = new WorkItemBuilder().WithId(99).WithType("Bug").WithState(t.InProgressState).Build(); + + var result = detector.Detect(item, []); + + result.Phase.ShouldBe(SdlcPhase.Unknown); + result.Action.ShouldBe(SdlcAction.None); + } +} diff --git a/tests/Polyphony.Tests/Routing/CrossProcessTransitionValidatorTests.cs b/tests/Polyphony.Tests/Routing/CrossProcessTransitionValidatorTests.cs new file mode 100644 index 00000000..bc1770c0 --- /dev/null +++ b/tests/Polyphony.Tests/Routing/CrossProcessTransitionValidatorTests.cs @@ -0,0 +1,641 @@ +using Polyphony.Configuration; +using Polyphony.Routing; +using Polyphony.Tests.TestFixtures; +using Shouldly; +using Xunit; + +namespace Polyphony.Tests.Routing; + +/// +/// Cross-process template tests for . +/// Validates that lifecycle event transitions route correctly across +/// Basic, Agile, Scrum, and CMMI process templates. +/// +public sealed class CrossProcessTransitionValidatorTests +{ + /// + /// Defines the transition table and state names for a single process template. + /// + private sealed record TransitionTemplate( + string Name, + string TopType, + string MiddleType, + string LeafType, + string ProposedState, + string InProgressState, + string CompletedState, + Dictionary> Transitions); + + private static readonly TransitionTemplate[] Templates = + [ + new("Basic", + TopType: "Epic", + MiddleType: "Issue", + LeafType: "Task", + ProposedState: "To Do", + InProgressState: "Doing", + CompletedState: "Done", + Transitions: new Dictionary>(StringComparer.OrdinalIgnoreCase) + { + ["Epic"] = new(StringComparer.OrdinalIgnoreCase) + { + ["begin_planning"] = "Doing", + ["all_children_complete"] = "Done", + }, + ["Issue"] = new(StringComparer.OrdinalIgnoreCase) + { + ["begin_planning"] = "Doing", + ["begin_implementation"] = "Doing", + ["implementation_complete"] = "Done", + ["all_children_complete"] = "Done", + }, + ["Task"] = new(StringComparer.OrdinalIgnoreCase) + { + ["begin_implementation"] = "Doing", + ["implementation_complete"] = "Done", + }, + }), + new("Agile", + TopType: "Epic", + MiddleType: "User Story", + LeafType: "Task", + ProposedState: "New", + InProgressState: "Active", + CompletedState: "Closed", + Transitions: new Dictionary>(StringComparer.OrdinalIgnoreCase) + { + ["Epic"] = new(StringComparer.OrdinalIgnoreCase) + { + ["begin_planning"] = "Active", + ["all_children_complete"] = "Closed", + }, + ["User Story"] = new(StringComparer.OrdinalIgnoreCase) + { + ["begin_planning"] = "Active", + ["begin_implementation"] = "Active", + ["implementation_complete"] = "Closed", + ["all_children_complete"] = "Closed", + }, + ["Task"] = new(StringComparer.OrdinalIgnoreCase) + { + ["begin_implementation"] = "Active", + ["implementation_complete"] = "Closed", + }, + }), + new("Scrum", + TopType: "Epic", + MiddleType: "Product Backlog Item", + LeafType: "Task", + ProposedState: "New", + InProgressState: "Committed", + CompletedState: "Done", + Transitions: new Dictionary>(StringComparer.OrdinalIgnoreCase) + { + ["Epic"] = new(StringComparer.OrdinalIgnoreCase) + { + ["begin_planning"] = "Committed", + ["all_children_complete"] = "Done", + }, + ["Product Backlog Item"] = new(StringComparer.OrdinalIgnoreCase) + { + ["begin_planning"] = "Committed", + ["begin_implementation"] = "Committed", + ["implementation_complete"] = "Done", + ["all_children_complete"] = "Done", + }, + ["Task"] = new(StringComparer.OrdinalIgnoreCase) + { + ["begin_implementation"] = "Committed", + ["implementation_complete"] = "Done", + }, + }), + new("CMMI", + TopType: "Epic", + MiddleType: "Requirement", + LeafType: "Task", + ProposedState: "Proposed", + InProgressState: "Active", + CompletedState: "Closed", + Transitions: new Dictionary>(StringComparer.OrdinalIgnoreCase) + { + ["Epic"] = new(StringComparer.OrdinalIgnoreCase) + { + ["begin_planning"] = "Active", + ["all_children_complete"] = "Closed", + }, + ["Requirement"] = new(StringComparer.OrdinalIgnoreCase) + { + ["begin_planning"] = "Active", + ["begin_implementation"] = "Active", + ["resolve"] = "Resolved", + ["implementation_complete"] = "Closed", + ["all_children_complete"] = "Closed", + }, + ["Task"] = new(StringComparer.OrdinalIgnoreCase) + { + ["begin_implementation"] = "Active", + ["resolve"] = "Resolved", + ["implementation_complete"] = "Closed", + }, + }), + ]; + + public static IEnumerable AllTemplateNames => + Templates.Select(t => new object[] { t.Name }); + + private static TransitionTemplate GetTemplate(string name) => + Templates.First(t => t.Name == name); + + private static TransitionValidator CreateValidator(TransitionTemplate template) + { + var builder = new ProcessConfigBuilder() + .WithProcessTemplate(template.Name); + + foreach (var (typeName, transitions) in template.Transitions) + { + string[] capabilities = typeName == template.TopType + ? ["plannable"] + : typeName == template.LeafType + ? ["implementable"] + : ["plannable", "implementable"]; + + builder.WithType(typeName, capabilities, transitions); + } + + return new TransitionValidator(builder.Build()); + } + + // ── begin_planning: happy path ─────────────────────────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void BeginPlanning_TopLevel_WhenProposed_ReturnsValid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.ProposedState).Build(); + + var result = validator.Validate(item, "begin_planning", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe(t.Transitions[t.TopType]["begin_planning"]); + } + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void BeginPlanning_MiddleType_WhenProposed_ReturnsValid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(2).WithType(t.MiddleType).WithState(t.ProposedState).Build(); + + var result = validator.Validate(item, "begin_planning", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe(t.Transitions[t.MiddleType]["begin_planning"]); + } + + // ── begin_planning: precondition failure ───────────────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void BeginPlanning_WhenInProgress_ReturnsInvalid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.InProgressState).Build(); + + var result = validator.Validate(item, "begin_planning", []); + + result.IsValid.ShouldBeFalse(); + result.Message!.ShouldContain("begin_planning"); + result.Message!.ShouldContain("Proposed"); + } + + // ── begin_implementation: happy path ───────────────────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void BeginImplementation_Leaf_WhenProposed_ReturnsValid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(10).WithType(t.LeafType).WithState(t.ProposedState).Build(); + + var result = validator.Validate(item, "begin_implementation", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe(t.Transitions[t.LeafType]["begin_implementation"]); + } + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void BeginImplementation_Leaf_WhenInProgress_ReturnsValid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(10).WithType(t.LeafType).WithState(t.InProgressState).Build(); + + var result = validator.Validate(item, "begin_implementation", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe(t.Transitions[t.LeafType]["begin_implementation"]); + } + + // ── begin_implementation: precondition failure ─────────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void BeginImplementation_WhenCompleted_ReturnsInvalid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(10).WithType(t.LeafType).WithState(t.CompletedState).Build(); + + var result = validator.Validate(item, "begin_implementation", []); + + result.IsValid.ShouldBeFalse(); + result.Message!.ShouldContain("begin_implementation"); + result.Message!.ShouldContain("Proposed or InProgress"); + } + + // ── implementation_complete: happy path ────────────────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void ImplementationComplete_Leaf_WhenInProgress_ReturnsValid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(10).WithType(t.LeafType).WithState(t.InProgressState).Build(); + + var result = validator.Validate(item, "implementation_complete", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe(t.Transitions[t.LeafType]["implementation_complete"]); + } + + // ── implementation_complete: precondition failure ──────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void ImplementationComplete_WhenProposed_ReturnsInvalid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(10).WithType(t.LeafType).WithState(t.ProposedState).Build(); + + var result = validator.Validate(item, "implementation_complete", []); + + result.IsValid.ShouldBeFalse(); + result.Message!.ShouldContain("implementation_complete"); + result.Message!.ShouldContain("InProgress"); + } + + // ── all_children_complete: happy path ──────────────────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void AllChildrenComplete_TopLevel_WhenAllDone_ReturnsValid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.InProgressState).Build(); + var child1 = new WorkItemBuilder().WithId(10).WithType(t.MiddleType).WithState(t.CompletedState).Build(); + var child2 = new WorkItemBuilder().WithId(11).WithType(t.MiddleType).WithState(t.CompletedState).Build(); + + var result = validator.Validate(item, "all_children_complete", [child1, child2]); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe(t.Transitions[t.TopType]["all_children_complete"]); + } + + // ── all_children_complete: precondition failure ────────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void AllChildrenComplete_WhenChildNotDone_ReturnsInvalid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.InProgressState).Build(); + var child1 = new WorkItemBuilder().WithId(10).WithType(t.MiddleType).WithState(t.CompletedState).Build(); + var child2 = new WorkItemBuilder().WithId(11).WithType(t.MiddleType).WithState(t.InProgressState).Build(); + + var result = validator.Validate(item, "all_children_complete", [child1, child2]); + + result.IsValid.ShouldBeFalse(); + result.Message!.ShouldContain("child #11"); + } + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void AllChildrenComplete_WhenNoChildren_ReturnsInvalid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.InProgressState).Build(); + + var result = validator.Validate(item, "all_children_complete", []); + + result.IsValid.ShouldBeFalse(); + result.Message!.ShouldContain("no children"); + } + + // ── unknown event ─────────────────────────────────────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void UnknownEvent_ReturnsInvalid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.ProposedState).Build(); + + var result = validator.Validate(item, "nonexistent_event", []); + + result.IsValid.ShouldBeFalse(); + result.Message!.ShouldContain("Unknown event"); + } + + // ── target state correctness ──────────────────────────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void ValidTransition_IncludesCorrectTargetStateInResult(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(10).WithType(t.LeafType).WithState(t.InProgressState).Build(); + + var result = validator.Validate(item, "implementation_complete", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe(t.CompletedState); + result.Message!.ShouldContain(t.CompletedState); + } + + // ── begin_implementation: middle type happy paths ────────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void BeginImplementation_MiddleType_WhenProposed_ReturnsValid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(2).WithType(t.MiddleType).WithState(t.ProposedState).Build(); + + var result = validator.Validate(item, "begin_implementation", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe(t.Transitions[t.MiddleType]["begin_implementation"]); + } + + // ── implementation_complete: middle type happy path ────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void ImplementationComplete_MiddleType_WhenInProgress_ReturnsValid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(2).WithType(t.MiddleType).WithState(t.InProgressState).Build(); + + var result = validator.Validate(item, "implementation_complete", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe(t.Transitions[t.MiddleType]["implementation_complete"]); + } + + // ── all_children_complete: middle type happy path ──────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void AllChildrenComplete_MiddleType_WhenInProgress_AllDone_ReturnsValid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(2).WithType(t.MiddleType).WithState(t.InProgressState).Build(); + var child1 = new WorkItemBuilder().WithId(10).WithType(t.LeafType).WithState(t.CompletedState).Build(); + var child2 = new WorkItemBuilder().WithId(11).WithType(t.LeafType).WithState(t.CompletedState).Build(); + + var result = validator.Validate(item, "all_children_complete", [child1, child2]); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe(t.Transitions[t.MiddleType]["all_children_complete"]); + } + + // ── begin_planning: when Completed (additional precondition) ──── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void BeginPlanning_WhenCompleted_ReturnsInvalid(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.CompletedState).Build(); + + var result = validator.Validate(item, "begin_planning", []); + + result.IsValid.ShouldBeFalse(); + result.Message!.ShouldContain("begin_planning"); + result.Message!.ShouldContain("Proposed"); + } + + // ── event not defined for type ────────────────────────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void BeginPlanning_NotDefinedForLeaf_ReturnsUnknownEvent(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(10).WithType(t.LeafType).WithState(t.ProposedState).Build(); + + var result = validator.Validate(item, "begin_planning", []); + + result.IsValid.ShouldBeFalse(); + result.Message!.ShouldContain("Unknown event"); + } + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void BeginImplementation_NotDefinedForTopLevel_ReturnsUnknownEvent(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(1).WithType(t.TopType).WithState(t.ProposedState).Build(); + + var result = validator.Validate(item, "begin_implementation", []); + + result.IsValid.ShouldBeFalse(); + result.Message!.ShouldContain("Unknown event"); + } + + // ── unknown work item type ────────────────────────────────────── + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public void UnknownWorkItemType_ReturnsStructuredError(string templateName) + { + var t = GetTemplate(templateName); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(99).WithType("UnknownType").WithState(t.ProposedState).Build(); + + var result = validator.Validate(item, "begin_planning", []); + + result.IsValid.ShouldBeFalse(); + result.Message!.ShouldContain("UnknownType"); + result.WorkItemId.ShouldBe(99); + result.Event.ShouldBe("begin_planning"); + } + + // ═══════════════════════════════════════════════════════════════════ + // Scrum-specific: Three InProgress state variants for transitions + // (Approved, Committed, In Progress) all satisfy InProgress preconditions + // ═══════════════════════════════════════════════════════════════════ + + [Theory] + [InlineData("Approved")] + [InlineData("Committed")] + [InlineData("In Progress")] + public void ScrumBeginImplementation_Task_WhenInProgressVariant_ReturnsValid(string state) + { + var t = GetTemplate("Scrum"); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(10).WithType("Task").WithState(state).Build(); + + var result = validator.Validate(item, "begin_implementation", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe("Committed"); + } + + [Theory] + [InlineData("Approved")] + [InlineData("Committed")] + [InlineData("In Progress")] + public void ScrumImplementationComplete_Task_WhenInProgressVariant_ReturnsValid(string state) + { + var t = GetTemplate("Scrum"); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(10).WithType("Task").WithState(state).Build(); + + var result = validator.Validate(item, "implementation_complete", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe("Done"); + } + + [Theory] + [InlineData("Approved")] + [InlineData("Committed")] + [InlineData("In Progress")] + public void ScrumBeginImplementation_PBI_WhenInProgressVariant_ReturnsValid(string state) + { + var t = GetTemplate("Scrum"); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(2).WithType("Product Backlog Item").WithState(state).Build(); + + var result = validator.Validate(item, "begin_implementation", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe("Committed"); + } + + [Theory] + [InlineData("Approved")] + [InlineData("Committed")] + [InlineData("In Progress")] + public void ScrumAllChildrenComplete_PBI_WhenInProgressVariant_AllDone_ReturnsValid(string state) + { + var t = GetTemplate("Scrum"); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(2).WithType("Product Backlog Item").WithState(state).Build(); + var child1 = new WorkItemBuilder().WithId(10).WithType("Task").WithState("Done").Build(); + var child2 = new WorkItemBuilder().WithId(11).WithType("Task").WithState("Done").Build(); + + var result = validator.Validate(item, "all_children_complete", [child1, child2]); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe("Done"); + } + + [Theory] + [InlineData("Approved")] + [InlineData("Committed")] + [InlineData("In Progress")] + public void ScrumAllChildrenComplete_Epic_WhenInProgressVariant_AllDone_ReturnsValid(string state) + { + var t = GetTemplate("Scrum"); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(1).WithType("Epic").WithState(state).Build(); + var child1 = new WorkItemBuilder().WithId(2).WithType("Product Backlog Item").WithState("Done").Build(); + var child2 = new WorkItemBuilder().WithId(3).WithType("Product Backlog Item").WithState("Done").Build(); + + var result = validator.Validate(item, "all_children_complete", [child1, child2]); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe("Done"); + } + + // ═══════════════════════════════════════════════════════════════════ + // CMMI-specific: Active → Resolved transition via "resolve" event + // ═══════════════════════════════════════════════════════════════════ + + [Fact] + public void CmmiResolve_Requirement_WhenActive_ReturnsValid() + { + var t = GetTemplate("CMMI"); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(2).WithType("Requirement").WithState("Active").Build(); + + var result = validator.Validate(item, "resolve", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe("Resolved"); + } + + [Fact] + public void CmmiResolve_Task_WhenActive_ReturnsValid() + { + var t = GetTemplate("CMMI"); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(10).WithType("Task").WithState("Active").Build(); + + var result = validator.Validate(item, "resolve", []); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe("Resolved"); + } + + [Fact] + public void CmmiResolve_NotDefinedForEpic_ReturnsInvalid() + { + var t = GetTemplate("CMMI"); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(1).WithType("Epic").WithState("Active").Build(); + + var result = validator.Validate(item, "resolve", []); + + result.IsValid.ShouldBeFalse(); + result.Message!.ShouldContain("Unknown event"); + } + + [Fact] + public void CmmiAllChildrenComplete_Requirement_InResolved_ReturnsValid() + { + // CMMI Requirement in Resolved state with all children complete + // should allow the all_children_complete transition to Closed. + var t = GetTemplate("CMMI"); + var validator = CreateValidator(t); + var item = new WorkItemBuilder().WithId(2).WithType("Requirement").WithState("Resolved").Build(); + var child1 = new WorkItemBuilder().WithId(10).WithType("Task").WithState("Closed").Build(); + var child2 = new WorkItemBuilder().WithId(11).WithType("Task").WithState("Closed").Build(); + + var result = validator.Validate(item, "all_children_complete", [child1, child2]); + + result.IsValid.ShouldBeTrue(); + result.TargetState.ShouldBe("Closed"); + } +} diff --git a/tests/Polyphony.Tests/Routing/DepthBudgetTests.cs b/tests/Polyphony.Tests/Routing/DepthBudgetTests.cs new file mode 100644 index 00000000..136a7850 --- /dev/null +++ b/tests/Polyphony.Tests/Routing/DepthBudgetTests.cs @@ -0,0 +1,426 @@ +using NSubstitute; +using Polyphony.Configuration; +using Polyphony.Routing; +using Polyphony.Tests.TestFixtures; +using Shouldly; +using Twig.Domain.Aggregates; +using Twig.Domain.Interfaces; +using Xunit; + +namespace Polyphony.Tests.Routing; + +/// +/// Verifies that HierarchyWalker correctly reports plannable depth in its output +/// so that the depth guard can enforce the budget. +/// +/// Architectural boundary: Depth budget enforcement is handled by +/// scripts/depth-guard.ps1 (a deterministic conductor agent), which receives +/// the current recursion depth and emits allowed=false when the limit is +/// exceeded. The .NET layer's responsibility is to accurately represent the +/// hierarchy with capability annotations — it does not reject deep trees itself. +/// Pester tests in scripts/depth-guard.Tests.ps1 cover the enforcement logic. +/// These xUnit tests verify the .NET side of the contract. +/// +public sealed class DepthBudgetTests +{ + private readonly IWorkItemRepository _repository = Substitute.For(); + + /// + /// Process config with 5 plannable types to enable deep plannable hierarchies. + /// "Portfolio", "Initiative", "Epic", "Feature", and "Story" are all plannable; + /// "Task" is implementable-only. + /// + private readonly ProcessConfig _config = new ProcessConfigBuilder() + .WithType("Portfolio", ["plannable"]) + .WithType("Initiative", ["plannable"]) + .WithType("Epic", ["plannable"]) + .WithType("Feature", ["plannable"]) + .WithType("Story", ["plannable", "implementable"]) + .WithType("Task", ["implementable"]) + .Build(); + + private HierarchyWalker CreateWalker() => new(_config, _repository); + + /// + /// Recursively counts the maximum number of nested plannable levels + /// in a tree. Only nodes whose + /// contain "plannable" are counted. + /// + private static int CountMaxPlannableDepth(HierarchyResult? node) + { + if (node is null) + return 0; + + var isPlannable = node.Capabilities.Contains("plannable"); + var childMax = 0; + + if (node.Children is { Length: > 0 }) + { + foreach (var child in node.Children) + { + var childDepth = CountMaxPlannableDepth(child); + if (childDepth > childMax) + childMax = childDepth; + } + } + + return isPlannable ? 1 + childMax : childMax; + } + + // ────────────────────────────────────────────── + // Plannable depth counting from HierarchyResult + // ────────────────────────────────────────────── + + [Fact] + public async Task SinglePlannableNode_HasPlannableDepthOfOne() + { + var epic = new WorkItemBuilder() + .WithId(1).WithType("Epic").WithTitle("Root Epic").WithState("Doing").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + + var result = await CreateWalker().WalkAsync(1, maxDepth: 0, CancellationToken.None); + + result.ShouldNotBeNull(); + CountMaxPlannableDepth(result).ShouldBe(1); + } + + [Fact] + public async Task ImplementableOnlyNode_HasPlannableDepthOfZero() + { + var task = new WorkItemBuilder() + .WithId(1).WithType("Task").WithTitle("Leaf Task").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(task); + + var result = await CreateWalker().WalkAsync(1, maxDepth: 0, CancellationToken.None); + + result.ShouldNotBeNull(); + CountMaxPlannableDepth(result).ShouldBe(0); + } + + [Fact] + public async Task TwoPlannableLevels_ReportsDepthTwo() + { + // Epic → Feature (both plannable) + var epic = new WorkItemBuilder() + .WithId(1).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var feature = new WorkItemBuilder() + .WithId(10).WithType("Feature").WithTitle("Feature").WithState("Doing").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { feature }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List()); + + var result = await CreateWalker().WalkAsync(1, maxDepth: 3, CancellationToken.None); + + result.ShouldNotBeNull(); + CountMaxPlannableDepth(result).ShouldBe(2); + } + + [Fact] + public async Task FourPlannableLevels_WithinBudget() + { + // Portfolio → Initiative → Epic → Feature (4 plannable levels = within budget) + var portfolio = new WorkItemBuilder() + .WithId(1).WithType("Portfolio").WithTitle("Portfolio").WithState("Doing").Build(); + var initiative = new WorkItemBuilder() + .WithId(10).WithType("Initiative").WithTitle("Initiative").WithState("Doing").Build(); + var epic = new WorkItemBuilder() + .WithId(100).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var feature = new WorkItemBuilder() + .WithId(1000).WithType("Feature").WithTitle("Feature").WithState("Doing").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(portfolio); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { initiative }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { epic }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List { feature }); + _repository.GetChildrenAsync(1000, Arg.Any()) + .Returns(new List()); + + var result = await CreateWalker().WalkAsync(1, maxDepth: 5, CancellationToken.None); + + result.ShouldNotBeNull(); + var plannableDepth = CountMaxPlannableDepth(result); + plannableDepth.ShouldBe(4); + // 4 plannable levels is within the budget (≤4 is acceptable) + plannableDepth.ShouldBeLessThanOrEqualTo(4); + } + + [Fact] + public async Task FivePlannableLevels_ExceedsBudget() + { + // Portfolio → Initiative → Epic → Feature → Story (5 plannable levels = exceeds budget) + // depth-guard.ps1 would set allowed=false when depth ≥ MaxDepth. + // The .NET layer must faithfully report all 5 levels so the PS guard can detect it. + var portfolio = new WorkItemBuilder() + .WithId(1).WithType("Portfolio").WithTitle("Portfolio").WithState("Doing").Build(); + var initiative = new WorkItemBuilder() + .WithId(10).WithType("Initiative").WithTitle("Initiative").WithState("Doing").Build(); + var epic = new WorkItemBuilder() + .WithId(100).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var feature = new WorkItemBuilder() + .WithId(1000).WithType("Feature").WithTitle("Feature").WithState("Doing").Build(); + var story = new WorkItemBuilder() + .WithId(10000).WithType("Story").WithTitle("Story").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(portfolio); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { initiative }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { epic }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List { feature }); + _repository.GetChildrenAsync(1000, Arg.Any()) + .Returns(new List { story }); + _repository.GetChildrenAsync(10000, Arg.Any()) + .Returns(new List()); + + var result = await CreateWalker().WalkAsync(1, maxDepth: 6, CancellationToken.None); + + result.ShouldNotBeNull(); + var plannableDepth = CountMaxPlannableDepth(result); + plannableDepth.ShouldBe(5); + // >4 plannable levels exceeds the budget — depth-guard.ps1 would reject this + plannableDepth.ShouldBeGreaterThan(4); + } + + // ────────────────────────────────────────────── + // Non-plannable nodes don't inflate depth count + // ────────────────────────────────────────────── + + [Fact] + public async Task PlannableWithImplementableLeaf_DoesNotCountImplementableInDepth() + { + // Epic (plannable) → Task (implementable) — plannable depth is 1, not 2 + var epic = new WorkItemBuilder() + .WithId(1).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(10).WithType("Task").WithTitle("Task").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List()); + + var result = await CreateWalker().WalkAsync(1, maxDepth: 3, CancellationToken.None); + + result.ShouldNotBeNull(); + CountMaxPlannableDepth(result).ShouldBe(1); + } + + [Fact] + public async Task InterleavedPlannableAndImplementable_CountsOnlyPlannableNodes() + { + // Epic (plannable) → Task (implementable) — only 1 plannable level despite 2 total levels + // This verifies that implementable-only nodes interleaved in the tree + // don't inflate the plannable depth count. + var epic = new WorkItemBuilder() + .WithId(1).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(10).WithType("Task").WithTitle("Task").WithState("Doing").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { task }); + + var result = await CreateWalker().WalkAsync(1, maxDepth: 2, CancellationToken.None); + + result.ShouldNotBeNull(); + result.Children.ShouldNotBeNull(); + result.Capabilities.ShouldContain("plannable"); + result.Children[0].Capabilities.ShouldNotContain("plannable"); + CountMaxPlannableDepth(result).ShouldBe(1); + } + + // ────────────────────────────────────────────── + // maxDepth parameter truncates before exceeding budget + // ────────────────────────────────────────────── + + [Fact] + public async Task MaxDepthTruncation_PreventsDeepPlannableTraversal() + { + // Tree has 5 plannable levels, but maxDepth=3 truncates at level 3. + // The walker should only return 3 plannable levels. + var portfolio = new WorkItemBuilder() + .WithId(1).WithType("Portfolio").WithTitle("Portfolio").WithState("Doing").Build(); + var initiative = new WorkItemBuilder() + .WithId(10).WithType("Initiative").WithTitle("Initiative").WithState("Doing").Build(); + var epic = new WorkItemBuilder() + .WithId(100).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(portfolio); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { initiative }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { epic }); + // epic at depth 2 should NOT have its children loaded when maxDepth=2 + // (children would be at depth 3, but maxDepth truncates) + + var result = await CreateWalker().WalkAsync(1, maxDepth: 2, CancellationToken.None); + + result.ShouldNotBeNull(); + CountMaxPlannableDepth(result).ShouldBe(3); + // Even though more plannable levels exist, maxDepth prevents traversal + result.Children![0].Children![0].Children.ShouldBeNull(); + await _repository.DidNotReceive() + .GetChildrenAsync(100, Arg.Any()); + } + + // ────────────────────────────────────────────── + // Branching hierarchies — deepest plannable path wins + // ────────────────────────────────────────────── + + [Fact] + public async Task BranchingHierarchy_ReportsDeepestPlannablePath() + { + // Epic → Feature (plannable, depth 2) + // → Task (implementable, depth 1) + // Max plannable depth should be 2 (via Epic → Feature path) + var epic = new WorkItemBuilder() + .WithId(1).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var feature = new WorkItemBuilder() + .WithId(10).WithType("Feature").WithTitle("Feature").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(11).WithType("Task").WithTitle("Task").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { feature, task }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List()); + + var result = await CreateWalker().WalkAsync(1, maxDepth: 3, CancellationToken.None); + + result.ShouldNotBeNull(); + CountMaxPlannableDepth(result).ShouldBe(2); + } + + [Fact] + public async Task BranchingHierarchy_AsymmetricPlannableDepths() + { + // Portfolio → Initiative → Epic (3 plannable via left branch) + // → Feature (2 plannable via right branch) + // Max plannable depth should be 3 + var portfolio = new WorkItemBuilder() + .WithId(1).WithType("Portfolio").WithTitle("Portfolio").WithState("Doing").Build(); + var initiative = new WorkItemBuilder() + .WithId(10).WithType("Initiative").WithTitle("Initiative").WithState("Doing").Build(); + var feature = new WorkItemBuilder() + .WithId(11).WithType("Feature").WithTitle("Feature").WithState("Doing").Build(); + var epic = new WorkItemBuilder() + .WithId(100).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(portfolio); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { initiative, feature }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { epic }); + _repository.GetChildrenAsync(11, Arg.Any()) + .Returns(new List()); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List()); + + var result = await CreateWalker().WalkAsync(1, maxDepth: 4, CancellationToken.None); + + result.ShouldNotBeNull(); + CountMaxPlannableDepth(result).ShouldBe(3); + } + + // ────────────────────────────────────────────── + // Capabilities are faithfully annotated for budget decisions + // ────────────────────────────────────────────── + + [Fact] + public async Task DeepHierarchy_AllNodesHaveCorrectCapabilities() + { + // Verify that each level in a deep plannable tree has the correct + // capabilities annotated so the depth guard can make accurate decisions. + var portfolio = new WorkItemBuilder() + .WithId(1).WithType("Portfolio").WithTitle("Portfolio").WithState("Doing").Build(); + var initiative = new WorkItemBuilder() + .WithId(10).WithType("Initiative").WithTitle("Initiative").WithState("Doing").Build(); + var epic = new WorkItemBuilder() + .WithId(100).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var story = new WorkItemBuilder() + .WithId(1000).WithType("Story").WithTitle("Story").WithState("To Do").Build(); + var task = new WorkItemBuilder() + .WithId(10000).WithType("Task").WithTitle("Task").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(portfolio); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { initiative }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { epic }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List { story }); + _repository.GetChildrenAsync(1000, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(10000, Arg.Any()) + .Returns(new List()); + + var result = await CreateWalker().WalkAsync(1, maxDepth: 5, CancellationToken.None); + + result.ShouldNotBeNull(); + + // Level 0: Portfolio — plannable only + result.Capabilities.ShouldBe(["plannable"]); + + // Level 1: Initiative — plannable only + var level1 = result.Children![0]; + level1.Capabilities.ShouldBe(["plannable"]); + + // Level 2: Epic — plannable only + var level2 = level1.Children![0]; + level2.Capabilities.ShouldBe(["plannable"]); + + // Level 3: Story — plannable + implementable + var level3 = level2.Children![0]; + level3.Capabilities.ShouldBe(["plannable", "implementable"]); + + // Level 4: Task — implementable only (not plannable, stops the plannable chain) + var level4 = level3.Children![0]; + level4.Capabilities.ShouldBe(["implementable"]); + + // Total plannable depth = 4 (Portfolio, Initiative, Epic, Story) + CountMaxPlannableDepth(result).ShouldBe(4); + } + + [Fact] + public async Task UnknownTypeInHierarchy_HasZeroPlannableContribution() + { + // Epic (plannable) → Bug (unknown type, no capabilities) → Feature (plannable) + // Plannable depth = 2 (Epic and Feature counted; Bug is not plannable but + // its subtree still contributes if it contains plannable children) + var epic = new WorkItemBuilder() + .WithId(1).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var bug = new WorkItemBuilder() + .WithId(10).WithType("Bug").WithTitle("Bug").WithState("Doing").Build(); + var feature = new WorkItemBuilder() + .WithId(100).WithType("Feature").WithTitle("Feature").WithState("Doing").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { bug }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { feature }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List()); + + var result = await CreateWalker().WalkAsync(1, maxDepth: 4, CancellationToken.None); + + result.ShouldNotBeNull(); + // Bug has empty capabilities — not plannable + result.Children![0].Capabilities.ShouldBeEmpty(); + // Feature beneath Bug is still plannable + result.Children[0].Children![0].Capabilities.ShouldContain("plannable"); + // Total plannable depth = 2 (Epic + Feature; Bug doesn't count) + CountMaxPlannableDepth(result).ShouldBe(2); + } +} diff --git a/tests/Polyphony.Tests/Routing/HierarchyTierTests.cs b/tests/Polyphony.Tests/Routing/HierarchyTierTests.cs new file mode 100644 index 00000000..bbce2e90 --- /dev/null +++ b/tests/Polyphony.Tests/Routing/HierarchyTierTests.cs @@ -0,0 +1,571 @@ +using NSubstitute; +using Polyphony.Configuration; +using Polyphony.Routing; +using Polyphony.Tests.TestFixtures; +using Shouldly; +using Twig.Domain.Aggregates; +using Twig.Domain.Interfaces; +using Xunit; + +namespace Polyphony.Tests.Routing; + +/// +/// Tests for HierarchyWalker across 2-tier (Issue→Task), 3-tier (Epic→Middle→Task), +/// and 4-tier (Epic→Feature→Issue→Task) hierarchies. +/// Verifies that capability annotations are correct at every level for each process template. +/// +public sealed class HierarchyTierTests +{ + private readonly IWorkItemRepository _repository = Substitute.For(); + + // --- Template definitions for parameterized 3-tier tests --- + + /// + /// Defines the 3-tier hierarchy structure for a single process template. + /// + private sealed record TemplateDefinition( + string Name, + string TopType, + string[] TopCapabilities, + string MiddleType, + string[] MiddleCapabilities, + string LeafType, + string[] LeafCapabilities); + + private static readonly TemplateDefinition[] Templates = + [ + new("Basic", "Epic", ["plannable"], "Issue", ["plannable", "implementable"], "Task", ["implementable"]), + new("Agile", "Epic", ["plannable"], "User Story", ["plannable", "implementable"], "Task", ["implementable"]), + new("Scrum", "Epic", ["plannable"], "Product Backlog Item", ["plannable", "implementable"], "Task", ["implementable"]), + new("CMMI", "Epic", ["plannable"], "Requirement", ["plannable", "implementable"], "Task", ["implementable"]), + ]; + + public static IEnumerable AllTemplateNames => + Templates.Select(t => new object[] { t.Name }); + + private static TemplateDefinition GetTemplate(string name) => + Templates.First(t => t.Name == name); + + private static ProcessConfig BuildConfig(TemplateDefinition template) => + new ProcessConfigBuilder() + .WithProcessTemplate(template.Name) + .WithType(template.TopType, template.TopCapabilities) + .WithType(template.MiddleType, template.MiddleCapabilities) + .WithType(template.LeafType, template.LeafCapabilities) + .Build(); + + private HierarchyWalker CreateWalker(ProcessConfig config) => new(config, _repository); + + // =================================================================== + // 2-tier: Issue → Task (Basic config, simplest hierarchy) + // =================================================================== + + private static readonly ProcessConfig TwoTierConfig = new ProcessConfigBuilder() + .WithProcessTemplate("Basic") + .WithType("Issue", ["plannable", "implementable"]) + .WithType("Task", ["implementable"]) + .Build(); + + [Fact] + public async Task TwoTier_IssueToTask_WalksCorrectly() + { + var issue = new WorkItemBuilder() + .WithId(1).WithType("Issue").WithTitle("Parent Issue").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(10).WithType("Task").WithTitle("Child Task").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(issue); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(TwoTierConfig); + var result = await walker.WalkAsync(1, maxDepth: 2, CancellationToken.None); + + result.ShouldNotBeNull(); + result.WorkItemId.ShouldBe(1); + result.Type.ShouldBe("Issue"); + result.Children.ShouldNotBeNull(); + result.Children.Length.ShouldBe(1); + result.Children[0].WorkItemId.ShouldBe(10); + result.Children[0].Type.ShouldBe("Task"); + } + + [Fact] + public async Task TwoTier_IssueToTask_AnnotatesCapabilitiesCorrectly() + { + var issue = new WorkItemBuilder() + .WithId(1).WithType("Issue").WithTitle("Parent Issue").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(10).WithType("Task").WithTitle("Child Task").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(issue); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(TwoTierConfig); + var result = await walker.WalkAsync(1, maxDepth: 2, CancellationToken.None); + + result.ShouldNotBeNull(); + result.Capabilities.ShouldBe(["plannable", "implementable"]); + result.Children.ShouldNotBeNull(); + result.Children[0].Capabilities.ShouldBe(["implementable"]); + } + + [Fact] + public async Task TwoTier_IssueWithMultipleTasks_AllChildrenAnnotated() + { + var issue = new WorkItemBuilder() + .WithId(1).WithType("Issue").WithTitle("Parent Issue").WithState("Doing").Build(); + var task1 = new WorkItemBuilder() + .WithId(10).WithType("Task").WithTitle("Task One").WithState("To Do").Build(); + var task2 = new WorkItemBuilder() + .WithId(11).WithType("Task").WithTitle("Task Two").WithState("Doing").Build(); + var task3 = new WorkItemBuilder() + .WithId(12).WithType("Task").WithTitle("Task Three").WithState("Done").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(issue); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { task1, task2, task3 }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List()); + _repository.GetChildrenAsync(11, Arg.Any()) + .Returns(new List()); + _repository.GetChildrenAsync(12, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(TwoTierConfig); + var result = await walker.WalkAsync(1, maxDepth: 2, CancellationToken.None); + + result.ShouldNotBeNull(); + result.Children.ShouldNotBeNull(); + result.Children.Length.ShouldBe(3); + + foreach (var child in result.Children) + { + child.Capabilities.ShouldBe(["implementable"]); + } + } + + [Fact] + public async Task TwoTier_LeafTaskHasNoChildren() + { + var issue = new WorkItemBuilder() + .WithId(1).WithType("Issue").WithTitle("Parent Issue").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(10).WithType("Task").WithTitle("Child Task").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(issue); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(TwoTierConfig); + var result = await walker.WalkAsync(1, maxDepth: 2, CancellationToken.None); + + result.ShouldNotBeNull(); + result.Children.ShouldNotBeNull(); + result.Children[0].Children.ShouldBeNull(); + } + + // =================================================================== + // 3-tier: Epic → Middle → Task (parameterized across all 4 templates) + // =================================================================== + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public async Task ThreeTier_WalksFullHierarchy(string templateName) + { + var t = GetTemplate(templateName); + var config = BuildConfig(t); + + var epic = new WorkItemBuilder() + .WithId(1).WithType(t.TopType).WithTitle("Root").WithState("Doing").Build(); + var middle = new WorkItemBuilder() + .WithId(10).WithType(t.MiddleType).WithTitle("Middle").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(100).WithType(t.LeafType).WithTitle("Leaf").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { middle }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(config); + var result = await walker.WalkAsync(1, maxDepth: 3, CancellationToken.None); + + result.ShouldNotBeNull(); + result.WorkItemId.ShouldBe(1); + result.Type.ShouldBe(t.TopType); + + result.Children.ShouldNotBeNull(); + result.Children.Length.ShouldBe(1); + result.Children[0].WorkItemId.ShouldBe(10); + result.Children[0].Type.ShouldBe(t.MiddleType); + + result.Children[0].Children.ShouldNotBeNull(); + result.Children[0].Children!.Length.ShouldBe(1); + result.Children[0].Children![0].WorkItemId.ShouldBe(100); + result.Children[0].Children![0].Type.ShouldBe(t.LeafType); + } + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public async Task ThreeTier_AnnotatesCapabilitiesAtEveryLevel(string templateName) + { + var t = GetTemplate(templateName); + var config = BuildConfig(t); + + var epic = new WorkItemBuilder() + .WithId(1).WithType(t.TopType).WithTitle("Root").WithState("Doing").Build(); + var middle = new WorkItemBuilder() + .WithId(10).WithType(t.MiddleType).WithTitle("Middle").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(100).WithType(t.LeafType).WithTitle("Leaf").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { middle }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(config); + var result = await walker.WalkAsync(1, maxDepth: 3, CancellationToken.None); + + result.ShouldNotBeNull(); + result.Capabilities.ShouldBe(t.TopCapabilities); + + result.Children.ShouldNotBeNull(); + result.Children[0].Capabilities.ShouldBe(t.MiddleCapabilities); + + result.Children[0].Children.ShouldNotBeNull(); + result.Children[0].Children![0].Capabilities.ShouldBe(t.LeafCapabilities); + } + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public async Task ThreeTier_LeafNodeHasNoChildren(string templateName) + { + var t = GetTemplate(templateName); + var config = BuildConfig(t); + + var epic = new WorkItemBuilder() + .WithId(1).WithType(t.TopType).WithTitle("Root").WithState("Doing").Build(); + var middle = new WorkItemBuilder() + .WithId(10).WithType(t.MiddleType).WithTitle("Middle").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(100).WithType(t.LeafType).WithTitle("Leaf").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { middle }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(config); + var result = await walker.WalkAsync(1, maxDepth: 3, CancellationToken.None); + + result.ShouldNotBeNull(); + result.Children.ShouldNotBeNull(); + result.Children[0].Children.ShouldNotBeNull(); + result.Children[0].Children![0].Children.ShouldBeNull(); + } + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public async Task ThreeTier_TopLevelIsPlannable(string templateName) + { + var t = GetTemplate(templateName); + var config = BuildConfig(t); + + var epic = new WorkItemBuilder() + .WithId(1).WithType(t.TopType).WithTitle("Root").WithState("Doing").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(config); + var result = await walker.WalkAsync(1, maxDepth: 3, CancellationToken.None); + + result.ShouldNotBeNull(); + result.Capabilities.ShouldContain("plannable"); + } + + [Theory] + [MemberData(nameof(AllTemplateNames))] + public async Task ThreeTier_LeafIsImplementable(string templateName) + { + var t = GetTemplate(templateName); + var config = BuildConfig(t); + + var epic = new WorkItemBuilder() + .WithId(1).WithType(t.TopType).WithTitle("Root").WithState("Doing").Build(); + var middle = new WorkItemBuilder() + .WithId(10).WithType(t.MiddleType).WithTitle("Middle").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(100).WithType(t.LeafType).WithTitle("Leaf").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { middle }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(config); + var result = await walker.WalkAsync(1, maxDepth: 3, CancellationToken.None); + + result.ShouldNotBeNull(); + var leaf = result.Children![0].Children![0]; + leaf.Capabilities.ShouldContain("implementable"); + leaf.Capabilities.ShouldNotContain("plannable"); + } + + // =================================================================== + // 4-tier: Epic → Feature → Issue → Task (hypothetical deep hierarchy) + // =================================================================== + + private static readonly ProcessConfig FourTierConfig = new ProcessConfigBuilder() + .WithProcessTemplate("Basic") + .WithType("Epic", ["plannable"]) + .WithType("Feature", ["plannable"]) + .WithType("Issue", ["plannable", "implementable"]) + .WithType("Task", ["implementable"]) + .Build(); + + [Fact] + public async Task FourTier_WalksFullHierarchy() + { + var epic = new WorkItemBuilder() + .WithId(1).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var feature = new WorkItemBuilder() + .WithId(10).WithType("Feature").WithTitle("Feature").WithState("Doing").Build(); + var issue = new WorkItemBuilder() + .WithId(100).WithType("Issue").WithTitle("Issue").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(1000).WithType("Task").WithTitle("Task").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { feature }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { issue }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(1000, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(FourTierConfig); + var result = await walker.WalkAsync(1, maxDepth: 4, CancellationToken.None); + + result.ShouldNotBeNull(); + result.WorkItemId.ShouldBe(1); + result.Type.ShouldBe("Epic"); + + result.Children.ShouldNotBeNull(); + result.Children.Length.ShouldBe(1); + var featureNode = result.Children[0]; + featureNode.WorkItemId.ShouldBe(10); + featureNode.Type.ShouldBe("Feature"); + + featureNode.Children.ShouldNotBeNull(); + featureNode.Children!.Length.ShouldBe(1); + var issueNode = featureNode.Children[0]; + issueNode.WorkItemId.ShouldBe(100); + issueNode.Type.ShouldBe("Issue"); + + issueNode.Children.ShouldNotBeNull(); + issueNode.Children!.Length.ShouldBe(1); + var taskNode = issueNode.Children[0]; + taskNode.WorkItemId.ShouldBe(1000); + taskNode.Type.ShouldBe("Task"); + } + + [Fact] + public async Task FourTier_AnnotatesCapabilitiesAtEveryLevel() + { + var epic = new WorkItemBuilder() + .WithId(1).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var feature = new WorkItemBuilder() + .WithId(10).WithType("Feature").WithTitle("Feature").WithState("Doing").Build(); + var issue = new WorkItemBuilder() + .WithId(100).WithType("Issue").WithTitle("Issue").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(1000).WithType("Task").WithTitle("Task").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { feature }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { issue }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(1000, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(FourTierConfig); + var result = await walker.WalkAsync(1, maxDepth: 4, CancellationToken.None); + + result.ShouldNotBeNull(); + result.Capabilities.ShouldBe(["plannable"]); + + var featureNode = result.Children![0]; + featureNode.Capabilities.ShouldBe(["plannable"]); + + var issueNode = featureNode.Children![0]; + issueNode.Capabilities.ShouldBe(["plannable", "implementable"]); + + var taskNode = issueNode.Children![0]; + taskNode.Capabilities.ShouldBe(["implementable"]); + } + + [Fact] + public async Task FourTier_LeafTaskHasNoChildren() + { + var epic = new WorkItemBuilder() + .WithId(1).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var feature = new WorkItemBuilder() + .WithId(10).WithType("Feature").WithTitle("Feature").WithState("Doing").Build(); + var issue = new WorkItemBuilder() + .WithId(100).WithType("Issue").WithTitle("Issue").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(1000).WithType("Task").WithTitle("Task").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { feature }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { issue }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(1000, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(FourTierConfig); + var result = await walker.WalkAsync(1, maxDepth: 4, CancellationToken.None); + + result.ShouldNotBeNull(); + var taskNode = result.Children![0].Children![0].Children![0]; + taskNode.Children.ShouldBeNull(); + } + + [Fact] + public async Task FourTier_IntermediateLevelsArePlannable() + { + var epic = new WorkItemBuilder() + .WithId(1).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var feature = new WorkItemBuilder() + .WithId(10).WithType("Feature").WithTitle("Feature").WithState("Doing").Build(); + var issue = new WorkItemBuilder() + .WithId(100).WithType("Issue").WithTitle("Issue").WithState("Doing").Build(); + var task = new WorkItemBuilder() + .WithId(1000).WithType("Task").WithTitle("Task").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { feature }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { issue }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List { task }); + _repository.GetChildrenAsync(1000, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(FourTierConfig); + var result = await walker.WalkAsync(1, maxDepth: 4, CancellationToken.None); + + result.ShouldNotBeNull(); + + // Epic is plannable-only + result.Capabilities.ShouldContain("plannable"); + result.Capabilities.ShouldNotContain("implementable"); + + // Feature is plannable-only + var featureNode = result.Children![0]; + featureNode.Capabilities.ShouldContain("plannable"); + featureNode.Capabilities.ShouldNotContain("implementable"); + + // Issue is plannable AND implementable + var issueNode = featureNode.Children![0]; + issueNode.Capabilities.ShouldContain("plannable"); + issueNode.Capabilities.ShouldContain("implementable"); + + // Task is implementable-only + var taskNode = issueNode.Children![0]; + taskNode.Capabilities.ShouldContain("implementable"); + taskNode.Capabilities.ShouldNotContain("plannable"); + } + + [Fact] + public async Task FourTier_WithBranchingChildren_AllAnnotatedCorrectly() + { + var epic = new WorkItemBuilder() + .WithId(1).WithType("Epic").WithTitle("Epic").WithState("Doing").Build(); + var feature1 = new WorkItemBuilder() + .WithId(10).WithType("Feature").WithTitle("Feature 1").WithState("Doing").Build(); + var feature2 = new WorkItemBuilder() + .WithId(11).WithType("Feature").WithTitle("Feature 2").WithState("Doing").Build(); + var issue1 = new WorkItemBuilder() + .WithId(100).WithType("Issue").WithTitle("Issue 1").WithState("Doing").Build(); + var issue2 = new WorkItemBuilder() + .WithId(101).WithType("Issue").WithTitle("Issue 2").WithState("Doing").Build(); + var task1 = new WorkItemBuilder() + .WithId(1000).WithType("Task").WithTitle("Task 1").WithState("To Do").Build(); + var task2 = new WorkItemBuilder() + .WithId(1001).WithType("Task").WithTitle("Task 2").WithState("To Do").Build(); + + _repository.GetByIdAsync(1, Arg.Any()).Returns(epic); + _repository.GetChildrenAsync(1, Arg.Any()) + .Returns(new List { feature1, feature2 }); + _repository.GetChildrenAsync(10, Arg.Any()) + .Returns(new List { issue1 }); + _repository.GetChildrenAsync(11, Arg.Any()) + .Returns(new List { issue2 }); + _repository.GetChildrenAsync(100, Arg.Any()) + .Returns(new List { task1 }); + _repository.GetChildrenAsync(101, Arg.Any()) + .Returns(new List { task2 }); + _repository.GetChildrenAsync(1000, Arg.Any()) + .Returns(new List()); + _repository.GetChildrenAsync(1001, Arg.Any()) + .Returns(new List()); + + var walker = CreateWalker(FourTierConfig); + var result = await walker.WalkAsync(1, maxDepth: 4, CancellationToken.None); + + result.ShouldNotBeNull(); + + // Two features under the epic + result.Children.ShouldNotBeNull(); + result.Children.Length.ShouldBe(2); + + foreach (var featureNode in result.Children) + { + featureNode.Capabilities.ShouldBe(["plannable"]); + featureNode.Children.ShouldNotBeNull(); + featureNode.Children!.Length.ShouldBe(1); + + var issueNode = featureNode.Children[0]; + issueNode.Capabilities.ShouldBe(["plannable", "implementable"]); + issueNode.Children.ShouldNotBeNull(); + issueNode.Children!.Length.ShouldBe(1); + + var taskNode = issueNode.Children[0]; + taskNode.Capabilities.ShouldBe(["implementable"]); + taskNode.Children.ShouldBeNull(); + } + } +}