chore: save local changes

Author: Aitomates

CLAUDE.md

@@ -0,0 +1,69 @@
+# gsd-orchestrator
+
+Autonomous GitHub workflow engine. Reads issues, plans code changes via Claude (MCP), branches, edits, commits, opens PRs, and generates tests — driven by a state machine. Production-grade .NET 10 C# with enterprise patterns.
+
+## Project Context
+
+See `.planning/PROJECT.md` for goals, milestone status, and requirements.
+
+**Current milestone**: v3.0 — multi-repo support, test generation, PR review loop. All 5 phases complete, 35 tests green.
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Language | C# / .NET 10 |
+| State machine | Custom `GsdStateMachine` with 11 `IWorkflowState` implementations |
+| Claude integration | MCP stdio client (`McpStdioClient` / `IMcpClient`) — JSON-RPC over subprocess |
+| Resilience | Polly (`Microsoft.Extensions.Resilience`) |
+| Logging | Serilog with structured JSON output |
+| DI | `Microsoft.Extensions.DependencyInjection` + `IHost` |
+| Checkpointing | File-based (`FileCheckpointStore`) — namespaced per `{owner}_{repo}_{workflowId}.json` |
+| Auth | GitHub PAT (`GitHubPatProvider`) via env var |
+| Tests | xUnit + NSubstitute |
+
+## State Machine Flow
+
+```
+Idle → Triaging → Analyzing → Branching → Editing → Committing
+     → TestGenerating → Reviewing → Validating → Documenting → PrCreating
+```
+
+Each state implements `IWorkflowState` in `src/GsdOrchestrator/Workflows/States/`.
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `src/GsdOrchestrator/Program.cs` | DI wiring, host setup, CLI entrypoint |
+| `src/GsdOrchestrator/Workflows/GsdStateMachine.cs` | State machine orchestrator |
+| `src/GsdOrchestrator/Mcp/McpStdioClient.cs` | JSON-RPC stdio client to Claude |
+| `src/GsdOrchestrator/Mcp/McpToolDispatcher.cs` | Tool dispatch over MCP |
+| `src/GsdOrchestrator/Checkpointing/FileCheckpointStore.cs` | Workflow persistence |
+| `src/GsdOrchestrator/Workflows/Models/RepoConfigLoader.cs` | `GSD_REPOS` JSON config |
+
+## Configuration
+
+All configuration is environment-variable driven (`.env` or shell):
+- `GSD_REPOS` — JSON array of `{owner, repo}` objects for multi-repo support
+- `GITHUB_TOKEN` — PAT for GitHub API
+- `ANTHROPIC_API_KEY` — or via MCP config
+- `GSD_CHECKPOINT_DIR` — defaults to `state/checkpoints/`
+
+## Build & Test
+
+```powershell
+dotnet build src/GsdOrchestrator.sln
+dotnet test src/GsdOrchestrator.Tests/GsdOrchestrator.Tests.csproj
+```
+
+## Conventions
+
+- `PascalCase` for types, `camelCase` for locals, `_camelCase` for private fields
+- State classes are self-contained — inject only what they need, return `IWorkflowState` for transitions
+- Never access `HttpClient` or GitHub API directly from state classes — go through injected services
+- Tests use NSubstitute mocks, never live API calls
+
+## GSD Workflow
+
+Use `/gsd:plan-phase` before any multi-file change. Use `/gsd:quick` for single-file fixes.

coverage-results/2cc7c2ec-58e3-42e1-844e-e1248c401094/coverage.cobertura.xml

@@ -0,0 +1,6 @@
+import os
+base = "C:/PersonalRepo/portfolio/gsd-orchestrator/src/GsdOrchestrator.Tests"
+content = open("C:/PersonalRepo/portfolio/gsd-orchestrator/validating_template.cs").read()
+with open(f"{base}/States/ValidatingStateTests.cs", "w") as f:
+    f.write(content)
+print("done")

coverage-results/567d92fc-bc21-498c-9bd7-90b876780eb6/coverage.cobertura.xml

