feat: throw PipelineFailedException on pipeline failure for CI exit codes

Add PipelineFailedException that is thrown after the pipeline summary
is printed when one or more modules have failed. This ensures CI/CD
systems receive a non-zero exit code when the pipeline fails.

The exception includes:
- The PipelineSummary for inspection
- List of failed module names
- Clear error message

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: thomhurst

src/ModularPipelines/Engine/Executors/ExecutionOrchestrator.cs

@@ -1,5 +1,6 @@
 using System.Diagnostics;
 using Microsoft.Extensions.Logging;
+using ModularPipelines.Enums;
 using ModularPipelines.Exceptions;
 using ModularPipelines.Helpers;
 using ModularPipelines.Models;
@@ -147,6 +148,16 @@ private async Task<PipelineSummary> OnEnd(OrganizedModules organizedModules, Sto
                 _engineCancellationToken.Reason);
         }
 
+        // Throw exception if pipeline failed - this ensures non-zero exit code in CI
+        if (pipelineSummary.Status == Status.Failed)
+        {
+            var failedModules = pipelineSummary.GetFailedModuleResults()
+                .Select(r => r.ModuleType.Name)
+                .ToList();
+
+            throw new PipelineFailedException(pipelineSummary, failedModules);
+        }
+
         return pipelineSummary;
     }
 

src/ModularPipelines/Exceptions/PipelineFailedException.cs

@@ -0,0 +1,59 @@
+using ModularPipelines.Models;
+
+namespace ModularPipelines.Exceptions;
+
+/// <summary>
+/// Thrown when the pipeline completes with one or more failed modules.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This exception is thrown after the pipeline summary has been printed to indicate
+/// that the pipeline did not complete successfully. This ensures that CI/CD systems
+/// receive a non-zero exit code when the pipeline fails.
+/// </para>
+/// <para><b>When this is thrown:</b></para>
+/// <list type="bullet">
+/// <item>After the pipeline summary is printed</item>
+/// <item>When one or more modules have failed</item>
+/// </list>
+/// <para><b>Properties available:</b></para>
+/// <list type="bullet">
+/// <item><see cref="Summary"/> - The pipeline summary containing details of all module results</item>
+/// <item><see cref="FailedModules"/> - List of module names that failed</item>
+/// </list>
+/// </remarks>
+/// <seealso cref="PipelineException"/>
+public class PipelineFailedException : PipelineException
+{
+    /// <summary>
+    /// Gets the pipeline summary containing details of all module results.
+    /// </summary>
+    public PipelineSummary Summary { get; }
+
+    /// <summary>
+    /// Gets the names of the modules that failed.
+    /// </summary>
+    public IReadOnlyList<string> FailedModules { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PipelineFailedException"/> class.
+    /// </summary>
+    /// <param name="summary">The pipeline summary.</param>
+    /// <param name="failedModules">The names of modules that failed.</param>
+    public PipelineFailedException(PipelineSummary summary, IReadOnlyList<string> failedModules)
+        : base(FormatMessage(failedModules))
+    {
+        Summary = summary;
+        FailedModules = failedModules;
+    }
+
+    private static string FormatMessage(IReadOnlyList<string> failedModules)
+    {
+        if (failedModules.Count == 1)
+        {
+            return $"Pipeline failed: {failedModules[0]} failed.";
+        }
+
+        return $"Pipeline failed: {failedModules.Count} modules failed ({string.Join(", ", failedModules)}).";
+    }
+}