@@ -0,0 +1,82 @@
+using GsdOrchestrator.Auth;
+using Microsoft.Extensions.Configuration;
+using NSubstitute;
+using Xunit;
+
+namespace GsdOrchestrator.Tests;
+
+/// <summary>
+/// Tests for GitHubPatProvider — reads GitHub PAT from IConfiguration.
+/// </summary>
+public class GitHubPatProviderTests
+{
+    private static IConfiguration BuildConfig(string? token)
+    {
+        var config = Substitute.For<IConfiguration>();
+        config["GITHUB_PERSONAL_ACCESS_TOKEN"].Returns(token);
+        return config;
+    }
+
+    // PATPROV-01: valid ghp_ token is accepted and stored
+    [Fact]
+    public void Constructor_ValidGhpToken_StoresToken()
+    {
+        var config = BuildConfig("ghp_abc123XYZ");
+        var sut = new GitHubPatProvider(config);
+        Assert.Equal("ghp_abc123XYZ", sut.Token);
+    }
+
+    // PATPROV-01: valid ghs_ token is accepted
+    [Fact]
+    public void Constructor_ValidGhsToken_StoresToken()
+    {
+        var config = BuildConfig("ghs_servicesecret99");
+        var sut = new GitHubPatProvider(config);
+        Assert.Equal("ghs_servicesecret99", sut.Token);
+    }
+
+    // PATPROV-01: valid github_pat_ fine-grained token is accepted
+    [Fact]
+    public void Constructor_ValidGithubPatPrefixToken_StoresToken()
+    {
+        var config = BuildConfig("github_pat_11ABCDE0000_LONGTOKEN");
+        var sut = new GitHubPatProvider(config);
+        Assert.Equal("github_pat_11ABCDE0000_LONGTOKEN", sut.Token);
+    }
+
+    // PATPROV-02: missing token throws InvalidOperationException
+    [Fact]
+    public void Constructor_NullToken_ThrowsInvalidOperationException()
+    {
+        var config = BuildConfig(null);
+        var ex = Assert.Throws<InvalidOperationException>(() => new GitHubPatProvider(config));
+        Assert.Contains("GITHUB_PERSONAL_ACCESS_TOKEN", ex.Message);
+    }
+
+    // PATPROV-02: whitespace-only token throws InvalidOperationException
+    [Fact]
+    public void Constructor_WhitespaceToken_ThrowsInvalidOperationException()
+    {
+        var config = BuildConfig("   ");
+        var ex = Assert.Throws<InvalidOperationException>(() => new GitHubPatProvider(config));
+        Assert.Contains("GITHUB_PERSONAL_ACCESS_TOKEN", ex.Message);
+    }
+
+    // PATPROV-03: token with wrong prefix throws InvalidOperationException
+    [Fact]
+    public void Constructor_WrongPrefixToken_ThrowsInvalidOperationException()
+    {
+        var config = BuildConfig("xgh_invalidtoken123");
+        var ex = Assert.Throws<InvalidOperationException>(() => new GitHubPatProvider(config));
+        Assert.Contains("valid GitHub token", ex.Message);
+    }
+
+    // PATPROV-03: plain token with no prefix throws
+    [Fact]
+    public void Constructor_PlainStringToken_ThrowsInvalidOperationException()
+    {
+        var config = BuildConfig("mysecrettoken");
+        var ex = Assert.Throws<InvalidOperationException>(() => new GitHubPatProvider(config));
+        Assert.Contains("valid GitHub token", ex.Message);
+    }
+}

coverage-results/7acf5f7a-00e1-43ed-8c5f-920b77563b7d/coverage.cobertura.xml

@@ -0,0 +1,157 @@
+using System.Text.Json.Nodes;
+using GsdOrchestrator.Checkpointing;
+using GsdOrchestrator.Mcp;
+using GsdOrchestrator.Workflows;
+using GsdOrchestrator.Workflows.Models;
+using GsdOrchestrator.Workflows.States;
+using Microsoft.Extensions.Logging.Abstractions;
+using NSubstitute;
+using Polly.Registry;
+using Xunit;
+
+namespace GsdOrchestrator.Tests;
+
+/// <summary>
+/// Additional tests covering GsdStateMachine gaps: GetState, PostFailureCommentAsync.
+/// </summary>
+public class GsdStateMachineAdditionalTests
+{
+    private static GsdStateMachine BuildSut(
+        ICheckpointStore checkpoints,
+        IWorkflowState[] states,
+        IMcpClient? mcpClient = null)
+    {
+        var client = mcpClient ?? Substitute.For<IMcpClient>();
+        var registry = new ResiliencePipelineRegistry<string>();
+        registry.TryAddBuilder("mcp-tools", (b, _) => { });
+        var dispatcher = new McpToolDispatcher(
+            client, registry, NullLogger<McpToolDispatcher>.Instance);
+        return new GsdStateMachine(
+            checkpoints, dispatcher, states, NullLogger<GsdStateMachine>.Instance);
+    }
+
+    private static IWorkflowState MakeState(WorkflowState from, WorkflowState to)
+    {
+        var s = Substitute.For<IWorkflowState>();
+        s.State.Returns(from);
+        s.ExecuteAsync(Arg.Any<GsdWorkflowContext>(), Arg.Any<CancellationToken>())
+         .Returns(ci => Task.FromResult(ci.Arg<GsdWorkflowContext>() with { CurrentState = to }));
+        return s;
+    }
+
+    // SM-GETSTATE-01: GetState returns registered state handler
+    [Fact]
+    public void GetState_RegisteredState_ReturnsHandler()
+    {
+        var checkpoints = Substitute.For<ICheckpointStore>();
+        var idleState = MakeState(WorkflowState.Idle, WorkflowState.Done);
+        var sut = BuildSut(checkpoints, [idleState]);
+
+        var handler = sut.GetState(WorkflowState.Idle);
+
+        Assert.NotNull(handler);
+        Assert.Equal(WorkflowState.Idle, handler.State);
+    }
+
+    // SM-GETSTATE-02: GetState for unregistered state throws InvalidOperationException
+    [Fact]
+    public void GetState_UnregisteredState_ThrowsInvalidOperationException()
+    {
+        var checkpoints = Substitute.For<ICheckpointStore>();
+        var sut = BuildSut(checkpoints, []);
+
+        var ex = Assert.Throws<InvalidOperationException>(
+            () => sut.GetState(WorkflowState.Idle));
+        Assert.Contains("Idle", ex.Message);
+    }
+
+    // SM-FAILURE-01: on failure, add_issue_comment is called with failure details
+    [Fact]
+    public async Task RunAsync_StateThrowsException_PostsFailureComment()
+    {
+        var checkpoints = Substitute.For<ICheckpointStore>();
+        checkpoints.SaveAsync(Arg.Any<GsdWorkflowContext>(), Arg.Any<CancellationToken>())
+                   .Returns(Task.CompletedTask);
+
+        var mcp = Substitute.For<IMcpClient>();
+        mcp.CallToolAsync(Arg.Any<string>(), Arg.Any<JsonObject>(), Arg.Any<CancellationToken>())
+           .Returns(Task.FromResult(new McpToolResult("", false)));
+
+        var failingState = Substitute.For<IWorkflowState>();
+        failingState.State.Returns(WorkflowState.Idle);
+        failingState.ExecuteAsync(Arg.Any<GsdWorkflowContext>(), Arg.Any<CancellationToken>())
+                    .Returns<Task<GsdWorkflowContext>>(_ => throw new InvalidOperationException("boom"));
+
+        var sut = BuildSut(checkpoints, [failingState], mcp);
+
+        var ctx = await sut.RunAsync("owner", "repo", 1, triageModeOnly: false, CancellationToken.None);
+
+        Assert.Equal(WorkflowState.Failed, ctx.CurrentState);
+        // Verify add_issue_comment was called for the failure notification
+        await mcp.Received().CallToolAsync(
+            Arg.Is<string>("add_issue_comment"),
+            Arg.Any<JsonObject>(),
+            Arg.Any<CancellationToken>());
+    }
+
+    // SM-FAILURE-02: when Issue is null, PostFailureCommentAsync is a no-op (no MCP call)
+    [Fact]
+    public async Task RunAsync_FailureWithNullIssue_DoesNotCallMcp()
+    {
+        // Create a state machine with NO states and override so failure happens with no issue context
+        var checkpoints = Substitute.For<ICheckpointStore>();
+        checkpoints.SaveAsync(Arg.Any<GsdWorkflowContext>(), Arg.Any<CancellationToken>())
+                   .Returns(Task.CompletedTask);
+
+        var mcp = Substitute.For<IMcpClient>();
+
+        var failingState = Substitute.For<IWorkflowState>();
+        failingState.State.Returns(WorkflowState.Idle);
+        failingState.ExecuteAsync(Arg.Any<GsdWorkflowContext>(), Arg.Any<CancellationToken>())
+                    .Returns<Task<GsdWorkflowContext>>(ci =>
+                    {
+                        // Return a failed context with no issue
+                        var ctx = ci.Arg<GsdWorkflowContext>() with
+                        {
+                            Issue = null,
+                            FailureReason = "no issue",
+                            CurrentState = WorkflowState.Failed
+                        };
+                        return Task.FromResult(ctx);
+                    });
+
+        var sut = BuildSut(checkpoints, [failingState], mcp);
+        var result = await sut.RunAsync("owner", "repo", 1, triageModeOnly: false, CancellationToken.None);
+
+        Assert.Equal(WorkflowState.Failed, result.CurrentState);
+        // No add_issue_comment should be fired when Issue is null
+        await mcp.DidNotReceive().CallToolAsync(
+            Arg.Is<string>("add_issue_comment"),
+            Arg.Any<JsonObject>(),
+            Arg.Any<CancellationToken>());
+    }
+
+    // SM-FAILURE-03: PostFailureCommentAsync McpException is swallowed (logged, not rethrown)
+    [Fact]
+    public async Task RunAsync_FailureCommentThrows_DoesNotRethrow()
+    {
+        var checkpoints = Substitute.For<ICheckpointStore>();
+        checkpoints.SaveAsync(Arg.Any<GsdWorkflowContext>(), Arg.Any<CancellationToken>())
+                   .Returns(Task.CompletedTask);
+
+        var mcp = Substitute.For<IMcpClient>();
+        mcp.CallToolAsync(Arg.Any<string>(), Arg.Any<JsonObject>(), Arg.Any<CancellationToken>())
+           .Returns<Task<McpToolResult>>(_ => throw new McpException("mcp dead", isTransient: false));
+
+        var failingState = Substitute.For<IWorkflowState>();
+        failingState.State.Returns(WorkflowState.Idle);
+        failingState.ExecuteAsync(Arg.Any<GsdWorkflowContext>(), Arg.Any<CancellationToken>())
+                    .Returns<Task<GsdWorkflowContext>>(_ => throw new InvalidOperationException("state exploded"));
+
+        var sut = BuildSut(checkpoints, [failingState], mcp);
+
+        // Should not throw even when MCP call for comment also fails
+        var ctx = await sut.RunAsync("owner", "repo", 1, triageModeOnly: false, CancellationToken.None);
+        Assert.Equal(WorkflowState.Failed, ctx.CurrentState);
+    }
+}

coverage-results/f697cb52-e85a-479c-84d3-5489b58c1321/coverage.cobertura.xml

@@ -0,0 +1,68 @@
+using System.Reflection;
+using GsdOrchestrator.Mcp;
+using Xunit;
+
+namespace GsdOrchestrator.Tests;
+
+/// <summary>
+/// Covers McpException.FromToolError (internal static factory — lines 18-27)
+/// via reflection since the method is internal to GsdOrchestrator.
+/// </summary>
+public class McpExceptionFromToolErrorTests
+{
+    private static McpException InvokeFromToolError(string text)
+    {
+        var method = typeof(McpException)
+            .GetMethod("FromToolError", BindingFlags.NonPublic | BindingFlags.Static)!;
+        return (McpException)method.Invoke(null, [text])!;
+    }
+
+    [Fact]
+    public void FromToolError_PlainText_IsNotTransientNotSecondary()
+    {
+        var ex = InvokeFromToolError("generic API error");
+        Assert.False(ex.IsTransient);
+        Assert.False(ex.IsSecondaryRateLimit);
+        Assert.Equal("generic API error", ex.Message);
+    }
+
+    [Fact]
+    public void FromToolError_SecondaryRateLimitText_SetsBothFlags()
+    {
+        var ex = InvokeFromToolError("You have exceeded the secondary rate limit.");
+        Assert.True(ex.IsSecondaryRateLimit);
+        Assert.True(ex.IsTransient);
+    }
+
+    [Fact]
+    public void FromToolError_SecondaryRateLimitMixedCase_Detected()
+    {
+        var ex = InvokeFromToolError("Secondary Rate Limit triggered");
+        Assert.True(ex.IsSecondaryRateLimit);
+        Assert.True(ex.IsTransient);
+    }
+
+    [Fact]
+    public void FromToolError_PrimaryRateLimitExceeded_IsTransientNotSecondary()
+    {
+        var ex = InvokeFromToolError("rate limit exceeded on this endpoint");
+        Assert.True(ex.IsTransient);
+        Assert.False(ex.IsSecondaryRateLimit);
+    }
+
+    [Fact]
+    public void FromToolError_ApiRateLimit_IsTransientNotSecondary()
+    {
+        var ex = InvokeFromToolError("API rate limit reached for user");
+        Assert.True(ex.IsTransient);
+        Assert.False(ex.IsSecondaryRateLimit);
+    }
+
+    [Fact]
+    public void FromToolError_PreservesMessageVerbatim()
+    {
+        var msg = "Tool error: NOT_FOUND (404)";
+        var ex = InvokeFromToolError(msg);
+        Assert.Equal(msg, ex.Message);
+    }
+}